This API represents a many-to-many relationship between two records through a third record. More...

#include <HasManyThrough.hpp>

Classes
struct	Loader
	Carries the deferred loads, installed by the DataMapper. More...

Public Types
using	ThroughRecord = ThroughRecordOf< ThroughSpec >
	The record type of the "through" side of the relationship.

using	ReferencedRecord = ReferencedRecordT
	The record type of the "many" side of the relationship.

using	ReferencedRecordList = std::vector< std::shared_ptr< ReferencedRecord > >
	The list of records on the "many" side of the relationship.

using	value_type = ReferencedRecord
	Value type for range-based iteration.

using	iterator = ReferencedRecordList::iterator
	Iterator type for the list of records.

using	const_iterator = ReferencedRecordList::const_iterator
	Const iterator type for the list of records.

Public Member Functions
RelationResult< std::reference_wrapper< ReferencedRecordList const > >	All () const
	Retrieves the records, loading them on first access.

RelationResult< std::reference_wrapper< ReferencedRecordList > >	All ()
	Retrieves the records, loading them on first access.

ReferencedRecordList &	Emplace (ReferencedRecordList &&records) noexcept
	Emplaces the given list of records into this relationship.

RelationResult< std::size_t >	Count () const

RelationResult< bool >	IsEmpty () const

ReferencedRecord const &	At (std::size_t index) const
	Retrieves the record at the given index, loading the records on first access.

ReferencedRecord &	At (std::size_t index)
	Retrieves the record at the given index, loading the records on first access.

ReferencedRecord const &	operator[] (std::size_t index) const
	Retrieves the record at the given index, loading the records on first access.

ReferencedRecord &	operator[] (std::size_t index)
	Retrieves the record at the given index, loading the records on first access.

iterator	begin ()

iterator	end ()

const_iterator	begin () const

const_iterator	end () const

std::weak_ordering	operator<=> (HasManyThrough const &other) const noexcept=default
	Default three-way comparison operator.

void	SetAutoLoader (Loader loader) noexcept
	Used internally to configure on-demand loading of the records.

RelationResult< void >	Reload ()
	Loads the records from the database again, forgetting what was loaded or known before.

template<typename Callable >
RelationResult< void >	Each (Callable const &callable)
	Calls `callable` for each record, without holding them all in memory when not loaded yet.

Static Public Attributes
static constexpr auto	OwnerSelector = TheOwnerSelector
	Singles out the join record's foreign key pointing at the record owning this relationship.

static constexpr auto	ReferencedSelector = TheReferencedSelector
	Singles out the join record's foreign key pointing at ReferencedRecord.

Detailed Description

template<typename ReferencedRecordT, typename ThroughSpec, auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>
class Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >

This API represents a many-to-many relationship between two records through a third record.

The join record is named with the Through marker, so that the reader can tell it apart from the referenced record at a glance:

struct Friendship;
struct Human
{
    Field<int, PrimaryKey::AutoAssign> id;
    HasManyThrough<Human, Through<Friendship>> friends;
};

The join record must declare one BelongsTo pointing back at the record owning this relationship, and one pointing at the referenced record. Both are located by matching the relationship type.

When the join record cannot be resolved that way - most notably a self-referential many-to-many, where both of its foreign keys point at the same table - name the two foreign key columns explicitly:

struct Friendship;
struct Human
{
    Field<int, PrimaryKey::AutoAssign> id;
    HasManyThrough<Human, Through<Friendship>, SqlRealName { "a_id" }, SqlRealName { "b_id" }> friends;
};
struct Friendship
{
    Field<int, PrimaryKey::AutoAssign> id;
    BelongsTo<&Human::id, SqlRealName { "a_id" }> a;
    BelongsTo<&Human::id, SqlRealName { "b_id" }> b;
};

Template Parameters

