=pod
=head1 NAME
Class::STL::Containers - Perl extension for STL-like object management
=head1 SYNOPSIS
use stl;
# Deque container...
my $d = stl::deque(qw(first second third fourth));
$d->push_back($d->factory('fifth'));
$d->push_front($d->factory('seventh'));
$d->pop_front(); # remove element at front.
$d->pop_back(); # remove element at back.
stl::for_each($d->begin(), $d->end(), ptr_fun('::myprint'));
sub myprint { print "Data:", @_, "\n"; }
# Copy constructor...
my $d_copy = stl::deque($d);
# Algorithms -- find_if()
print "Element 'second' was ",
stl::find_if($d->begin(), $d->end(), stl::bind1st(stl::equal_to(), 'second'))
? 'found' : 'not found', "\n";
# Algorithms -- count_if()
print "Number of elements matching /o/ = ",
stl::count_if($d->begin(), $d->end(), stl::bind2nd(stl::matches(), 'o')),
"\n"; # prints '2' -- matches 'second' and 'fourth'
# Algorithms -- transform()
stl::transform($d->begin(), $d->end(), $d2->begin(), stl::ptr_fun('ucfirst'));
stl::transform($d->begin(), $d->end(), $d2->begin(), $d3->begin(), stl::ptr_fun_binary('::mybfun'));
sub mybfun { return $_[0] . '-' . $_[1]; }
# Function Adaptors -- bind1st
stl::remove_if($v->begin(), $v->end(), stl::bind1st(stl::equal_to(), $v->back()));
# remove element equal to back() -- ie remove last element.
stl::remove_if($v->begin(), $v->end(), stl::bind2nd(stl::matches(), '^fi'));
# remove all elements that match reg-ex '^fi'
# Sort list according to elements cmp() function
$v->sort();
# Queue containers -- FIFO
my $v = stl::queue(qw(first second third fourth fifth));
print 'Back:', $v->back()->data(), "\n" # Back:fifth
print 'Front:', $v->front()->data(), "\n" # Front:first
$v->pop(); # pop element first in
$v->push($v->factory('sixth')), "\n"
print 'Back:', $v->back()->data(), "\n" # Back:sixth
print 'Front:', $v->front()->data(), "\n" # Front:second
# Iterators
for (my $i = $v->begin(); !$i->at_end(); ++$i)
{
print "Data:", $i->p_element()->data();
}
# Iterators -- reverse_iterator
my $ri = stl::reverse_iterator($v->iter())->first();
while (!$ri->at_end())
{
print "Data:", $ri->p_element()->data();
++$ri;
}
# Inserters
my $three2one = stl::list(qw(3 2 1));
my $four2six = stl::list(qw(4 5 6));
my $seven2nine = stl::list(qw(7 8 9));
my $result = stl::list();
stl::copy($three2one->begin(), $three2one->end(), stl::front_inserter($result));
stl::copy($seven2nine->begin(), $seven2nine->end(), stl::back_inserter($result));
my $iseven = stl::find($result->begin(), $result->end(), 7);
stl::copy($four2six->begin(), $four2six->end(), stl::inserter($result, $iseven));
# $result now contains (1, 2, 3, 4, 5, 6, 7, 8, 9);
# Vector container...
my $v = stl::vector(qw(first second third fourth fifth));
my $e = $v->at(0); # return pointer to first element.
print 'Element-0:', $e->data(), "\n"; # Element-0:first
$e = $v->at($v->size()-1); # return pointer to last element.
print 'Element-last:', $e->data(), "\n"; # Element-last:fifth
$e = $v->at(2); # return pointer to 3rd element (idx=2).
print 'Element-2:', $e->data(), "\n"; # Element-2:third
# Priority Queue
my $p = stl::priority_queue();
$p->push($p->factory(priority => 10, data => 'ten'));
$p->push($p->factory(priority => 2, data => 'two'));
$p->push($p->factory(priority => 12, data => 'twelve'));
$p->push($p->factory(priority => 3, data => 'three'));
$p->push($p->factory(priority => 11, data => 'eleven'));
$p->push($p->factory(priority => 1, data => 'one'));
$p->push($p->factory(priority => 1, data => 'one-2'));
$p->push($p->factory(priority => 12, data => 'twelve-2'));
$p->push($p->factory(priority => 20, data => 'twenty'), $p->factory(priority => 0, data => 'zero'));
print "\$p->size()=", $p->size(), "\n";
print "\$p->top():", $p->top(), "\n";
$p->top()->priority(7); # change priority for top element.
$p->refresh(); # refresh required after priority change.
$p->pop(); # remove element with highest priority.
print "\$p->top():", $p->top(), "\n";
# Clone $d container into $d1...
my $d1 = $d->clone();
my $d2 = stl::deque(qw(sixth seventh eight));
# Append $d container to end of $d2 container...
$d2 += $d;
# DataMembers -- Class builder helper...
{
package MyClass;
use Class::STL::ClassMembers (
qw(attrib1 attrib2), # data members
Class::STL::ClassMembers::DataMember->new(
name => 'attrib3', default => '100', validate => '^\d+$'), # data member with attributes
Class::STL::ClassMembers::DataMember->new(
name => 'attrib4', default => 'med', validate => '^(high|med|low)$'),
);
use Class::STL::ClassMembers::Constructor; # produce class new() function
}
my $cl = MyClass->new(attrib1 => 'hello', attrib2 => 'world');
print $cl->attrib1(), " ", $cl->attrib2(), "\n"; # 'hello world'
$cl->attrib1(ucfirst($cl->attrib1));
$cl->attrib2(ucfirst($cl->attrib2));
print $cl->attrib1(), " ", $cl->attrib2(), "\n"; # 'Hello World'
$cl->attrib4('avg'); # Causes progam to die with '** Function attrib2 value failed validation...'
=head1 DESCRIPTION
This package provides a framework for rapid Object Oriented Perl application development. It consists of a number of base classes that are similar to the C++/STL framework, plus a number of I<helper> classes which provide the I<glue> to transparently generate common functions, and will enable you to put your Perl application together very quickly.
The I<STL> functionality provided consists of F<containers>, F<algorithms>, F<utilities> and F<iterators> as follows:
=item F<Containers>
vector, list, deque, queue, priority_queue, stack, tree.
=item F<Iterators>
iterator, bidirectional_iterator, reverse_iterator, forward_iterator.
=item F<Algorithms>
find, find_if, for_each, transform, count, count_if, copy, copy_backward, remove, remove_if, remove_copy, remove_copy_if, replace, replace_if, replace_copy, replace_copy_if.
=item F<Utilities>
equal_to, not_equal_to, greater, greater_equal, less, less_equal, compare, bind1st, bind2nd, mem_fun, ptr_fun, ptr_fun_binary, matches, matches_ic, logical_and, logical_or, multiplies, divides, plus, minus, modulus.
=head2 F<Differences From C++/STL>
Most of the functions have the same arguments and return types as their STL equivalent. There are some differences though between the C++/STL and this implementation:
=item Iterators and the I<end()> function
An I<iterator> object points to a numeric position within the container, and not to an I<element>. If new elements are inserted to, or removed from, a postion preceding the iterator, then the iterator will point to the same I<position> but to a different element.
The I<end> function will return a newly constructed iterator object which will point to the I<last> element within the container, unlike the C++/STL equivalent which points to I<after> the last element.
=item The I<tree> Container
This container provides a hierarchical tree structure. Each element within a I<tree> container can be either a simple element or another container object. The I<algorithms> and overridden I<to_array> functions will traverse the tree and pocess all element I<nodes> within the tree.
=item Utilities I<matches>, I<matches_ic> functions
These utilities provide unary functions for regular expression matching. The first or second argument will be a regular expression string. The I<match_ic> provides case insensitive matching.
=item Container I<append> function
This function and the overridden C<+>, C<+=> operators will combine the two containers together.
=item The I<clone> function
This function returns a newly constructed object that is a copy of its caller object.
=item The Container I<to_array> function
This function will return an array consisting of all element objects within the container.
=item Container I<element> type
All containers contain collections of objects which are of type F<Class::STL::Element>, or classes derived from this type. The container classes are themselves, ultimately, derived from this I<element> type.
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::ClassMembers>
These I<helper> classes can be used to generate code for various basic class functions. This module requires an import list consisting of target data member names or I<Class::STL::ClassMembers::DataMember> objects. When using I<ClassMembers> B<ALL> data members should be included in order for the generated I<clone> and I<swap> functions to function correctly. The constructor function code can be produces as well by using the package F<Class::STL::ClassMembers::Constructor>, or F<Class::STL::ClassMembers::SingletonConstructor> to create a singleton class type.
The following target member functions will be generated and made available to the class:
=item Data Member Accessor Get/Put Function
This function will have the same name as the data member and should be used to I<set> or I<get> the value for the data member. Pass the value as the argument when setting the value for a data member. For I<comlpex> data members with a F<validate> attribute, a validation check will be performed when attempting to set the member value by matching the value against the I<validate> regular expression string.
=item Class I<members_init()> Function
This function should be called in the target class's I<new> function after I<$self> has been blessed. It will perform the necessary data members initialisation.
=item Class I<clone()> Function
This function will construct and return an object containing a copy of the caller object.
=item Class I<swap()> Function
This function requires one argument consisting of an object of the same type as the caller. It will swap the caller object with this I<other> object.
=item Class I<members()> Function
This function will return a pointer to an anonymous hash containing the data member names (as the key) and data member attibutes array list consisting of F<default> and F<validate> attribute fields in that order. All data members, including inherited members are contained in this hash.
=item Class I<members_local()> Function
Same as F<members> function except that only the data members local to the class are contained in the hash returned.
=item Class::STL::ClassMembers::DataMember
For more complex data members, this class may be used to provide additional information about the member. This information consist of: F<name>, F<default>, and F<validate>. The F<name> attribute contains the member name; the F<default> attribute contains a default value for the member when initialised; the F<validate> attribute consists of a regular expression string that will be used to validate the member value by matching it to this regex string.
=item Class::STL::ClassMembers::Constructor
The constructor function with the name F<new()> will be produced for a package that uses this module. It is recomended that this constructor is produced for any class (package) that uses the F<ClassMembers> package to produce the data members. This will ensure that the correct calls are done during construction and copy-construction of an object. This constructor will make a call to the C<static> user member function F<new_extra> if it exists in the calling class. The F<new_extra> function will have the object reference passed as the first argument.
=item Class::STL::ClassMembers::SingletonConstructor
Use this package to produce a singleton class. This constructor will ensure that only one instance of this class will be constructed.
=head2 Example
=begin
{
package MyClass;
use Class::STL::ClassMembers (
qw(attrib1 attrib2),
Class::STL::ClassMembers::DataMember->new(
name => 'attrib3', default => '100', validate => '^\d+$'),
Class::STL::ClassMembers::DataMember->new(
name => 'attrib4', default => 'med', validate => '^(high|med|low)$'),
);
use Class::STL::ClassMembers::Constructor; # produce class new() function
}
my $cl = MyClass->new(attrib1 => 'hello', attrib2 => 'world');
print $cl->attrib1(), " ", $cl->attrib2(), "\n"; # 'hello world'
$cl->attrib1(ucfirst($cl->attrib1));
$cl->attrib2(ucfirst($cl->attrib2));
print $cl->attrib1(), " ", $cl->attrib2(), "\n"; # 'Hello World'
$cl->attrib4('avg'); # Causes progam to die with '** Function attrib2 value failed validation...'
=end
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers>
=head2 Exports
F<vector>, F<list>, F<deque>, F<queue>, F<priority_queue>, F<stack>, F<tree>.
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Abstract>
This is the I<abstract> base class for all other container classes. Objects should not be constructed directly from this class, but from any of the derived container classes. Common functions are documented here.
=head2 Extends I<Class::STL::Element>
=over
=item F<new>
I<container-ref new ( [ named-argument-list ] );>
I<container-ref new ( container-ref );>
I<container-ref new ( element [, ...] );>
I<container-ref new ( iterator-start [, iterator-finish ] );>
I<container-ref new ( raw-data [, ... ] );>
The I<new> function constructs an object for this class and returns a blessed reference to this object. All forms accept an optional I<hash> containing any of the following named arguments: I<element_type>. The I<element_type> defines the class type of element objects that the container will hold. I<element_type> will default to F<Class::STL::Element> if not specified; when specified, the type must be derived from F<Class::STL::Element>.
The second form is a I<copy constructor>. It requires another container reference as the argument, and will return a copy of this container.
The third form requires one or more element refs as arguments. These elements will be copied into the newly constructed container.
The fourth form requires one I<start> iterator and an optional I<finish> iterator. All the element objects with, and including, the I<start> and I<finish> (or I<end> if not specified) positions will be copied into the newly constructed container.
The fifth form accepts a list of raw data values. Each of these values will be stored inside a F<Class::STL::Element> object constructed by the container's I<factory> function, with the element's I<data> member containing the raw data value.
=item F<clone>
Returns a newly constructed object which is identical to the calling (this) object.
=item F<factory>
I<element-ref factory ( %attributes );>
The I<factory> function constructs a new element object and returns a reference to this. The type of object created is as specified by the I<element_type> container attribute. The I<attributes> argument consists of a hash and is passed on to the element class I<new> function. Override this function if you want to avoid the 'eval' call.
=item F<erase>
I<iterator erase ( iterator-start [, iterator-finish ] );>
The I<erase> function requires one starting iterator and an optional finish iterator as arguments. It will delete all the elements in the container within, and including, these two iterator positions. The I<erase> funtion returns and iterator pointing to the element following the last deleted element.
=item F<insert>
I<void insert ( position, iterator-start, iterator-finish );>
I<void insert ( position, iterator-start );>
I<void insert ( position, element [, ...] );>
I<void insert ( position, size, element );>
The first form will insert copies of elements within the I<iterator-start> and I<iterator-finish> positions before I<position>.
The second form will insert copies of elements within the I<iterator-start> and I<end> positions before I<position>
The third form will insert the element, or elements (I<not copies>) before I<position>.
The fourth form will insert I<size> copies of I<element> before I<position>.
=item F<pop>
I<void pop ( );>
The I<pop> function requires no arguments. It will remove the element at the I<top> of the container.
=item F<push>
I<void push ( element [, ...] );>
The I<push> function requires one or more arguments consisting of elements. This will append the element(s) to the end of the container.
=item F<clear>
I<void clear ( );>
This function will delete all the elements from the container.
=item F<begin>
I<iterator-ref begin ( );>
The I<begin> function constructs and returns a new iterator object which points to the I<front> element within the container.
=item F<end>
I<iterator-ref end ( );>
The I<end> function constructs and returns a new iterator object which points to the F<back> element within the container. **Note that, unlike C++/STL, this object points to the last element and not I<after the last element>.
=item F<rbegin>
I<iterator-ref rbegin ( );>
The I<rbegin> function is the reverse of the I<begin> function -- the newly constructed iterator points to the last element.
=item F<rend>
I<iterator-ref rend ( );>
The I<rend> function is the reverse of the I<end> function -- the newly constructed iterator points to the first element.
=item F<size>
I<int size ( );>
The I<size> function requires no arguments. It will return an integer value containing the number of elements in the container.
=item F<empty>
I<bool empty ( );>
This function returns I<'1'> if the container is empty (ie. contains no elements), and I<'0'> if the container contains one or more elements.
=item F<to_array>
I<array to_array ( );>
The I<to_array> function returns an array containing the elements (references) from the container.
=item F<eq>
I<bool eq ( container-ref );>
The I<eq> function compares the I<elements> in this container with the I<elements> in the container refered to by the argument I<container-ref>. The elements are compared using the element I<eq> function. The function will return I<'1'> if both containers contain the same number of elements and all elements in one container are equal to, and in the same order as, all elements in the I<container-ref> container.
=item F<ne>
I<bool ne ( container-ref );>
Inverse of I<eq> function.
=item F<operator +>, F<operator +=>
Append containers.
=item F<operator == >
Containers equality comparison.
=item F<operator != >
Containers non-equality comparison.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::List>
A list container can have elements pushed and popped from both ends, and also inserted at any location. Access to the elements is sequential.
=head2 Extends I<Class::STL::Containers::Deque>
=over
=item F<reverse>
I<void reverse ( );>
The I<reverse> function will alter the order of the elements in list by reversing their order.
=item F<sort>
I<void sort ( );>
The I<sort> function will alter the order of the elements in list by sorting the elements. Sorting is done based on the elements I<cmp> comparison function.
=back
=head2 Example
=begin
use stl;
# Construct the list object:
my $list = list(qw( first second third fourth fifth));
# Display the number of elements in the list:
print "Size:", $list->size(), "\n"; # Size:5
# Reverse the order of elements in the list:
$list->reverse();
# Display the contents of the element at the front of the list:
print 'Front:', $list->front(), "\n";
# Display the contents of the element at the back of the list:
print 'Back:', $list->back(), "\n";
# Display the contents of all the elements in the list:
for_each($list->begin(), $list->end(), MyPrint->new());
# Return an array of all elements-refs:
my @arr = $l1->to_array();
# Delete all elements from list:
$list->clear();
print "Size:", $list->size(), "\n"; # Size:0
print '$list container is ',
$list->empty() ? 'empty' : 'not empty', "\n";
# MyPrint Unary Function -- used in for_each() above...
{
package MyPrint;
use base qw(Class::STL::Utilities::FunctionObject::UnaryFunction);
sub function_operator
{
my $self = shift;
my $arg = shift;
print "Data:", $arg->data(), "\n";
}
}
=end
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Vector>
A vector allows for random access to its elements via the I<at> function.
=head2 Extends I<Class::STL::Containers::Abstract>
=over
=item F<push_back>
I<void push_back ( element [, ...] );>
The I<push_back> function requires one or more arguments consisting of elements. This will append the element(s) to the end of the I<vector>.
=item F<pop_back>
I<void pop_back ( );>
The I<pop_back> function requires no arguments. It will remove the element at the I<top> of the I<vector>.
=item F<back>
I<element-ref back ( );>
The I<back> function requires no arguments. It returns a reference to the element at the I<back> of the I<vector>.
=item F<front>
The I<front> function requires no arguments. It returns a reference to the element at the I<front> of the I<vector>.
=item F<at>
I<element-ref at ( index );>
The I<at> function requires an I<index> argument. This function will return a reference to the element at the location within the I<vector> specified by the argument I<index>.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Deque>
A double-ended container. Elements can be I<pushed> and I<popped> at both ends.
=head2 Extends I<Class::STL::Containers::Vector>
=over
=item F<push_front>
I<void push_front ( element [, ...] );>
The I<push_front> function requires one or more arguments consisting of elements. This will insert the element(s) to the front of the I<deque>.
=item F<pop_front>
I<void pop_front ( );>
The I<pop_front> function requires no arguments. It will remove the element at the I<front> of the I<deque>.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Queue>
A queue is a FIFO (first-in-first-out) container. Elements can be I<pushed> at the back and I<popped> from the front.
=head2 Extends I<Class::STL::Containers::Abstract>
=over
=item F<push>
I<void push ( element [, ...] );>
The I<push> function requires one or more arguments consisting of elements. This will append the element(s) to the back of the I<queue>.
=item F<pop>
I<void pop ( );>
The I<pop> function requires no arguments. It will remove the element at the I<front> of the I<queue>. This is the earliest inserted element.
=item F<back>
I<element-ref back ( );>
The I<back> function requires no arguments. It returns a reference to the element at the I<back> of the I<queue>. This is the element last inserted.
=item F<front>
I<element-ref front ( );>
The I<front> function requires no arguments. It returns a reference to the element at the I<front> of the I<queue>. This is the earliest inserted element.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Stack>
A stack is a LIFO (last-in-first-out) container. Elements can be I<pushed> at the top and I<popped> from the top.
=head2 Extends I<Class::STL::Containers::Abstract>
=over
=item F<push>
I<void push ( element [, ...] );>
The I<push> function requires one or more arguments consisting of elements. This will append the element(s) to the top of the I<stack>.
=item F<pop>
I<void pop ( );>
The I<pop> function requires no arguments. It will remove the element at the I<top> of the I<stack>. This is the last inserted element.
=item F<top>
I<element-ref top ( );>
The I<top> function requires no arguments. It returns a reference to the element at the I<top> of the I<stack>. This is the last inserted element.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::Tree>
A tree is a hierarchical structure. Each element within a I<tree> container can be either a simple element or another container object. The overridden I<to_array> function will traverse the tree and return an array consisting of all the I<nodes> in the tree.
=head2 Extends I<Class::STL::Containers::Deque>
=over
=item F<to_array>
I<array to_array ( );>
The overridden I<to_array> function will traverse the tree and return an array consisting of all the element I<nodes> in the tree container.
=back
=head2 Examples
=begin
# Tree containers; construct two trees from
# previously construced containers:
my $t1 = tree($l1);
my $t2 = tree($l2);
# Construct a third tree:
my $tree = tree();
# Add other tree containers as elements to this tree:
$tree->push_back($tree->factory($t1));
$tree->push_back($tree->factory($t2));
# Search for element ('pink') in tree:
if (my $f = find_if($tree->begin(), $tree->end(), bind1st(equal_to(), 'pink'))
print "FOUND:", $f->data(), "\n";
} else {
print "'pink' NOT FOUND", "\n";
}
# Traverse tree returning all element nodes:
my @tarr = $tree->to_array();
=end
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Containers::PriorityQueue>
A priority queue will maintain the order of the elements based on their priority, with highest priority elements at the top of the container. Elements contained in a priority queue must be of the type, or derived from, I<Class::STL::Element::Priority>. This element type contains the attribute I<priority>, and needs to have its value set whenever an object of this element type is constructed.
=head2 Extends I<Class::STL::Containers::Vector>
=head2 Element Type I<Class::STL::Element::Priority>
=over
=item F<push>
I<void push ( element [, ...] );>
The I<push> function requires one or more arguments consisting of elements. This will place the element(s) in the queue according to their priority value.
=item F<pop>
I<void pop_back ( );>
The I<pop> function requires no arguments. It will remove the element with the highest priority.
=item F<top>
I<element-ref top ( );>
The I<top> function requires no arguments. It returns a reference to the element with the highest priority.
=item F<refresh>
I<void refresh ( );>
The I<refresh> function should be called whenever the priority value for an element has been order. This will update the ordering of the elements if required.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Algorithms>
This module contains various algorithm functions.
=head2 Exports
F<remove_if>, F<find_if>, F<for_each>, F<transform>, F<count_if>, F<find>, F<count>, F<copy>, F<copy_backward>, F<remove>, F<remove_copy>, F<remove_copy_if>, F<replace>, F<replace_if>, F<replace_copy>, F<replace_copy_if>, F<generate>, F<generate_n>, F<fill>, F<fill_n>, F<equal>, F<reverse>, F<reverse_copy>, F<rotate>, F<rotate_copy>, F<partition>, F<stable_partition>, F<min_element>, F<max_element>, F<unique>, F<unique_copy>, F<adjacent_find>
The F<Algorithms> package consists of various I<static> algorithm functions.
The I<unary-function> / I<binary-function> argument must be derived from I<Class::STL::Utilities::FunctionObject::UnaryFunction> and I<Class::STL::Utilities::FunctionObject::BinaryFunction> respectively. Standard utility functions are provided in the I<Class::STL::Utilities> module. A function object contains the function I<function_operator>. This I<function_operator> function will, in turn, be called by the algorithm for each element traversed. The algorithm will pass the element reference as the argument to the I<function_operator> function.
=over
=item F<for_each>
I<void for_each ( iterator-start, iterator-finish, unary-function );>
The I<for_each> function will traverse the container starting from I<iterator-start> and ending at I<iterator-finish> and execute the I<unary-function> with the element passed in as the argument.
=item F<transform>
I<void transform ( iterator-start, iterator-finish, iterator-result, unary-function );>
I<void transform ( iterator-start, iterator-finish, iterator-start2, iterator-result, binary-function );>
The I<transform> functions has two forms. The first form will traverse the container starting from I<iterator-start> and ending at I<iterator-finish> and execute the I<unary-function> with the element passed in as the argument, producing I<iterator-result>.
The second form will traverse two containers with the second one starting from I<iterator-start2>. The I<binary-function> will be called for each pair of elements. The resulting elements will be placed in I<iterator-result>.
=item F<count>
I<int count ( iterator-start, iterator-finish, element-ref );>
=item F<count_if>
I<int count_if ( iterator-start, iterator-finish, unary-function );>
The I<count_if> function will traverse the container starting from I<iterator-start> and ending at I<iterator-finish> and return a count of the elements that evaluate to true by the I<unary-function>.
=item F<find>
I<iterator-ref find ( iterator-start, iterator-finish, element-ref );>
=item F<find_if>
I<iterator-ref find_if ( iterator-start, iterator-finish, unary-function );>
The I<find_if> function will traverse the container starting from I<iterator-start> and ending at I<iterator-finish> and return an I<iterator> pointing to the first element that evaluate to true by the I<unary-function>. If no elements evaluates to true then 'o' is returned.
=item F<copy>
I<void copy ( iterator-start, iterator-finish, iterator-result );>
=item F<copy_backward>
I<void copy_backward ( iterator-start, iterator-finish, iterator-result );>
=item F<remove>
I<void remove ( iterator-start, iterator-finish, element-ref );>
=item F<remove_if>
I<void remove_if ( iterator-start, iterator-finish, unary-function );>
The I<remove_if> function will traverse the container starting from I<iterator-start> and ending at I<iterator-finish> and remove the elements that evaluate to true by the I<unary-function>.
=item F<remove_copy>
I<void remove_copy ( iterator-start, iterator-finish, iterator-result, element-ref );>
=item F<remove_copy_if>
I<void remove_copy_if ( iterator-start, iterator-finish, iterator-result, unary-function );>
=item F<replace>
I<void replace ( iterator-start, iterator-finish, old-element-ref, new-element-ref );>
=item F<replace_if>
I<void replace_if ( iterator-start, iterator-finish, unary-function, new-element-ref );>
=item F<replace_copy>
I<void replace_copy ( iterator-start, iterator-finish, iterator-result, old-element-ref, new-element-ref );>
=item F<replace_copy_if>
I<void replace_copy_if ( iterator-start, iterator-finish, iterator-result, unary-function, new-element-ref );>
=item F<generate>
I<void generate ( iterator-start, iterator-finish, generator-function );>
=item F<generate_n>
I<void generate_n ( iterator-start, size, generator-function );>
=item F<fill>
I<void fill ( iterator-start, iterator-finish, element-ref );>
=item F<fill_n>
I<void fill_n ( iterator-start, size, element-ref );>
=item F<equal>
I<bool equal ( iterator-start, iterator-finish, iterator-result [, binary-function ] );>
=item F<reverse>
I<void reverse ( iterator-start, iterator-finish );>
=item F<reverse_copy>
I<void reverse_copy ( iterator-start, iterator-finish, iterator-result );>
=item F<rotate>
I<void rotate ( iterator-start, iterator-mid, iterator-finish );>
=item F<rotate_copy>
I<void rotate_copy ( iterator-start, iterator-mid, iterator-finish, iterator-result );>
=item F<partition>
I<void partition ( iterator-start, iterator-finish, [, unary-predicate ] );>
=item F<stable_partition>
I<void stable_partition ( iterator-start, iterator-finish, [, unary-predicate ] );>
=item F<min_element>
I<iterator min_element ( iterator-start, iterator-mid [, binary-function ] );>
=item F<max_element>
I<iterator max_element ( iterator-start, iterator-mid [, binary-function ] );>
=item F<unique>
I<iterator unique ( iterator-start, iterator-finish, [, binary-function ] );>
=item F<unique_copy>
I<iterator unique_copy ( iterator-start, iterator-finish, iterator-result [, binary-function ] );>
=item F<adjacent_find>
I<iterator ajacent_find ( iterator-start, iterator-finish, [, binary-predicate ] );>
=back
=head2 Examples
=begin
use Class::STL::Containers;
use Class::STL::Algorithms;
use Class::STL::Utilities;
# Display all elements in list container '$list'
# using unary-function 'myprint' and algorithm 'for_each':
for_each($list->begin(), $list->end(), ptr_fun('::myprint'));
sub myprint { print "Data:", @_, "\n"; }
# Algorithms -- remove_if()
# Remove element equal to back() -- ie remove last element:
remove_if($list->begin(), $list->end(), bind1st(equal_to(), $list->back()));
# Remove all elements that match regular expression '^fi':
remove_if($v->begin(), $v->end(), bind2nd(matches(), '^fi'));
# Search for element ('pink') in tree:
if (my $f = $tree->find_if($tree->begin(), $tree->end(), bind1st(equal_to(), "pink"))) {
print "FOUND:", $f->p_element()->data(), "\n";
} else {
print "'pink' NOT FOUND", "\n";
}
=end
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Utilities>
=head2 Exports
F<equal_to>, F<not_equal_to>, F<greater>, F<greater_equal>, F<less>, F<less_equal>, F<compare>, F<bind1st>, F<bind2nd>, F<mem_fun>, F<ptr_fun>, F<ptr_fun_binary>, F<matches>, F<matches_ic>, F<logical_and>, F<logical_or>, F<multiplies>, F<divides>, F<plus>, F<minus>, F<modulus>.
This module contains various utility function objects. Each object will be constructed automatically when the function name (eg. 'equal_to') is used. Each of the function objects are derived from either I<Class::STL::Utilities::FunctionObject::UnaryFunction> or I<Class::STL::Utilities::FunctionObject::BinaryFunction>.
=over
=item F<equal_to>
F<Binary predicate>. This function-object will return the result of I<equality> between its argument and the object I<arg> attribute's value. The element's I<eq> function is used for the comparison.
=item F<not_equal_to>
F<Binary predicate>. This function is the inverse of I<equal_to>.
=item F<greater>
F<Binary predicate>. This function-object will return the result of I<greater-than> comparison between its argument and the object I<arg> attribute's value. The element's I<gt> function is used for the comparison.
=item F<greater_equal>
F<Binary predicate>. This function-object will return the result of I<greater-than-or-equal> comparison between its argument and the object I<arg> attribute's value. The element's I<ge> function is used for the comparison.
=item F<less>
F<Binary predicate>. This function-object will return the result of I<less-than> comparison between its argument and the object I<arg> attribute's value. The element's I<lt> function is used for the comparison.
=item F<less_equal>
F<Binary predicate>. This function-object will return the result of I<less-than-or-equal> comparison between its argument and the object I<arg> attribute's value. The element's I<le> function is used for the comparison.
=item F<compare>
F<Binary predicate>. This function-object will return the result of I<compare> comparison between its argument and the object I<arg> attribute's value. The element's I<cmp> function is used for the comparison.
=item F<matches>
F<Binary predicate>. This function-object will return the result (true or false) of the regular expression comparison between its first argument and its second argument which contains a regular expression string.
=item F<matches_ic>
F<Binary predicate>. Case-insensitive version of the I<matches> function.
=item F<bind1st>
F<Unary function>. This function requires two arguments consisting of a I<binary-function-object> and a element or value argument. It will produce a I<unary-function> object whose I<function_operator> member will call the I<binary-function> with I<argument> as the first argument.
=item F<bind2nd>
F<Unary function>. This function requires two arguments consisting of a I<binary-function-object> and a element or value argument. It will produce a I<unary-function> object whose I<function_operator> member will call the I<binary-function> with I<argument> as the second argument.
=item F<mem_fun>
This function requires one argument consisting of the class member function name (string). It will construct an object whose I<function_operator> member will require an element object to be passed as the first argument. It will call the elements's member function as specified by the I<mem_fun> argument.
=item F<ptr_fun>
F<Unary function>. This function requires one argument consisting of a global function name (string).
=item F<ptr_fun_binary>
F<Binary function>. This function requires one argument consisting of global function name (string).
=item F<logical_and>
F<Binary predicate>.
=item F<logical_or>
F<Binary predicate>.
=item F<multiplies>
F<Binary function>. This function-object will return the result of I<multiply> between its two element arguments. The element's I<mult> function is used for the calculation. It will return a newly construced element object containing the result.
=item F<divides>
F<Binary function>. This function-object will return the result of I<division> between its two element arguments. The element's I<div> function is used for the calculation. It will return a newly construced element object containing the result.
=item F<plus>
F<Binary function>. This function-object will return the result of I<plus> between its two element arguments. The element's I<add> function is used for the calculation. It will return a newly construced element object containing the result.
=item F<minus>
F<Binary function>. This function-object will return the result of I<subtract> between its two element arguments. The element's I<subtract> function is used for the calculation. It will return a newly construced element object containing the result.
=item F<modulus>.
F<Binary function>. This function-object will return the result of I<modulus> between its two element arguments. The element's I<mod> function is used for the calculation. It will return a newly construced element object containing the result.
=back
=cut --------------------------------------------------------------------------------
=head1 F<CLASS Class::STL::Iterators>
This module contains the iterator classes.
=head2 Exports
F<iterator>, F<bidirectional_iterator>, F<reverse_iterator>, F<forward_iterator>, F<++>, F<-->, F<==>, F<!=>, E<gt>F<=>, E<lt>F<=>, F<+>, F<+=>, F<->, F<-=>, F<distance>, F<advance>, F<front_inserter>, F<back_inserter>, F<inserter>.
=over
=item F<new>
=item F<p_container>
Returns a reference to the container that is associated with the iterator.
=item F<p_element>
This function will return a reference to the element pointed to by the iterator.
=item F<distance>
B<Static function>. This function will return the I<distance> between two iterators. Both iterators must be from the same container. I<Iterator-finish> must be positioned after I<iterator-first>.
I<int distance ( iterator-start, iterator-finish ] );>
=item F<advance>
B<Static function>. Moves the iterator forward, or backwards if size is negative.
I<iterator advance ( iterator, size );>
=item F<inserter>
B<Static function>.
I<iterator inserter ( container, iterator );>
=item F<front_inserter>
B<Static function>.
I<iterator front_inserter ( container );>
=item F<back_inserter>
B<Static function>.
I<iterator back_inserter ( container );>
=item F<first>
=item F<next>
=item F<last>
=item F<prev>
=item F<at_end>
=item F<eq>
=item F<ne>
=item F<lt>
=item F<le>
=item F<gt>
=item F<ge>
=item F<cmp>
=back
=head2 Examples
=begin
# Using overoaded inrement operator:
for (my $i = $p->begin(); !$i->at_end(); $i++)
{
MyPrint->new()->function_operator($i->p_element());
}
# Using overoaded decrement operator:
for (my $i = $p->end(); !$i->at_end(); --$i)
{
MyPrint->new()->function_operator($i->p_element());
}
# Reverse iterator:
my $ri = reverse_iterator($p->iter())->first();
while (!$ri->at_end())
{
MyPrint->new()->function_operator($ri->p_element());
$ri->next();
}
=end
=cut --------------------------------------------------------------------------------
=head1 SEE ALSO
Sourceforge Project Page: C<http://sourceforge.net/projects/pstl>
=cut --------------------------------------------------------------------------------
=head1 AUTHOR
m gaffiero, E<lt>gaffie@users.sourceforge.netE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright E<copy>1999-2007, Mario Gaffiero. All Rights Reserved.
This file is part of Class::STL::Containers(TM).
Class::STL::Containers is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.
Class::STL::Containers is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with Class::STL::Containers; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
=cut