RTI Connext Modern C++ API  Version 6.1.2
dds::sub::LoanedSamples< T > Class Template Reference

<<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 () throw ()
 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...
 
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
TThe 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 (const 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]

◆ ~LoanedSamples()

template<typename T>
dds::sub::LoanedSamples< T >::~LoanedSamples ( )
throw (
)
inline

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
indexThe 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.

◆ begin() [1/2]

template<typename T>
iterator dds::sub::LoanedSamples< T >::begin ( )
inline

Gets an iterator to the first sample.

Referenced by dds::sub::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::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)
related

Creates a new LoanedSamples instance by moving the contents of an existing one.

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
lsThe 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

◆ begin() [1/2]

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

◆ begin() [2/2]

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

◆ end() [1/2]

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

◆ end() [2/2]

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

◆ swap()

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

◆ valid_data() [1/2]

template<typename T >
ValidLoanedSamples< T > valid_data ( LoanedSamples< T > &&  samples)
related

<<C++11>> <<extension>> Returns a collection that provides access only to samples with valid data

Template Parameters
TThe 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 (const auto& sample : valid_samples) {
// no need to check sample.info().valid()
std::cout << sample.data() << std::endl;
}
Parameters
samplesThe 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)
related

<<extension>> Returns an iterator that skips invalid samples

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& ()).

std::vector<KeyedType> data_vector;
std::copy(
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