Basic sparse set implementation. More...

#include <sparse_set.hpp>

Public Types
using	allocator_type = typename alloc_traits::allocator_type
	Allocator type.

using	entity_type = Entity
	Underlying entity identifier.

using	size_type = std::size_t
	Unsigned integer type.

using	pointer = alloc_const_pointer
	Pointer type to contained entities.

using	iterator = sparse_set_iterator
	Random access iterator type.

using	reverse_iterator = std::reverse_iterator< iterator >
	Reverse iterator type.

Public Member Functions
	basic_sparse_set (deletion_policy pol, const allocator_type &alloc={})
	Constructs an empty container with the given policy and allocator. More...

	basic_sparse_set (const allocator_type &alloc={})
	Constructs an empty container with the given allocator. More...

	basic_sparse_set (basic_sparse_set &&other)
	Move constructor. More...

virtual	~basic_sparse_set ()
	Default destructor.

basic_sparse_set &	operator= (basic_sparse_set &&other)
	Move assignment operator. More...

deletion_policy	policy () const
	Returns the deletion policy of a sparse set. More...

size_type	slot () const
	Returns the next slot available for insertion. More...

void	reserve (const size_type cap)
	Increases the capacity of a sparse set. More...

size_type	capacity () const
	Returns the number of elements that a sparse set has currently allocated space for. More...

void	shrink_to_fit ()
	Requests the removal of unused capacity.

size_type	extent () const
	Returns the extent of a sparse set. More...

size_type	size () const
	Returns the number of elements in a sparse set. More...

bool	empty () const
	Checks whether a sparse set is empty. More...

pointer	data () const
	Direct access to the internal packed array. More...

iterator	begin () const
	Returns an iterator to the beginning. More...

iterator	end () const
	Returns an iterator to the end. More...

reverse_iterator	rbegin () const
	Returns a reverse iterator to the beginning. More...

reverse_iterator	rend () const
	Returns a reverse iterator to the end. More...

iterator	find (const entity_type entt) const
	Finds an entity. More...

bool	contains (const entity_type entt) const
	Checks if a sparse set contains an entity. More...

size_type	index (const entity_type entt) const
	Returns the position of an entity in a sparse set. More...

entity_type	at (const size_type pos) const
	Returns the entity at specified location, with bounds checking. More...

entity_type	operator[] (const size_type pos) const
	Returns the entity at specified location, without bounds checking. More...

size_type	emplace_back (const entity_type entt)
	Appends an entity to a sparse set. More...

size_type	emplace (const entity_type entt)
	Assigns an entity to a sparse set. More...

template<typename It >
void	insert (It first, It last)
	Assigns one or more entities to a sparse set. More...

void	erase (const entity_type entt, void *ud=nullptr)
	Erases an entity from a sparse set. More...

template<typename It >
void	erase (It first, It last, void *ud=nullptr)
	Erases entities from a set. More...

bool	remove (const entity_type entt, void *ud=nullptr)
	Removes an entity from a sparse set if it exists. More...

template<typename It >
size_type	remove (It first, It last, void *ud=nullptr)
	Removes entities from a sparse set if they exist. More...

void	compact ()
	Removes all tombstones from the packed array of a sparse set.

void	swap (const entity_type lhs, const entity_type rhs)
	Swaps two entities in the internal packed array. More...

template<typename Compare , typename Sort = std_sort, typename... Args>
void	sort_n (const size_type length, Compare compare, Sort algo=Sort{}, Args &&... args)
	Sort the first count elements according to the given comparison function. More...

template<typename Compare , typename Sort = std_sort, typename... Args>
void	sort (Compare compare, Sort algo=Sort{}, Args &&... args)
	Sort all elements according to the given comparison function. More...

void	respect (const basic_sparse_set &other)
	Sort entities according to their order in another sparse set. More...

void	clear (void *ud=nullptr)
	Clears a sparse set. More...

Protected Member Functions
virtual void	swap_at ([[maybe_unused]] const std::size_t lhs, [[maybe_unused]] const std::size_t rhs)
	Swaps two entities in the internal packed array. More...

virtual void	move_and_pop ([[maybe_unused]] const std::size_t from, [[maybe_unused]] const std::size_t to)
	Moves an entity in the internal packed array. More...

virtual void	swap_and_pop (const Entity entt, [[maybe_unused]] void *ud)
	Attempts to erase an entity from the internal packed array. More...

virtual void	in_place_pop (const Entity entt, [[maybe_unused]] void *ud)
	Attempts to erase an entity from the internal packed array. More...

Detailed Description

template<typename Entity, typename Allocator>
class entt::basic_sparse_set< Entity, Allocator >

Basic sparse set implementation.

Sparse set or packed array or whatever is the name users give it.
Two arrays: an external one and an internal one; a sparse one and a packed one; one used for direct access through contiguous memory, the other one used to get the data through an extra level of indirection.
This is largely used by the registry to offer users the fastest access ever to the components. Views and groups in general are almost entirely designed around sparse sets.

This type of data structure is widely documented in the literature and on the web. This is nothing more than a customized implementation suitable for the purpose of the framework.

Note: Internal data structures arrange elements to maximize performance. There are no guarantees that entities are returned in the insertion order when iterate a sparse set. Do not make assumption on the order in any case.

Template Parameters

Entity	A valid entity type (see entt_traits for more details).
Allocator	Type of allocator used to manage memory and elements.

Definition at line 53 of file sparse_set.hpp.

Constructor & Destructor Documentation

◆ basic_sparse_set() [1/3]

template<typename Entity , typename Allocator >

entt::basic_sparse_set< Entity, Allocator >::basic_sparse_set	(	deletion_policy	pol,
		const allocator_type &	alloc = `{}`
	)

inlineexplicit

Constructs an empty container with the given policy and allocator.

Parameters

pol	Type of deletion policy.
alloc	Allocator to use (possibly default-constructed).

Definition at line 295 of file sparse_set.hpp.

◆ basic_sparse_set() [2/3]

template<typename Entity , typename Allocator >

entt::basic_sparse_set< Entity, Allocator >::basic_sparse_set ( const allocator_type & alloc = {} )

inlineexplicit

Constructs an empty container with the given allocator.

Parameters

alloc Allocator to use (possibly default-constructed).

Definition at line 311 of file sparse_set.hpp.

◆ basic_sparse_set() [3/3]

template<typename Entity , typename Allocator >

entt::basic_sparse_set< Entity, Allocator >::basic_sparse_set ( basic_sparse_set< Entity, Allocator > && other )

inline

Move constructor.

Parameters

other The instance to move from.

Definition at line 319 of file sparse_set.hpp.

Member Function Documentation

◆ at()

template<typename Entity , typename Allocator >

entity_type entt::basic_sparse_set< Entity, Allocator >::at ( const size_type pos ) const

inline

Returns the entity at specified location, with bounds checking.

Parameters

pos	The position for which to return the entity.

Returns: The entity at specified location if any, a null entity otherwise.

Definition at line 544 of file sparse_set.hpp.

◆ begin()

template<typename Entity , typename Allocator >

iterator entt::basic_sparse_set< Entity, Allocator >::begin ( ) const

inline

Returns an iterator to the beginning.

The returned iterator points to the first entity of the internal packed array. If the sparse set is empty, the returned iterator will be equal to end().

Returns: An iterator to the first entity of the internal packed array.

Definition at line 456 of file sparse_set.hpp.

◆ capacity()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::capacity ( ) const

inline

Returns the number of elements that a sparse set has currently allocated space for.

Returns: Capacity of the sparse set.

Definition at line 392 of file sparse_set.hpp.

◆ clear()

template<typename Entity , typename Allocator >

void entt::basic_sparse_set< Entity, Allocator >::clear ( void * ud = nullptr )

inline

Clears a sparse set.

Parameters

ud	Optional user data that are forwarded as-is to derived classes.

Definition at line 843 of file sparse_set.hpp.

◆ contains()

template<typename Entity , typename Allocator >

bool entt::basic_sparse_set< Entity, Allocator >::contains ( const entity_type entt ) const

inline

Checks if a sparse set contains an entity.

Parameters

entt	A valid entity identifier.

Returns: True if the sparse set contains the entity, false otherwise.

Definition at line 517 of file sparse_set.hpp.

◆ data()

template<typename Entity , typename Allocator >

pointer entt::basic_sparse_set< Entity, Allocator >::data ( ) const

inline

Direct access to the internal packed array.

Returns: A pointer to the internal packed array.

Definition at line 443 of file sparse_set.hpp.

◆ emplace()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::emplace ( const entity_type entt )

inline

Assigns an entity to a sparse set.

Warning: Attempting to assign an entity that already belongs to the sparse set results in undefined behavior.

Parameters

entt	A valid entity identifier.

Returns: The slot used for insertion.

Definition at line 591 of file sparse_set.hpp.

◆ emplace_back()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::emplace_back ( const entity_type entt )

inline

Appends an entity to a sparse set.

