RTI Connext C API  Version 5.0.0
DDS_StringSeq Struct Reference

Instantiates FooSeq < ::char* > with value type semantics. More...

Detailed Description

Instantiates FooSeq < ::char* > with value type semantics.

StringSeq is a sequence that contains strings.

Even though the element type is a ::char*, i.e. a pointer, the sequence semantically behaves as a sequence of ::char* value types. When a DDS_StringSeq is copied or deleted, the contained strings are also respectively copied or deleted.

Important: Users of this type must understand its memory management contract.

  • Ownership of this sequence's buffer implies ownership of the pointers stored in that buffer; a loan of the buffer implies lack of ownership of the pointers. In other words, for a type FooSeq where Foo is a pointer, ownership of Foo implies ownership of Foo. In other words, deleting a string sequence that owns its memory implies the deletion of all strings in that sequence. See FooSeq_loan_contiguous for more information about sequence memory ownership.
  • The second important rule is that non-NULL strings are assumed to be of sufficient size to store the necessary characters. This is a dangerous rule, but it cannot be avoided because a string doesn't store the amount of memory it has. The only other alternative is to always free and re-allocate memory. Not only would this latter policy be very expensive, but it would essentially render any loaned DDS_StringSeq immutable, since to modify any string in it would require freeing and re-allocating that string, which would violate the first principle discussed above.

It is also worth noting that the element type of a string sequence is char, not const char*. It is therefore incorrect and dangerous, for example, to insert a string literal into a string sequence without first copying it into mutable memory.

In order to guarantee correct behavior, it is recommended that the contained elements always be manipulated using the string support API's described in String Support.

See Also
String Support
Instantiates:
<<generic>> FooSeq
See Also
FooSeq


RTI Connext C API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc