rwsf::CString

HydraExpress C++ API Reference Guide
Rogue Wave web site: Home Page | Main Documentation Page

rwsf::CString

Group: Core String Manipulation


Does not inherit

Local Index
Header File
Description
Public Enums
Public Constructors
Public Destructors
Public Static Member Functions
Public Member Functions
Public Operators

Local Index

Members

append()
byteCount()
capacity()
caseCompare
collate()
compareTo()
contains()
copy()
CString()

data()
first()
hash()
index()
insert()
isAscii()
isNull()
last()
length()

mbLength()
operator std::string()
operator()()
operator+=()
operator=()
operator[]()
prepend()
remove()
replace()

resize()
strip()
stripType
stripWhitespace()
subString()
toLower()
toUpper()
~CString()

Header File

#include rwsf/core/CString.h

Description

Class rwsf::CString offers powerful and convenient facilities for manipulating strings.

Although the class is primarily intended to be used to handle single-byte character sets (SBCS; such as ASCII or ISO Latin-1), with care it can be used to handle multibyte character sets (MBCS). There are two things that must be kept in mind when working with MBCS:

Because characters can be more than one byte long, the number of bytes in a string can, in general, be greater than the number of characters in the string. Use function rwsf::CString::length() to get the number of bytes in a string, function rwsf::CString::mbLength() to get the number of characters. Note that the latter is much slower because it must determine the number of bytes in every character. Hence, if the string is known to be nothing but SBCS, then rwsf::CString::length() is preferred.
One or more bytes of a multibyte character can be zero. Hence, MBCS cannot be counted on being null terminated. In practice, it is a rare MBCS that uses embedded nulls. Nevertheless, you should be aware of this and program defensively. In any case, class rwsf::CString can handle embedded nulls.

Parameters of type constchar* must not be passed a value of zero. This is detected in the debug version of the library.

A separate class rwsf::CSubString supports substring extraction and modification operations.

Deprecated. Use std::string instead.

Public Enums

caseCompare { exact, ignoreCase, ignoreCaseStrict }

Used to specify whether comparisons, searches, and hashing functions should use case sensitive (exact) or case-insensitive (ignoreCase) semantics.

stripType { leading, trailing, both }

Used to specify whether characters are stripped from the beginning of the string, the end, or both.

Public Constructors

CString();

Creates a string of length zero (the null string).

CString(size_t ic);

Creates a string of length zero (the null string). The string's capacity (that is, the size it can grow to without resizing) is given by the parameter ic. We recommend creating a size_t value from a numerical constant to pass into this constructor. While size_t knows how to convert size_t's to itself, conforming compilers will choose the conversion to char instead.

CString(const CString & str);

Copy constructor. The created string will copystr's data.

CString(const char * cstr);

Conversion from the null-terminated character string cstr. The created string will copy the data pointed to by cstr, up to the first terminating null.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString(const char * cstr,
    size_t len);

Constructs a string from the character string cstr. The created string will copy the data pointed to by cstr. Exactly len bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cstr must be at least len bytes long.

CString(char c,
    size_t rep);

Constructs a string composed of the character c repeated rep times.

CString(const CSubString & str);

Conversion from sub-string. The created string will copy the substring represented by str.

CString(const std::string & str);

Conversion from std::string. The created string will copy the value represented by str.

Public Destructors

~CString();

Destructor.

Public Static Member Functions

size_t
byteCount(const char * cstr,
    size_t nChars = RWSF_NPOS);

Given a multibyte sequence, cstr, and a number of multibyte characters to consider, nChars, this method calculates the number of bytes required to store the sequence. If nChars is RWSF_NPOS, then the method counts characters up to, but not including, the first NULL character in the sequence. The method returns the number of bytes required to represent the string. If an error occurs during the operation, then RWSF_NPOS is returned.

unsigned
hash(const CString & str);

Returns the hash value of str as returned by str.hash(CString::exact).

size_t
mbLength(const char * cstr,
    size_t nBytes = RWSF_NPOS);

Given a multibyte character sequence, cstr, and a number of bytes to consider, nBytes, this method calculates the number of multibyte characters in the sequence. If nBytes is RWSF_NPOS, then the method counts the characters up to, but not including, the first occurrence of a NULL character. The method returns the length, in characters, of the input multibyte sequence if successful. If an error occurs in the conversion, then RWSF_NPOS is returned.

Public Member Functions

CString &
append(const char * cstr);

Append a copy of the null-terminated character string pointed to by cstr to self. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
append(const char * cstr,
    size_t len);

Append a copy of the character string cstr to self. Exactly len bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cstr must be at least len bytes long. Returns a reference to self.

CString &
append(const CString & str);

Append a copy of the string str to self. Returns a reference to self.

CString &
append(const CString & str,
    size_t len);

Append the first len bytes or the length of str (whichever is less) to self. Returns a reference to self.

CString &
append(char c,
    size_t rep = 1);

Append rep copies of the character c to self. The default is 1. Returns a reference to self.

size_t
capacity() const;

Return the current capacity of self. This is the number of bytes the string can hold without resizing.

size_t
capacity(size_t capac);

Hint to the implementation to change the capacity of self to capac. Returns the actual capacity.

int
collate(const char * cstr) const;

Returns an int less then, greater than, or equal to zero.

int
collate(const CString & str) const;

Returns an int less then, greater than, or equal to zero.

int
compareTo(const CString & str,
    caseCompare cmp = exact) const;

Returns an int less than, greater than, or equal to zero. Case sensitivity is according to the cmp argument, and may be CString::exact or CString::ignoreCase.

Note

If cmp is exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings. This function is incompatible with constchar* strings with embedded nulls. This function may be incompatible with constchar* MBCS strings.

int
compareTo(const char * cstr,
    caseCompare cmp = exact) const;

Returns an int less than, greater than, or equal to zero. Case sensitivity is according to the cmp argument, and may be CString::exact or CString::ignoreCase.

Note

int
compareTo(const CString * str,
    caseCompare cmp = exact) const;

Returns an int less than, greater than, or equal to zero. Case sensitivity is according to the cmp argument, and may be CString::exact or CString::ignoreCase.

Note

bool
contains(const char * pat,
    caseCompare cmp = exact) const;

Pattern matching. Returns true if pat occurs in self. Case sensitivity is according to the cmp argument, and may be CString::exact or CString::ignoreCase.

Note

bool
contains(const CString & pat,
    caseCompare cmp = exact) const;

Pattern matching. Returns true if pat occurs in self. Case sensitivity is according to the cmp argument, and may be CString::exact or CString::ignoreCase.

Note

CString
copy() const;

Makes a distinct copy. Attaches to and increments the reference count.

const char *
data() const;

Access to the rwsf::CString's data as a null terminated string. This datum is owned by the rwsf::CString and may not be deleted or changed. If the rwsf::CString object itself changes or goes out of scope, the pointer value previously returned will become invalid. While the string is null terminated, note that its length is still given by the member function length(). That is, it may contain embedded nulls.

size_t
first(char c) const;

Returns the index of the first occurrence of the character c in self. Returns RWSF_NPOS if there is no such character or if there is an embedded null prior to finding c.

Note

This function is incompatible with strings with embedded nulls. This function is incompatible with MBCS strings.

size_t
first(char c,
    size_t i) const;

Returns the index of the first occurrence of the character c in self. Continues to search past embedded nulls, up to i characters. Returns RWSF_NPOS if there is no such character.

Note

This function is incompatible with MBCS strings.

size_t
first(const char * cstr) const;

Returns the index of the first occurrence in self of any character in cstr. Returns RWSF_NPOS if there is no match or if there is an embedded null prior to finding any character from cstr.

Note

This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.

size_t
first(const char * cstr,
    size_t i) const;

Returns the index of the first occurrence in self of any character in cstr. Exactly i bytes in cstr are checked including any embedded nulls so cstr must point to a buffer containing at least i bytes. Returns RWSF_NPOS if there is no match.

unsigned
hash(caseCompare cmp = exact) const;

Returns a suitable hash value.

Note

If cmp is ignoreCase, then this function will be incompatible with MBCS strings.