Warning: Attempting to assign an entity that already belongs to the sparse set results in undefined behavior.

Parameters

entt	A valid entity identifier.

Returns: The slot used for insertion.

Definition at line 568 of file sparse_set.hpp.

◆ empty()

template<typename Entity , typename Allocator >

bool entt::basic_sparse_set< Entity, Allocator >::empty ( ) const

inline

Checks whether a sparse set is empty.

Returns: True if the sparse set is empty, false otherwise.

Definition at line 435 of file sparse_set.hpp.

◆ end()

template<typename Entity , typename Allocator >

iterator entt::basic_sparse_set< Entity, Allocator >::end ( ) const

inline

Returns an iterator to the end.

The returned iterator points to the element following the last entity in the internal packed array. Attempting to dereference the returned iterator results in undefined behavior.

Returns: An iterator to the element following the last entity of the internal packed array.

Definition at line 470 of file sparse_set.hpp.

◆ erase() [1/2]

template<typename Entity , typename Allocator >

void entt::basic_sparse_set< Entity, Allocator >::erase	(	const entity_type	entt,
		void *	ud = `nullptr`
	)

inline

Erases an entity from a sparse set.

Warning: Attempting to erase an entity that doesn't belong to the sparse set results in undefined behavior.

Parameters

entt	A valid entity identifier.
ud	Optional user data that are forwarded as-is to derived classes.

Definition at line 636 of file sparse_set.hpp.

◆ erase() [2/2]

template<typename Entity , typename Allocator >

template<typename It >

void entt::basic_sparse_set< Entity, Allocator >::erase	(	It	first,
		It	last,
		void *	ud = `nullptr`
	)

inline

Erases entities from a set.

See also: erase

Template Parameters

It	Type of input iterator.

Parameters

first	An iterator to the first element of the range of entities.
last	An iterator past the last element of the range of entities.
ud	Optional user data that are forwarded as-is to derived classes.

Definition at line 652 of file sparse_set.hpp.

◆ extent()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::extent ( ) const

inline

Returns the extent of a sparse set.

The extent of a sparse set is also the size of the internal sparse array. There is no guarantee that the internal packed array has the same size. Usually the size of the internal sparse array is equal or greater than the one of the internal packed array.

Returns: Extent of the sparse set.

Definition at line 413 of file sparse_set.hpp.

◆ find()

template<typename Entity , typename Allocator >

iterator entt::basic_sparse_set< Entity, Allocator >::find ( const entity_type entt ) const

inline

Finds an entity.

Parameters

entt	A valid entity identifier.

Returns: An iterator to the given entity if it's found, past the end iterator otherwise.

Definition at line 508 of file sparse_set.hpp.

◆ in_place_pop()

template<typename Entity , typename Allocator >

virtual void entt::basic_sparse_set< Entity, Allocator >::in_place_pop	(	const Entity	entt,
		[[maybe_unused] ] void *	ud
	)

inlineprotectedvirtual

Attempts to erase an entity from the internal packed array.

Parameters

entt	A valid entity identifier.
ud	Optional user data that are forwarded as-is to derived classes.

Definition at line 266 of file sparse_set.hpp.

◆ index()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::index ( const entity_type entt ) const

inline

Returns the position of an entity in a sparse set.

Warning: Attempting to get the position of an entity that doesn't belong to the sparse set results in undefined behavior.

Parameters

entt	A valid entity identifier.

Returns: The position of the entity in the sparse set.

Definition at line 534 of file sparse_set.hpp.

◆ insert()

template<typename Entity , typename Allocator >

template<typename It >

void entt::basic_sparse_set< Entity, Allocator >::insert	(	It	first,
		It	last
	)

inline

Assigns one or more entities to a sparse set.

Warning: Attempting to assign an entity that already belongs to the sparse set results in undefined behavior.

Template Parameters

It	Type of input iterator.

Parameters

first	An iterator to the first element of the range of entities.
last	An iterator past the last element of the range of entities.

Definition at line 615 of file sparse_set.hpp.

◆ move_and_pop()

template<typename Entity , typename Allocator >

virtual void entt::basic_sparse_set< Entity, Allocator >::move_and_pop	(	[[maybe_unused] ] const std::size_t	from,
		[[maybe_unused] ] const std::size_t	to
	)

inlineprotectedvirtual

Moves an entity in the internal packed array.

Parameters

from	A valid position of an entity within storage.
to	A valid position of an entity within storage.

Definition at line 240 of file sparse_set.hpp.

◆ operator=()

template<typename Entity , typename Allocator >

basic_sparse_set& entt::basic_sparse_set< Entity, Allocator >::operator= ( basic_sparse_set< Entity, Allocator > && other )

inline

Move assignment operator.

Parameters

other The instance to move from.

Returns: This sparse set.

Definition at line 341 of file sparse_set.hpp.

◆ operator[]()

template<typename Entity , typename Allocator >

entity_type entt::basic_sparse_set< Entity, Allocator >::operator[] ( const size_type pos ) const

inline

Returns the entity at specified location, without bounds checking.

Parameters

pos	The position for which to return the entity.

Returns: The entity at specified location.

Definition at line 553 of file sparse_set.hpp.

◆ policy()

template<typename Entity , typename Allocator >

deletion_policy entt::basic_sparse_set< Entity, Allocator >::policy ( ) const

inline

Returns the deletion policy of a sparse set.

Returns: The deletion policy of the sparse set.

Definition at line 361 of file sparse_set.hpp.

◆ rbegin()

template<typename Entity , typename Allocator >

reverse_iterator entt::basic_sparse_set< Entity, Allocator >::rbegin ( ) const

inline

Returns a reverse iterator to the beginning.

The returned iterator points to the first entity of the reversed internal packed array. If the sparse set is empty, the returned iterator will be equal to rend().

Returns: An iterator to the first entity of the reversed internal packed array.

Definition at line 484 of file sparse_set.hpp.

◆ remove() [1/2]

template<typename Entity , typename Allocator >

bool entt::basic_sparse_set< Entity, Allocator >::remove	(	const entity_type	entt,
		void *	ud = `nullptr`
	)

inline

Removes an entity from a sparse set if it exists.

Parameters

entt	A valid entity identifier.
ud	Optional user data that are forwarded as-is to derived classes.

Returns: True if the entity is actually removed, false otherwise.

Definition at line 664 of file sparse_set.hpp.

◆ remove() [2/2]

template<typename Entity , typename Allocator >

template<typename It >

size_type entt::basic_sparse_set< Entity, Allocator >::remove	(	It	first,
		It	last,
		void *	ud = `nullptr`
	)

inline

Removes entities from a sparse set if they exist.

Template Parameters

It	Type of input iterator.

Parameters

first	An iterator to the first element of the range of entities.
last	An iterator past the last element of the range of entities.
ud	Optional user data that are forwarded as-is to derived classes.

Returns: The number of entities actually removed.

Definition at line 677 of file sparse_set.hpp.

◆ rend()

template<typename Entity , typename Allocator >

reverse_iterator entt::basic_sparse_set< Entity, Allocator >::rend ( ) const

inline

Returns a reverse iterator to the end.

The returned iterator points to the element following the last entity in the reversed internal packed array. Attempting to dereference the returned iterator results in undefined behavior.

Returns: An iterator to the element following the last entity of the reversed internal packed array.

Definition at line 498 of file sparse_set.hpp.

◆ reserve()

template<typename Entity , typename Allocator >

void entt::basic_sparse_set< Entity, Allocator >::reserve ( const size_type cap )

inline

Increases the capacity of a sparse set.

If the new capacity is greater than the current capacity, new storage is allocated, otherwise the method does nothing.

Parameters

cap	Desired capacity.

Definition at line 381 of file sparse_set.hpp.

◆ respect()

template<typename Entity , typename Allocator >

void entt::basic_sparse_set< Entity, Allocator >::respect ( const basic_sparse_set< Entity, Allocator > & other )

inline

Sort entities according to their order in another sparse set.

Entities that are part of both the sparse sets are ordered internally according to the order they have in other. All the other entities goes to the end of the list and there are no guarantees on their order.
In other terms, this function can be used to impose the same order on two sets by using one of them as a master and the other one as a slave.

Iterating the sparse set with a couple of iterators returns elements in the expected order after a call to respect. See begin and end for more details.

Parameters

other The sparse sets that imposes the order of the entities.

Definition at line 821 of file sparse_set.hpp.

◆ size()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::size ( ) const

inline

Returns the number of elements in a sparse set.

The number of elements is also the size of the internal packed array. There is no guarantee that the internal sparse array has the same size. Usually the size of the internal sparse array is equal or greater than the one of the internal packed array.

Returns: Number of elements.

Definition at line 427 of file sparse_set.hpp.

◆ slot()

template<typename Entity , typename Allocator >

size_type entt::basic_sparse_set< Entity, Allocator >::slot ( ) const

inline

Returns the next slot available for insertion.

Returns: The next slot available for insertion.

