sca Namespace Reference

Classes
class	slice_of
	the underlying type returned by slice() representing a subset of a container More...
class	const_slice_of
	const variation of slice_of More...

Functions
template<typename C >
size_t	size (C &&c)
	return an iterable container's size, regardless if it implements a size() method More...
template<typename C >
auto	pointers (C &c)
	copy the addresses of elements in a container to a new container More...
template<typename C >
auto	pointers (const C &c)
template<typename C >
auto	values (C &&c)
	return a container of deep value copies (never pointers) from a container of values or pointers More...
template<typename C >
auto	slice (C &&c, size_t idx, size_t len)
	create a slice_of object from a container which allows iteration over a subset of another container More...
template<typename C >
auto	slice (const C &c, size_t idx, size_t len)
	create a const_slice_of object from a container which allows iteration over a subset of another container More...
template<typename C >
auto	slice (C &c, size_t idx, size_t len)
	create a const_slice_of object from a container which allows iteration over a subset of another container More...
template<typename C >
auto	mslice (C &&c, size_t idx, size_t len)
	create a mutable slice_of object which allows iteration of a subset of another container More...
template<typename C >
auto	mslice (C &c, size_t idx, size_t len)
template<typename C , typename C2 , typename... Cs>
auto	group (C &&c, C2 &&c2, Cs &&... cs)
	assemble a container containing all elements of two or more containers More...
template<typename C >
auto	reverse (C &&c)
	return a container where the order of elements is the reverse of the input container More...
template<typename C , typename F >
auto	sort (C &&c, F &&cmp)
	return a container whose elements are sorted based on a comparison Callable More...
template<typename F , typename C >
auto	filter (F &&f, C &&c)
	return a filtered container of elements More...
template<typename F , typename C , typename... Cs>
auto	map (F &&f, C &&c, Cs &&... cs)
	evaluate function with the elements of containers grouped by index and return a container filled with the results of each function call More...
template<typename F , typename Result , typename C , typename... Cs>
auto	fold (F &&f, Result &&init, C &&c, Cs &&... cs)
	perform a calculation on the elements of containers grouped by index More...
template<typename F , typename C , typename... Cs>
void	each (F &&f, C &&c, Cs &&... cs)
	evaluate function with the elements of containers grouped by index More...
template<typename F , typename C , typename... Cs>
bool	all (F &&f, C &&c, Cs &&... cs)
	evaluate if a function returns true with all the elements of containers grouped by index More...
template<typename F , typename C , typename... Cs>
bool	some (F &&f, C &&c, Cs &&... cs)
	evaluate if a function returns true with at least one of the elements of containers grouped by index More...

Detailed Description

A NOTE ON API DESIGN

As a note, much of the complexity of these templates is caused by more effort being put into usability, rather than implementing minimalist algorithms.

The algorithms defined in the c++ standard library typically deal with iterators rather than containers. Instead, this library's data processing algorithms accept iterable objects/containers as arguments and return iterable containers. This leaves the smallest amount of work for the user and reduces risk of exception throwing bugs. This also helps the user avoid making trivial efficiency mistakes when writing algorithm code.

In c++, vectors typically outperform other container types, so algorithms in this library convert to them internally and return them as the result.

PROVIDED ALGORITHMS

The algorithms in this header library are intended for general usecases and composability (the results of one algorithm can often be used as an argument in another). They are not exhaustive, but should cover the majority of simple data processing usecases.

Algorithms and Objects provided by this header:

• size() - return an iterable container's size, regardless if it implements a size() method
• pointers() - return container of the addresses of elements in another container
• values() - return a container of deep value copies (never pointers) from a container of values or pointers
• slice_of - object capable of iterating a subset of a container
• const_slice_of - const object capable of iterating a subset of a container
• slice() - return a slice_of<T> (potentially const_slice_of<T>) capable of iterating a subset of a container
• mslice() - return an mutable slice_of<T> capable of iterating a mutable subset of a container
• group() - return a container composed of all elements of all argument containers
• reverse() - return a container whose elements are in reverse order of input container
• sort() = return a container whose elements are sorted based on a comparison Callable
• filter() - return a container filled with only elements which return true when applied to a Callable
• map() - return the results of applying all elements of argument containers to a Callable
• fold() - calculate a result after iterating through all elements of argument containers
• each() - apply a Callable to every element of a container
• all() - return true if all elements return true when applied to a Callable
• some() - return true if at least one element returns true when applied to a Callable