size_t
index(const char pat,
    size_t i = 0,
    caseCompare cmp = exact) const;

Pattern matching. Starting with index i, searches for the first occurrence of pat in self and returns the index of the start of the match. Returns RWSF_NPOS if there is no such pattern. Case sensitivity is according to the cmp argument; it defaults to exact.

Note

If cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.

size_t
index(const char * pat,
    size_t i = 0,
    caseCompare cmp = exact) const;

Note

If cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.

size_t
index(const CString & s,
    size_t i = 0,
    caseCompare cmp = exact) const;

Note

If cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.

size_t
index(const char * pat,
    size_t patlen,
    size_t i,
    caseCompare cmp) const;

Pattern matching. Starting with index i, searches for the first occurrence of the first patlen bytes from pat in self and returns the index of the start of the match. Returns RWSF_NPOS if there is no such pattern. Case sensitivity is according to the cmp argument.

Note

If cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.

size_t
index(const CString & s,
    size_t patlen,
    size_t i,
    caseCompare cmp) const;

Note

If cmp = exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.

CString &
insert(size_t pos,
    const char * cstr);

Insert a copy of the null-terminated string cstr into self at byte position pos, thus expanding the string. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
insert(size_t pos,
    const char * cstr,
    size_t len);

Insert a copy of the first len bytes of cstr into self at byte position pos, thus expanding the string. Exactly len bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cstr must be at least len bytes long. Returns a reference to self.

CString &
insert(size_t pos,
    const CString & str);

Insert a copy of the string str into self at byte position pos. Returns a reference to self.

CString &
insert(size_t pos,
    const CString & str,
    size_t len);

Insert a copy of the first len bytes or the length of str (whichever is less) of str into self at byte position pos. Returns a reference to self.

bool
isAscii() const;

Returns true if self contains no bytes with the high bit set.

bool
isNull() const;

Returns true if this is a zero length string (i.e., the null string).

size_t
last(char c) const;

Returns the index of the last occurrence in the string of the character c. Returns RWSF_NPOS if there is no such character or if there is an embedded null to the right of c in self.

Note

This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.

size_t
last(char c,
    size_t i) const;

Returns the index of the last occurrence in the string of the character c. Continues to search past embedded nulls, up to i characters. Returns RWSF_NPOS if there is no such character.

Note

This function is incompatible with MBCS strings.

size_t
length() const;

Return the number of bytes in self.

Note

If self contains multibyte characters, then this will not be the number of characters.

size_t
mbLength() const;

Return the number of multibyte characters in self, according to the Standard C function mblen(). Returns RWSF_NPOS if a bad character is encountered.

Note

In general, mbLength()=length(). Provided only on platforms that provide mblen().

CString &
prepend(const char * cstr);

Prepend a copy of the null-terminated character string pointed to by cstr to self. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
prepend(const char * cstr,
    size_t len);

Prepend a copy of the character string cstr to self. Exactly len bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cstr must be at least len bytes long. Returns a reference to self.

CString &
prepend(const CString & str);

Prepends a copy of the string str to self. Returns a reference to self.

CString &
prepend(const CString & str,
    size_t len);

Prepend the first len bytes or the length of str (whichever is less) of str to self. Returns a reference to self.

CString &
prepend(char c,
    size_t rep = 1);

Prepend rep copies of character c to self. Returns a reference to self.

CString &
remove(size_t pos);

Removes the bytes from the byte position pos, which must be no greater than length(), to the end of string. Returns a reference to self.

CString &
remove(size_t pos,
    size_t N);

Removes N bytes or to the end of string (whichever comes first) starting at the byte position pos, which must be no greater than length(). Returns a reference to self.

CString &
replace(size_t pos,
    size_t N,
    const char * cstr);

Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the null-terminated string cstr. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
replace(size_t pos,
    size_t N,
    const char * cstr,
    size_t len);

Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string cstr. Exactly len bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cstr must be at least len bytes long. Returns a reference to self.

CString &
replace(size_t pos,
    size_t N,
    const CString & str);

Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string str. Returns a reference to self.

