Defines sequence interface and primitive data types sequences. More...

Data Structures
struct	FooSeq
	<<interface>> <<generic>> <<cert>> A type-safe, ordered collection of elements. The type of these elements is referred to in this documentation as `"Foo"`. More...

Macros
#define	DDS_SEQUENCE_INITIALIZER
	An initializer for new sequence instances.

Functions
DDS_Boolean	FooSeq_initialize (struct FooSeq *self)
	<<cert>> Initialize sequence instances.
DDS_Long	FooSeq_get_maximum (const struct FooSeq *self)
	<<cert>> Get the current maximum number of elements that can be stored in this sequence.
DDS_Boolean	FooSeq_set_maximum (struct FooSeq *self, DDS_Long new_max)
	<<cert>> Resize this sequence to a new desired maximum.
DDS_Boolean	FooSeq_set_maximum_w_max (struct FooSeq *self, DDS_Long new_max, DDS_UnsignedLong max_size)
	<<cert>> Resize this sequence to a new desired maximum and allocate `max_size` + 1 bytes for each pointer element.
DDS_Long	FooSeq_get_length (const struct FooSeq *self)
	<<cert>> Get the logical length of this sequence.
DDS_Boolean	FooSeq_set_length (struct FooSeq *self, DDS_Long new_length)
	<<cert>> Change the length of this sequence.
Foo *	FooSeq_get_reference (const struct FooSeq *self, DDS_Long i)
	<<cert>> Get the pointer to the `i-th` element of this sequence.
struct FooSeq *	FooSeq_copy (struct FooSeq self, const struct FooSeq src_seq)
	Copy elements from another sequence, resizing the sequence if necessary.
struct FooSeq *	FooSeq_copy_w_max (struct FooSeq self, const struct FooSeq src_seq, DDS_UnsignedLong max_size)
	Copy elements from another sequence, resizing the sequence if necessary.

Detailed Description

Defines sequence interface and primitive data types sequences.

Macro Definition Documentation

#define DDS_SEQUENCE_INITIALIZER

An initializer for new sequence instances.

This constant will initialize a new sequence to a valid empty state. C language users should assign it to uninitialized sequence instances before using them, at the time they are declared, or use FooSeq_initialize as an alternative function to initialize new sequences.

Function Documentation

DDS_Boolean FooSeq_initialize ( struct FooSeq * self )

<<cert>> Initialize sequence instances.

Use this function to initialize new sequences to a valid emptu state. C users should initialize sequences before using them.

Parameters:

self	<<in>> Cannot be NULL.

Returns:: DDS_BOOLEAN_TRUE if the sequence was successfully initialized; DDS_BOOLEAN_FALSE otherwise.

MT Safety:: This operation is not thread safe.

See also:: DDS_SEQUENCE_INITIALIZER

DDS_Long FooSeq_get_maximum ( const struct FooSeq * self )

<<cert>> Get the current maximum number of elements that can be stored in this sequence.

The maximum of the sequence represents the maximum number of elements that the underlying buffer can hold. It does not represent the current number of elements.

The maximum is a non-negative number. It is initialized when the sequence is first created and can only be set by means of the FooSeq_set_maximum operation.

Note that the maximum can only be set once, and cannot be changed after FooSeq_set_maximum has been called for the first time.

Parameters:

self	<<in>> Cannot be NULL.

Returns:: the current maximum of the sequence.

MT Safety:: This operation is not thread safe.

See also:: FooSeq_get_length

DDS_Boolean FooSeq_set_maximum	(	struct FooSeq *	self,
		DDS_Long	new_max
	)

<<cert>> Resize this sequence to a new desired maximum.

This operation does nothing if the new desired maximum matches the current maximum.

This operation can only allocate memory for a buffer once, and will fail if the existing maximum is not zero.

Precondition:: maximum == 0 or maximum == new_max; owned == DDS_BOOLEAN_TRUE

Postcondition:: owned == DDS_BOOLEAN_TRUE; length == MINIMUM(original length, new_max)

Parameters:

self	<<in>> Cannot be NULL.
new_max	Must be >= 0.

Returns:: DDS_BOOLEAN_TRUE on success, DDS_BOOLEAN_FALSE if the preconditions are not met. In that case the sequence is not modified.

MT Safety:: This operation is not thread safe.

API Restriction:: This function must only be called after DDS_DomainParticipantFactory_get_instance.

Note:: This operation is not available for sequences of type DDS_WString. The operation named DDS_WStringSeq_set_maximum is an implementation of FooSeq_set_maximum_w_max.

