<<move-only-type>> Provides temporary access to a collection of samples (data and info) from a DataReader. More...

#include <LoanedSamplesImpl.hpp>

Public Types
typedef SampleIterator< T >	iterator
	The iterator type. More...

Public Member Functions
	LoanedSamples ()
	Creates an empty LoanedSamples object. More...

	~LoanedSamples () noexcept
	Automatically returns the loan to the DataReader. More...

value_type	operator[] (size_t index)
	Provides access to the underlying LoanedSample object in array-like syntax. More...

unsigned int	length () const
	Gets the number of samples in this collection. More...

void	return_loan ()
	Returns the samples to the DataReader. More...

bool	return_loan_noexcept () noexcept
	Returns the samples to the DataReader (noexcept version) More...

iterator	begin ()
	Gets an iterator to the first sample. More...

iterator	end ()
	Gets an iterator to one past the last sample. More...

const_iterator	begin () const
	Gets an iterator to the first sample. More...

const_iterator	end () const
	Gets an iterator to one past the last sample. More...

void	swap (LoanedSamples &other) throw ()
	Swap two LoanedSamples containers. More...

	LoanedSamples (LoanedSamples &&other)
	<<C++11>> Moves the loan from an existing LoanedSamples to a new one More...

Related Functions
(Note that these are not member functions.)
template<typename T >
LoanedSamples< T >	move (LoanedSamples< T > &ls) OMG_NOEXCEPT
	Creates a new LoanedSamples instance by moving the contents of an existing one. More...

