Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Array::Window(3)      User Contributed Perl Documentation     Array::Window(3)

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 <adamk@cpan.org>

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

COPYRIGHT
       Copyright 2002 -	2008 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.

perl v5.32.0			  2008-06-05		      Array::Window(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SUPPORT | TO DO | AUTHOR | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Array::Window&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help