RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
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_length (const char *string)
 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*'.

Conventions

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

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:

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:


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 
   \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.
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.
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 == s2, > 0 if s1 > s2 and < 0 if s1 < s2
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 null-termination character. If a NULL value is passed as argument, RTI_SIZE_INVALID will be returned.

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc