Lagoon - Range utilities

Functions
template<typename ValueType , class... Ranges>
UnspecifiedRange< ValueType >	lagoon::chain (const Ranges &...ranges)
	Chains the ranges into a single range with a common ValueType.
template<typename Interface , class... Ranges>
UnspecifiedRange< shared < Interface > >	lagoon::chain_mo (const Ranges &...ranges)
	Chains the ranges into a single range with a common Interface.
template<class Range , typename Predicate >
bool	lagoon::contains (Range range, Predicate predicate)
	Searches a range for an element satisfying a predicate.
template<class Interface , class Range >
UnspecifiedRange< Interface >	lagoon::extract (const Range &metaobjects)
	Extracts only meta-objects with a particular interface.
template<class Range , typename Predicate >
Range	lagoon::find_if (Range range, Predicate predicate)
	Searches a range for an element satisfying a predicate.
UnspecifiedRange< shared < meta_named_scoped_object > >	lagoon::flatten (const shared< meta_scope > &scope)
	Get a range of all members of a scope including nested members.
UnspecifiedRange< shared < meta_named_scoped_object > >	lagoon::flatten_in_order (const shared< meta_scope > &scope)
	Get a range of all members of a scope including nested members.
template<typename State , class Range , typename BinaryOp >
State	lagoon::fold (Range range, State state, BinaryOp op)
	Accumulating the results of calling a binary functor on the elements.
template<typename State , class Range , typename BinaryOp >
State &	lagoon::fold_ref (Range range, State &state_ref, BinaryOp op)
	Accumulating the results of calling a binary functor on the elements.
template<typename State , class Range , typename InitialOp , typename DefaultOp , typename FinalOp >
State &	lagoon::fold_ref (Range range, State &state_ref, InitialOp initial, DefaultOp op, FinalOp final)
	Accumulating the results of calling a binary functor on the elements.
template<class Range , typename Functor >
Functor	lagoon::for_each (Range range, Functor func)
	Executes an unary functor on each element of a range.
template<class Range >
UnspecifiedRange	lagoon::limit (Range range, size_t count)
	Limits the range to contain maximum of n elements.
template<class Range >
UnspecifiedRange	lagoon::link (const std::initializer_list< Range > &ranges)
	Links the homogenous ranges into a single range.
template<class Range >
Range	lagoon::offset (Range range, size_t amount)
	Offsets the beginning of the range by N elements.
template<class Range , typename Predicate >
UnspecifiedRange	lagoon::only_if (Range range, Predicate predicate)
	Adapts the range to contain only elements satisfying a predicate.
template<class Range , typename SortProc >
UnspecifiedRange	lagoon::sort (Range range, SortProc sort_proc)
	Sorts the elements in the range by using a strict weak ordering proc.
template<class Range >
StdRange	lagoon::make_std_range (Range range)
	Adapts a Lagoon's range to have a begin() and end() functions.
template<class Range , typename Transform >
UnspecifiedRange	lagoon::transform (Range range, Transform transf)
	Transforms the elements in the range by a functor.
template<class Range , typename Predicate >
UnspecifiedRange	lagoon::until (Range range, Predicate predicate)
	Adapts the range to end when a predicate is satisfied.

---

Detailed Description

Lagoon provides an extensive set of utilities for tasks like range transformation, filtering, sorting, searching, etc. which make writing complex range manipulating algorithms easier and more straightforward.

---

Function Documentation

template<typename ValueType , class... Ranges>

UnspecifiedRange<ValueType> lagoon::chain

(

const Ranges &...

ranges

)

Chains the ranges into a single range with a common ValueType.

Returns a single range that contains a sequence of elements from the provided ranges. The elements in the individual ranges must be convertible to ValueType. The chained ranges may be of different types.

Template Parameters:

ValueType	the common type to be used for the elements of the chained ranges
Ranges	the pack of range types to be chained

Parameters:

ranges

the pack of ranges to be chained

template<typename Interface , class... Ranges>

UnspecifiedRange<shared<Interface> > lagoon::chain_mo

(

const Ranges &...

ranges

)

Chains the ranges into a single range with a common Interface.

Returns a single range that contains a sequence of shared meta-objects from the provided ranges. The elements in the individual ranges must have the specified Interface.

Template Parameters:

