ACE_CString(3)

NAME

ACE_CString - This class provides a wrapper facade for C strings.

SYNOPSIS

#include <ace/SString.h>
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 ([email protected])

LIBRARY

ace