view release on metacpan or  search on metacpan

lib/Array/Window.pm  view on Meta::CPAN

  my $previous = $window->previous;

=head1 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.

=head2 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;

=head1 METHODS

=head2 new %options

The C<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, C<Array::Window> can
handle ranges where the first element is something other than zero.

For a typical 100 element array C<@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 B<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.

=head2 source_start

Returns the index of the first source value, which will usually be 0.

=head2 source_end

Returns the index of the last source value, which for array C<@array>, will be
the same as C<$#array>.

=head2 source_length

Returns the number of elements in the source array.

=head2 window_start

Returns the index of the first value in the window.

=head2 window_end

Returns the index of the last value in the window.

=head2 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.

=head2 window_length_desired

Returns the desired window length. i.e. The value you originally entered.

=head2 human_window_start

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

=head2 human_window_end

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

=head2 previous_start

If a 'previous' window can be calculated, this will return the index of the
start of the previous window.

=head2 next_start

If a 'next' window can be calculated, this will return the index of the start
of the next window.

=head2 first

This method returns an C<Array::Window> object representing the first window,