Interface	the common meta-object iterface to be used for the elements of the chained ranges
Ranges	the pack of range types to be chained

Parameters:

ranges

the pack of ranges to be chained

template<class Range , typename Predicate >

bool lagoon::contains	(	Range	range,
		Predicate	predicate
	)

Searches a range for an element satisfying a predicate.

Traverses a range checking the result of a predicate on each element. Stops at the first element satisfying the predicate and returns true. If no such elements exists in the range returns false.

Parameters:

range	the range to be searched
predicate	the predicate to be used on each element of the range

Examples:

lagoon/example/various_02.cpp.

template<class Interface , class Range >

UnspecifiedRange<Interface> lagoon::extract

(

const Range &

metaobjects

)

Extracts only meta-objects with a particular interface.

Adapts the range so that it contains only meta-objects implementing the desired Interface. The interface of the meta-objects in the resulting range is cast to Interface.

Template Parameters:

Interface

the desired interface

Parameters:

metaobjects

the range or shared metaobjects to extract from

template<class Range , typename Predicate >

Range lagoon::find_if	(	Range	range,
		Predicate	predicate
	)

Searches a range for an element satisfying a predicate.

Traverses a range checking the result of a predicate on each element. Stops at the first element satisfying the predicate and returns the resulting range.

Parameters:

range	the range to be searched
predicate	the predicate to be used on each element of the range

Examples:

lagoon/example/std_range_03.cpp.

UnspecifiedRange<shared<meta_named_scoped_object> > lagoon::flatten

(

const shared< meta_scope > &

scope

)

Get a range of all members of a scope including nested members.

This function returns a range of all members, including nested, of the scope passed as argument. No particular order of traversal is to be expected.

Parameters:

scope

the scope to be flattened

Examples:

lagoon/example/for_each_11.cpp.

UnspecifiedRange<shared<meta_named_scoped_object> > lagoon::flatten_in_order

(

const shared< meta_scope > &

scope

)

Get a range of all members of a scope including nested members.

This function returns a range of all members, including nested, of the scope passed as argument. The members are traversed in the same order in which they were registered and nested members of a scope are ordered right after their parent scope.

Parameters:

scope

the scope to be flattened

Examples:

lagoon/example/for_each_12.cpp.

template<typename State , class Range , typename BinaryOp >

State lagoon::fold	(	Range	range,
		State	state,
		BinaryOp	op
	)

Accumulating the results of calling a binary functor on the elements.

Returns the result of successive application of a binary forward operation on the result of previous invocations and every element in the range.

Parameters:

range	the range to be folded
state	the initial state used in the first invocation
op	the functor to be called on each element of the range

References Range< Element >::empty(), Range< Element >::front(), and Range< Element >::step_front().

template<typename State , class Range , typename BinaryOp >

State& lagoon::fold_ref	(	Range	range,
		State &	state_ref,
		BinaryOp	op
	)

Accumulating the results of calling a binary functor on the elements.

Returns the result of successive application of a binary forward operation on the result of previous invocations and every element in the range.

Parameters:

range	the range to be folded
state_ref	reference to the state variable gradually modified by op
op	the functor to be called on each element of the range

Examples:

lagoon/example/fold_01.cpp.

References Range< Element >::empty(), Range< Element >::front(), and Range< Element >::step_front().

template<typename State , class Range , typename InitialOp , typename DefaultOp , typename FinalOp >

State& lagoon::fold_ref	(	Range	range,
		State &	state_ref,
		InitialOp	initial,
		DefaultOp	op,
		FinalOp	final
	)

Accumulating the results of calling a binary functor on the elements.

Returns the result of successive application of a binary forward operation on the result of previous invocations and every element in the range. This version uses three different binary functors; one for the first element, one for the last element and one for the remaining elements. If the range has only one element the initial functor is called.

Parameters:

range	the range to be folded
state_ref	reference to the state variable gradually modified by op
initial	the functor to be called on the first element of the range
op	the functor to be called on each element of the range except the first and the last
final	the functor to be called on the last element of the range

References Range< Element >::empty(), Range< Element >::front(), and Range< Element >::step_front().

template<class Range , typename Functor >

Functor lagoon::for_each	(	Range	range,
		Functor	func
	)

Executes an unary functor on each element of a range.

