String Support

<<extension>> String creation, cloning, assignment, and deletion. More...

Functions
char *	DDS_String_alloc (size_t 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.
DDS_Wchar *	DDS_Wstring_alloc (DDS_UnsignedLong length)
	Create a new empty string that can hold up to length wide characters.
DDS_UnsignedLong	DDS_Wstring_length (const DDS_Wchar *str)
	Get the number of wide characters in the given string.
DDS_Wchar *	DDS_Wstring_copy (DDS_Wchar *dst, const DDS_Wchar *src)
	Copy the source string over the destination string reallocating the space if it's necessary.
DDS_Wchar *	DDS_Wstring_copy_and_widen (DDS_Wchar *dst, const char *src)
	Copy the source string over the destination string, widening each character.
DDS_Wchar *	DDS_Wstring_dup (const DDS_Wchar *str)
	Clone a string of wide characters. Creates a new string that duplicates the value of string.
DDS_Wchar *	DDS_Wstring_dup_and_widen (const char *str)
	Clone a string of characters as a string of wide characters.
void	DDS_Wstring_free (DDS_Wchar *str)
	Delete a string.

Detailed Description

<<extension>> 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*'.

Conventions

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

• 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.
  • DDS_StringSeq is a value type that contains strings; it owns the memory for the contained strings. When a DDS_StringSeq is assigned or deleted, the contained strings are also assigned or deleted respectively.
• 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 must therefore make some assumptions when a user requests that a string be copied into. The following rules apply when RTI Connext is copying into a string or string sequence:

• If the 'char*' is NULL, RTI Connext 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 Usage below).
• If the 'char*' is not NULL, RTI Connext 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 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; you are likely to crash.

Usage

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

Always use 
     DDS_String_alloc() to create,
     DDS_String_dup() to clone,
     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."

See Also

DDS_StringSeq

Function Documentation

char* DDS_String_alloc

(

size_t

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 
   \p length characters, \b 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.

Examples:

HelloWorld.cxx.

Referenced by DDS_KeyedOctets::DDS_KeyedOctets(), and DDS_KeyedString::DDS_KeyedString().

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.

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.

Examples:

HelloWorld.cxx.

Referenced by DDS_KeyedOctets::DDS_KeyedOctets(), DDS_KeyedString::DDS_KeyedString(), DDS_KeyedOctets::~DDS_KeyedOctets(), and DDS_KeyedString::~DDS_KeyedString().

DDS_Wchar* DDS_Wstring_alloc

(

DDS_UnsignedLong

length

)

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

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

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

Parameters

length

<<in>> Capacity of the string.

Returns

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

DDS_UnsignedLong DDS_Wstring_length

(

const DDS_Wchar *

str

)

Get the number of wide characters in the given string.

The result does not count the terminating zero character.

Parameters

str	<<in>> A non-NULL string.

Returns

The number of wide characters in the string.

DDS_Wchar* DDS_Wstring_copy	(	DDS_Wchar *	dst,
		const DDS_Wchar *	src
	)

Copy the source string over the destination string reallocating the space if it's necessary.

Parameters

dst
src

Returns

dst

DDS_Wchar* DDS_Wstring_copy_and_widen	(	DDS_Wchar *	dst,
		const char *	src
	)

Copy the source string over the destination string, widening each character.

Parameters

dst	<<in>> A non-NULL string to be overwritten by src.
src	<<in>> A non-NULL string to be copied over dst

Returns

dst

DDS_Wchar* DDS_Wstring_dup

(

const DDS_Wchar *

str

)

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

A string created by this method must be deleted using DDS_Wstring_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.

DDS_Wchar* DDS_Wstring_dup_and_widen

(

const char *

str

)

Clone a string of characters as a string of wide characters.

A string created by this method must be deleted using DDS_Wstring_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.

void DDS_Wstring_free

(

DDS_Wchar *

str

)

Delete a string.

Precondition

string must either NULL, or must have been created using DDS_Wstring_alloc(), DDS_Wstring_dup(), or DDS_Wstring_replace()

Parameters

str	<<in>> The string to delete.