#include "DataReader.hpp"

Public Member Functions
	ManipulatorSelector (DataReader &dr)

ManipulatorSelector &	content (const dds::sub::Query &query)

ManipulatorSelector &	instance (const dds::core::InstanceHandle &handle)

ManipulatorSelector &	max_samples (uint32_t n)

ManipulatorSelector &	next_instance (const dds::core::InstanceHandle &handle)

ManipulatorSelector &	operator>> (dds::sub::LoanedSamples< T > &samples)

ManipulatorSelector &	operator>> (ManipulatorSelector &(manipulator)(ManipulatorSelector &))

template<typename Functor >
ManipulatorSelector	operator>> (Functor f)

bool	read_mode ()

void	read_mode (bool readmode)

ManipulatorSelector &	state (const dds::sub::status::DataState &state)

Detailed Description

template<typename T>
class dds::sub::DataReader< T >::ManipulatorSelector

The ManipulatorSelector class is used by the DataReader to compose streaming read operations.

A ManipulatorSelector can perform complex data selections, such as per-instance selection, content and status filtering, etc, when reading or taking samples through the streaming operator.

Convenience functors
The following convenience functors use a ManipulatorSelector implicitly and can be used in the streaming operator:

// Take a maximum of 3 new samples of a certain instance.
reader >> dds::sub::take
       >> dds::sub::max_samples(3)
       >> dds::sub::state(dds::sub::status::DataState::new_data())
       >> dds::sub::instance(someValidInstanceHandle)
       >> samples;

However, this will create and destroy ManipulatorSelectors and Functors for every read, which is not very performance friendly.

The performance can be increase by creating a ManipulatorSelector up front and doing the reading on that ManipulatorSelector directly and re-using it.

// Create a ManipulatorSelector as selective reader up front.
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
// Configure it to take a maximum of 3 new samples of a certain instance
selectiveReader.max_samples(3);
selectiveReader.state(dds::sub::status::DataState::new_data());
selectiveReader.instance(someValidInstanceHandle);
selectiveReader.read_mode(false); // take
// Use the configured ManipulatorSelector to -take- a maximum of 3 samples of a
// certain instance (which it was configured to do).
// This can be used in loops for example, reducing the need for creating
// implicit ManipulatorSelectors for every take.
selectiveReader >> samples;

Defaults

Element	Default Value
read_mode	true (read)
state	dds::sub::status::DataState::any
content	Empty dds::sub::Query
max_samples	dds::core::LENGTH_UNLIMITED
instance	dds::core::InstanceHandle nil

See also: DataReader stream operator>>

Definition at line 508 of file DataReader.hpp.

Constructor & Destructor Documentation

◆ ManipulatorSelector()

template<typename T >

dds::sub::DataReader< T >::ManipulatorSelector::ManipulatorSelector ( DataReader & dr )

Construct a ManipulatorSelector for a DataReader.

See also DataReader stream operator>>

Parameters

DataReader

Definition at line 176 of file DataReaderImpl.hpp.

Member Function Documentation

◆ content()

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::content ( const dds::sub::Query & query )

Set Query to filter with during the read or take.

Convenience Functor: dds::sub::content

Example
Read only samples that will be filtered according to the given dds::sub::Query.

// Assume data type has an element called long_1
dds::sub::Query query(reader, "long_1 > 1 and long_1 < 7");
// Implicit use of ManipulatorSelector
reader >> dds::sub::content(query) >> samples;
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.content(query);
selectiveReader >> read;

See also DataReader stream operator>>

Parameters

query The Query to apply to a read/take

Definition at line 261 of file DataReaderImpl.hpp.

◆ instance()

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::instance ( const dds::core::InstanceHandle & handle )

Set InstanceHandle to filter with during the read or take.

Convenience Functor: dds::sub::instance

Example
Read only samples of the given instance.

dds::core::InstanceHandle hdl = someValidInstanceHandle;
// Implicit use of ManipulatorSelector
reader >> dds::sub::instance(hdl) >> samples;
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.instance(hdl);
selectiveReader >> samples;

See also DataReader stream operator>>

Parameters

handle the InstanceHandle for the read/take

Definition at line 198 of file DataReaderImpl.hpp.

◆ max_samples()

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::max_samples ( uint32_t n )

Set max_samples to limit the number of sample to get during the read or take.

Convenience Functor: dds::sub::max_samples

Example
Read a maximum of three samples.

// Implicit use of ManipulatorSelector
reader >> dds::sub::max_samples(3) >> samples;
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.max_samples(3);
selectiveReader >> samples;

See also DataReader stream operator>>

Parameters

n	maximum number of samples

Definition at line 271 of file DataReaderImpl.hpp.

◆ next_instance()

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::next_instance ( const dds::core::InstanceHandle & handle )

Set next InstanceHandle to filter with during the read or take.

Convenience Functor: dds::sub::next_instance

Example
Read all samples, instance by instance.