This function calls the func on each element of the range passed as the first argument

Parameters:

range	the range to be traversed
func	the functor to be called on each element of the range

Examples:

lagoon/example/for_each_01.cpp, lagoon/example/for_each_02.cpp, lagoon/example/for_each_03.cpp, lagoon/example/for_each_04.cpp, lagoon/example/for_each_05.cpp, lagoon/example/for_each_06.cpp, lagoon/example/for_each_07.cpp, lagoon/example/for_each_08.cpp, lagoon/example/for_each_09.cpp, lagoon/example/for_each_10.cpp, lagoon/example/for_each_11.cpp, lagoon/example/for_each_12.cpp, and lagoon/example/std_range_01.cpp.

References Range< Element >::empty(), Range< Element >::front(), and Range< Element >::step_front().

template<class Range >

UnspecifiedRange lagoon::limit	(	Range	range,
		size_t	count
	)

Limits the range to contain maximum of n elements.

Adapts the range so that it contains maximally count elements or less if the adapted range is shorter

Parameters:

range	the range to be limited
count	the upper limit of the count of elements

Examples:

lagoon/example/for_each_05.cpp.

template<class Range >

UnspecifiedRange lagoon::link

(

const std::initializer_list< Range > &

ranges

)

Links the homogenous ranges into a single range.

Returns a single range that contains a sequence of elements from the provided ranges. The ranges must have the same type.

Template Parameters:

Range

the type the of ranges to be linked

Parameters:

ranges

the list of ranges to be linked

Examples:

lagoon/example/for_each_10.cpp.

template<class Range >

StdRange lagoon::make_std_range

(

Range

range

)

Adapts a Lagoon's range to have a begin() and end() functions.

This function transforms the interface of a Lagoon's range adding two member functions begin() and end() returning standard const input iterators usable by standard algorithms.

Parameters:

range

the range to be adapted

Examples:

lagoon/example/std_range_01.cpp, lagoon/example/std_range_02.cpp, lagoon/example/std_range_03.cpp, and lagoon/example/std_range_04.cpp.

template<class Range >

Range lagoon::offset	(	Range	range,
		size_t	amount
	)		[inline]

Offsets the beginning of the range by N elements.

Adapts the range so that the front is moved by count elements or less if the adapted range is shorter. In the latter case the resulting range will be empty.

Parameters:

range	the range to be offset
amount	the numer of elements to offset the range by

Examples:

lagoon/example/for_each_05.cpp.

template<class Range , typename Predicate >

UnspecifiedRange lagoon::only_if	(	Range	range,
		Predicate	predicate
	)

Adapts the range to contain only elements satisfying a predicate.

Traverses a range checking the result of a predicate on each element. Skips the elements not satisfying the predicate.

Parameters:

range	the range to be searched
predicate	the predicate to be used to filter the range

Examples:

lagoon/example/for_each_03.cpp, lagoon/example/for_each_04.cpp, lagoon/example/for_each_06.cpp, and lagoon/example/std_range_04.cpp.

template<class Range , typename SortProc >

UnspecifiedRange lagoon::sort	(	Range	range,
		SortProc	sort_proc
	)

Sorts the elements in the range by using a strict weak ordering proc.

Returns a range containing the elements of the original range sorted by the binary strict weak ordering functor.

Parameters:

range	the range to be sorted
sort_proc	the functor sorting the elements

Examples:

lagoon/example/for_each_07.cpp, and lagoon/example/std_range_01.cpp.

template<class Range , typename Transform >

UnspecifiedRange lagoon::transform	(	Range	range,
		Transform	transf
	)

Transforms the elements in the range by a functor.

Returns a range containing the elements of the original range transformed by the unary functor.

Parameters:

range	the range to be transformed
transf	the functor transforming the elements

Examples:

lagoon/example/for_each_06.cpp, and lagoon/example/std_range_04.cpp.

template<class Range , typename Predicate >

UnspecifiedRange lagoon::until	(	Range	range,
		Predicate	predicate
	)

Adapts the range to end when a predicate is satisfied.

Template Parameters:

Range	The type of the underlying range
Predicate	The type of the terminating predicate

Parameters:

range	the underlying range
predicate	the predicate whose satisfying stops the traversal

Examples:

lagoon/example/for_each_08.cpp.