String Support

String creation, cloning, assignment, and deletion. More...

Functions
char *	DDS_String_alloc (DDS_UnsignedLong length)
	Create a new empty string that can hold up to length characters.
char *	DDS_String_dup (const char *str)
	Clone a string. Creates a new string that duplicates the value of string.
void	DDS_String_free (char *str)
	Delete a string.
int	DDS_String_cmp (const char *s1, const char *s2)
	Compare two strings.
int	DDS_String_ncmp (const char *s1, const char *s2, DDS_UnsignedLong num)
	Compare two strings.
int	DDS_String_length (const char *string)
	Return the length of a string.
int	DDS_Wstring_compare (const DDS_Wstring *s1, const DDS_Wstring *s2)
	Return the length of a string.

---

Detailed Description

String creation, cloning, assignment, and deletion.

The methods in this class ensure consistent cross-platform implementations for string creation (DDS_String_alloc()), deletion (DDS_String_free()), and cloning (DDS_String_dup()) that preserve the mutable value type semantics. These are to be viewed as methods that define a string class whose data is represented by a 'char*'.

The following conventions govern the memory management of strings in RTI Connext Micro:

• The DDS implementation ensures that when value types containing strings are passed back and forth to the DDS APIs, the strings are created/deleted/assigned/cloned using the string class methods.
• Value types containing strings have ownership of the contained string. Thus, when a value type is deleted, the contained string field is also deleted.
• The user must ensure that when value types containing strings are passed back and forth to the DDS APIs, the strings are created/deleted/assigned/cloned using the String class methods.

The representation of a string in C/C++ unfortunately does not allow programs to detect how much memory has been allocated for a string. RTI Connext Micro must therefore make some assumptions when a user requests that a string be copied into. The following rules apply when RTI Connext Micro is copying into a string or string sequence:

• If the 'char*' is NULL, RTI Connext Micro will log a warning and allocate a new string on behalf of the user. To avoid leaking memory, you must ensure that the string will be freed (see below).
• If the 'char*' is not NULL, RTI Connext Micro will assume that you are managing the string's memory yourself and have allocated enough memory to store the string to be copied. RTI Connext Micro will copy into your memory; to avoid memory corruption, be sure to allocate enough of it. Also, do not pass structures containing junk pointers into RTI Connext Micro; you are likely to crash.

This requirement can generally be assured by adhering to the following idiom for manipulating strings:

• Always use DDS_String_alloc() to create a string
• Always use DDS_String_dup() to clone a string
• Always use DDS_String_free() to delete a string 'char*' that is passed back and forth between user code and the DDS C/C++ APIs

Not adhering to this idiom can result in bad pointers, and incorrect memory being freed.

In addition, the user code should be vigilant to avoid memory leaks. It is good practice to:

• Balance occurrences of DDS_String_alloc(), DDS_String_dup(), with matching occurrences of DDS_String_free() in the code.
• Finalize value types containing strings. In C++ the destructor accomplishes this automatically. in C, explicit "destructor" functions are provided; these functions are typically called "finalize."

---

Function Documentation

char* DDS_String_alloc

(

DDS_UnsignedLong

length

)

Create a new empty string that can hold up to length characters.

A string created by this method must be deleted using DDS_String_free().

This function will allocate enough memory to hold a string of length characters, plus one additional byte to hold the NULL terminating character.

Parameters:

length

<<in>> Capacity of the string.

Returns:

A newly created non-NULL string upon success or NULL upon failure.

MT Safety:

This operation is thread safe.

API Restriction:

This function must only be called after DDSDomainParticipantFactory::get_instance.

char* DDS_String_dup

(

const char *

str

)

Clone a string. Creates a new string that duplicates the value of string.

A string created by this method must be deleted using DDS_String_free()

Parameters:

str	<<in>> The string to duplicate.

Returns:

If string == NULL, this method always returns NULL. Otherwise, upon success it returns a newly created string whose value is string; upon failure it returns NULL.

MT Safety:

UNSAFE. This operation is not thread safe. This operation does not protect the source or destination from being modified by another thread while the source is being copied to the destination.

API Restriction:

This function must only be called after DDSDomainParticipantFactory::get_instance.

void DDS_String_free

(

char *

str

)

Delete a string.

Precondition:

string must be either NULL, or must have been created using DDS_String_alloc(), DDS_String_dup()

Parameters:

str	<<in>> The string to delete.

int DDS_String_cmp	(	const char *	s1,
		const char *	s2
	)

Compare two strings.

Precondition:

s1 and s2 can be NULL or non-NULL.

Parameters:

s1	<<in>> String 1 to compare.
s2	<<in>> String 2 to compare.

Returns:

0 if s1 equals s2, positive integer if s1 is greater than s2, negative integer if s1 is less than s2

MT Safety:

UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.

int DDS_String_ncmp	(	const char *	s1,
		const char *	s2,
		DDS_UnsignedLong	num
	)

Compare two strings.

This function compares two strings for lexicographic equivalence, but only up to num bytes.

Parameters:

[in]	s1	<<in>> Left side of comparison
[in]	s2	<<in>> Right side of comparison
[in]	num	Maximum number of bytes to compare

Returns:

0 if s1 equals s2, positive integer if s1 is greater than s2, negative integer if s1 is less than s2

MT Safety:

UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.

int DDS_String_length

(

const char *

string

)

Return the length of a string.

Precondition:

string must be non-NULL

Parameters:

string

<<in>> String to return length of

Returns:

length of string. Does not include the NUL-termination character. If a NULL value is passed as argument, RTI_SIZE_INVALID will be returned.

MT Safety:

This operation is not thread safe.

int DDS_Wstring_compare	(	const DDS_Wstring *	s1,
		const DDS_Wstring *	s2
	)

Return the length of a string.

Precondition:

s1 and s2 can be NULL or non-NULL.

Parameters:

s1	<<in>> String 1 to compare.
s2	<<in>> String 2 to compare.

Returns:

• 0 if *s1 is lexiographically  equal to *s2
• a value larger than 0 if *s1 is lexiographically  larger than to *s2
• a value less than 0 if *s1 is lexiographically  less than to *s2
• 0 if s1 or s2 is equal to 'nil'
• 0 if *s1 and *s2 is equal to 'nil'
• a value less than 0 if *s1 is 'nil'
• a value larger than 0 if *s2 is 'nil

MT Safety:

UNSAFE. This operation does not protect against the left or right side from being modified by another thread while the comparison is made.