ReferencedRecordT	The record type on the "many" side of the relationship.
ThroughSpec	The join record, wrapped as `Through<T>`. Naming the record bare is deprecated.
TheOwnerSelector	Singles out the join record's foreign key pointing at the owning record.
TheReferencedSelector	Singles out the join record's foreign key pointing at `ReferencedRecordT`.

See also: DataMapper, Field, HasMany, Through, RelationSelector

Definition at line 69 of file HasManyThrough.hpp.

Member Typedef Documentation

◆ ThroughRecord

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::ThroughRecord = ThroughRecordOf<ThroughSpec>

The record type of the "through" side of the relationship.

Definition at line 81 of file HasManyThrough.hpp.

◆ ReferencedRecord

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::ReferencedRecord = ReferencedRecordT

The record type of the "many" side of the relationship.

Definition at line 84 of file HasManyThrough.hpp.

◆ ReferencedRecordList

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::ReferencedRecordList = std::vector<std::shared_ptr<ReferencedRecord> >

The list of records on the "many" side of the relationship.

Definition at line 93 of file HasManyThrough.hpp.

◆ value_type

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::value_type = ReferencedRecord

Value type for range-based iteration.

Definition at line 96 of file HasManyThrough.hpp.

◆ iterator

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::iterator = ReferencedRecordList::iterator

Iterator type for the list of records.

Definition at line 98 of file HasManyThrough.hpp.

◆ const_iterator

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

using Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::const_iterator = ReferencedRecordList::const_iterator

Const iterator type for the list of records.

Definition at line 100 of file HasManyThrough.hpp.

Member Function Documentation

