Library | File Standard Definitions

CIP string Type

# include <cipxx.h>

typedef cStringT xrstring
# define xstringnil ((xrstring) -1)
 
typedef cWStringT xrwstring
# define xwstringnil ((xrwstring) -1)


typedef struct __xstring_c
{
     void *buffer;
     String mbstr;
     Wstring wcstr;
 
} xstring_c;


class xstring
{
public:
     xstring ()
     xstring (const xstring &str)
     xstring (const xstring_c &str)
     xstring (cStringT str)
     xstring (cWStringT str)
     xstring (cStringT str1, cStringT str2)
     xstring (cWStringT str1, cWStringT str2)
     xstring (cStringT str, int len)
     xstring (cWStringT str, int len)
     xstring (cStringT str, int from, int to)
     xstring (cWStringT str, int from, int to)
     xstring (strstream & stream)
 
     operator cStringT ();
     operator cWStringT ();
 
     xstring_c getxstring_c () const;
 
     xstring &operator= (cStringT str);
     xstring &operator= (cWStringT str);
     xstring &operator= (const xstring &str);
     xstring &operator= (const xstring_c &str);
     xstring &operator= (strstream &stream);
 
     xstring &operator+= (Char ch);
     xstring &operator+= (WChar ch);
     xstring &operator+= (cStringT str);
     xstring &operator+= (cWStringT str);
     xstring &operator+= (const xstring &str);
 
     bool IsNull () const;
     bool IsEmpty () const;
     size_t GetMBSize () const;
     int GetLength () const;
 
     bool ToInt (int *out_val) const;
     bool ToDouble (double *out_val) const;
 
     xstring ToUpper () const;
     xstring ToLower () const;
 
     xstring Substring (int from, int to = -1) const;
 
     int GetNWords (cStringT seps = " \t\n") const;
     int GetNWords (cWStringT seps) const;
     int GetNWords (const xstring &seps) const;
 
     xstring GetWord (int idx, cStringT seps = " \t\n") const;
     xstring GetWord (int idx, cWStringT seps) const;
     xstring GetWord (int idx, const xstring &seps) const;
 
     int Pos (cStringT substring) const;
     int Pos (cWStringT substring) const;
     int Pos (const xstring &substring) const;
 
     bool Match (cStringT pattern) const;
     bool Match (cWStringT pattern) const;
     bool Match (const  xstring &pattern) const;
 
     void Substitute (cStringT target, cStringT replacement, int firstOccur = 1, int maxCount = -1);
     void Substitute (cWStringT target, cWStringT replacement, int firstOccur = 1, int maxCount = -1);
     void Substitute (const xstring &target, const xstring &replacement, int firstOccur = 1, int maxCount = -1);
 
     static xstring Printf (cStringT format, ...);
};


bool operator== (const xstring &str1, cStringT str2);
bool operator== (const xstring &str1, cWStringT str2);
bool operator== (cWStringT str1, const xstring &str2);
bool operator== (cStringT str1, const xstring &str2);
bool operator== (const xstring &str1, const xstring &str2);
 
bool operator!= (const xstring &str1, cStringT str2);
bool operator!= (const xstring &str1, cWStringT str2);
bool operator!= (cStringT str1, const xstring &str2);
bool operator!= (cWStringT str1, const xstring &str2);
bool operator!= (const xstring &str1, const xstring &str2);
 
xstring operator+ (const xstring &str1, cStringT str2);
xstring operator+ (const xstring &str1, cWStringT str2);
xstring operator+ (cStringT str1, const xstring &str2);
xstring operator+ (cWStringT str1, const xstring &str2);
xstring operator+ (const xstring &str1, const xstring &str2);
 
xstring operator<< (ostream &os, const xstring &str);


Description

Class xstring represents character strings. A string is stored as either a multibyte string or as a wide character string, or as both. Memory is allocated on demand and owned by the xstring object. When an xstring object is assigned to another xstring object, the memory allocated for the string storage does not get duplicated. xstring uses reference counting mechanism for its memory management. xstring object is allowed to have a null value; a null string is not the same as an empty string.

Warning:

xstringnil(xwstringnil) is not the same as a NULL pointer in C/C++. Do not pass a C/C++ NULL pointer to xstring methods, use these inline functions to convert between C-style and CIP-style optional string pointers.


