NAME
Array::Window - Calculate windows/subsets/pages of arrays.
SYNOPSIS
# Your search routine returns an reference to an array
# of sorted results of unknown quantity.
my $results = SomeSearch->find( 'blah' );
# We want to display 20 results at a time
my $Window = Array::Window->new(
source => $results,
window_start => 0,
window_length => 20,
);
# Do we need to split into pages at all?
my $show_pages = $Window->required;
# Extract the subset from the array
my $subset = $Window->extract( $results );
# Are there 'First', 'Last', 'Next' or 'Previous' windows?
my $First = $Window->first;
my $Last = $Window->last;
my $Next = $Window->next;
my $Previous = $Window->previous;DESCRIPTION
Many applications require that a large set of results be broken down into a smaller set of 'windows', or 'pages' in web language. Array::Window implements an algorithm specifically for dealing with these windows. It is very flexible and permissive, making adjustments to the window as needed.
Note that this is NOT under Math:: for a reason. It doesn't implement in a pure fashion, it handles idiosyncracies and corner cases specifically relating to the presentation of data.
Values are not in human terms
People will generally refer to the first value in a set as the 1st element, that is, a set containing 10 things will start at 1 and go up to 10. Computers refer to the first value as the '0th' element, with the same set starting at 0 and going up to 9.
The methods for this class return computer orientated values, so if you were to generate a message for a particular window, it might go as follows.
print 'Displaying Widgets ' . ($Window->window_start + 1)
. ' to ' . ($Window->window_end + 1)
. ' of ' . ($Window->source_end + 1);The inconvenience of this may be addressed in a later version of the module.
METHODS
new %options
The new constructor is very flexible with regards to the options that can be passed to it. However, this generally breaks down into deriving two things.
Firstly, it needs know about the source, usually an array, but more generically handled as a range of integers. This means that although the "first" element of the array would typically be zero, Array::Window can handle ranges where the first element is something other than zero.
For a typical 100 element array @array, you could use any of the following sets of options for defining the source array.
Array::Window->new( source => \@array );
Array::Window->new( source_length => 100 ); # Assume start at zero
Array::Window->new( source_start => 0, source_end => 99 );
Array::Window->new( source_start => 0, source_length => 100 );
Array::Window->new( source_end => 99, source_length => 100 );Secondly, the object needs to know information about Window it will be finding. Assuming a desired window size of 10, and assuming we use the first of the two options above, you would end up with the following.
# EITHER
Array::Window->new( source => \@array,
window_start => 0, window_length => 10 );
# OR
Array::Window->new( source => \@array,
window_start => 0, window_end => 9 );Although the second option looks a little silly, bear in mind that Array::Window will not assume that just because you WANT a window from 0 - 9, it's actually going to fit the size of the array.
Please note that the object does NOT make a copy or otherwise retain information about the array, so if you change the array later, you will need to create a new object.
source_start
Returns the index of the first source value, which will usually be 0.
source_end
Returns the index of the last source value, which for array @array, will be the same as $#array.
source_length
Returns the number of elements in the source array.
window_start
Returns the index of the first value in the window.
window_end
Returns the index of the last value in the window.
window_length
Returns the length of the window. This is NOT guarenteed to be the same as you initially entered, as the value you entered may have not fit. Imagine trying to get a 100 element long window on a 10 element array. Something has to give.
window_length_desired
Returns the desired window length. i.e. The value you originally entered.
previous_start
If a 'previous' window can be calculated, this will return the index of the start of the previous window.
next_start
If a 'next' window can be calculated, this will return the index of the start of the next window.
first
This method returns an Array::Window object representing the first window, which you can then use as needed. Returns false if the current window is already the first window.
last
This method return an Array::Window object representing the last window, which you can then use as needed. Returns false if the current window is already the last window.
previous
This method returns an Array::Window object representing the previous window, which you can then apply as needed. Returns false if the window is already at the 'beginning' of the source, and no previous window exists.
next
This method returns an Array::Window object representing the next window, which you can apply as needed. Returns false if the window is already at the 'end' of the source, and no window exists after this one.
required
Looks at the window and source and tries to determine if the entire source can be shown without the need for windowing. This can be usefull for interface code, as you can avoid generating 'next' or 'previous' controls at all.
extract \@array
Applies the object to an array, extracting the subset of the array that the window represents.
SUPPORT
Bugs should be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Array%3A%3AWindowFor other issues, contact the author
TO DO
- Determine how many windows there are. - human_values method to return human readable values.
AUTHOR
Adam Kennedy ( maintainer )
cpan@ali.as
http://ali.as/SEE ALSO
Set::Window - For more math orientated windows
COPYRIGHT
Copyright 2002 - 2004 Adam Kennedy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.