CString &
replace(size_t pos,
    size_t N,
    const CString &,
    size_t len);

Replaces N bytes or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the first len bytes, or the length of str (whichever is less), from str. Returns a reference to self.

void
resize(size_t n);

Changes the length of self to n bytes, adding blanks or truncating as necessary.

CSubString
strip(stripType s = trailing,
    char c = ' ');

Returns a substring of self where the character c has been stripped off the beginning, end, or both ends of the string.

The enum stripType can take values:

leading

Remove characters at beginning

trailing

Remove characters at end

both

Remove characters at both ends

CSubString
strip(stripType s = trailing,
    char c = ' ') const;

Returns a substring of self where the character c has been stripped off the beginning, end, or both ends of the string.

The enum stripType can take values:

leading

Remove characters at beginning

trailing

Remove characters at end

both

Remove characters at both ends

CSubString
stripWhitespace(stripType s = trailing);

Returns a substring of self where any whitespace (space, tab, newline, carriage return) has been stripped off the beginning, end, or both ends of the string. The interpretation of stripType is the same as the strip() function.

CSubString
stripWhitespace(stripType s = trailing) const;

CSubString
subString(const char * pat,
    size_t start = 0,
    caseCompare = exact) const;

Returns a substring representing the first occurence of the null-terminated string pointed to by pat. Case sensitivity is according to the caseCompare argument; it defaults to rwsf::CString::exact.

Note

If caseCompare is rwsf::CString::ignoreCase then this function is incompatible with MBCS strings. This function is incompatible with pat strings with embedded nulls. This function may be incompatible with pat MBCS strings.

CSubString
subString(const char * pat,
    size_t start = 0,
    caseCompare = exact);

Note

void
toLower();

Changes all upper-case letters in self to lower-case.

Note

This function is incompatible with MBCS strings.

void
toUpper();

Changes all lower-case letters in self to upper-case.

Note

This function is incompatible with MBCS strings.

Public Operators

char
operator()(size_t i) const;

Returns the ith character of the substring. The index i must be between zero and the length of the substring, less one. Bounds checking is not performed.

char &
operator()(size_t i);

Returns the ith character of the substring. The index i must be between zero and the length of the substring, less one. Bounds checking is not performed.

CSubString
operator()(size_t start,
    size_t len) const;

Substring operator. Returns an rwsf::CSubString of self with length len, starting at index start.

The sum of start plus len must be less than or equal to the string length. If the library was built using the RWSF_CORE_DEBUG flag, and start and len are out of range, then an exception of type rwsf::OutOfBoundsException will occur.

CSubString
operator()(size_t start,
    size_t len);

Substring operator. Returns an rwsf::CSubString of self with length len, starting at index start.

char &
operator[](short);

Returns the ith character of the substring. The index i must be between zero and the length of the substring, less one. Bounds checking is performed: if the index is out of range, then an exception of type rwsf::OutOfBoundsException is thrown.

char &
operator[](int);

char &
operator[](long);

char &
operator[](unsigned short);

char &
operator[](unsigned int);

char &
operator[](unsigned long);

char &
operator[](rwsflonglong);

char &
operator[](rwsfulonglong);

char
operator[](short) const;

char
operator[](int) const;

char
operator[](long) const;

char
operator[](unsigned short) const;

char
operator[](unsigned int) const;

char
operator[](unsigned long) const;

char
operator[](rwsflonglong) const;

char
operator[](rwsfulonglong) const;

CString &
operator+=(const char * cstr);

Append the null-terminated character string to self. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
operator+=(const CString & str);

Append the string str to self. Returns a reference to self.

CString &
operator+=(char c);

Append the character c to self. Returns a reference to self.

CString &
operator=(const char * cstr);

Assignment operator. Copies the null-terminated character string pointed to by cstr into self. Returns a reference to self.

Note

This function is incompatible with cstr strings with embedded nulls. This function may be incompatible with cstr MBCS strings.

CString &
operator=(const CString & str);

Assignment operator. The string will replace the string's data. Returns a reference to self.

operator std::string() const;

Conversion operator. Converts an rwsf::CString instance to a std::string value.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.