Definition at line 369 of file sparse_set.hpp.

◆ sort()

template<typename Entity , typename Allocator >

template<typename Compare , typename Sort = std_sort, typename... Args>

void entt::basic_sparse_set< Entity, Allocator >::sort	(	Compare	compare,
		Sort	algo = `Sort{}`,
		Args &&...	args
	)

inline

Sort all elements according to the given comparison function.

See also: sort_n

Template Parameters

Compare	Type of comparison function object.
Sort	Type of sort function object.
Args	Types of arguments to forward to the sort function object.

Parameters

compare	A valid comparison function object.
algo	A valid sort function object.
args	Arguments to forward to the sort function object, if any.

Definition at line 802 of file sparse_set.hpp.

◆ sort_n()

template<typename Entity , typename Allocator >

template<typename Compare , typename Sort = std_sort, typename... Args>

void entt::basic_sparse_set< Entity, Allocator >::sort_n	(	const size_type	length,
		Compare	compare,
		Sort	algo = `Sort{}`,
		Args &&...	args
	)

inline

Sort the first count elements according to the given comparison function.

The comparison function object must return true if the first element is less than the second one, false otherwise. The signature of the comparison function should be equivalent to the following:

bool(const Entity, const Entity);

Moreover, the comparison function object shall induce a strict weak ordering on the values.

The sort function object must offer a member function template operator() that accepts three arguments:

An iterator to the first element of the range to sort.
An iterator past the last element of the range to sort.
A comparison function to use to compare the elements.

Template Parameters

Compare	Type of comparison function object.
Sort	Type of sort function object.
Args	Types of arguments to forward to the sort function object.

Parameters

length	Number of elements to sort.
compare	A valid comparison function object.
algo	A valid sort function object.
args	Arguments to forward to the sort function object, if any.

Definition at line 767 of file sparse_set.hpp.

◆ swap()

template<typename Entity , typename Allocator >

void entt::basic_sparse_set< Entity, Allocator >::swap	(	const entity_type	lhs,
		const entity_type	rhs
	)

inline

Swaps two entities in the internal packed array.

For what it's worth, this function affects both the internal sparse array and the internal packed array. Users should not care of that anyway.

Warning: Attempting to swap entities that don't belong to the sparse set results in undefined behavior.

Parameters

lhs	A valid entity identifier.
rhs	A valid entity identifier.

Definition at line 720 of file sparse_set.hpp.

◆ swap_and_pop()

template<typename Entity , typename Allocator >

virtual void entt::basic_sparse_set< Entity, Allocator >::swap_and_pop	(	const Entity	entt,
		[[maybe_unused] ] void *	ud
	)

inlineprotectedvirtual

Attempts to erase an entity from the internal packed array.

Parameters

entt	A valid entity identifier.
ud	Optional user data that are forwarded as-is to derived classes.

Definition at line 247 of file sparse_set.hpp.

◆ swap_at()

template<typename Entity , typename Allocator >

virtual void entt::basic_sparse_set< Entity, Allocator >::swap_at	(	[[maybe_unused] ] const std::size_t	lhs,
		[[maybe_unused] ] const std::size_t	rhs
	)

inlineprotectedvirtual

Swaps two entities in the internal packed array.

Parameters

lhs	A valid position of an entity within storage.
rhs	A valid position of an entity within storage.

Definition at line 233 of file sparse_set.hpp.

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

src/entt/entity/fwd.hpp
src/entt/entity/sparse_set.hpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

template<typename Entity, typename Allocator> class entt::basic_sparse_set< Entity, Allocator >

Constructor & Destructor Documentation

◆ basic_sparse_set() [1/3]

◆ basic_sparse_set() [2/3]

◆ basic_sparse_set() [3/3]

Member Function Documentation

◆ at()

◆ begin()

◆ capacity()

◆ clear()

◆ contains()

◆ data()

◆ emplace()

◆ emplace_back()

◆ empty()

◆ end()

◆ erase() [1/2]

◆ erase() [2/2]

◆ extent()

◆ find()

◆ in_place_pop()

◆ index()

◆ insert()

◆ move_and_pop()

◆ operator=()

◆ operator[]()

◆ policy()

◆ rbegin()

◆ remove() [1/2]

◆ remove() [2/2]

◆ rend()

◆ reserve()

◆ respect()

◆ size()

◆ slot()

◆ sort()

◆ sort_n()

◆ swap()

◆ swap_and_pop()

◆ swap_at()

template<typename Entity, typename Allocator>
class entt::basic_sparse_set< Entity, Allocator >