rerun::Collection< TElement > Class Template Reference

Generic collection of elements that are roughly contiguous in memory. More...

#include <rerun/collection.hpp>

Public Types
using	value_type = TElement
	Type of the elements in the collection.
template<typename TContainer >
using	Adapter = CollectionAdapter< TElement, std::remove_cv_t< std::remove_reference_t< TContainer > >, std::enable_if_t< true > >
	Type of an adapter given an input container type.

Public Member Functions
	Collection ()
	Creates a new empty collection.
template<typename TContainer , typename = std::enable_if_t< !std::is_same_v<std::remove_reference_t<TContainer>, Collection<TElement>>>>
	Collection (TContainer &&input)
	Construct using a CollectionAdapter for the given input type.
	Collection (const Collection< TElement > &other)
	Copy constructor.
void	operator= (const Collection< TElement > &other)
	Copy assignment.
	Collection (Collection< TElement > &&other)
	Move constructor.
void	operator= (Collection< TElement > &&other)
	Move assignment.
	Collection (std::initializer_list< TElement > data)
	Construct from a initializer list of elements that are compatible with TElement.
void	swap (Collection< TElement > &other)
	Swaps the content of this collection with another.
size_t	size () const
	Returns the number of instances in this collection.
bool	empty () const
	Returns true if the collection is empty.
const TElement *	data () const
	Returns a raw pointer to the underlying data.
const TElement *	begin () const
	TODO(andreas): Return proper iterator.
const TElement *	end () const
	TODO(andreas): Return proper iterator.
const TElement &	operator[] (size_t i) const
	Random read access to the underlying data.
CollectionOwnership	get_ownership () const
	Returns the data ownership of collection.
std::vector< TElement >	to_vector () const &
	Copies the data into a new std::vector.
std::vector< TElement >	to_vector () &&
	Copies the data into a new std::vector.
Collection< uint8_t >	to_uint8 () const
	Reinterpret this collection as a collection of bytes.

Static Public Member Functions
template<typename T >
static Collection< TElement >	borrow (const T *data, size_t num_instances=1)
	Borrows binary compatible data into the collection from a typed pointer.
static Collection	borrow (const void *data, size_t num_instances=1)
	Borrows binary compatible data into the collection from an untyped pointer.
template<typename T >
static Collection	borrow (const std::vector< T > &data)
	Borrows binary compatible data into the collection from a vector.
static Collection< TElement >	take_ownership (std::vector< TElement > &&data)
	Takes ownership of a temporary std::vector, moving it into the collection.
static Collection< TElement >	take_ownership (TElement &&data)
	Takes ownership of a single element, moving it into the collection.
static Collection< TElement >	take_ownership (const TElement &data)
	Takes ownership of a single element, copying it into the collection.

Detailed Description

template<typename TElement>
class rerun::Collection< TElement >

Generic collection of elements that are roughly contiguous in memory.

The most notable feature of the rerun::Collection is that its data may be either owned or borrowed:

