## 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);
        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 '\ '), 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 '\ ' 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);

Copy `s` into this `ACE_CString`.

    void set (const char *s, size_t len, int release);

Copy `len` bytes of `s` (will NUL terminate the result).

    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 '\ ').

    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