// Implicit use of ManipulatorSelector
{
    // Get sample(s) of first instance
    dds::core::InstanceHandle hdl; //nil
    reader >> dds::sub::next_instance(hdl) >> samples;
    while (samples.length() > 0) {
        // Handle the sample(s) of this instance (just the first one in this case)
        const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
        // Get sample(s) of the next instance
        hdl = sample.info().instance_handle();
        reader >> dds::sub::next_instance(hdl) >> samples;
    }
}
// Explicit use of ManipulatorSelector
{
    // Get sample(s) of first instance
    dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
    dds::core::InstanceHandle hdl; //nil
    selectiveReader.next_instance(hdl);
    selectiveReader >> samples;
    while (samples.length() > 0) {
        // Handle the sample(s) of this instance (just the first one in this case)
        const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
        // Get sample(s) of the next instance
        hdl = sample.info().instance_handle();
        selectiveReader.next_instance(hdl);
        selectiveReader >> samples;
    }
}

See also DataReader stream operator>>

Parameters

handle the 'previous' InstanceHandle associated with new the read/take

Definition at line 208 of file DataReaderImpl.hpp.

◆ operator>>() [1/3]

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::operator>> ( dds::sub::LoanedSamples< T > & samples )

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

Definition at line 218 of file DataReaderImpl.hpp.

◆ operator>>() [2/3]

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::operator>> ( ManipulatorSelector & manipulator)(ManipulatorSelector & )

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

Definition at line 228 of file DataReaderImpl.hpp.

◆ operator>>() [3/3]

template<typename T>

template<typename Functor >

ManipulatorSelector dds::sub::DataReader< T >::ManipulatorSelector::operator>> ( Functor f )

This operation works the same as the DataReader stream operator>> , except that it is performed on this ManipulatorSelector with possible filters set.

Exceptions

dds::core::Error	An internal error has occurred.
dds::core::NullReferenceError	The entity was not properly created and references to dds::core::null.
dds::core::AlreadyClosedError	The entity has already been closed.
dds::core::OutOfResourcesError	The Data Distribution Service ran out of resources to complete this operation.
dds::core::NotEnabledError	The DataReader has not yet been enabled.

◆ read_mode() [1/2]

template<typename T >

bool dds::sub::DataReader< T >::ManipulatorSelector::read_mode ( )

Get the read_mode.

The read_mode specifies if a sample should be read or taken:

true = read (default)
false = take

Returns: true if read_mode is set to read

Definition at line 180 of file DataReaderImpl.hpp.

◆ read_mode() [2/2]

template<typename T >

void dds::sub::DataReader< T >::ManipulatorSelector::read_mode ( bool readmode )

Set the read_mode.

The read_mode specifies if a sample should be read or taken:

true = read (default)
false = take

Convenience Functor: dds::sub::read
Convenience Functor: dds::sub::take

Example
Determine to read or take samples.

// No usage of ManipulatorSelector, means a read iso take as default.
reader >> samples;
// Implicit use of ManipulatorSelector
reader >> dds::sub::read >> samples;
reader >> dds::sub::take >> samples;
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector readingReader(reader);
readingReader.read_mode(true); // Read, which is already the default.
readingReader >> samples;
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector takingReader(reader);
takingReader.read_mode(false); // Take.
takingReader >> samples;

See also DataReader stream operator>>

Parameters

readmode the read mode of the DataReader

Definition at line 189 of file DataReaderImpl.hpp.

◆ state()

template<typename T >

DataReader< T >::ManipulatorSelector & dds::sub::DataReader< T >::ManipulatorSelector::state ( const dds::sub::status::DataState & state )

Set DataState to filter with during the read or take.

Convenience Functor: dds::sub::state

Example
Read only new data.

// DataState to filter only new data
dds::sub::status::DataState newData = dds::sub::status::DataState::new_data();
// Implicit use of ManipulatorSelector
reader >> dds::sub::state(newData) >> samples;
// Explicit use of ManipulatorSelector
dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
selectiveReader.state(newData);
selectiveReader.read() >> samples;

See also DataReader stream operator>>

Parameters

state the required DataState of the samples

Definition at line 251 of file DataReaderImpl.hpp.

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

include/dcps/C++/isocpp2/dds/sub/DataReader.hpp
include/dcps/C++/isocpp2/dds/sub/detail/DataReaderImpl.hpp

Public Member Functions

Detailed Description

template<typename T> class dds::sub::DataReader< T >::ManipulatorSelector

Constructor & Destructor Documentation

◆ ManipulatorSelector()

Member Function Documentation

◆ content()

◆ instance()

◆ max_samples()

◆ next_instance()

◆ operator>>() [1/3]

◆ operator>>() [2/3]

◆ operator>>() [3/3]

◆ read_mode() [1/2]

◆ read_mode() [2/2]

◆ state()

template<typename T>
class dds::sub::DataReader< T >::ManipulatorSelector