◆ All() [1/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

RelationResult< std::reference_wrapper< ReferencedRecordList const > > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::All ( ) const

inline

Retrieves the records, loading them on first access.

Never throws for unavailable records: the reason comes back as the error instead.

Returns: The records; or RelationError::NotConfigured when there is no loader (a hand-built record, or one read with loadRelations = false), RelationError::Outdated when the default connection string changed since the record was read, RelationError::QueryFailed when the load query failed.

Definition at line 110 of file HasManyThrough.hpp.

Referenced by Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Each().

◆ All() [2/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

RelationResult< std::reference_wrapper< ReferencedRecordList > > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::All ( )

inline

Retrieves the records, loading them on first access.

Never throws for unavailable records: the reason comes back as the error instead.

Returns: The records; or RelationError::NotConfigured when there is no loader (a hand-built record, or one read with loadRelations = false), RelationError::Outdated when the default connection string changed since the record was read, RelationError::QueryFailed when the load query failed.

Definition at line 116 of file HasManyThrough.hpp.

◆ Emplace()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

ReferencedRecordList & Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Emplace ( ReferencedRecordList && records )

inlinenoexcept

Emplaces the given list of records into this relationship.

Definition at line 122 of file HasManyThrough.hpp.

◆ Count()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

RelationResult< std::size_t > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Count ( ) const

inline

Returns: The number of records in this relationship - counted by a query, without loading them, unless they are loaded already - or why it is unavailable (see All()).

Definition at line 132 of file HasManyThrough.hpp.

References Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Loader::count, NotConfigured, and QueryFailed.

Referenced by Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::IsEmpty().

◆ IsEmpty()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

RelationResult< bool > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::IsEmpty ( ) const

inline

Returns: Whether this relationship is empty, or why that is unknown (see All()).

Definition at line 152 of file HasManyThrough.hpp.

References Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Count().

◆ At() [1/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

ReferencedRecord const & Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::At ( std::size_t index ) const

inline

Retrieves the record at the given index, loading the records on first access.

Parameters

index The index of the record to retrieve.

Exceptions

SqlRequireLoadedError	The records are unavailable; All() reports why without throwing.
std::out_of_range	`index` is out of bounds.

Definition at line 162 of file HasManyThrough.hpp.

◆ At() [2/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

ReferencedRecord & Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::At ( std::size_t index )

inline

Retrieves the record at the given index, loading the records on first access.

Parameters

index The index of the record to retrieve.

Exceptions

SqlRequireLoadedError	The records are unavailable; All() reports why without throwing.
std::out_of_range	`index` is out of bounds.

Definition at line 168 of file HasManyThrough.hpp.

◆ operator[]() [1/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

ReferencedRecord const & Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::operator[] ( std::size_t index ) const

inline

Retrieves the record at the given index, loading the records on first access.

Parameters

index The index of the record to retrieve; out of bounds is undefined behaviour.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 177 of file HasManyThrough.hpp.

◆ operator[]() [2/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

ReferencedRecord & Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::operator[] ( std::size_t index )

inline

Retrieves the record at the given index, loading the records on first access.

Parameters

index The index of the record to retrieve; out of bounds is undefined behaviour.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 183 of file HasManyThrough.hpp.

◆ begin() [1/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

iterator Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::begin ( )

inline

Returns an iterator to the beginning of the record list, loading the records on first access.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 190 of file HasManyThrough.hpp.

◆ end() [1/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

iterator Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::end ( )

inline

Returns an iterator to the end of the record list, loading the records on first access.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 197 of file HasManyThrough.hpp.

◆ begin() [2/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

const_iterator Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::begin ( ) const

inline

Returns a const iterator to the beginning of the record list, loading the records on first access.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 204 of file HasManyThrough.hpp.

◆ end() [2/2]

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

const_iterator Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::end ( ) const

inline

Returns a const iterator to the end of the record list, loading the records on first access.

Exceptions

SqlRequireLoadedError The records are unavailable; All() reports why without throwing.

Definition at line 211 of file HasManyThrough.hpp.

◆ SetAutoLoader()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

void Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::SetAutoLoader ( Loader loader )

inlinenoexcept

Used internally to configure on-demand loading of the records.

Definition at line 231 of file HasManyThrough.hpp.

◆ Reload()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

RelationResult< void > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Reload ( )

inline

Loads the records from the database again, forgetting what was loaded or known before.

Returns: Nothing, or why the records are unavailable (see All()).

Definition at line 238 of file HasManyThrough.hpp.

◆ Each()

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

template<typename Callable >

RelationResult< void > Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Each ( Callable const & callable )

inline

Calls callable for each record, without holding them all in memory when not loaded yet.

An exception thrown by callable propagates unchanged.

Parameters

callable Called once per record.

Returns: Nothing, or why the records are unavailable (see All()).

Definition at line 253 of file HasManyThrough.hpp.

References Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::All(), Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::Loader::each, and QueryFailed.

Member Data Documentation

◆ OwnerSelector

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

constexpr auto Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::OwnerSelector = TheOwnerSelector

staticconstexpr

Singles out the join record's foreign key pointing at the record owning this relationship.

Definition at line 87 of file HasManyThrough.hpp.

◆ ReferencedSelector

template<typename ReferencedRecordT , typename ThroughSpec , auto TheOwnerSelector = AutoDetectRelation, auto TheReferencedSelector = AutoDetectRelation>

constexpr auto Lightweight::HasManyThrough< ReferencedRecordT, ThroughSpec, TheOwnerSelector, TheReferencedSelector >::ReferencedSelector = TheReferencedSelector

staticconstexpr

Singles out the join record's foreign key pointing at ReferencedRecord.

Definition at line 90 of file HasManyThrough.hpp.

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

Lightweight/DataMapper/HasManyThrough.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ ThroughRecord

◆ ReferencedRecord

◆ ReferencedRecordList

◆ value_type

◆ iterator

◆ const_iterator

Member Function Documentation

◆ All() [1/2]

◆ All() [2/2]

◆ Emplace()

◆ Count()

◆ IsEmpty()

◆ At() [1/2]

◆ At() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ begin() [1/2]

◆ end() [1/2]

◆ begin() [2/2]

◆ end() [2/2]

◆ SetAutoLoader()

◆ Reload()

◆ Each()

Member Data Documentation

◆ OwnerSelector

◆ ReferencedSelector