Overview

The RoseStringObject is an internal class used by some operations to wrap C-style strings with memory allocation and cleanup. ROSE library functions take or return const char*, which is easily passed to STL, CString, and other string classes.

This class manages string storage and provides operations for copy, concatenate, and buffer sizing. Use C-style functions that take const char* for any other string operation.

Constructor

RoseStringObject()
RoseStringObject (const RoseStringObject & other)
RoseStringObject (const char * str);

The RoseStringObject class provides a default constructor, a copy constructor, and one that initializes from a C-string.

The default constructor initializes the object to null. The C-string constructor allocates a new character buffer and copies the string.

The object copy constructor just shares the same character buffer as the original. Reference counts are kept and a the buffer will only be duplicated on write or when a non-const reference is used.

RoseStringObject r_string;		// equivalent
const char * c_string = NULL;

RoseStringObject r_string("foo"); 	// roughly equivalent (will copy)
const char * c_string = "foo";

Cast / as_const() / as_char()

operator char *()
operator const char *() const 

char * as_char()
char * as_const() const

The cast operators return the C string stored by this object. Objects may share the character buffer for efficiency, so there are two versions of these functions. Use the const version if you will not modify the string data. This lets the RoseStringObject store the string data more efficiently.

The const versions allow the object to continue sharing, while the others force the C string to only be used by that single object. The character pointer is only valid for as long as the RoseStringObject you got it from stays around.

The as_const() and as_char() functions are simply aliases for the const and non-const cast operations. The C++ compiler will automatically call the cast operators where typing is known, but it is clearer to use a function rather than a cast when using printf() and some other circumstances.

RoseStringObject name = "foo";

// automatic use of const char* cast
if (!strcmp(name, "bar"))
   return;

// use of function makes it clearer that we are dealing with an object
printf("my name is %s\n", name.as_const());

capacity()

size_t capacity() const;

The capacity() function returns the size of the memory buffer allocated for the string data. This is not the size of the string, but it is the maximum amount of string data (including the null terminator) that can be stored without reallocating the buffer.

Change the size of this buffer with resize()

cat()

RoseStringObject& cat (const char *);

RoseStringObject& operator+= (const char * s);
RoseStringObject& operator+= (const RoseStringObject& s);

The cat() function concatenates and assigns like strcat. It will resize the string as needed to hold the result. The "plus-equals" operator is an alias for cat().

catchar()

RoseStringObject& catchar (char c);

The catchar() function concatenates and assigns a single character. It will resize the string as needed to hold the result.

copy()

RoseStringObject& copy (const char *);
RoseStringObject& copy (const RoseStringObject&);

RoseStringObject& operator= (const char * s);
RoseStringObject& operator= (const RoseStringObject& s);

The assignment opertator (=) and copy() function assigns a string value to the object. The C-string assignment allocates a new character buffer and copies the string. The assignment tolerates null pointers.

The object assignment will reference and share the same character buffer as the original. Reference counts are kept and the buffer will only be duplicated on write or when a non-const reference is used.

RoseStringObject str1;
RoseStringObject str2;

str1 = foo; 		// allocate buffer, copy string
str1.copy(bar); 	// same, allocate and copy

str2 = str1;		// quick, share until write.
str2.copy(str1);	// quick, share until write.

is_empty() / is_null()

int operator!() const;
int is_null() const;

int is_empty() const;

The Not operartor, is_null() and is_empty() functions test whether the string object has a string setting.

The not operator and is_null() functions are equivalent, and they return true if the object contains no string buffer. The character pointer for the string object is a null pointer (zero).

The is_empty() function returns true if the object contains no string buffer or the empty string "".

RoseStringObject str;

if (!str) 		// easy test null
if (str.is_null())	// other test null

if (str.is_empty()) 	// test string null or ""

len()

size_t len() const;

The len() function returns the length of the string in the same way as the strlen() function. The function returns zero if the string is null or empty.

resize()

char * resize (size_t new_sz);

The resize() function sets the size of the char buffer, and any existing string data is copied. If the object was previously unset, the new string buffer will contain the empty string "". If the new size is zero, any existing string buffer will be deleted and the object will revert to unset.

The function returns a pointer to the new char buffer. Use capacity() to find the size of the data buffer.

RoseStringObject new_rs;
printf (old capacity was %d\n, new_rs.capacity());

char * c_string = new_rs.resize(20);	// get char[20] buffer;
c_string[0] = 'A';		// manipulate buffer directly;
c_string[1] = 0;		// manipulate buffer directly; 

ncat()

RoseStringObject& ncat (const char *, size_t sz);

The ncat() function concatenates the first sz characters with another string. This function tolerates nulls.

ncopy()

RoseStringObject& ncopy (const char *, size_t sz);
RoseStringObject& ncopy (const RoseStringObject&, size_t sz);

The ncopy() function assigns a the first sz characters of a string to the object. The function tolerates null pointers. If the input is a null string, the result will be a null string.