Core object used to query items and hold the sequence state. More...

#include <query.h>

Public Types
typedef T	item_type
	Type of items to query over. Used for type deduction.

Public Member Functions
	Queryable (std::vector< T > items)
	Construct a new Queryable object from a sequence of items.
	Queryable ()=delete
	Empty constructor.
	Queryable (Queryable &&) noexcept=default
	Move assignment operator.
	Queryable (const Queryable &)=delete
	Copy constructor operator.
Queryable &	operator= (const Queryable &)=delete
	Copy assignment operator.
	operator std::vector< T > () &&
	Implicit cast operator to vector from an rvalue.
	operator std::vector< T > () const &
	Implicit cast operator to vector from an lvalue.
template<typename U, typename AccumulateFn>
U	accumulate (U initial, AccumulateFn accumulate_func) const
	Sums all the projected values of the sequence into a single value.
template<typename ActionFn>
Queryable< T >	action (ActionFn action_func)
	Executes a void action to create side effects.
template<typename Predicate>
bool	all (Predicate predicate) const
	Determines whether all items of a sequence satisfy a condition.
template<typename Predicate>
bool	any (Predicate predicate) const
	Determines whether a sequence contains any items.
template<typename Predicate>
WhenTrue< T >	branch (Predicate predicate)
	Branches the sequence into two based on a condition.
Queryable< T >	difference (std::vector< T > rhs_items)
	Produces the multiset difference of two sequences.
Queryable< T >	distinct ()
	Gets distinct items from a sequence.
bool	empty () const
	Indicates of the sequence is empty.
template<typename Predicate>
std::optional< T >	first_or_default (Predicate predicate)
	Gets the first item of a sequence, or a default value if no item is found.
auto	flatten ()
	Projects each item in the sequence-of-sequences and flattens the resulting sequences into one (i.e. vector<vector<T>> -> vector<T>).
template<typename KeySelector>
Queryable< std::vector< T > >	group_by (KeySelector key_selector)
	Groups the items of a sequence.
Queryable< T >	intersect (std::vector< T > rhs_items)
	Produces the multiset intersection of two sequences.
template<typename U, typename LhsKeySelector, typename RhsKeySelector>
Queryable< std::tuple< T, U > >	join (std::vector< U > rhs_items, LhsKeySelector lhs_key_selector, RhsKeySelector rhs_key_selector)
	Correlates the items of two sequences based on matching keys.
template<typename KeySelector>
auto	keyed_group_by (KeySelector key_selector)
	Groups the items of a sequence by key and produces as a key-group pair sequence.
T	max ()
	Gets the maximum item from the sequence.
template<typename ValueSelector>
T	max (ValueSelector value_selector)
	Gets the maximum item from the sequence based on a selected value.
T	min ()
	Gets the minimum item from the sequence.
template<typename ValueSelector>
T	min (ValueSelector value_selector)
	Gets the minimum item from the sequence based on a selected value.
template<typename ValueSelector>
Queryable< T >	order_by (ValueSelector value_selector, bool descending=false)
	Orders the sequence by the selected value.
Queryable< T >	reverse ()
	Inverts the order of the items in the sequence.
template<typename Selector>
auto	select (Selector selector)
	Projects each item of a sequence into a new form.
Queryable< T >	shuffle ()
	Randomizes / shuffles all the item's order in the sequence.
size_t	size () const
	Gets the size of the sequence.
Queryable< T >	skip (size_t value)
	Bypasses a specified number of items in the sequence and then returns the remaining items.
Queryable< T >	slice (size_t start_index, size_t size, size_t stride=1)
	Gets a slice of the sequence.
Queryable< T >	sort ()
	Sorts the items in the sequence.
Queryable< T >	take (size_t value)
	Takes a specified number of contiguous items from the start of a sequence.
Queryable< T >	take_random (size_t value)
	Takes the specified number of items from the sequence at random places.
Queryable< T >	trim (size_t size)
	Trim from the back of the sequence.
template<typename KeySelector>
auto	to_multi_value_map (KeySelector key_selector)
	Groups items by a selected key value and puts them into a hash map.
template<typename KeySelector>
auto	to_single_value_map (KeySelector key_selector)
	Groups items by selected key value, takes the first item of every group, and puts them into a hash map.
std::set< T >	to_set ()
	Gets the sequence as a set.
std::vector< T >	to_vector ()
	Gets the sequence as a vector.
Queryable< T >	unionize (std::vector< T > rhs_items)
	Unions the left hand and right hand side sequences.
template<typename Predicate>
Queryable< T >	where (Predicate predicate)
	Selects items in the sequence that satisfy the predicate / conditional.
template<typename U>
Queryable< std::tuple< T, U > >	zip (std::vector< U > rhs_items, bool truncate=false)
	Produces a sequence of tuples with items from the two specified sequences.
template<typename U>
Queryable< std::tuple< T, U > >	zip (std::initializer_list< U > rhs_items, bool truncate=false)
	Produces a sequence of tuples with items from the two specified sequences.

Friends
bool	operator== (const Queryable< T > &lhs, const std::vector< T > &rhs)
	Equals overload operator for Queryable<T> against a std::vector<T>.
bool	operator== (const Queryable< T > &lhs, const Queryable< T > &rhs)
	Equals overload operator.

Detailed Description

template<typename T>
class fcpp::Queryable< T >

Core object used to query items and hold the sequence state.

Any operation performed from Queryable<T> will be moved into the new instance of Queryable<T>. This means that any reference to the previous instance of Queryable<T> may have unexpected behavior dependent on the operation performed and memory semantics of the object under query.

The nomenclature used in the documentation is as follows:

Sequence refers to an ordered collection that can contain duplicates.
Item refers to an object in a sequence. It doesn't have any inherit properties.
Key refers to an object that has equality.
Value refers to an object that has comparison. It the context of hash tables, it refers to the value part of the key-value pair.

Remarks: Note that not all methods are type dependent and will not always be valid. For example the max method will not work on items that don't have comparability. This will show as an error at compile time though.

In terms of memory semantics, if a signature takes by value and not reference, it is because it makes modifications to the value and doesn't want to cause side effects. To prevent a copy of a single use variable, it must be moved.

Lambdas can be passed with arguments by reference or value depending on the caller's preference. Pass by reference may be the case if the object is large. [](auto x) { return x.y; } // Fundamental type [](auto& x) { return x.y; } // Larger composite type

Template Parameters

T	Type of items to query over.

Constructor & Destructor Documentation

◆ Queryable() [1/4]

template<typename T>

fcpp::Queryable< T >::Queryable ( std::vector< T > items )

explicit

Construct a new Queryable object from a sequence of items.

Parameters

items Sequence of items to query over.

◆ Queryable() [2/4]

template<typename T>

fcpp::Queryable< T >::Queryable ( )

delete

Empty constructor.

Remarks: Removed since no-op state is unusable.

◆ Queryable() [3/4]

template<typename T>

fcpp::Queryable< T >::Queryable ( Queryable< T > && )

defaultnoexcept

Move assignment operator.

Remarks: Allowed since state will be stable as it isn't shared amongst multiple copies.

◆ Queryable() [4/4]

template<typename T>

fcpp::Queryable< T >::Queryable ( const Queryable< T > & )

delete

Copy constructor operator.

Remarks: Not allowed since state will not be stable as multiple Queryables are moving items.

Member Function Documentation

◆ accumulate()

template<typename T>

template<typename U, typename AccumulateFn>

U fcpp::Queryable< T >::accumulate	(	U	initial,
		AccumulateFn	accumulate_func ) const

Sums all the projected values of the sequence into a single value.

Template Parameters

U	Accumulating value type.
AccumulateFn	std::function<U(U, T)> Transform function type.

Parameters

initial	Value to start with before iterating sequence.
accumulate_func	Transform function to apply to each item.

Returns: U The final accumulated value.

◆ action()

template<typename T>

template<typename ActionFn>

Queryable< T > fcpp::Queryable< T >::action ( ActionFn action_func )

Executes a void action to create side effects.

Parameters

action_func Void function to apply to each item.

Returns: Queryable<T>

◆ all()

template<typename T>

template<typename Predicate>

bool fcpp::Queryable< T >::all ( Predicate predicate ) const

Determines whether all items of a sequence satisfy a condition.

Parameters

predicate Function to test each item for a condition.

Returns: true if all items satisfy the predicate.; false if one of the items doesn't satisfy the predicate.

◆ any()

template<typename T>

template<typename Predicate>

bool fcpp::Queryable< T >::any ( Predicate predicate ) const

Determines whether a sequence contains any items.

Parameters

predicate Function to test each item for a condition.

Returns: true if all of the items satisfy the predicate.; false if none of the items satisfy the predicate.

◆ branch()

template<typename T>

template<typename Predicate>

WhenTrue< T > fcpp::Queryable< T >::branch ( Predicate predicate )

Branches the sequence into two based on a condition.

Parameters

predicate Function to test each item for a condition.

Returns: WhenTrue<T> True / if block query for items that evaluated to true.

◆ difference()

template<typename T>

Queryable< T > fcpp::Queryable< T >::difference ( std::vector< T > rhs_items )

Produces the multiset difference of two sequences.

Each right hand side item cancels out at most one equivalent left hand side item. Neither sequence needs to be sorted.

Parameters

rhs_items Right hand side sequence.

Returns: Queryable<T> Left hand side items not cancelled out, in their original order.

◆ distinct()

template<typename T>

Queryable< T > fcpp::Queryable< T >::distinct ( )

Gets distinct items from a sequence.

Returns: Queryable<T> Distinct items in sorted order.

◆ empty()

template<typename T>

bool fcpp::Queryable< T >::empty ( ) const

nodiscard

Indicates of the sequence is empty.

Returns: true if the sequence is empty.; false if the sequence is populated.

◆ first_or_default()

template<typename T>

template<typename Predicate>

std::optional< T > fcpp::Queryable< T >::first_or_default ( Predicate predicate )

Gets the first item of a sequence, or a default value if no item is found.

Parameters

predicate Function to test each item for a condition.

Returns: std::optional<T> Either the satisfying item or the not found item of std::nullopt

◆ flatten()

template<typename T>

auto fcpp::Queryable< T >::flatten ( )

Projects each item in the sequence-of-sequences and flattens the resulting sequences into one (i.e. vector<vector<T>> -> vector<T>).

Returns: Queryable<U = std::vector<T>>

◆ group_by()

template<typename T>

template<typename KeySelector>

Queryable< std::vector< T > > fcpp::Queryable< T >::group_by ( KeySelector key_selector )

Groups the items of a sequence.

Template Parameters

KeySelector Transform function type. std::function<K(T)>

Parameters

key_selector Transform to key function to apply to each item.

Returns: Queryable<std::vector<T>>

◆ intersect()

template<typename T>

Queryable< T > fcpp::Queryable< T >::intersect ( std::vector< T > rhs_items )

Produces the multiset intersection of two sequences.

Each right hand side item matches at most one equivalent left hand side item. Neither sequence needs to be sorted.

Parameters

rhs_items Right hand side sequence.

Returns: Queryable<T> Left hand side items that were matched, in their original order.

◆ join()

template<typename T>

template<typename U, typename LhsKeySelector, typename RhsKeySelector>

Queryable< std::tuple< T, U > > fcpp::Queryable< T >::join	(	std::vector< U >	rhs_items,
		LhsKeySelector	lhs_key_selector,
		RhsKeySelector	rhs_key_selector )

Correlates the items of two sequences based on matching keys.

Template Parameters

U	Type of the right hand side sequence.
LhsKeySelector	Transform to key function type. std::function<K(T)>
RhsKeySelector	Transform to key function type. std::function<K(U)>

Parameters

rhs_items	The right hand side sequence to join against.
lhs_key_selector	Transform to key function to apply to each item in this / left hand side sequence.
rhs_key_selector	Transform to key function to apply to each item in the right hand side sequence.

Returns: Queryable<std::tuple<T, U>>

Remarks: An item that matches more than one item on the other side is copied, so this throws std::invalid_argument for non-copyable items.

◆ keyed_group_by()

template<typename T>

template<typename KeySelector>

auto fcpp::Queryable< T >::keyed_group_by ( KeySelector key_selector )

Groups the items of a sequence by key and produces as a key-group pair sequence.

Template Parameters

KeySelector Transform to key function type. std::function<K(T)>

Parameters

key_selector Transform to key function to apply to each item.

Returns: Queryable<std::pair<K, std::vector<T>>>

◆ max() [1/2]

template<typename T>

T fcpp::Queryable< T >::max ( )

Gets the maximum item from the sequence.

Returns: T

◆ max() [2/2]

template<typename T>

template<typename ValueSelector>

T fcpp::Queryable< T >::max ( ValueSelector value_selector )

Gets the maximum item from the sequence based on a selected value.

Template Parameters

ValueSelector Transform to value function type. std::function<V(T)>

Parameters

value_selector Transform to value function to apply to each item.

Returns: T

◆ min() [1/2]

template<typename T>

T fcpp::Queryable< T >::min ( )

Gets the minimum item from the sequence.

Returns: T

◆ min() [2/2]

template<typename T>

template<typename ValueSelector>

T fcpp::Queryable< T >::min ( ValueSelector value_selector )

Gets the minimum item from the sequence based on a selected value.

Template Parameters

ValueSelector Transform to value function type. std::function<V(T)>

Parameters

value_selector Transform to value function to apply to each item.

Returns: T

◆ operator std::vector< T >() [1/2]

template<typename T>

fcpp::Queryable< T >::operator std::vector< T > ( ) &&

inline

Implicit cast operator to vector from an rvalue.

Remarks: Object state will be invalid after this call since items have been moved out.

Returns: std::vector<T>

◆ operator std::vector< T >() [2/2]

template<typename T>

fcpp::Queryable< T >::operator std::vector< T > ( ) const &

inline

Implicit cast operator to vector from an lvalue.

Remarks: Copies the items; requires T to be copy constructible.

Returns: std::vector<T>

◆ operator=()

template<typename T>

Queryable & fcpp::Queryable< T >::operator= ( const Queryable< T > & )

delete

Copy assignment operator.

Remarks: Not allowed since state will not be stable as multiple Queryables are moving items.

Returns: Queryable&

◆ order_by()

template<typename T>

template<typename ValueSelector>

Queryable< T > fcpp::Queryable< T >::order_by	(	ValueSelector	value_selector,
		bool	descending = false )

Orders the sequence by the selected value.

The sort is stable and the value selector is called once per item.

Template Parameters

ValueSelector Transform to value function type. std::function<V(T)>

Parameters

value_selector	Transform to value function to apply to each item.
descending	True if to order by greater to smaller values, otherwise smaller to greater.

Returns: Queryable<T>

◆ reverse()

template<typename T>

Queryable< T > fcpp::Queryable< T >::reverse ( )

Inverts the order of the items in the sequence.

Returns: Queryable<T>

◆ select()

template<typename T>

template<typename Selector>

auto fcpp::Queryable< T >::select ( Selector selector )

Projects each item of a sequence into a new form.

Template Parameters

Selector Transform function type that takes. std::function<V(T)>

Parameters

selector Transform function to apply to each item.

Returns: Queryable<decltype(selector(T))>

◆ shuffle()

template<typename T>

Queryable< T > fcpp::Queryable< T >::shuffle ( )

Randomizes / shuffles all the item's order in the sequence.

Returns: Queryable<T>

◆ size()

template<typename T>

size_t fcpp::Queryable< T >::size ( ) const

nodiscard

Gets the size of the sequence.

Returns: size_t

◆ skip()

template<typename T>

Queryable< T > fcpp::Queryable< T >::skip ( size_t value )

Bypasses a specified number of items in the sequence and then returns the remaining items.

Parameters

value The number of items from the beginning to skip.

Returns: Queryable<T>

◆ slice()

template<typename T>

Queryable< T > fcpp::Queryable< T >::slice	(	size_t	start_index,
		size_t	size,
		size_t	stride = 1 )

Gets a slice of the sequence.

Remarks: See std::slice for exact behavior.

query({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}).slice(2, 3, 2)

.to_vector() == {3, 5, 7};

fcpp::Queryable::slice

Queryable< T > slice(size_t start_index, size_t size, size_t stride=1)

Gets a slice of the sequence.

Definition query.h:1026

fcpp::query

Queryable< T > query(std::vector< T > items)

Queries the sequence of items using a vector.

Definition query.h:663

Parameters

start_index	The initial / starting index into the sequence inclusively.
size	The number of the items to retrieve starting at start_index.
stride	The length of the skip to the next size items. A stride of zero repeats the item at start_index, which requires T to be copyable.

Returns: Queryable<T>

◆ sort()

template<typename T>

Queryable< T > fcpp::Queryable< T >::sort ( )

Sorts the items in the sequence.

Returns: Queryable<T>

◆ take()

template<typename T>

Queryable< T > fcpp::Queryable< T >::take ( size_t value )

Takes a specified number of contiguous items from the start of a sequence.

Parameters

value The number of items from the beginning to keep.

Returns: Queryable<T>

◆ take_random()

template<typename T>

Queryable< T > fcpp::Queryable< T >::take_random ( size_t value )

Takes the specified number of items from the sequence at random places.

Parameters

value The number of items to take randomly.

Returns: Queryable<T>

◆ to_multi_value_map()

template<typename T>

template<typename KeySelector>

auto fcpp::Queryable< T >::to_multi_value_map ( KeySelector key_selector )

Groups items by a selected key value and puts them into a hash map.

Template Parameters

KeySelector Transform to key function type. std::function<K(T)>

Parameters

key_selector Transform to key function to apply to each item.

Returns: std::map<K, std::vector<T>>

◆ to_set()

template<typename T>

std::set< T > fcpp::Queryable< T >::to_set ( )

Gets the sequence as a set.

Returns: std::set<T>

◆ to_single_value_map()

template<typename T>

template<typename KeySelector>

auto fcpp::Queryable< T >::to_single_value_map ( KeySelector key_selector )

Groups items by selected key value, takes the first item of every group, and puts them into a hash map.

Template Parameters

KeySelector Transform to key function type. std::function<K(T)>

Parameters

key_selector Transform to key function to apply to each item.

Returns: std::map<K, T>

◆ to_vector()

template<typename T>

std::vector< T > fcpp::Queryable< T >::to_vector ( )

Gets the sequence as a vector.

Returns: std::vector<T>

◆ trim()

template<typename T>

Queryable< T > fcpp::Queryable< T >::trim ( size_t size )

Trim from the back of the sequence.

Parameters

size	The number of items to trim / erase from the back.

Returns: Queryable<T>

◆ unionize()

template<typename T>

Queryable< T > fcpp::Queryable< T >::unionize ( std::vector< T > rhs_items )

Unions the left hand and right hand side sequences.

Parameters

rhs_items The right hand side sequence to union.

Returns: Queryable<T> Distinct items from both sequences in sorted order.

◆ where()

template<typename T>

template<typename Predicate>

Queryable< T > fcpp::Queryable< T >::where ( Predicate predicate )

Selects items in the sequence that satisfy the predicate / conditional.

Parameters

predicate Function to test each item for a condition.

Returns: Queryable<T>

◆ zip() [1/2]

template<typename T>

template<typename U>

Queryable< std::tuple< T, U > > fcpp::Queryable< T >::zip	(	std::initializer_list< U >	rhs_items,
		bool	truncate = false )

Produces a sequence of tuples with items from the two specified sequences.

Template Parameters

U	Type of the right hand side items.

Parameters

rhs_items	Right hand side items of the produced tuple sequence.
truncate	Truncate the combined sequence by the minimum size of the two. If false and the sizes differ, the shorter side is padded with default values, which throws std::invalid_argument if that type has no default constructor.

Returns: Queryable<std::tuple<T, U>>

◆ zip() [2/2]

template<typename T>

template<typename U>

Queryable< std::tuple< T, U > > fcpp::Queryable< T >::zip	(	std::vector< U >	rhs_items,
		bool	truncate = false )

Produces a sequence of tuples with items from the two specified sequences.

Template Parameters

U	Type of the right hand side items.

Parameters

rhs_items	Right hand side items of the produced tuple sequence.
truncate	Truncate the combined sequence by the minimum size of the two. If false and the sizes differ, the shorter side is padded with default values, which throws std::invalid_argument if that type has no default constructor.

Returns: Queryable<std::tuple<T, U>>

◆ operator== [1/2]

template<typename T>

bool operator==	(	const Queryable< T > &	lhs,
		const Queryable< T > &	rhs )

friend

Equals overload operator.

Parameters

lhs	Left operand Queryable<T> to compare.
rhs	Right operand Queryable<T> to compare.

Returns: true if both sides are equal.; false if both side are not equal.

◆ operator== [2/2]

template<typename T>

bool operator==	(	const Queryable< T > &	lhs,
		const std::vector< T > &	rhs )

friend

Equals overload operator for Queryable<T> against a std::vector<T>.

Remarks: Based off of internal items_ stored inside Queryable<T>.

Parameters

lhs	Left operand Queryable<T> to compare.
rhs	Right operand std::vector<T> to compare.

Returns: true if both sides are equal.; false if both side are not equal.

The documentation for this class was generated from the following file:

/home/runner/work/fluentcpp/fluentcpp/include/fluentcpp/query.h

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Queryable() [1/4]

◆ Queryable() [2/4]

◆ Queryable() [3/4]

◆ Queryable() [4/4]

Member Function Documentation

◆ accumulate()

◆ action()

◆ all()

◆ any()

◆ branch()

◆ difference()

◆ distinct()

◆ empty()

◆ first_or_default()

◆ flatten()

◆ group_by()

◆ intersect()

◆ join()

◆ keyed_group_by()

◆ max() [1/2]

◆ max() [2/2]

◆ min() [1/2]

◆ min() [2/2]

◆ operator std::vector< T >() [1/2]

◆ operator std::vector< T >() [2/2]

◆ operator=()

◆ order_by()

◆ reverse()

◆ select()

◆ shuffle()

◆ size()

◆ skip()

◆ slice()

◆ sort()

◆ take()

◆ take_random()

◆ to_multi_value_map()

◆ to_set()

◆ to_single_value_map()

◆ to_vector()

◆ trim()

◆ unionize()

◆ where()

◆ zip() [1/2]

◆ zip() [2/2]

Friends And Related Symbol Documentation

◆ operator== [1/2]

◆ operator== [2/2]