Function Documentation

all()

template<typename F , typename C , typename... Cs>

bool sca::all	(	F &&	f,
		C &&	c,
		Cs &&...	cs
	)

evaluate if a function returns true with all the elements of containers grouped by index

Evaluation ends when traversible element in container c has been iterated.

Each container can contain a different value type as long as the value type can be passed to the function.

Parameters

f	a predicate function applied to elements of input containers
c	the first container whose elements will have f applied to
cs	the optional remaining containers whose elements will have f applied to

Returns

true if f returns true for all iterated elements, else false

each()

template<typename F , typename C , typename... Cs>

void sca::each	(	F &&	f,
		C &&	c,
		Cs &&...	cs
	)

evaluate function with the elements of containers grouped by index

Evaluation ends when traversible element in container c has been iterated.

No value is returned from this function, any changes are side effects of executing the function.

Each container can contain a different value type as long as the value type can be passed to the function.

Parameters

f	a function to call
c	the first container
cs...	the remaining containers

filter()

template<typename F , typename C >

auto sca::filter	(	F &&	f,
		C &&	c
	)

return a filtered container of elements

Parameters

f	a predicate function which gets applied to each element of the input container
c	the input container

Returns

a container of only the elements for which applying the predicate returned true

fold()

template<typename F , typename Result , typename C , typename... Cs>

auto sca::fold	(	F &&	f,
		Result &&	init,
		C &&	c,
		Cs &&...	cs
	)

perform a calculation on the elements of containers grouped by index

Evaluation ends when every traversible element in container c has been iterated.

The argument function must accept the current calculated value as its first argument, and the elements of the argument containers stored in the current iteration. The value returned by the function becomes the new current calculated value, which be subsequently passed as an argument to the calculation function in the next iteration. When iteration completes fold() will return the final return value of the calculation function.

Each container can contain a different value type as long as the value type can be passed to the calculation function.

Parameters

f	the calculation function
init	the initial value of the calculation being performed
c	the first container whose elements will be calculated
cs	optional additional containers whose elements will also be calculated

Returns

the final calculated value returned from function f

group()

template<typename C , typename C2 , typename... Cs>

auto sca::group	(	C &&	c,
		C2 &&	c2,
		Cs &&...	cs
	)

assemble a container containing all elements of two or more containers

Parameters

c	the first container whose elements should be grouped together with the others
c2	the second container whose elements should be grouped together with the others
cs	optional, additional containers whose elements should be grouped together with the others

Returns

a container containing all elements of the arguments

map()

template<typename F , typename C , typename... Cs>

auto sca::map	(	F &&	f,
		C &&	c,
		Cs &&...	cs
	)

evaluate function with the elements of containers grouped by index and return a container filled with the results of each function call

Evaluation begins at index 0, and ends when every traversible element in container c has been iterated. It returns an std::vector<T> (where T is the deduced return value of user function f) containing the result of every invocation of user function f.

Each container can contain a different value type as long as the value type can be passed to the function.

Parameters

f	a function to call
c	the first container
cs...	the remaining containers

Returns

a container R of the results from calling f with elements in c and cs...

mslice()

template<typename C >

auto sca::mslice	(	C &&	c,
		size_t	idx,
		size_t	len
	)

create a mutable slice_of object which allows iteration of a subset of another container

This is the mutable reference implementation of the algorithm, returning a slice_of. This can be dangerous when used inline carelessly, as it will be treated as an rvalue by algorithms causing unexpected swaps. Best usage is to explicitly save the result of this method as an lvalue before usage:

auto my_lvalue_slice = sca::mslice(my_container, 0, 13);
auto my_result = sca::map(my_function, my_lvalue_slice));

Parameters

idx	starting index of the range of values
len	length of range represented by slice
c	container to take slice of

Returns

a slice object capable of iterating a given container

pointers()

template<typename C >

auto sca::pointers

(

C &

c

)

copy the addresses of elements in a container to a new container

This a helper mechanism for ensuring all calculations on data are by reference to a specific set of values. This can be used to simplify operations on large sets of data so that downstream calculations like filter() and map() never have to consider reference value categories.

This algorithm also useful when sorting data in-place without modifying the source data's container positions (std::sort()), while still being able to reference the original data within the sorted set. Furthermore, any kind of sort operation when applied to pointers is very fast.

It may be beneficial to apply pointers() to the result of slice(), to only operate on the necessary subset of elements.

Parameters

c	container of elements

Returns

a container of pointers to elements in the argument container

reverse()

template<typename C >

auto sca::reverse

(

C &&

c

)

return a container where the order of elements is the reverse of the input container

Parameters

c	an input container

Returns

a new container with elements reversed from the input container

size()

template<typename C >

size_t sca::size

(

C &&

c

)

return an iterable container's size, regardless if it implements a size() method

Parameters

c	a container

Returns

the size of the container

slice() [1/3]

template<typename C >

auto sca::slice	(	C &&	c,
		size_t	idx,
		size_t	len
	)

create a slice_of object from a container which allows iteration over a subset of another container

This implementation only gets selected when the input container is an rvalue. The slice_of object will keep the original container in memory as long as the slice_of object exists.

Typical usecase is to use auto as the returned variable's type:

auto my_slice = sca::slice(my_container, 0, 13);
auto my_result = sca::map(my_function, my_slice);

Or to use the slice inline:

auto my_result = sca::map(my_function, sca::slice(my_container, 0, 13));

Parameters

idx	starting index of the range of values
len	length of range represented by slice
c	container to take slice of

Returns

a slice object capable of iterating a given container

slice() [2/3]

template<typename C >

auto sca::slice	(	C &	c,
		size_t	idx,
		size_t	len
	)

create a const_slice_of object from a container which allows iteration over a subset of another container

This is the lvalue reference implementation. Must return a const_slice_of in order to prevent inline uses of the slice() from treating the returned object as an rvalue. If a mutable slice_of object is required, call mslice() instead.

slice() [3/3]

template<typename C >

auto sca::slice	(	const C &	c,
		size_t	idx,
		size_t	len
	)

create a const_slice_of object from a container which allows iteration over a subset of another container

This is the const lvalue reference implementation.

some()

template<typename F , typename C , typename... Cs>

bool sca::some	(	F &&	f,
		C &&	c,
		Cs &&...	cs
	)

evaluate if a function returns true with at least one of the elements of containers grouped by index

Evaluation ends when traversible element in container c has been iterated.

Each container can contain a different value type as long as the value type can be passed to the function.

Parameters

f	a predicate function applied to elements of input containers
c	the first container whose elements will have f applied to
cs	the optional remaining containers whose elements will have f applied to

Returns

true if f returns true for at least one iterated element, else false

sort()

template<typename C , typename F >

auto sca::sort	(	C &&	c,
		F &&	cmp
	)

return a container whose elements are sorted based on a comparison Callable

Parameters

c	container whose elements will be copied and sorted in the output
cmp	a function which must accept two elements from the container and return a boolean

Returns

a sorted container of elements

values()

template<typename C >

auto sca::values

(

C &&

c

)

return a container of deep value copies (never pointers) from a container of values or pointers

If input argument is a container of pointers, those pointers are dereferenced before copying.

Useful when operations on the result of a call to sca::pointers() are complete and a copy of pointed values is required. It is also useful when copying an arbitrary container or slice into a vector.

Parameters

c	a container of values or pointers

Returns

a container of value copies