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 normal methods for this class return computer orientated values. If
   you want to generate values for human messages, you should instead use
   the following.

     print 'Displaying Widgets ' . $Window->human_window_start
           . ' to ' . $Window->human_window_end
           . ' of ' . $Window->human_source_end;

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.

 human_window_start
   Returns the index of the first value in the window in human terms ( 1 ..
   n )

 human_window_end
   Returns the index of the last value in the window in human terms ( 1 ..
   n )

 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-Window>

   For other issues, or commercial enhancement or support, contact the
   author.

TO DO
   - Determine how many windows there are.

   - Provide the option to only work at strict intervals

AUTHOR
   Adam Kennedy <[email protected]>

SEE ALSO
   Set::Window, <http://ali.as/>

COPYRIGHT
   Copyright 2002 - 2007 Adam Kennedy.

   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.