template<typename T >
LoanedSamples< T >::iterator	begin (LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::const_iterator	begin (const LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::iterator	end (LoanedSamples< T > &ls)

template<typename T >
LoanedSamples< T >::const_iterator	end (const LoanedSamples< T > &ls)

template<typename T >
void	swap (LoanedSamples< T > &ls1, LoanedSamples< T > &ls2) throw()

template<typename T >
ValidLoanedSamples< T >	valid_data (LoanedSamples< T > &&samples)
	<<C++11>> <<extension>> Returns a collection that provides access only to samples with valid data More...

template<typename T >
ValidSampleIterator< T >	valid_data (const SampleIterator< T > &sample_iterator)
	<<extension>> Returns an iterator that skips invalid samples More...

Detailed Description

template<typename T>
class dds::sub::LoanedSamples< T >

<<move-only-type>> Provides temporary access to a collection of samples (data and info) from a DataReader.

Template Parameters

T	The topic-type. It has to match the type of the DataReader.

This STL-like container encapsulates a collection of loaned, read-only data samples (data and info) from a DataReader.

To obtain a LoanedSamples you need to call one of the read/take operations from a DataReader. The samples have to be eventually returned to the DataReader. The destructor takes care of that, and the return_loan() function lets you do it explicitly if needed.

As a move-only type copying a LoanedSamples is not allowed. If you want to have more than one reference to a collection of loaned sample, see SharedSamples. If you need to return a LoanedSamples from a function or assign it to another variable, use dds::core::move() (or std::move() <<C++11>>).

Iterators and overloaded subscript operators let you access the samples in this container, which are of the type rti::sub::LoanedSample.

This code demonstrates how to access the info and data of each sample in a DataReader:

auto samples = reader.take();
for (auto sample : samples) {
    if (sample.info().valid()) {
        std::cout << sample.data() << std::endl;
    }
}

See also: Reading data samples for more examples

Examples: Foo_subscriber.cxx.

Member Typedef Documentation

◆ iterator

template<typename T >

typedef SampleIterator<T> dds::sub::LoanedSamples< T >::iterator

The iterator type.

Constructor & Destructor Documentation

◆ LoanedSamples() [1/2]

template<typename T >

dds::sub::LoanedSamples< T >::LoanedSamples ( )

inline

Creates an empty LoanedSamples object.

◆ ~LoanedSamples()

template<typename T >

dds::sub::LoanedSamples< T >::~LoanedSamples ( )

inlinenoexcept

Automatically returns the loan to the DataReader.

See also: return_loan

◆ LoanedSamples() [2/2]

template<typename T >

dds::sub::LoanedSamples< T >::LoanedSamples ( LoanedSamples< T > && other )

inline

<<C++11>> Moves the loan from an existing LoanedSamples to a new one

References dds::sub::LoanedSamples< T >::swap().

Member Function Documentation

◆ operator[]()

template<typename T >

value_type dds::sub::LoanedSamples< T >::operator[] ( size_t index )

inline

Provides access to the underlying LoanedSample object in array-like syntax.

Parameters

index The index of the Sample. Allowed values are from 0 to length()-1.

Returns: A LoanedSample object that refers to data and SampleInfo at the specified index.

◆ length()

template<typename T >

unsigned int dds::sub::LoanedSamples< T >::length ( ) const

inline

Gets the number of samples in this collection.

◆ return_loan()

template<typename T >

void dds::sub::LoanedSamples< T >::return_loan ( )

inline

Returns the samples to the DataReader.

Note: Explicitly calling return_loan is optional, since the destructor does it implicitly.

This operation tells the dds::sub::DataReader that the application is done accessing the collection of samples.

It is not necessary for an application to return the loans immediately after the call to read or take. However, as these buffers correspond to internal resources, the application should not retain them indefinitely.

◆ return_loan_noexcept()

template<typename T >

bool dds::sub::LoanedSamples< T >::return_loan_noexcept ( )

inlinenoexcept

Returns the samples to the DataReader (noexcept version)

This operation has the same behavior as return_loan() but returns false in case of error and doesn't throw exceptions.

◆ begin() [1/2]

template<typename T >

iterator dds::sub::LoanedSamples< T >::begin ( )

inline

Gets an iterator to the first sample.

Referenced by dds::sub::LoanedSamples< T >::begin().

◆ end() [1/2]

template<typename T >

iterator dds::sub::LoanedSamples< T >::end ( )

inline

Gets an iterator to one past the last sample.

Referenced by dds::sub::LoanedSamples< T >::end().

◆ begin() [2/2]

template<typename T >

const_iterator dds::sub::LoanedSamples< T >::begin ( ) const

inline

Gets an iterator to the first sample.

◆ end() [2/2]

template<typename T >

const_iterator dds::sub::LoanedSamples< T >::end ( ) const

inline

Gets an iterator to one past the last sample.

◆ swap()

template<typename T >

void dds::sub::LoanedSamples< T >::swap	(	LoanedSamples< T > &	other	)
throw	(
	)

inline

Swap two LoanedSamples containers.

Referenced by dds::sub::LoanedSamples< T >::LoanedSamples().

Friends And Related Function Documentation

◆ move()

template<typename T >

LoanedSamples< T > move ( LoanedSamples< T > & ls )

Note: in <<C++11>> you can directly use std::move.

The parameter object loses the ownership of the underlying samples and its state is reset as if it was default initialized. This function must be used to move any named LoanedSamples instance (lvalue) in and out of a function by-value. Using this function is not necessary if the original LoanedSamples is an rvalue. Moving is a very efficient operation and is guaranteed to not throw any exception.

Parameters

ls	The LoanedSamples object that transfers its ownership of the contained samples into the returned object. After this call, `ls` is empty.

Returns: A new LoanedSamples object, the new loan owner, with the same contents as ls had.

See also: LoanedSamples

References dds::sub::move().

◆ begin() [1/2]

template<typename T >

LoanedSamples< T >::iterator begin ( LoanedSamples< T > & ls )

See also: LoanedSamples::begin()

References dds::sub::LoanedSamples< T >::begin().

◆ begin() [2/2]

template<typename T >

LoanedSamples< T >::const_iterator begin ( const LoanedSamples< T > & ls )

See also: LoanedSamples::begin()

References dds::sub::LoanedSamples< T >::begin().

◆ end() [1/2]

template<typename T >

LoanedSamples< T >::iterator end ( LoanedSamples< T > & ls )

See also: LoanedSamples::end()

References dds::sub::LoanedSamples< T >::end().

◆ end() [2/2]

template<typename T >

LoanedSamples< T >::const_iterator end ( const LoanedSamples< T > & ls )

See also: LoanedSamples::end()

References dds::sub::LoanedSamples< T >::end().

◆ swap()

template<typename T >

void swap	(	LoanedSamples< T > &	ls1,
		LoanedSamples< T > &	ls2
	)
throw	(
	)

See also: LoanedSamples::swap()

◆ valid_data() [1/2]

template<typename T >

ValidLoanedSamples< T > valid_data ( LoanedSamples< T > && samples )

Template Parameters

T	The topic-type. It has to match the type of the DataReader.

This function transforms a LoanedSamples collection into another collection whose iterators only access valid-data samples, skipping any sample such that !sample.info().valid().

This operation is O(1) and will not copy the data samples or allocated any additional memory.

The typical way to use this function is to directly call it on the return value of a read()/take() operation and use it in a for-loop. For example:

auto valid_samples = rti::sub::valid_data(reader.read());
for (auto sample : valid_samples) {
    // no need to check sample.info().valid()
    std::cout << sample.data() << std::endl;
}

Parameters

samples

The collection of LoanedSamples to transform into a ValidLoanedSamples. It must be an rvalue, so valid actual parameters are the result of one of the read/take operations:

auto vs = rti::sub::valid_data(reader.take());

Or an std::move'd existing collection:

auto ls = reader.take();
auto vs = rti::sub::valid_data(std::move(ls));
// 'ls' is now invalid and can't be further used

Returns: A forward-iterable collection that provides access only to samples with valid data. Note that this collection doesn't provide random access.

Postcondition: samples is invalid cannot be used after this call

See also: rti::sub::valid_data(const SampleIterator<T>&), which applies to an iterator rather to the whole collection; Reading data samples

◆ valid_data() [2/2]

template<typename T >

ValidSampleIterator< T > valid_data ( const SampleIterator< T > & sample_iterator )

Given a regular sample iterator, this functions creates another iterator it that behaves exactly the same except that it++ moves to the next valid sample (or to the end of the collection). That is, if it doesn't point to the end of the collection, it->info.valid() is always true.

This is useful when your application doesn't need to deal with samples containing meta-information only.

For example, the following code copies all the data in a LoanedSamples collection skipping any invalid samples (otherwise, attempting to copy the data from an invalid sample would throw an exception, see rti::sub::LoanedSample::operator const DataType& ()).

dds::sub::LoanedSamples<KeyedType> samples = reader.take();
std::vector<KeyedType> data_vector;
std::copy(
     rti::sub::valid_data(samples.begin()),
     rti::sub::valid_data(samples.end()),
     std::back_inserter(data_vector));

Note that valid_data(samples.begin()) won't point to the first element if that element is not a valid sample.

A similar utility is the functor rti::sub::IsValidData.

See also: dds::sub::LoanedSamples; rti::sub::IsValidData; dds::sub::SampleInfo::valid(); rti::sub::valid_data(LoanedSamples<T>&&), which applies to the whole collection instead of an iterator; Reading data samples

Public Types

Public Member Functions

Related Functions

Detailed Description

Member Typedef Documentation

◆ iterator

Constructor & Destructor Documentation

◆ LoanedSamples() [1/2]

◆ ~LoanedSamples()

◆ LoanedSamples() [2/2]

Member Function Documentation

◆ operator[]()

◆ length()

◆ return_loan()

◆ return_loan_noexcept()

◆ begin() [1/2]

◆ end() [1/2]

◆ begin() [2/2]

◆ end() [2/2]

◆ swap()

Friends And Related Function Documentation

◆ move()

◆ begin() [1/2]

◆ begin() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ swap()

◆ valid_data() [1/2]

◆ valid_data() [2/2]