--- name: "ACE_CString" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_CString" --- # ACE\_CString(3) This class provides a wrapper facade for C strings. ## NAME ACE\_CString - This class provides a wrapper facade for C strings. ## SYNOPSIS ``` #include class ACE_CString { public: static const int npos; ACE_CString (ACE_Allocator *alloc = 0); ACE_CString ( const char *s, ACE_Allocator *alloc = 0, int release = 1 ); ACE_CString ( const char *s, size_t len, ACE_Allocator *alloc = 0, int release = 1 ); ACE_CString (const ACE_CString &); ACE_CString (const ACE_USHORT16 *s, ACE_Allocator *alloc = 0); ACE_CString (char c, ACE_Allocator *alloc = 0); ~ACE_CString (void); const char &operator [] (size_t slot) const; char &operator [] (size_t slot); ACE_CString &operator = (const ACE_CString &); void set (const char *s, int release = 1); void set (const char *s, size_t len, int release); ACE_CString substring (size_t offset, ssize_t length = -1) const; ACE_CString substr (size_t offset, ssize_t length = -1) const; ACE_CString &operator += (const ACE_CString &); u_long hash (void) const; size_t length (void) const; char *rep (void) const; const char *fast_rep (void) const; const char *c_str (void) const; int strstr (const ACE_CString &s) const; int find (const ACE_CString &str, int pos = 0) const; int find (const char *s, int pos = 0) const; int find (char c, int pos = 0) const; int rfind (char c, int pos = npos) const; int operator == (const ACE_CString &s) const; int operator < (const ACE_CString &s) const; int operator > (const ACE_CString &s) const; int operator != (const ACE_CString &s) const; int compare (const ACE_CString &s) const; void dump (void) const; ACE_ALLOC_HOOK_DECLARE; private: ACE_Allocator *allocator_; size_t len_; size_t buf_len_; char *rep_; int release_; static char NULL_CString_; }; ``` ## DESCRIPTION This class uses an ACE\_Allocator to allocate memory. The user can make this a persistant class by providing an ACE\_Allocator with a persistable memory pool. NOTE: if an instance of this class is constructed from or assigned an empty string (with first element of '\\0'), then it is \_not\_ allocated new space. Instead, its internal representation is set equal to a global empty string. CAUTION: in cases when ACE\_CString is constructed from provided buffer with release parameter set to 0, ACE\_CString is not guaranteed to be '\\0' terminated. This is a place holder until all compilers implement the ANSI/ISO C++ standard String class. ## PUBLIC MEMBERS ``` static const int npos; ``` No position constant ``` ACE_CString (ACE_Allocator *alloc = 0); ``` Default constructor. ``` ACE_CString ( const char *s, ACE_Allocator *alloc = 0, int release = 1 ); ``` Constructor that copies s into dynamically allocated memory. If release is non-0 then the ACE\_allocator is responsible for freeing this memory. Memory is \_not\_ allocated/freed if release is 0. ``` ACE_CString ( const char *s, size_t len, ACE_Allocator *alloc = 0, int release = 1 ); ``` Constructor that copies len chars of s into dynamically allocated memory (will NUL terminate the result). If release is non-0 then the ACE\_allocator is responsible for freeing this memory. Memory is \_not\_ allocated/freed if release is 0. ``` ACE_CString (const ACE_CString &); ``` Copy constructor. ``` ACE_CString (const ACE_USHORT16 *s, ACE_Allocator *alloc = 0); ``` Constructor that copies s into dynamically allocated memory. Probable loss of data. Please use with care. ``` ACE_CString (char c, ACE_Allocator *alloc = 0); ``` Constructor that copies c into dynamically allocated memory. ``` ~ACE_CString (void); ``` Deletes the memory... ``` const char &operator [] (size_t slot) const; ``` Return the slot'th character in the string (doesn't perform bounds checking). ``` char &operator [] (size_t slot); ``` Return the slot'th character by reference in the string (doesn't perform bounds checking). ``` ACE_CString &operator = (const ACE_CString &); ``` Assignment operator (does copy memory). ``` void set (const char *s, int release = 1); ``` Copy s into this ACE\_CString. Memory is \_not\_ allocated/freed if release is 0. ``` void set (const char *s, size_t len, int release); ``` Copy len bytes of s (will NUL terminate the result). Memory is \_not\_ allocated/freed if release is 0. ``` ACE_CString substring (size_t offset, ssize_t length = -1) const; ``` Return a substring given an offset and length, if length == -1 use rest of str. Return empty substring if offset or offset/length are invalid. ``` ACE_CString substr (size_t offset, ssize_t length = -1) const; ``` Same as substring. ``` ACE_CString &operator += (const ACE_CString &); ``` Concat operator (copies memory). ``` u_long hash (void) const; ``` Returns a hash value for this string. ``` size_t length (void) const; ``` Return the length of the string. ``` char *rep (void) const; ``` Get a copy of the underlying pointer. ``` const char *fast_rep (void) const; ``` Get at the underlying representation directly! \_Don't\_ even think about casting the result to (char \*) and modifying it, if it has length 0! ``` const char *c_str (void) const; ``` Same as STL String's c\_str and fast\_rep. ``` int strstr (const ACE_CString &s) const; ``` Comparison operator that will match substrings. Returns the slot of the first location that matches, else -1. ``` int find (const ACE_CString &str, int pos = 0) const; ``` Find str starting at pos. Returns the slot of the first location that matches, else npos. ``` int find (const char *s, int pos = 0) const; ``` Find s starting at pos. Returns the slot of the first location that matches, else npos. ``` int find (char c, int pos = 0) const; ``` Find c starting at pos. Returns the slot of the first location that matches, else npos. ``` int rfind (char c, int pos = npos) const; ``` Find c starting at pos (counting from the end). Returns the slot of the first location that matches, else npos. ``` int operator == (const ACE_CString &s) const; ``` Equality comparison operator (must match entire string). ``` int operator < (const ACE_CString &s) const; ``` Less than comparison operator. ``` int operator > (const ACE_CString &s) const; ``` Greater than comparison operator. ``` int operator != (const ACE_CString &s) const; ``` Inequality comparison operator. ``` int compare (const ACE_CString &s) const; ``` Performs a strcmp-style comparison. ``` void dump (void) const; ``` Dump the state of an object. ``` ACE_ALLOC_HOOK_DECLARE; ``` Declare the dynamic allocation hooks. ## PRIVATE MEMBERS ``` ACE_Allocator *allocator_; ``` Pointer to a memory allocator. ``` size_t len_; ``` Length of the ACE\_CString data (not counting the trailing '\\0'). ``` size_t buf_len_; ``` Length of the ACE\_CString data buffer. Keeping track of the length allows to avoid unnecessary dynamic allocations. ``` char *rep_; ``` Pointer to data. ``` int release_; ``` Flag that indicates if we own the memory ``` static char NULL_CString_; ``` Represents the "NULL" string to simplify the internal logic. ## AUTHOR Douglas C. Schmidt (schmidt@cs.wustl.edu) ## LIBRARY ace