## NAME

ACE_WString - This class provides a wrapper facade for C wide strings.

## SYNOPSIS

    #include <ace/SString.h>

    class ACE_WString
    {
      public:
        static const int npos;
        ACE_WString (ACE_Allocator *alloc = 0);
        ACE_WString (const char *s, ACE_Allocator *alloc = 0);
        ACE_WString (const ACE_USHORT16 *s, ACE_Allocator *alloc = 0);
        ACE_WString (
            const ACE_USHORT16 *s,
            size_t len,
            ACE_Allocator *alloc = 0
            );
        ACE_WString (size_t len, ACE_Allocator *alloc = 0);
        ACE_WString (const ACE_WString &s);
        ACE_WString (ACE_USHORT16 c, ACE_Allocator *alloc = 0);
        ~ACE_WString (void);
        ACE_USHORT16 operator [] (size_t slot) const;
        ACE_USHORT16 &operator [] (size_t slot);
        ACE_WString &operator = (const ACE_WString &);
        void set (const ACE_USHORT16 *s);
        void set (const ACE_USHORT16 *s, size_t len);
        ACE_WString substring (size_t offset, ssize_t length = -1) const;
        ACE_WString substr (size_t offset, ssize_t length = -1) const;
        ACE_WString &operator += (const ACE_WString &);
        u_long hash (void) const;
        size_t length (void) const;
        ACE_USHORT16 *rep (void) const;
        char *char_rep (void) const;
        const ACE_USHORT16 *fast_rep (void) const;
        const ACE_USHORT16 *c_str (void) const;
        int strstr (const ACE_WString &s) const;
        int find (const ACE_WString &str, int pos = 0) const;
        int find (const ACE_USHORT16 *s, int pos = 0) const;
        int find (ACE_USHORT16 c, int pos = 0) const;
        int rfind (ACE_USHORT16 c, int pos = npos) const;
        int operator == (const ACE_WString &s) const;
        int operator < (const ACE_WString &s) const;
        int operator > (const ACE_WString &s) const;
        int operator != (const ACE_WString &s) const;
        int compare (const ACE_WString &s) const;
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
        static size_t strlen (const ACE_USHORT16 *);
        static const ACE_USHORT16 *strstr (
            const ACE_USHORT16 *s1,
            const ACE_USHORT16 *s2
            );
        void resize (size_t len);
      private:
        ACE_Allocator *allocator_;
        size_t len_;
        ACE_USHORT16 *rep_;
    };

## PUBLIC MEMBERS

    static const int npos;

No position constant

    ACE_WString (ACE_Allocator *alloc = 0);

Default constructor.

    ACE_WString (const char *s, ACE_Allocator *alloc = 0);

Constructor that copies `s` into dynamically allocated memory.

    ACE_WString (const ACE_USHORT16 *s, ACE_Allocator *alloc = 0);

Constructor that copies `s` into dynamically allocated memory.

    ACE_WString (
        const ACE_USHORT16 *s,
        size_t len,
        ACE_Allocator *alloc = 0
        );

Constructor that copies `len` ACE_USHORT16's of `s` into dynamically allocated memory (will NUL terminate the result).

    ACE_WString (size_t len, ACE_Allocator *alloc = 0);

Constructor that dynamically allocates memory for `len` + 1 ACE_USHORT16 characters. The newly created memory is set memset to 0.

    ACE_WString (const ACE_WString &s);

Copy constructor.

    ACE_WString (ACE_USHORT16 c, ACE_Allocator *alloc = 0);

Constructor that copies `c` into dynamically allocated memory.

    ~ACE_WString (void);

Deletes the memory...

    ACE_USHORT16 operator [] (size_t slot) const;

Return the `slot'th` character in the string (doesn't perform bounds checking).

    ACE_USHORT16 &operator [] (size_t slot);

Return the `slot'th` character by reference in the string (doesn't perform bounds checking).

    ACE_WString &operator = (const ACE_WString &);

Assignment operator (does copy memory).

    void set (const ACE_USHORT16 *s);

Copy `s`

    void set (const ACE_USHORT16 *s, size_t len);

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

    ACE_WString 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_WString substr (size_t offset, ssize_t length = -1) const;

Same as substring

    ACE_WString &operator += (const ACE_WString &);

Concat operator (does copy memory).

    u_long hash (void) const;

Returns a hash value for this string.

    size_t length (void) const;

Return the length of the string.

    ACE_USHORT16 *rep (void) const;

Gets a copy of the underlying pointer.

    char *char_rep (void) const;

Transform into a copy of the ASCII character representation.

    const ACE_USHORT16 *fast_rep (void) const;

Get at the underlying representation directly!

    const ACE_USHORT16 *c_str (void) const;

Same as STL String's `c_str` and `fast_rep`.

    int strstr (const ACE_WString &s) const;

Comparison operator that will match substrings. Returns the slot of the first location that matches, else -1.

    int find (const ACE_WString &str, int pos = 0) const;

Find `str` starting at pos. Returns the slot of the first location that matches, else npos.

    int find (const ACE_USHORT16 *s, int pos = 0) const;

Find `s` starting at pos. Returns the slot of the first location that matches, else npos.

    int find (ACE_USHORT16 c, int pos = 0) const;

Find `c` starting at pos. Returns the slot of the first location that matches, else npos.

    int rfind (ACE_USHORT16 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_WString &s) const;

Equality comparison operator (must match entire string).

    int operator < (const ACE_WString &s) const;

Less than comparison operator.

    int operator > (const ACE_WString &s) const;

Greater than comparison operator.

    int operator != (const ACE_WString &s) const;

Inequality comparison operator.

    int compare (const ACE_WString &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.

    static size_t strlen (const ACE_USHORT16 *);

Computes the length of a "0" terminated ACE_USHORT16 *.

    static const ACE_USHORT16 *strstr (
        const ACE_USHORT16 *s1,
        const ACE_USHORT16 *s2
        );

Traditional style strstr

    void resize (size_t len);

This method is designed for high-performance. Please use with care ;-) If the current size of the string is less than `len`, the string is resized to the new length. The data is is zero'd out after this operation.

## PRIVATE MEMBERS

    ACE_Allocator *allocator_;

Pointer to a memory allocator.

    size_t len_;

Length of the ACE_WString.

    ACE_USHORT16 *rep_;

Pointer to data.

## AUTHOR

Douglas C. Schmidt (schmidt@cs.wustl.edu)

## 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. This is a place holder until all compilers implement the ANSI/ISO C++ standard String class.

## LIBRARY

ace