DDS_Boolean FooSeq_set_maximum_w_max	(	struct FooSeq *	self,
		DDS_Long	new_max,
		DDS_UnsignedLong	max_size
	)

<<cert>> Resize this sequence to a new desired maximum and allocate max_size + 1 bytes for each pointer element.

This operation does nothing if the new desired maximum matches the current maximum.

This operation can only allocate memory for a buffer once, and will fail if the existing maximum is not zero.

Precondition:: maximum == 0 or maximum == new_max; owned == DDS_BOOLEAN_TRUE

Postcondition:: owned == DDS_BOOLEAN_TRUE; length == MINIMUM(original length, new_max)

Parameters:

self	<<in>> Cannot be NULL.
new_max	Must be >= 0.
max_size	<<in>> Each pointer element is allocated to to `max_size` + 1 bytes.

Returns:: DDS_BOOLEAN_TRUE on success, DDS_BOOLEAN_FALSE if the preconditions are not met. In that case the sequence is not modified.

MT Safety:: This operation is not thread safe.

API Restriction:: This function must only be called after DDS_DomainParticipantFactory_get_instance.

Note:: This operation is only available for sequences of types DDS_String and DDS_Wstring. Note that for wide strings, this operation is named DDS_WStringSeq_set_maximum.

DDS_Long FooSeq_get_length ( const struct FooSeq * self )

<<cert>> Get the logical length of this sequence.

Get the length that was last set, or zero if the length has never been set.

Parameters:

self	<<in>> Cannot be NULL.

Returns:: the length of the sequence

MT Safety:: This operation is not thread safe.

DDS_Boolean FooSeq_set_length	(	struct FooSeq *	self,
		DDS_Long	new_length
	)

<<cert>> Change the length of this sequence.

This function does not allocate/deallocate memory.

The new length must not exceed the maximum of this sequence as returned by the FooSeq_get_maximum operation. (Note that, if necessary, the maximum of this sequence can be increased manually by using the FooSeq_set_maximum operation.)

The elements of the sequence are not modified by this operation. If the new length is larger than the original length, the new elements will be uninitialized; if the length is decreased, the old elements that are beyond the new length will physically remain in the sequence but will not be accessible.

Postcondition:: length = new_length.

Parameters:

self	<<in>> Cannot be NULL.
new_length	the new desired length. This value must be non-negative and cannot exceed maximum of the sequence. In other words 0 <= new_length <= maximum

Returns:: DDS_BOOLEAN_TRUE on sucess or DDS_BOOLEAN_FALSE on failure

MT Safety:: This operation is not thread safe.

Foo* FooSeq_get_reference	(	const struct FooSeq *	self,
		DDS_Long	i
	)

<<cert>> Get the pointer to the i-th element of this sequence.

Parameters:

self	<<in>> Cannot be NULL.
i	index of element to access, must be >= 0 and less than FooSeq_get_length

Returns:: the i-th element

MT Safety:: This operation is not thread safe.

struct FooSeq* FooSeq_copy	(	struct FooSeq *	self,
		const struct FooSeq *	src_seq
	)

read

Copy elements from another sequence, resizing the sequence if necessary.

This function invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.

It is important to know that no check for overlapping memory regions is performed, and copying sequences with overlapping memory regions has undefined behavior. For example, copying two string sequences where the strings are overlapping has undefined behavior.

RTI Connext Micro does not create overlapping memory regions.

NOTE: If this function is called on a sequence that has been created with set_maxmium_w_max, it will automatically call copy_w_max().

Parameters:

self	<<in>> Cannot be NULL.
src_seq	<<in>> the sequence from which to copy

Returns:: self, this sequence

MT Safety:: This operation is not thread safe.

API Restriction:: This function must only be called after DDS_DomainParticipantFactory_get_instance.

Note:: This operation is not available for sequences of type DDS_Wstring. The operation named DDS_WStringSeq_copy is an implementation of FooSeq_copy_w_max.

struct FooSeq* FooSeq_copy_w_max	(	struct FooSeq *	self,
		const struct FooSeq *	src_seq,
		DDS_UnsignedLong	max_size
	)

read

Copy elements from another sequence, resizing the sequence if necessary.

This function invokes copies the content of the specified sequence, after ensuring that this sequence has enough capacity to hold the elements to be copied.

Parameters:

self	<<in>> Cannot be NULL.
src_seq	<<in>> the sequence from which to copy
max_size	<<in>> Each element is a pointer to `max_size` + 1 bytes.

Returns:: self, this sequence

MT Safety:: This operation is not thread safe.

Note:: This operation is only available for sequences of types DDS_String and DDS_Wstring. Note that for wide strings, this operation is named DDS_WStringSeq_copy.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation