RTI Connext C API Version 7.3.0

<<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. More...
 
char * DDS_String_dup (const char *str)
 Clone a string. Creates a new string that duplicates the value of string. More...
 
char * DDS_String_replace (char **string_ptr, const char *new_value)
 Assign a new value to a string. Replaces the string pointed to by string_ptr, with a string whose value is new_value. More...
 
void DDS_String_free (char *str)
 Delete a string. More...
 
DDS_WcharDDS_Wstring_alloc (DDS_UnsignedLong length)
 Create a new empty string that can hold up to length wide characters. More...
 
DDS_UnsignedLong DDS_Wstring_length (const DDS_Wchar *str)
 Get the number of wide characters in the given string. More...
 
DDS_WcharDDS_Wstring_copy (DDS_Wchar *dst, const DDS_Wchar *src)
 Copy the source string over the destination string reallocating the space if it's necessary. More...
 
DDS_WcharDDS_Wstring_copy_and_widen (DDS_Wchar *dst, const char *src)
 Copy the source string over the destination string, widening each character. More...
 
DDS_WcharDDS_Wstring_dup (const DDS_Wchar *str)
 Clone a string of wide characters. Creates a new string that duplicates the value of string. More...
 
DDS_WcharDDS_Wstring_dup_and_widen (const char *str)
 Clone a string of characters as a string of wide characters. More...
 
void DDS_Wstring_free (DDS_Wchar *str)
 Delete a string. More...
 

Detailed Description

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

The functions 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 functions that define a string class whose data is represented by a 'char*'.

String Conventions

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

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:

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.
void DDS_String_free(char *str)
Delete a string.
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.

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:

Note
When dealing with the DDS_PublishModeQosPolicy::flow_controller_name and DDS_MultiChannelQosPolicy::filter_name fields, we advise taking a look at the sample code for how to properly assign new values and free the old ones.
See also
DDS_StringSeq

Function Documentation

◆ DDS_String_alloc()

char * DDS_String_alloc ( size_t  length)

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

A string created by this function 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.
Examples
HelloWorld.c.

◆ DDS_String_dup()

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 function must be deleted using DDS_String_free()

Parameters
str<<in>> The string to duplicate.
Returns
If string == NULL, this function always returns NULL. Otherwise, upon success it returns a newly created string whose value is string; upon failure it returns NULL.

◆ DDS_String_replace()

char * DDS_String_replace ( char **  string_ptr,
const char *  new_value 
)

Assign a new value to a string. Replaces the string pointed to by string_ptr, with a string whose value is new_value.

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

This function is most commonly used when manipulating string sequences, DDS_StringSeq.

Precondition
string_ptr be a non-NULL pointer. *string_ptr must be either NULL, or a string created using DDS_String_alloc() or DDS_String_dup(), or DDS_String_replace().
Parameters
string_ptr<<inout>> Pointer to the string to replace.
new_value<<in>> The value of the replacement string.
Returns
If new_value = NULL, this function always returns NULL. Otherwise, upon success it returns *string_ptr whose value is new_value; upon failure it returns NULL.
Postcondition
If new_value = NULL, *string_ptr == NULL. Otherwise, upon success string_ptr contains a pointer to a string whose value is new_value; upon failure, string_ptr is left unchanged.

◆ DDS_String_free()

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.c.

◆ DDS_Wstring_alloc()

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 function 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_Wstring_length()

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_Wstring_copy()

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_Wstring_copy_and_widen()

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_Wstring_dup()

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 function must be deleted using DDS_Wstring_free().

Parameters
str<<in>> The string to duplicate.
Returns
If string == NULL, this function always returns NULL. Otherwise, upon success it returns a newly created string whose value is string; upon failure it returns NULL.

◆ DDS_Wstring_dup_and_widen()

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 function must be deleted using DDS_Wstring_free()

Parameters
str<<in>> The string to duplicate.
Returns
If string == NULL, this function always returns NULL. Otherwise, upon success it returns a newly created string whose value is string; upon failure it returns NULL.

◆ DDS_Wstring_free()

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.