NAME
    Array::Window - Calculate windows/subsets/pages of arrays.

SYNOPSIS
      # Your search routine returns 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 'Next' or 'Previous' windows?
      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 treated as a range of integers. For a typical 100 element
    array @array, you could use one of the following sets of options.

    Either

      Array::Window->new( source => \@array );

    OR

      Array::Window->new( source_start => 0, source_end => 99 );

    The source value will ONLY be taken as an array reference.

    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 be 0.

  source_end()
    Returns the index of the last source value, which for array @array, will
    be the same as $#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.

  previous()
    This method returns an "Array::Window" object representing the previous
    window, which you can then apply as needed. Returns 0 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 0 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 generate 'next' of 'previous'
    controls at all.

  extract( \@array )
    Applies the object to an array, extracting the subset of the array that
    the window represents.

SUPPORT
    Contact the author

TO DO
    - The "first_window" and "last_window" methods. - 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 (c) 2002 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.