coherence/lang/String.hpp

/*
* String.hpp
*
* Copyright 2001-2008 by Oracle. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_STRING_HPP
#define COH_STRING_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/Array.hpp"
#include "coherence/lang/Comparable.hpp"
#include "coherence/lang/Object.hpp"

#include <memory>
#include <ostream>
#include <sstream>
#include <string>

COH_OPEN_NAMESPACE2(coherence,lang)

/**
* @internal
*
* Used to proced protected inheritance of Array<octet_t> by String, as
* spec based class definitions don't have a notion of protected
* inheritance.
*/
class COH_EXPORT_SPEC ProtectedOctetArray
    : protected Array<octet_t>
    {
    public:
        typedef Array<octet_t>::super super;
        typedef Array<octet_t>::alias alias;

    protected:
        ProtectedOctetArray(size32_t cb)
            : Array<octet_t>(cb)
            {}

        ProtectedOctetArray(const ProtectedOctetArray& that)
            : Array<octet_t>(that)
            {}

        ProtectedOctetArray(ProtectedOctetArray::View vThat,
            size32_t iFrom, size32_t iTo)
            : Array<octet_t>(vThat, iFrom, iTo)
            {}

        virtual ~ProtectedOctetArray()
            {}
    };

/**
* A managed C-style (NUL terminated) string.
*
* In addition to exposing the underlying char array, the String class
* supports tranformations to and from Unicode code points within the Basic
* Multilingual Plane (BMP):
*
* <ul>
* <li>UTF-8  BMP char array</li>
* <li>UTF-16 BMP wchar_t array (on platforms where wchar_t is >= 16 bits)</li>
* <li>UTF-8  BMP octet_t array</li>
* <li>UTF-16 BMP char16_t array</li>
* </ul>
*
* Note: the ASCII character set is a subset of UTF-8 BMP.
*
* Unlike most managed types in the Coherence class hierarchy, Strings are
* auto-boxable by default. That is a String::Handle or String::View can be
* directly asssigned from or to common string representations.  For example
* the following code is legal:
* @code
* String::Handle hs = "hello world";
* @endcode
* as is
* @code
* void someFunction(String::View vs);
*
* someFunction("some value");
* @endcode
*
* @see StringHandle for details
*
* @author mf/jh/djl  2007.07.05
*/
class COH_EXPORT String
    : public cloneable_spec<String,
        extends<ProtectedOctetArray>,
        implements<Comparable> >
    {
    friend class factory<String>;

    // ----- constants ------------------------------------------------------

    public:
        /**
        * The largest possible value of type size32_t.
        */
        static const size32_t npos = size32_t(-1);


    // ----- typedefs -------------------------------------------------------

    public:
        /**
        * While StringHandle boxes a number of common string types, String is
        * still compatible with BoxHandle, and when used with it can box to
        * only one type. By default Strings are boxable from a number of
        * types, see StringHandle for details.
        */
        typedef std::string BoxedType;


    // ----- nested class: StringHandle -------------------------------------

    public:
        /**
        * StringHandle provides standard TypedHandle feaures as well as
        * auto-boxing support for standard string types including:
        *
        * <ul>
        * <li>char[]       C-style NUL terminated char array</li>
        * <li>wchar_t[]    C-style NUL terminated wide char array</li>
        * <li>std::string  STL string</li>
        * <li>std::wstring STL wide string</li>
        * </ul>
        *
        * Unboxing to char[] and wchar[] is not supported as it is unsafe to
        * maintain a reference to the underlying character array without
        * holding a reference to the String. Unboxing to std::string, and
        * std::wstring is both supported and safe.
        */
        template<class T> class StringHandle
            : public TypedHandle<T>
            {
            // ----- constructors ---------------------------------------

            public:
                /**
                * Create an empty StringHandle.
                */
                StringHandle()
                        : TypedHandle<T>()
                    {
                    }

                /**
                * Create a new StringHandle from a boxable type.
                */
                StringHandle(const char* ach)
                        : TypedHandle<T>()
                    {
                    if (NULL != ach)
                        {
                        TypedHandle<T>::set(get_pointer(T::create(ach)));
                        }
                    }

                /**
                * Create a new StringHandle from a boxable type.
                */
                StringHandle(const wchar_t* ach)
                        : TypedHandle<T>()
                    {
                    if (NULL != ach)
                        {
                        TypedHandle<T>::set(get_pointer(T::create(ach)));
                        }
                    }

                /**
                * Create a new StringHandle from a boxable type.
                */
                StringHandle(const std::string& s)
                        : TypedHandle<T>()
                    {
                    TypedHandle<T>::set(get_pointer(T::create(s)));
                    }

                /**
                * Create a new StringHandle from a boxable type.
                */
                StringHandle(const std::wstring& ws)
                        : TypedHandle<T>()
                    {
                    TypedHandle<T>::set(get_pointer(T::create(ws)));
                    }

                /**
                * Create a new StringHandle from the TypedHandle with a type
                * conversion.
                */
                template<class O> StringHandle<T>(const TypedHandle<O>& h)
                        : TypedHandle<T>()
                    {
                    TypedHandle<T>::set(get_pointer(h));
                    }

                /**
                * Create a new StringHandle from the raw pointer.
                */
                StringHandle(T* o)
                        : TypedHandle<T>()
                    {
                    TypedHandle<T>::set(o);
                    }

                /**
                * The destructor.
                */
                ~StringHandle()
                    {
                    }

            // ----- operators ------------------------------------------

            public:
                /**
                * The assignment operator.
                */
                template<class O>
                StringHandle& operator=(const TypedHandle<O>& h)
                    {
                    TypedHandle<T>::set(get_pointer(h));
                    return *this;
                    }

                /**
                * The "boxing" operator.
                */
                StringHandle& operator=(const char* ach)
                    {
                    if (NULL == ach)
                        {
                        TypedHandle<T>::set(NULL);
                        }
                    else
                        {
                        TypedHandle<T>::set(get_pointer(T::create(ach)));
                        }
                    return *this;
                    }

                /**
                * The "boxing" operator.
                */
                StringHandle& operator=(const wchar_t* ach)
                    {
                    if (NULL == ach)
                        {
                        TypedHandle<T>::set(NULL);
                        }
                    else
                        {
                        TypedHandle<T>::set(get_pointer(T::create(ach)));
                        }
                    return *this;
                    }

                /**
                * The "boxing" operator.
                */
                StringHandle& operator=(const std::string& s)
                    {
                    TypedHandle<T>::set(get_pointer(T::create(s)));
                    return *this;
                    }

                /**
                * The "boxing" operator.
                */
                StringHandle& operator=(const std::wstring& ws)
                    {
                    TypedHandle<T>::set(get_pointer(T::create(ws)));
                    return *this;
                    }

                /**
                * The "unboxing" operator.
                *
                * @return a copy of the referenced Object
                */
                operator std::string() const
                    {
                    const T* pT = TypedHandle<T>::get();
                    if (NULL == pT)
                        {
                        coh_throw_npe(typeid(T));
                        }
                    return (std::string) *pT;
                    }

                /**
                * The "unboxing" operator.
                *
                * @return a copy of the referenced Object
                */
                operator std::wstring() const
                    {
                    const T* pT = TypedHandle<T>::get();
                    if (NULL == pT)
                        {
                        coh_throw_npe(typeid(T));
                        }
                    return (std::wstring) *pT;
                    }

                /**
                * The equality operator.
                */
                template<class O>
                bool operator==(const TypedHandle<O>& h)
                   {
                   return ((const Object*) get_pointer(*this)) ==
                          ((const Object*) get_pointer(h));
                   }

                /**
                * The equality operator.
                */
                bool operator==(const Object* cpo) const
                    {
                    return ((const Object*) get_pointer(*this)) ==
                           ((const Object*) cpo);
                    }

                /**
                * The inequality operator.
                */
                template<class O>
                bool operator!=(const TypedHandle<O>& h)
                    {
                    return !operator==(h);
                    }

                /**
                * The inequality operator.
                */
                bool operator!=(const Object* cpo) const
                    {
                    return !operator==(cpo);
                    }
            };

    // ----- handle definitions ---------------------------------------------

    public:
        /**
        * Handle definition.
        */
        typedef StringHandle<String> Handle;

        /**
        * View definition.
        */
        typedef StringHandle<const String> View;


    // ----- constructors ---------------------------------------------------

    private:
        /**
        * Create a String from a C-style NUL terminated char array.
        *
        * @param ach  the NUL terminated string of chars to copy
        *
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-8 BMP
        */
        String(const char* achSrc = "");

        /**
        * Create a String from a C-style NUL terminated wide char array.
        *
        * @param ach  the NUL terminated string of wide chars to copy
        *
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-16 BMP
        */
        String(const wchar_t* achSrc);

        /**
        * Create a String from an STL string.
        *
        * @param s  the STL string to copy
        *
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-8 BMP
        */
        String(const std::string& s);

        /**
        * Create a String from an STL wstring.
        *
        * @param ws  the STL wstring to copy
        *
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-16 BMP
        */
        String(const std::wstring& ws);

        /**
        * Create a String from a char array.
        *
        * @param vach  the array of chars to copy
        * @param of    the offset at which to start copying
        * @param cch   the number of chars to copy; if npos, copy all
        *              subsequent chars in the array
        *
        * @throws IndexOutOfBoundsException if of > vach->length or if
        *         cch < npos and of + cch > vach->length
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-8 BMP
        */
        String(Array<char>::View vachSrc, size32_t of = 0, size32_t cch = npos);

        /**
        * Create a String from a wide char array.
        *
        * @param vach  the array of chars to copy
        * @param of    the offset at which to start copying
        * @param cch   the number of chars to copy; if npos, copy all
        *              subsequent chars in the array
        *
        * @throws IndexOutOfBoundsException if of > vach->length or if
        *         cch < npos and of + cch > vach->length
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-16 BMP
        * @throws UnsupportedOperationException if sizeof(wchar_t) <
        *         sizeof(char16_t)
        */
        String(Array<wchar_t>::View vachSrc, size32_t of = 0, size32_t cch = npos);

        /**
        * Create a String from an octet array.
        *
        * @param vab  the array of octets to copy
        * @param of   the offset at which to start copying
        * @param cb   the number of octets to copy; if npos, copy all
        *             subsequent octets in the array
        *
        * @throws IndexOutOfBoundsException if of > vab->length or if
        *         cb < npos and of + cb > vab->length
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-8 BMP
        */
        String(Array<octet_t>::View vabSrc, size32_t of = 0, size32_t cb = npos);

        /**
        * Create a String from a 16-bit char array.
        *
        * @param vach  the array of chars to copy
        * @param of    the offset at which to start copying
        * @param cch   the number of chars to copy; if npos, copy all
        *              subsequent chars in the array
        *
        * @throws IndexOutOfBoundsException if of > vach->length or if
        *         cch < npos and of + cch > vach->length
        * @throws IllegalArgumentException if any of the elements in the
        *         array are not UTF-16 BMP
        */
        String(Array<char16_t>::View vachSrc, size32_t of = 0, size32_t cch = npos);

        /**
        * Copy constructor.
        */
        String(const String& that);


    // ----- String interface -----------------------------------------------

    public:
        /**
        * Return true iff the String contains only ASCII (ISO-8859-1)
        * characters. In this case each character is represented by a single
        * char, otherwise a character can take between one and three chars.
        *
        * @return true iff the String contains only ASCII characters
        */
        virtual bool isASCII() const;

        /**
        * Return the number of unicode code points (characters) in this String.
        *
        * @return the number of characters in this String
        */
        virtual size32_t length() const;

        /**
        * Return the String as a C-style NUL terminated char array.
        *
        * If the String is non-ASCII then the String::next() method may be
        * used to expand the char array into a sequence of char16_t unicode
        * characters.
        *
        * The returned array's lifetime is bound to the lifetime of the
        * String which it was returned from. Specifically it is unsafe to use
        * the returned char* while not holding a handle to the String.
        *
        * @return the char array representing the String.
        */
        virtual const char* getCString() const;

        /**
        * Compare this String against the supplied C-style string.
        *
        * @param ach  the NUL terminated C-style string to compare to this
        *             String
        *
        * @return true iff the two strings are identical
        */
        virtual bool equals(const char* ach) const;

        /**
        * Compare this String against the supplied C-style wide char string.
        *
        * @param ach  the NUL terminated C-style string to compare to this
        *             String
        *
        * @return true iff the two strings are identical
        *
        * @throws UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_t)
        */
        virtual bool equals(const wchar_t* ach) const;

        /**
        * Compare this String against the supplied STL string.
        *
        * @param s  the STL string to compare to this String
        *
        * @return true iff the two strings are identical
        */
        virtual bool equalsStd(const std::string& s) const;

        /**
        * Compare this String against the supplied STL wstring.
        *
        * @param ws  the STL wstring to compare to this String
        *
        * @return true iff the two strings are identical
        *
        * @throws UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_t)
        */
        virtual bool equalsStd(const std::wstring& ws) const;

        /**
        * Return the index of a substring within this String.
        *
        * @param vsSearch  the substring to search for in vsSource
        * @param iBegin    the location in the string to start searching
        *
        * @return the index of the substring found within this String or npos
        */
        virtual size32_t indexOf(String::View vsSearch,
                size32_t iBegin = 0) const;

        /**
        * Return the index of a character within this String.
        *
        * @param chSearch  the character to search for in this String
        * @param iBegin    the location in this String to start searching
        *
        * @return the index of the character found within this String or npos
        */
        virtual size32_t indexOf(char16_t chSearch,
                size32_t iBegin = 0) const;

        /**
        * Return the index of a substring within this String by searching
        * backward from the given beginning index.
        *
        * @param vsSearh  the substring to search for within this String
        * @param iBegin   the location in this String to start searching
        *
        * @return the index of the substring found within this String or npos
        */
        virtual size32_t lastIndexOf(String::View vsSearch,
                size32_t iBegin = npos) const;

        /**
        * Return the index of a substring within this String by searching
        * backward from the given beginning index.
        *
        * @param chSearch  the character to search for in this String
        * @param iBegin    the location in this String to start searching
        *
        * @return the index of the character found within this String or npos
        */
        virtual size32_t lastIndexOf(char16_t chSearch,
                size32_t iBegin = npos) const;

        /**
        * Return a new String comprised of the substring of this string
        * from iBegin (inclusive) to iEnd (exclusive).
        *
        * @param iBegin    the starting index from which to create the string
        * @param iEnd      the index of where the substring should stop
        *                  in this String or npos for end of string
        *
        * @return the new substring created from this String
        */
        virtual String::View substring(size32_t iBegin,
                size32_t iEnd = npos) const;

        /**
        * Return true if this String starts with the supplied String.
        *
        * @param vsSearch  the string to search for
        *
        * @return true if this String starts with vsSearch
        */
        virtual bool startsWith(String::View vsSearch) const;

        /**
        * Return true if this String ends with the supplied Strng.
        *
        * @param vsSearch  the string to search for
        *
        * @return true if this String ends with vsSearch
        */
        virtual bool endsWith(String::View vsSearch) const;

        /**
        * A substring of this String is compared to a substring of a supplied
        * String.
        *
        * @param ofSource  the offset in this String where comparison begins
        * @param vsOther   the String whose substring is compared against
        *                  this String
        * @param ofOther   the offset in vsOther where comparison begins
        * @param cch       the count of characters to compare
        *
        * @return the result of the two substrings
        */
        virtual bool regionMatches(size32_t ofSourse,
                String::View vsOther, size32_t ofOther = 0,
                size32_t cch = npos) const;

        /**
        * Return a String that is the result of removing all leading and
        * trailing white space.
        *
        * @return a trimmed copy of this String
        */
        String::View trim() const;

        /**
        * Return the unerlying UTF-8 BMP NUL terminated Array<octet_t>.
        *
        * For performance reasons the returned Array may not support cloneing.
        * If clone() is called the result will a String, which depending on
        * the compiler's handling of dynamic_cast to a private super class may
        * fail to be castable to an Array<octet_t>.
        *
        * @return the Array<octet_t>
        */
        virtual Array<octet_t>::View getOctets() const;

        /**
        * Return an STL string containing the same contents as this String.
        *
        * @return a new STL string.
        */
        virtual operator std::string() const;

        /**
        * Return an STL wstring containing the same contents as this String.
        *
        * @return a new STL wstring.
        *
        * @throws UnsupportedOperationException if sizeof(wchar_t) < sizeof(char16_t)
        */
        virtual operator std::wstring() const;


    // ----- Comparable interface -------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual int32_t compareTo(Object::View v) const;


    // ----- Object interface -----------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual size32_t hashCode() const;

        /**
        * {@inheritDoc}
        */
        virtual void toStream(std::ostream& out) const;

        /**
        * {@inheritDoc}
        */
        virtual bool isImmutable() const;

        /**
        * {@inheritDoc}
        */
        virtual bool equals(Object::View v) const;

        /**
        * {@inheritDoc}
        */
        virtual size32_t sizeOf() const;


    // ----- static helpers -------------------------------------------------

    public:
        /**
        * Return the Unicode character as UTF-16 from the char array, and
        * increment the pointer such that it references the start of the
        * next Unicode character.
        *
        * @param ach  pointer to the start of the next UTF-8 code point.
        *
        * @return the next Unicode character
        *
        * @throws IllegalArgumentException  if a non UTF-8 BMP sequence is
        *                                   encountered
        */
        static char16_t next(const char*& ach);


    // ----- data members ---------------------------------------------------

    protected:
        /**
        * The number of unicode code points (characters) in the String.
        */
        size32_t m_ccp;


    // ----- constants ------------------------------------------------------

    public:
        /**
        * String referncing NULL.
        */
        static const String::Handle NULL_STRING;
    };


// ----- helper macros ------------------------------------------------------

/**
* This macro will take any set of streamable contents and turn them into a
* coherence#lang#String instance.
*
* @param CONTENTS  the contents to use in constructing the String.
*
* Usage example:
* @code
* String::Handle hsFoo = COH_TO_STRING("This value: " << 5 << " is my value");
* @endcode
*/
#define COH_TO_STRING(CONTENTS) \
    coherence::lang::String::create(((std::stringstream&) \
            (*(std::auto_ptr<std::stringstream>(new std::stringstream())) \
                << CONTENTS)).str())

COH_CLOSE_NAMESPACE2

#endif // COH_STRING_HPP

Copyright (c) 2000-2008 Oracle. All rights reserved.