Constructors

xstring ()
  Constructs a new null xstring.

xstring (const xstring &str)
  Copy constructor. Constructs a new xstring that contains the same sequence of characters as the xstring object passed as parameter. Memory allocated for the string storage does not get duplicated.

xstring (const xstring_c &str)
  Constructs a new xstring object that contains the same sequence of characters as the xstring_c object passed as parameter. Memory allocated for the string storage does not get duplicated.

xstring (cStringT str)
  Constructs a new xstring object from a multibyte string.

xstring (cWStringT str)
  Constructs a new xstring object from a wide string.

xstring (cSring str1, cStringT str2)
  Constructs a new xstring object that contains the concatenation of the two given multibyte strings.

xstring (CWSring str1, cWStringT str2)
  Constructs a new xstring object that contains the concatenation of the two given wide strings.

xstring (cSring str, int len)
  Constructs a new xstring object from the source multibyte string truncated to the given length (in characters).

xstring (CWSring str, int len)
  Constructs a new xstring object from the source wide string truncated to the given length (in characters).

xstring (cSring str1, int from, int to)
  Constructs a new xstring object from the source multibyte string. The result starts with character with index from and ends with character with index (to-1). If index to is -1, the source string is copied up to the end.

xstring (CWSring str1, int from, int to)
  Constructs a new xstring object from the source wide string. The result starts with character with index from and ends with character with index (to-1). If index to is -1, the source string is copied up to the end.

xstring (strstream &steam)
  Constructs a new xstring object from the contents of the strstream.


Operators

operator cStringT () const
  Returns the contents of the xstring object as a multibyte string. For a null string returns xstringnil. The returned string is owned by the xstring object and should not be deallocated by a caller.

operator cWStringT () const
  Returns the contents of the xstring object as a wide string. For a null string returns xwstringnil. The returned string is owned by the xstring object and should not be deallocated by a caller.

xstring &operator= (cStringT str)
  Assigns a multibyte string to the xstring object. Returns a reference to this xstring object.

xstring &operator= (cWStringT str)
  Assigns a wide string to the xstring object. Returns a reference to this xstring object.

xstring &operator= (const xstring &str)
  Assigns another xstring object to this xstring object. Returns a reference to this xstring object. The memory allocated for the string storage does not get duplicated.

xstring &operator= (const xstring_c &str)
  Assigns a C-style xstring_c object to this xstring object. Returns a reference to this xstring object. The memory allocated for the string storage does not get duplicated.

xstring &operator= (strstream &stream)
  Assigns contents of the strstream to this xstring object. Returns a reference to this xstring object.

xstring &operator+= (Char ch)
  Modifies the contents of the xstring object by appending a character to the end of the string. Returns a reference to the modified xstring object.

xstring &operator+= (WChar ch)
  Modifies the contents of the xstring object by appending a wide character to the end of the string. Returns a reference to the modified xstring object.

xstring &operator+= (cStringT str)
  Modifies the contents of the xstring object by appending a multibyte string to the end of the string. Returns a reference to the modified xstring object.

xstring &operator+= (cWStringT str)
  Modifies the contents of the xstring object by appending a wide string to the end of the string. Returns a reference to the modified xstring object.

xstring &operator+= (const xstring &str)
  Modifies the contents of the xstring object by appending a string represented by another xstring object the end of the string. Returns a reference to the modified xstring object.


Methods

xstring_c getxstring_c () const
  Returns a C-style xstring_c object corresponding to the xstring object.

bool IsNull () const
  Returns true if this xstring object is a null string, otherwise returns false. Null string is not the same as empty string. A string is null if it was created by the xstring default constructor or if it was assigned another null string, xstringnil or xwstringnil.

bool IsEmpty () const
  Returns true if this xstring object is a null string or an empty string (""), otherwise returns false.

size_t GetMBSize () const
  Returns size in bytes, including the last NULL character, of the multibyte representation contained by this string. This method does not allocate a multibyte representation is not already allocated.

int GetLength () const
  Returns the length in characters of the string represented by this xstring object.

bool ToInt (int *out_val) const
  Converts the string represented by this xstring object to an integer. If conversion fails returns false.