• Borrowed: ⚠️ If data is borrowed it must outlive its source ⚠️ (in particular, the pointer to the source mustn't invalidate)
• Owned: Owned data is copied into an internal std::vector

Collections are either filled explicitly using Collection::borrow &Collection::take_ownership or (most commonly in user code) implicitly using the CollectionAdapter trait (see documentation for CollectionAdapter for more information on how data can be adapted).

⚠️ To ensure that passed data is not destroyed, move it into the collection using std::move.

Other than being assignable, collections are generally immutable: there is no mutable data access in order to not violate the contract with the data lender and changes in size are not possible.

Implementation notes:

Does intentionally not implement copy construction since for the owned case this may be expensive. Typically, there should be no need to copy rerun collections, so this more than likely indicates a bug inside the Rerun SDK.

Member Typedef Documentation

value_type

template<typename TElement >

using rerun::Collection< TElement >::value_type = TElement

Type of the elements in the collection.

Note that calling this value_type makes it compatible with the STL.

Adapter

template<typename TElement >

template<typename TContainer >

using rerun::Collection< TElement >::Adapter = CollectionAdapter< TElement, std::remove_cv_t<std::remove_reference_t<TContainer> >, std::enable_if_t<true> >

Type of an adapter given an input container type.

Note that the "container" passed may also be a single element of something. The only thing relevant is that there's an Adapter for it.

Constructor & Destructor Documentation

Collection() [1/2]

template<typename TElement >

rerun::Collection< TElement >::Collection ( const Collection< TElement > &  other )

inline

Copy constructor.

If the data is owned, this will copy the data. If the data is borrowed, this will copy the borrow, meaning there's now (at least) two collections borrowing the same data.

Collection() [2/2]

template<typename TElement >

rerun::Collection< TElement >::Collection ( std::initializer_list< TElement >  data )

inline

Construct from a initializer list of elements that are compatible with TElement.

Takes ownership of the passed elements. If you want to avoid an allocation, you have to manually keep the data on the stack (e.g. as std::array) and construct the collection from this instead.

This is not done as a CollectionAdapter since it tends to cause deduction issues (since there's special rules for overload resolution for initializer lists)

Member Function Documentation

operator=()

template<typename TElement >

void rerun::Collection< TElement >::operator= ( const Collection< TElement > &  other )

inline

Copy assignment.

If the data is owned, this will copy the data. If the data is borrowed, this will copy the borrow, meaning there's now (at least) two collections borrowing the same data.

borrow() [1/3]

template<typename TElement >

template<typename T >

static Collection< TElement > rerun::Collection< TElement >::borrow ( const T *  data, size_t  num_instances = 1  )

inlinestatic

Borrows binary compatible data into the collection from a typed pointer.

Borrowed data must outlive the collection! (If the pointer passed is into an std::vector or similar, this std::vector mustn't be resized.) The passed type must be binary compatible with the collection type.

Since rerun::Collection does not provide write access, data is guaranteed to be unchanged by any function or operation taking on a Collection.

borrow() [2/3]

template<typename TElement >

static Collection rerun::Collection< TElement >::borrow ( const void *  data, size_t  num_instances = 1  )

inlinestatic

Borrows binary compatible data into the collection from an untyped pointer.

This version of borrow that takes a void pointer, omitting any checks.

Borrowed data must outlive the collection! (If the pointer passed is into an std::vector or similar, this std::vector mustn't be resized.)

Since rerun::Collection does not provide write access, data is guaranteed to be unchanged by any function or operation taking on a rerun::Collection.

borrow() [3/3]

template<typename TElement >

template<typename T >

static Collection rerun::Collection< TElement >::borrow ( const std::vector< T > &  data )

inlinestatic

Borrows binary compatible data into the collection from a vector.

Borrowed data must outlive the collection! The referenced vector must not be resized and musn't be temporary.

Since rerun::Collection does not provide write access, data is guaranteed to be unchanged by any function or operation taking on a rerun::Collection.

take_ownership()

template<typename TElement >

static Collection< TElement > rerun::Collection< TElement >::take_ownership ( std::vector< TElement > &&  data )

inlinestatic

Takes ownership of a temporary std::vector, moving it into the collection.

Takes ownership of the data and moves it into the collection.

data()

template<typename TElement >

const TElement * rerun::Collection< TElement >::data ( ) const

inline

Returns a raw pointer to the underlying data.

Do not use this if the data is not continuous in memory! TODO(#4257): So far it always is continuous, but in the future we want to support strides!

The pointer is only valid as long as backing storage is alive which is either until the collection is destroyed the borrowed source is destroyed/moved.

get_ownership()

template<typename TElement >

CollectionOwnership rerun::Collection< TElement >::get_ownership ( ) const

inline

Returns the data ownership of collection.

This is usually only needed for debugging and testing.

to_vector()

template<typename TElement >

std::vector< TElement > rerun::Collection< TElement >::to_vector ( ) &&

inline

Copies the data into a new std::vector.

If possible, this will move the underlying data.

---

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

• rerun/collection.hpp