CValueArrayAdapter< TValueNodeType, TOutputValueType, TEffectiveValueType > Class Template Reference

Adapter for accessing structured register known to include an array of selector-iterated values. More...

Inherits CValueArrayAdapterBase.

Public Member Functions
	CValueArrayAdapter (TValueNodeType *base_value, IInteger *selector)
	Creates a CValueArrayAdapter object. More...
bool	IsValid () const
	Check if the instance is valid and useable. More...
std::vector< TOutputValueType >	GetAllValues ()
	Get all values of the array. More...
void	GetAllValues (std::vector< TOutputValueType > &values)
	Get all values of the array. More...

Static Public Member Functions
static bool	CheckAdvertisedCompatibility (TValueNodeType *base_value, IInteger *selector)
	Check value/selector feature pair suitability for use with the adapter. More...

Detailed Description

template<typename TValueNodeType, typename TOutputValueType, typename TEffectiveValueType = TOutputValueType>
class GENAPI_NAMESPACE::CValueArrayAdapter< TValueNodeType, TOutputValueType, TEffectiveValueType >

Generic worker for any numeric "output" type, typically used through "concretized" children, CIntegerValueArray, CFloatValueArray or CBooleanValueArray. Intended to significantly improve performance when reading large contiguous arrays that would otherwise be read using selector-based iteration. To be eligible for use with the adapter, the XML definition of the feature and its selector must conform to specific rules that are documented with SFNC feature ValueArrayCandidates (and can be tested using member function CheckAdvertisedCompatibility). The "effective" value type is expected to be usually same as the "output" value type, with exception of retrieving the bool array as vector<uint8_t> instead of the possibly problematic vector<bool>.

Constructor & Destructor Documentation

CValueArrayAdapter()

CValueArrayAdapter	(	TValueNodeType *	base_value,
		IInteger *	selector
	)

Parameters

[in]	base_value	The value node holding the array of values (selector iterated).
[in]	selector	The selector node iterating the base_value array.

Does not throw C++ exceptions, except when memory allocation fails.

Member Function Documentation

IsValid()

bool IsValid

(

)

const

The created instance might be invalid in particular if given value/selector feature pair is not eligible for use with the adapter (they do not conform to required rules).

Does not throw C++ exceptions.

GetAllValues() [1/2]

std::vector<TOutputValueType> GetAllValues

(

)

Gets all values of the array (for current selector range) as a vector. Returns same results as if the value array was iterated using the corresponding selector - if given value/selector pair is eligible for use with the adapter and conforms to the required rules, otherwise the results are undefined.

The nodemap is expected to advertise the value/selector pairs suitable for use with the adapter using the ValueArrayCandidates feature (defined in SFNC). The device (nodemap) designer guarantees compatibility with the adapter for the advertised features.

The function does not check access mode of the value feature, user should verify its readability when desirable.

Note that the first run might be little bit slower than following runs, because of some initial internal allocations. The data are not cached, the array is retrieved fresh on each run.

Throws C++ exceptions if the operation fails.

GetAllValues() [2/2]

void GetAllValues

(

std::vector< TOutputValueType > &

values

)

Parameters

[out]

values

The output vector carrying the 'array' values.

Gets all values of the array (for current selector range) as a vector. Returns same results as if the value array was iterated using the corresponding selector - if given value/selector pair is eligible for use with the adapter and conforms to the required rules, otherwise the results are undefined.

The nodemap is expected to advertise the value/selector pairs suitable for use with the adapter using the ValueArrayCandidates feature (defined in SFNC). The device (nodemap) designer guarantees compatibility with the adapter for the advertised features.

The function does not check access mode of the value feature, user should verify its readability when desirable.

Note that the first run might be little bit slower than following runs, because of some initial internal allocations. The data are not cached, the array is retrieved fresh on each run.

This overload outputs the values in an out-parameter rather than as a return value which might offer small performance advantage if the same vector is reused across multiple calls (its capacity is reused).

Throws C++ exceptions if the operation fails.

CheckAdvertisedCompatibility()

static bool CheckAdvertisedCompatibility ( TValueNodeType *  base_value, IInteger *  selector  )

static

Parameters

[in]	base_value	The value node holding the array of values (selector iterated).
[in]	selector	The selector node iterating the base_value array.

Returns

Returns true if the value/selector pair is advertised to be eligible for use with the adapter.

The function does not directly touch the value/selector nodes, it rather checks, if the nodemap they belong to advertises their compatibility with the adapter using the ValueArrayCandidates SFNC feature. It is the device/nodemap designer's responsibility to advertise this compatibility only for suitable features.

Does not throw C++ exceptions.