bool ToDouble (double *out_val) const
  Converts the string represented by this xstring object to a real number. If conversion fails returns false.

xstring ToUpper () const
  Converts the content of the given xstring object to the upper case. Creates and returns a new xstring object which contains the resulting string consisting of all upper case charaters. The original xstring object does not get modified.

xstring ToLower () const
  Converts the content of the given xstring object to the lower case. Creates and returns a new xstring object which contains the resulting string consisting of all lower case charaters. The original xstring object does not get modified.

xstring Substring (int from, int to = -1) const
  Creates a new xstring object which contains a substring of the string represented by this xstring. The resulting string starts with character with index (from) and ends with the character with index (to-1). If index (to) is -1, the string is copied up to the end.

int GetNWords (cStringT seps = " \t\n") const
int GetNWords (cWStringT seps) const
int GetNWords (const xstring &seps) const
  Returns the number of words in the string represented by this xstring object. Words are considered to be separated by one of the charaters of string (seps).

xstring GetWord (int idx, cStringT seps = " \t\n") const
xstring GetWord (int idx, cWStringT seps) const
xstring GetWord (int idx, const xstring &seps) const
  Returns the new xstring object which contains the word with index (idx) of the string represented by this xstring object. Words are considered to be separated by one of the charaters of string (seps).

int Pos (cStringT substring) const
int Pos (cWStringT substring) const
int Pos (const xstring &substring) const
  Returns position in characters of the first occurence of a substring in the string represented by this xstring object. If the substring is not found returns -1.

bool Match (cStringT pattern) const
bool Match (cWStringT pattern) const
bool Match (const xstring &pattern) const
  Verifies if the string represented by this xstring object matches to a shell style pattern.

void Substitute (cStringT target, cStringT replacement, int firstOccur = 1, int maxCount = -1)
void Substitute (cWStringT target, cWStringT replacement, int firstOccur = 1, int maxCount = -1)
void Substitute (const xstring &target, const xstring &replacement, int firstOccur = 1, int maxCount = -1)
  Modifies the string represented by this xstring object by replacing at most (maxCount) occurences of substring (target) with string (replacement) beginning with occurence (firstOccur). If (maxCount) is -1, substitutes up to the end of the string.

static xstring Printf (cStringT format, ...)
  Returns a new xstring object which contains the method arguments converted and formated under control of the first argument (format). For detailed specification refer to the description of function sprintf in the standard C I/O library.


Global Operators

bool operator== (const xstring &str1, cStringT str2)
bool operator== (const xstring &str1, cWStringT str2)
bool operator== (const cStringT str1, const xstring &str2)
bool operator== (const cWStringT str1, const xstring &str2)
bool operator== (const xstring &str1, const xstring &str2)
  Compares two strings. Returns true if the strings are equal.

bool operator!= (const xstring &str1, cStringT str2)
bool operator!= (const xstring &str1, cWStringT str2)
bool operator!= (const cStringT str1, const xstring &str2)
bool operator!= (const cWStringT str1, const xstring &str2)
bool operator!= (const xstring &str1, const xstring &str2)
  Compares two strings. Returns true if the strings are not equal.

xstring operator+ (const xstring &str1, cStringT str2)
xstring operator+ (const xstring &str1, cWStringT str2)
xstring operator+ (cWStringT str1, const xstring &str2)
xstring operator+ (cStringT str1, const xstring &str2)
xstring operator+ (const xstring &str1, const xstring &str2)
  Creates a new string by concatenating of string (str2) to the end of string (str1).

ostream &operator<< (ostream &os, const xstring &str)
  Outputs string represented by the xstring object to output stream (os).


Converters between C-Style and CIP-Style Optional String Pointers

cStringT XOPTCVT_CS2XS (cStringT cs)
cWStringT XOPTCVT_CS2XS (cWStringT cs)
  Converts a C-style optional string pointer to a CIP-style optional string pointer. C NULL pointer is converted to xstringnil/xwstringnil.

cStringT XOPTCVT_XS2CS (cStringT cs)
cWStringT XOPTCVT_XS2CS (cWStringT cs)
  Converts a CIP-style optional string pointer to a C-style optional string pointer. CIP xstringnil/xwstringnil value is converted to a C NULL pointer.