This HasMany<OtherRecord> represents a simple one-to-many relationship between two records. More...

#include <HasMany.hpp>

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

Public Types
using	ReferencedRecord = OtherRecord
	The record type of the "many" side of the relationship.

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

using	value_type = OtherRecord
	Record type of the "many" side of the relationship.

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.

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

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

ReferencedRecordList *	LoadedRecords () noexcept
	Returns the already-loaded records, or `nullptr` when the relation is not loaded.

RelationResult< std::size_t >	Count () const

RelationResult< bool >	IsEmpty () const

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

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

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

OtherRecord &	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

constexpr std::weak_ordering	operator<=> (HasMany const &other) const noexcept=default
	Three-way comparison operator.

constexpr bool	operator== (HasMany const &other) const noexcept=default
	Equality comparison operator.

constexpr bool	operator!= (HasMany const &other) const noexcept=default
	Inequality comparison operator.

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

Static Public Attributes
static constexpr auto	InverseSelector = TheInverseSelector
	Singles out the foreign key of `OtherRecord` that backs this relationship.

Detailed Description

template<typename OtherRecord, auto TheInverseSelector = AutoDetectRelation>
class Lightweight::HasMany< OtherRecord, TheInverseSelector >

This HasMany<OtherRecord> represents a simple one-to-many relationship between two records.

The HasMany<OtherRecord> is a member of the "one" side of the relationship.

OtherRecord must declare a BelongsTo member that points back to this "one" side. That member is located by matching the relationship type, not by its position in either record, so the two relationship members may be declared at any index. Declaring no such BelongsTo is a compile-time error.

When OtherRecord holds more than one foreign key into this record's table - say a meeting that references the same person table both as its organizer and as whoever writes the minutes - the inverse is ambiguous. Name the foreign key column through TheInverseSelector to single one out:

struct Meeting;
struct Human
{
    Field<int, PrimaryKey::AutoAssign> id;
    HasMany<Meeting, SqlRealName { "organizer_id" }> organizedMeetings;
    HasMany<Meeting, SqlRealName { "minute_taker_id" }> minutedMeetings;
};
struct Meeting
{
    Field<int, PrimaryKey::AutoAssign> id;
    BelongsTo<&Human::id, SqlRealName { "organizer_id" }> organizer;
    BelongsTo<&Human::id, SqlRealName { "minute_taker_id" }, SqlNullable::Null> minuteTaker;
};

A meeting with many attendees is a many-to-many instead - see HasManyThrough. The worked example in docs/sql-to-lightweight.md combines both shapes.

Template Parameters

OtherRecord	The record type on the "many" side of the relationship.
TheInverseSelector	Singles out one of several foreign keys, see the RelationSelector concept.

See also: InverseBelongsToIndexOf, RelationSelector; DataMapper, Field, HasManyThrough

Definition at line 66 of file HasMany.hpp.

Member Typedef Documentation

◆ ReferencedRecord

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

using Lightweight::HasMany< OtherRecord, TheInverseSelector >::ReferencedRecord = OtherRecord

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

Definition at line 74 of file HasMany.hpp.

◆ ReferencedRecordList

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

using Lightweight::HasMany< OtherRecord, TheInverseSelector >::ReferencedRecordList = std::vector<std::shared_ptr<OtherRecord> >

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

Definition at line 80 of file HasMany.hpp.

◆ value_type

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

using Lightweight::HasMany< OtherRecord, TheInverseSelector >::value_type = OtherRecord

Record type of the "many" side of the relationship.

Definition at line 83 of file HasMany.hpp.

◆ iterator

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

using Lightweight::HasMany< OtherRecord, TheInverseSelector >::iterator = ReferencedRecordList::iterator

Iterator type for the list of records.

Definition at line 86 of file HasMany.hpp.

◆ const_iterator

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

using Lightweight::HasMany< OtherRecord, TheInverseSelector >::const_iterator = ReferencedRecordList::const_iterator

Const iterator type for the list of records.

Definition at line 89 of file HasMany.hpp.

Member Function Documentation

◆ All() [1/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE auto Lightweight::HasMany< OtherRecord, InverseSelector >::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 285 of file HasMany.hpp.

◆ All() [2/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE auto Lightweight::HasMany< OtherRecord, InverseSelector >::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 278 of file HasMany.hpp.

◆ Each()

template<typename OtherRecord , auto InverseSelector>

template<typename Callable >

RelationResult< void > Lightweight::HasMany< OtherRecord, InverseSelector >::Each ( Callable const & callable )

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

Use this to iterate over all records when the full data set would be too large to keep. 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 293 of file HasMany.hpp.

References QueryFailed.

◆ Emplace()

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE HasMany< OtherRecord, InverseSelector >::ReferencedRecordList & Lightweight::HasMany< OtherRecord, InverseSelector >::Emplace ( ReferencedRecordList && records )

inlinenoexcept

Emplaces the given list of records.

Definition at line 270 of file HasMany.hpp.

◆ LoadedRecords()

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

ReferencedRecordList * Lightweight::HasMany< OtherRecord, TheInverseSelector >::LoadedRecords ( )

inlinenoexcept

Returns the already-loaded records, or nullptr when the relation is not loaded.

Unlike All(), this never runs the on-demand loader: it reports what is present right now, which is what lets the batched relation loading walk one level deeper (With<A, B>()).

Returns: Pointer to the loaded list, or nullptr if the relation was never loaded.

Definition at line 123 of file HasMany.hpp.

◆ Count()

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE RelationResult< std::size_t > Lightweight::HasMany< OtherRecord, InverseSelector >::Count ( ) const

inline

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

Definition at line 310 of file HasMany.hpp.

References NotConfigured, and QueryFailed.

◆ IsEmpty()

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE RelationResult< bool > Lightweight::HasMany< OtherRecord, InverseSelector >::IsEmpty ( ) const

inline

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

Definition at line 330 of file HasMany.hpp.

References Count.

◆ At() [1/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE OtherRecord const & Lightweight::HasMany< OtherRecord, InverseSelector >::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 336 of file HasMany.hpp.

◆ At() [2/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE OtherRecord & Lightweight::HasMany< OtherRecord, InverseSelector >::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 342 of file HasMany.hpp.

◆ operator[]() [1/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE OtherRecord const & Lightweight::HasMany< OtherRecord, InverseSelector >::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 348 of file HasMany.hpp.

◆ operator[]() [2/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE OtherRecord & Lightweight::HasMany< OtherRecord, InverseSelector >::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 354 of file HasMany.hpp.

◆ begin() [1/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE HasMany< OtherRecord, InverseSelector >::iterator Lightweight::HasMany< OtherRecord, InverseSelector >::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 361 of file HasMany.hpp.

References Lightweight::HasMany< OtherRecord, TheInverseSelector >::begin().

Referenced by Lightweight::HasMany< OtherRecord, TheInverseSelector >::begin(), and Lightweight::HasMany< OtherRecord, TheInverseSelector >::begin().

◆ end() [1/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE HasMany< OtherRecord, InverseSelector >::iterator Lightweight::HasMany< OtherRecord, InverseSelector >::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 367 of file HasMany.hpp.

Referenced by Lightweight::HasMany< OtherRecord, TheInverseSelector >::end().

◆ begin() [2/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE HasMany< OtherRecord, InverseSelector >::const_iterator Lightweight::HasMany< OtherRecord, InverseSelector >::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 374 of file HasMany.hpp.

References Lightweight::HasMany< OtherRecord, TheInverseSelector >::begin().

◆ end() [2/2]

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE HasMany< OtherRecord, InverseSelector >::const_iterator Lightweight::HasMany< OtherRecord, InverseSelector >::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 381 of file HasMany.hpp.

References Lightweight::HasMany< OtherRecord, TheInverseSelector >::end().

◆ SetAutoLoader()

template<typename OtherRecord , auto InverseSelector>

LIGHTWEIGHT_FORCE_INLINE void Lightweight::HasMany< OtherRecord, InverseSelector >::SetAutoLoader ( Loader loader )

inlinenoexcept

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

Definition at line 228 of file HasMany.hpp.

Referenced by Lightweight::DataMapper::ConfigureRelationAutoLoading().

Member Data Documentation

◆ InverseSelector

template<typename OtherRecord , auto TheInverseSelector = AutoDetectRelation>

constexpr auto Lightweight::HasMany< OtherRecord, TheInverseSelector >::InverseSelector = TheInverseSelector

staticconstexpr

Singles out the foreign key of OtherRecord that backs this relationship.

Definition at line 77 of file HasMany.hpp.

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

Lightweight/DataMapper/HasMany.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ ReferencedRecord

◆ ReferencedRecordList

◆ value_type

◆ iterator

◆ const_iterator

Member Function Documentation

◆ All() [1/2]

◆ All() [2/2]

◆ Each()

◆ Emplace()

◆ LoadedRecords()

◆ 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()

Member Data Documentation

◆ InverseSelector