source: GTP/trunk/App/Demos/Geom/OgreStuff/include/CEGUI/CEGUIString.h @ 1092

/************************************************************************
        filename:       CEGUIString.h
        created:        26/2/2004
        author:         Paul D Turner
        
        purpose:        Defines string class used within the GUI system.
*************************************************************************/
/*************************************************************************
    Crazy Eddie's GUI System (http://www.cegui.org.uk)
    Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*************************************************************************/
#ifndef _CEGUIString_h_
#define _CEGUIString_h_

#include "CEGUIBase.h"
#include <string>
#include <string.h>
#include <stdexcept>

// Start of CEGUI namespace section
namespace CEGUI
{
#define STR_QUICKBUFF_SIZE      32
        /*************************************************************************
                Basic Types
        *************************************************************************/
        typedef         uint8   utf8;
        //typedef               uint16  utf16;  // removed typedef to prevent usage, as utf16 is not supported (yet)
        typedef         uint32  utf32;

/*!
\brief
        String class used within the GUI system.

        For the most part, this class can replace std::string in basic usage.  However, currently String does not use the
        current locale, and also comparisons do not take into account the Unicode data tables, so are not 'correct'
        as such.
*/
class CEGUIEXPORT String
{
public:
        /*************************************************************************
                Integral Types
        *************************************************************************/
        typedef         utf32                   value_type;                                     //!< Basic 'code point' type used for String (utf32)
        typedef         size_t                  size_type;                                      //!< Unsigned type used for size values and indices
        typedef         ptrdiff_t               difference_type;                        //!< Signed type used for differences
        typedef         utf32&                  reference;                                      //!< Type used for utf32 code point references
        typedef         const utf32&    const_reference;                        //!< Type used for constant utf32 code point references
        typedef         utf32*                  pointer;                                        //!< Type used for utf32 code point pointers
        typedef         const utf32*    const_pointer;                          //!< Type used for constant utf32 code point pointers

        static const size_type          npos;                                           //!< Value used to represent 'not found' conditions and 'all code points' etc.

private:
        /*************************************************************************
                Implementation data
        *************************************************************************/
        size_type       d_cplength;                     //!< holds length of string in code points (not including null termination)
        size_type       d_reserve;                      //!< code point reserve size (currently allocated buffer size in code points).

        mutable utf8*           d_encodedbuff;          //!< holds string data encoded as utf8 (generated only by calls to c_str() and data())
        mutable size_type       d_encodeddatlen;        //!< holds length of encoded data (in case it's smaller than buffer).
        mutable size_type       d_encodedbufflen;       //!< length of above buffer (since buffer can be bigger then the data it holds to save re-allocations).

        utf32           d_quickbuff[STR_QUICKBUFF_SIZE];        //!< This is a integrated 'quick' buffer to save allocations for smallish strings
        utf32*          d_buffer;                                                       //!< Pointer the the main buffer memory.  This is only valid when quick-buffer is not being used

public:
        /*************************************************************************
                Iterator Classes
        *************************************************************************/
        /*!
        \brief
                Constant forward iterator class for String objects
        */
#if defined(_MSC_VER) && (_MSC_VER <= 1200)
        class const_iterator : public std::iterator<std::random_access_iterator_tag, utf32>
#else
        class const_iterator : public std::iterator<std::random_access_iterator_tag, utf32, std::ptrdiff_t, const utf32*, const utf32&>
#endif
        {

        public:
                //////////////////////////////////////////////////////////////////////////
                // data
                //////////////////////////////////////////////////////////////////////////
                const utf32*    d_ptr;


                //////////////////////////////////////////////////////////////////////////
                // Methods
                //////////////////////////////////////////////////////////////////////////
                const_iterator(void)
                {
                        d_ptr = 0;
                }
                const_iterator(const_pointer ptr)
                {
                        d_ptr = ptr;
                }

                const_reference operator*() const
                {
                        return *d_ptr;
                }

#if defined(_MSC_VER) && (_MSC_VER <= 1200)
#       pragma warning (push)
#       pragma warning (disable : 4284)
#endif
                const_pointer   operator->() const              
                {
                        return &**this;
                }

#if defined(_MSC_VER) && (_MSC_VER <= 1200)
#       pragma warning (pop)
#endif

                const_iterator& operator++()
                {
                        ++d_ptr;
                        return *this;
                }

                const_iterator  operator++(int)         
                {
                        const_iterator temp = *this;
                        ++*this;
                        return temp;
                }

                const_iterator& operator--()
                {
                        --d_ptr;
                        return *this;
                }

                const_iterator  operator--(int)         
                {
                        const_iterator temp = *this;
                        --*this;
                        return temp;
                }

                const_iterator& operator+=(difference_type offset)
                {
                        d_ptr += offset;
                        return *this;
                }

                const_iterator operator+(difference_type offset) const
                {
                        const_iterator temp = *this;
                        return temp += offset;
                }

                const_iterator& operator-=(difference_type offset)
                {
                        return *this += -offset;
                }

                const_iterator operator-(difference_type offset) const
                {
                        const_iterator temp = *this;
                        return temp -= offset;
                }

                difference_type operator-(const const_iterator& iter) const
                {
                        return d_ptr - iter.d_ptr;
                }

                const_reference operator[](difference_type offset) const
                {
                        return *(*this + offset);
                }

                bool operator==(const const_iterator& iter) const
                {
                        return d_ptr == iter.d_ptr;
                }

                bool operator!=(const const_iterator& iter) const
                {
                        return !(*this == iter);
                }

                bool operator<(const const_iterator& iter) const
                {
                        return d_ptr < iter.d_ptr;
                }

                bool operator>(const const_iterator& iter) const
                {
                        return (!(iter < *this));
                }

                bool operator<=(const const_iterator& iter) const
                {
                        return (!(iter < *this));
                }

                bool operator>=(const const_iterator& iter) const
                {
                        return (!(*this < iter));
                }

                friend const_iterator operator+(difference_type offset, const const_iterator& iter)
                {
                        return iter + offset;
                }

        };

        /*!
        \brief
                Forward iterator class for String objects
        */
        class iterator : public const_iterator
        {
        public:
                iterator(void) {}
                iterator(pointer ptr) : const_iterator(ptr) {}


                reference operator*() const
                {
                        return ((reference)**(const_iterator *)this);
                }

#if defined(_MSC_VER) && (_MSC_VER <= 1200)
#       pragma warning (push)
#       pragma warning (disable : 4284)
#endif

                pointer operator->() const
                {
                        return &**this;
                }

#if defined(_MSC_VER) && (_MSC_VER <= 1200)
#       pragma warning (pop)
#endif

                iterator& operator++()
                {
                        ++this->d_ptr;
                        return *this;
                }

                iterator operator++(int)
                {
                        iterator temp = *this;
                        ++*this;
                        return temp;
                }

                iterator& operator--()
                {
                        --this->d_ptr;
                        return *this;
                }

                iterator operator--(int)
                {
                        iterator temp = *this;
                        --*this;
                        return temp;
                }

                iterator& operator+=(difference_type offset)
                {
                        this->d_ptr += offset;
                        return *this;
                }

                iterator operator+(difference_type offset) const
                {
                        iterator temp = *this;
                        return temp + offset;
                }

                iterator& operator-=(difference_type offset)
                {
                        return *this += -offset;
                }

                iterator operator-(difference_type offset) const
                {
                        iterator temp = *this;
                        return temp -= offset;
                }

                difference_type operator-(const const_iterator& iter) const
                {
                        return ((const_iterator)*this - iter);
                }

                reference operator[](difference_type offset) const
                {
                        return *(*this + offset);
                }

                friend iterator operator+(difference_type offset, const iterator& iter)
                {
                        return iter + offset;
                }

        };

        /*!
        \brief
                Constant reverse iterator class for String objects
        */
#if defined(_MSC_VER) && ((_MSC_VER <= 1200) || ((_MSC_VER <= 1300) && defined(_STLPORT_VERSION)))
        typedef std::reverse_iterator<const_iterator, const_pointer, const_reference, difference_type>  const_reverse_iterator;
#else
        typedef std::reverse_iterator<const_iterator>   const_reverse_iterator;
#endif

        /*!
        \brief
                Reverse iterator class for String objects
        */
#if defined(_MSC_VER) && ((_MSC_VER <= 1200) || ((_MSC_VER <= 1300) && defined(_STLPORT_VERSION)))
        typedef std::reverse_iterator<iterator, pointer, reference, difference_type>                    reverse_iterator;
#else
        typedef std::reverse_iterator<iterator>                 reverse_iterator;
#endif

public:
        //////////////////////////////////////////////////////////////////////////
        // Default Construction and Destructor
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Constructs an empty string
        */
        String(void)
        {
                init();
        }

        /*!
        \brief
                Destructor for String objects
        */
        ~String(void);

        //////////////////////////////////////////////////////////////////////////
        // Construction via CEGUI::String
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Copy constructor - Creates a new string with the same value as \a str

        \param str
                String object used to initialise the newly created string

        \return
                Nothing
        */
        String(const String& str)
        {
                init();
                assign(str);
        }
        

        /*!
        \brief
                Constructs a new string initialised with code points from another String object.

        \param str
                String object used to initialise the newly created string

        \param str_idx
                Starting code-point of \a str to be used when initialising the new String

        \param str_num
                Maximum number of code points from \a str that are to be assigned to the new String

        \return
                Nothing
        */
        String(const String& str, size_type str_idx, size_type str_num = npos)
        {
                init();
                assign(str, str_idx, str_num);
        }

        //////////////////////////////////////////////////////////////////////////
        // Construction via std::string
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Constructs a new string and initialises it using the std::string std_str

        \param std_str
                The std::string object that is to be used to initialise the new String object.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const std::string& std_str)
        {
                init();
                assign(std_str);
        }
                
        /*!
        \brief
                Constructs a new string initialised with characters from the given std::string object.

        \param std_str
                std::string object used to initialise the newly created string

        \param str_idx
                Starting character of \a std_str to be used when initialising the new String

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param str_num
                Maximum number of characters from \a std_str that are to be assigned to the new String

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const std::string& std_str, size_type str_idx, size_type str_num = npos)
        {
                init();
                assign(std_str, str_idx, str_num);
        }


        //////////////////////////////////////////////////////////////////////////
        // Construction via UTF-8 stream (for straight ASCII use, only codes 0x00 - 0x7f are valid)
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Constructs a new String object and initialise it using the provided utf8 encoded string buffer.

        \param utf8_str
                Pointer to a buffer containing a null-terminated Unicode string encoded as utf8 data.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const utf8* utf8_str)
        {
                init();
                assign(utf8_str);
        }

        /*!
        \brief
                Constructs a new String object and initialise it using the provided utf8 encoded string buffer.

                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param utf8_str
                Pointer to a buffer containing Unicode string data encoded as utf8.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param chars_len
                Length of the provided utf8 string in code units (not code-points).

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const utf8* utf8_str, size_type chars_len)
        {
                init();
                assign(utf8_str, chars_len);
        }

        //////////////////////////////////////////////////////////////////////////
        // Construction via code-point (using a UTF-32 code unit)
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Constructs a new String that is initialised with the specified code point

        \param num
                The number of times \a code_point is to be put into new String object

        \param code_point
                The Unicode code point to be used when initialising the String object

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(size_type num, utf32 code_point)
        {
                init();
                assign(num, code_point);
        }

        //////////////////////////////////////////////////////////////////////////
        // Construction via iterator
        //////////////////////////////////////////////////////////////////////////
        // Create string with characters in the range [beg, end)
        /*!
        \brief
                Construct a new string object and initialise it with code-points from the range [beg, end).

        \param beg
                Iterator describing the start of the data to be used when initialising the String object

        \param end
                Iterator describing the (exclusive) end of the data to be used when initialising the String object

        \return 
                Nothing
        */
        String(const_iterator beg, const_iterator end)
        {
                init();
                append(beg, end);
        }


        //////////////////////////////////////////////////////////////////////////
        // Construction via c-string
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Constructs a new String object and initialise it using the provided c-string.

        \param c_str
                Pointer to a c-string.

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const char* c_str)
        {
                init();
                assign(c_str);
        }

        /*!
        \brief
                Constructs a new String object and initialise it using characters from the provided char array.

        \param chars
                char array.

        \param chars_len
                Number of chars from the array to be used.

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        String(const char* chars, size_type chars_len)
        {
                init();
                assign(chars, chars_len);
        }


        //////////////////////////////////////////////////////////////////////////
        // Size operations
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Returns the size of the String in code points

        \return
                Number of code points currently in the String
        */
        size_type       size(void) const
        {
                return d_cplength;
        }

        /*!
        \brief
                Returns the size of the String in code points

        \return
                Number of code points currently in the String
        */
        size_type       length(void) const
        {
                return d_cplength;
        }

        /*!
        \brief
                Returns true if the String is empty

        \return
                true if the String is empty, else false.
        */
        bool    empty(void) const
        {
                return  (d_cplength == 0);
        }

        /*!
        \brief
                Returns the maximum size of a String.

                Any operation that would result in a String that is larger than this value will throw the std::length_error exception.

        \return
                The maximum number of code points that a string can contain
        */
        static size_type        max_size(void)
        {
                return (((size_type)-1) / sizeof(utf32));
        }

        //////////////////////////////////////////////////////////////////////////
        // Capacity Operations
        //////////////////////////////////////////////////////////////////////////
        // return the number of code points the string could hold without re-allocation
        // (due to internal encoding this will always report the figure for worst-case encoding, and could even be < size()!)
        /*!
        \brief
                Return the number of code points that the String could hold before a re-allocation would be required.

        \return
                Size of the current reserve buffer.  This is the maximum number of code points the String could hold before a buffer
                re-allocation would be required
        */
        size_type capacity(void) const
        {
                return d_reserve - 1;
        }

        // reserve internal memory for at-least 'num' code-points (characters).  if num is 0, request is shrink-to-fit.
        /*!
        \brief
                Specifies the amount of reserve capacity to allocate.

        \param num
                The number of code points to allocate space for.  If \a num is larger that the current reserve, then a re-allocation will occur.  If
                \a num is smaller than the current reserve (but not 0) the buffer may be shrunk to the larger of the specified number, or the current
                String size (operation is currently not implemented).  If \a num is 0, then the buffer is re-allocated to fit the current String size.

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String object would be too big.
        */
        void    reserve(size_type num = 0)
        {
                if (num == 0)
                        trim();
                else
                        grow(num);
        }

        //////////////////////////////////////////////////////////////////////////
        // Comparisons
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Compares this String with the String 'str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param str
                The String object that is to compared with this String.

        \return
                -  0 if the String objects are equal
                - <0 if this String is lexicographically smaller than \a str
                - >0 if this String is lexicographically greater than \a str
        */
        int             compare(const String& str) const
        {
                return compare(0, d_cplength, str);
        }

        /*!
        \brief
                Compares code points from this String with code points from the String 'str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param str
                The String object that is to compared with this String.

        \param str_idx
                Index of the first code point from String \a str to consider.

        \param str_len
                Maximum number of code points from String \a str to consider

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a str
                - >0 if specified sub-strings are lexicographically greater than \a str

        \exception std::out_of_range    Thrown if either \a idx or \a str_idx are invalid.
        */
        int             compare(size_type idx, size_type len, const String& str, size_type str_idx = 0, size_type str_len = npos) const
        {
                if ((d_cplength < idx) || (str.d_cplength < str_idx))
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if ((len == npos) || (idx + len > d_cplength))
                        len = d_cplength - idx;

                if ((str_len == npos) || (str_idx + str_len > str.d_cplength))
                        str_len = str.d_cplength - str_idx;

                int val = (len == 0) ? 0 : utf32_comp_utf32(&ptr()[idx], &str.ptr()[str_idx], (len < str_len) ? len : str_len);

                return (val != 0) ? ((val < 0) ? -1 : 1) : (len < str_len) ? -1 : (len == str_len) ? 0 : 1;
        }


        /*!
        \brief
                Compares this String with the std::string 'std_str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param std_str
                The std::string object that is to compared with this String.

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \return
                -  0 if the string objects are equal
                - <0 if this string is lexicographically smaller than \a std_str
                - >0 if this string is lexicographically greater than \a std_str
        */
        int             compare(const std::string& std_str) const
        {
                return compare(0, d_cplength, std_str);
        }


        /*!
        \brief
                Compares code points from this String with code points from the std::string 'std_str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param std_str
                The std::string object that is to compared with this String.

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \param str_idx
                Index of the first character from std::string \a std_str to consider.

        \param str_len
                Maximum number of characters from std::string \a std_str to consider

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a std_str
                - >0 if specified sub-strings are lexicographically greater than \a std_str

        \exception std::out_of_range    Thrown if either \a idx or \a str_idx are invalid.
        */
        int             compare(size_type idx, size_type len, const std::string& std_str, size_type str_idx = 0, size_type str_len = npos) const
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (std_str.size() < str_idx)
                        throw std::out_of_range("Index is out of range for std::string");

                if ((len == npos) || (idx + len > d_cplength))
                        len = d_cplength - idx;

                if ((str_len == npos) || (str_idx + str_len > std_str.size()))
                        str_len = (size_type)std_str.size() - str_idx;

                int val = (len == 0) ? 0 : utf32_comp_char(&ptr()[idx], &std_str.c_str()[str_idx], (len < str_len) ? len : str_len);

                return (val != 0) ? ((val < 0) ? -1 : 1) : (len < str_len) ? -1 : (len == str_len) ? 0 : 1;
        }


        /*!
        \brief
                Compares this String with the null-terminated utf8 encoded 'utf8_str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param utf8_str
                The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                -  0 if the strings are equal
                - <0 if this string is lexicographically smaller than \a utf8_str
                - >0 if this string is lexicographically greater than \a utf8_str
        */
        int             compare(const utf8* utf8_str) const
        {
                return compare(0, d_cplength, utf8_str, encoded_size(utf8_str));
        }


        /*!
        \brief
                Compares code points from this String with the null-terminated utf8 encoded 'utf8_str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param utf8_str
                The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a utf8_str
                - >0 if specified sub-strings are lexicographically greater than \a utf8_str

        \exception std::out_of_range    Thrown if \a idx is invalid.
        */
        int             compare(size_type idx, size_type len, const utf8* utf8_str) const
        {
                return compare(idx, len, utf8_str, encoded_size(utf8_str));
        }

        /*!
        \brief
                Compares code points from this String with the utf8 encoded data in buffer 'utf8_str'.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param utf8_str
                The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param str_cplen
                The number of encoded code points in the buffer \a utf8_str (this is not the same as the number of code units).

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a utf8_str
                - >0 if specified sub-strings are lexicographically greater than \a utf8_str

        \exception std::out_of_range    Thrown if \a idx is invalid.
        \exception std::length_error    Thrown if \a str_cplen is set to npos.
        */
        int             compare(size_type idx, size_type len, const utf8* utf8_str, size_type str_cplen) const
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (str_cplen == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if ((len == npos) || (idx + len > d_cplength))
                        len = d_cplength - idx;

                int val = (len == 0) ? 0 : utf32_comp_utf8(&ptr()[idx], utf8_str, (len < str_cplen) ? len : str_cplen);

                return (val != 0) ? ((val < 0) ? -1 : 1) : (len < str_cplen) ? -1 : (len == str_cplen) ? 0 : 1;
        }


        /*!
        \brief
                Compares this String with the given c-string.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param c_str
                The c-string that is to compared with this String.

        \return
                -  0 if the strings are equal
                - <0 if this string is lexicographically smaller than \a c_str
                - >0 if this string is lexicographically greater than \a c_str
        */
        int             compare(const char* c_str) const
        {
                return compare(0, d_cplength, c_str, strlen(c_str));
        }


        /*!
        \brief
                Compares code points from this String with the given c-string.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param c_str
                The c-string that is to compared with this String.

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a c_str
                - >0 if specified sub-strings are lexicographically greater than \a c_str

        \exception std::out_of_range    Thrown if \a idx is invalid.
        */
        int             compare(size_type idx, size_type len, const char* c_str) const
        {
                return compare(idx, len, c_str, strlen(c_str));
        }


        /*!
        \brief
                Compares code points from this String with chars in the given char array.

        \note
                This does currently not properly consider Unicode and / or the system locale.

        \param idx
                Index of the first code point from this String to consider.

        \param len
                Maximum number of code points from this String to consider.

        \param chars
                The array containing the chars that are to compared with this String.

        \param chars_len
                The number of chars in the array.

        \return
                -  0 if the specified sub-strings are equal
                - <0 if specified sub-strings are lexicographically smaller than \a chars
                - >0 if specified sub-strings are lexicographically greater than \a chars

        \exception std::out_of_range    Thrown if \a idx is invalid.
        \exception std::length_error    Thrown if \a chars_len is set to npos.
        */
        int             compare(size_type idx, size_type len, const char* chars, size_type chars_len) const
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if ((len == npos) || (idx + len > d_cplength))
                        len = d_cplength - idx;

                int val = (len == 0) ? 0 : utf32_comp_char(&ptr()[idx], chars, (len < chars_len) ? len : chars_len);

                return (val != 0) ? ((val < 0) ? -1 : 1) : (len < chars_len) ? -1 : (len == chars_len) ? 0 : 1;
        }


        //////////////////////////////////////////////////////////////////////////
        // Character access
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Returns the code point at the given index.

        \param idx
                Zero based index of the code point to be returned.

        \note
                - For constant strings length()/size() provide a valid index and will access the default utf32 value.
                - For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.

        \return
                The utf32 code point at the given index within the String.
        */
        reference       operator[](size_type idx)
        {
                return (ptr()[idx]);
        }

        /*!
        \brief
                Returns the code point at the given index.

        \param idx
                Zero based index of the code point to be returned.

        \note
                - For constant strings length()/size() provide a valid index and will access the default utf32 value.
                - For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.

        \return
                The utf32 code point at the given index within the String.
        */
        value_type      operator[](size_type idx) const
        {
                return ptr()[idx];
        }

        /*!
        \brief
                Returns the code point at the given index.

        \param idx
                Zero based index of the code point to be returned.

        \return
                The utf32 code point at the given index within the String.

        \exception std::out_of_range    Thrown if \a idx is >= length().
        */
        reference       at(size_type idx)
        {
                if (d_cplength <= idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                return ptr()[idx];
        }

        /*!
        \brief
                Returns the code point at the given index.

        \param idx
                Zero based index of the code point to be returned.

        \return
                The utf32 code point at the given index within the String.

        \exception std::out_of_range    Thrown if \a idx is >= length().
        */
        const_reference at(size_type idx) const
        {
                if (d_cplength <= idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                return ptr()[idx];
        }


        //////////////////////////////////////////////////////////////////////////
        // C-Strings and arrays
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Returns contents of the String as a null terminated string of utf8 encoded data.

        \return
                Pointer to a char buffer containing the contents of the String encoded as null-terminated utf8 data.

        \note
                The buffer returned from this function is owned by the String object.

        \note
                Any function that modifies the String data will invalidate the buffer returned by this call.
        */
        const char* c_str(void) const
        {
                return (const char*)build_utf8_buff();
        }

        /*!
        \brief
                Returns contents of the String as utf8 encoded data.

        \return
                Pointer to a buffer containing the contents of the String encoded utf8 data.

        \note
                The buffer returned from this function is owned by the String object.

        \note
                Any function that modifies the String data will invalidate the buffer returned by this call.
        */
        const utf8* data(void) const
        {
                return build_utf8_buff();
        }

        // copy, at most, 'len' code-points of the string, begining with code-point 'idx', into the array 'buf' as valid utf8 encoded data
        // return number of utf8 code units placed into the buffer
        /*!
        \brief
                Copies an area of the String into the provided buffer as encoded utf8 data.

        \param buf
                Pointer to a buffer that is to receive the encoded data (this must be big enough to hold the encoded data)

        \param len
                Maximum number of code points from the String that should be encoded into the buffer
        
        \param idx
                Index of the first code point to be encoded into the buffer

        \return
                The number of utf8 encoded code units transferred to the buffer.

                \note A code unit does not equal a code point.  A utf32 code point, when encoded as utf8, can occupy between 1 and 4 code units.

        \exception std::out_of_range    Thrown if \a idx was invalid for this String.
        */
        size_type       copy(utf8* buf, size_type len = npos, size_type idx = 0) const
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (len == npos)
                        len = d_cplength;

                return encode(&ptr()[idx], buf, npos, len);
        }

        //////////////////////////////////////////////////////////////////////////
        // UTF8 Encoding length information
        //////////////////////////////////////////////////////////////////////////
        // return the number of bytes required to hold 'num' code-points, starting at code-point 'idx', of the the string when encoded as utf8 data.
        /*!
        \brief
                Return the number of utf8 code units required to hold an area of the String when encoded as utf8 data

        \param num
                Maximum number of code points to consider when calculating utf8 encoded size.

        \param idx
                Index of the first code point to consider when calculating the utf8 encoded size

        \return
                The number of utf8 code units (bytes) required to hold the specified sub-string when encoded as utf8 data.

        \exception std::out_of_range    Thrown if \a idx was invalid for this String.
        */
        size_type       utf8_stream_len(size_type num = npos, size_type idx = 0)
        {
                using namespace std;

                if (d_cplength < idx)
                        throw out_of_range("Index was out of range for CEGUI::String object");

                size_type       maxlen = d_cplength - idx;

                return encoded_size(&ptr()[idx], ceguimin(num, maxlen));
        }

        //////////////////////////////////////////////////////////////////////////
        // Assignment Functions
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Assign the value of String \a str to this String

        \param str
                String object containing the string value to be assigned.

        \return
                This String after the assignment has happened
        */
        String& operator=(const String& str)
        {
                return assign(str);
        }

        /*!
        \brief
                Assign a sub-string of String \a str to this String

        \param str
                String object containing the string data to be assigned.

        \param str_idx
                Index of the first code point in \a str that is to be assigned

        \param str_num
                Maximum number of code points from \a str that are be be assigned

        \return
                This String after the assignment has happened

        \exception std::out_of_range    Thrown if str_idx is invalid for \a str
        */
        String& assign(const String& str, size_type str_idx = 0, size_type str_num = npos)
        {
                if (str.d_cplength < str_idx)
                        throw std::out_of_range("Index was out of range for CEGUI::String object");

                if (str_num == npos)
                        str_num = str.d_cplength - str_idx;

                grow(str_num);
                setlen(str_num);
                memcpy(ptr(), &str.ptr()[str_idx], str_num * sizeof(utf32));
                return *this;
        }

        /*!
        \brief
                Assign the value of std::string \a std_str to this String

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param std_str
                std::string object containing the string value to be assigned.

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& operator=(const std::string& std_str)
        {
                return assign(std_str);
        }

        /*!
        \brief
                Assign a sub-string of std::string \a std_str to this String

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param std_str
                std::string object containing the string value to be assigned.

        \param str_idx
                Index of the first character of \a std_str to be assigned

        \param str_num
                Maximum number of characters from \a std_str to be assigned

        \return
                This String after the assignment has happened

        \exception std::out_of_range    Thrown if \a str_idx is invalid for \a std_str
        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& assign(const std::string& std_str, size_type str_idx = 0, size_type str_num = npos)
        {
                if (std_str.size() < str_idx)
                        throw std::out_of_range("Index was out of range for std::string object");

                if (str_num == npos)
                        str_num = (size_type)std_str.size() - str_idx;

                grow(str_num);
                setlen(str_num);

                while(str_num--)
                {
                        ((*this)[str_num]) = static_cast<utf32>(static_cast<unsigned char>(std_str[str_num + str_idx]));
                }

                return *this;
        }

        /*!
        \brief
                Assign to this String the string value represented by the given null-terminated utf8 encoded data

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param utf8_str
                Buffer containing valid null-terminated utf8 encoded data

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& operator=(const utf8* utf8_str)
        {
                return assign(utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Assign to this String the string value represented by the given null-terminated utf8 encoded data

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param utf8_str
                Buffer containing valid null-terminated utf8 encoded data

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& assign(const utf8* utf8_str)
        {
                return assign(utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Assign to this String the string value represented by the given utf8 encoded data

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param utf8_str
                Buffer containing valid utf8 encoded data

        \param str_num
                Number of code units (not code points) in the buffer pointed to by \a utf8_str

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large, or if str_num is 'npos'.
        */
        String& assign(const utf8* utf8_str, size_type str_num)
        {
                if (str_num == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                size_type enc_sze = encoded_size(utf8_str, str_num);

                grow(enc_sze);
                encode(utf8_str, ptr(), d_reserve, str_num);
                setlen(enc_sze);
                return *this;
        }

        /*!
        \brief
                Assigns the specified utf32 code point to this String.  Result is always a String 1 code point in length.

        \param code_point
                Valid utf32 Unicode code point to be assigned to the string

        \return
                This String after assignment
        */
        String& operator=(utf32 code_point)
        {
                return assign(1, code_point);
        }

        /*!
        \brief
                Assigns the specified code point repeatedly to the String

        \param num
                The number of times to assign the code point

        \param code_point
                Valid utf32 Unicode code point to be assigned to the string

        \return
                This String after assignment.

        \exception std::length_error    Thrown if \a num was 'npos'
        */
        String& assign(size_type num, utf32 code_point)
        {
                if (num == npos)
                        throw std::length_error("Code point count can not be 'npos'");

                grow(num);
                setlen(num);
                utf32* p = ptr();

                while(num--)
                        *p = code_point;

                return *this;
        }


        /*!
        \brief
                Assign to this String the given C-string.

        \param c_str
                Pointer to a valid C style string.

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& operator=(const char* c_str)
        {
                return assign(c_str, strlen(c_str));
        }


        /*!
        \brief
                Assign to this String the given C-string.

        \param c_str
                Pointer to a valid C style string.

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& assign(const char* c_str)
        {
                return assign(c_str, strlen(c_str));
        }


        /*!
        \brief
                Assign to this String a number of chars from a char array.

        \param chars
                char array.

        \param chars_len
                Number of chars to be assigned.

        \return
                This String after the assignment has happened

        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& assign(const char* chars, size_type chars_len)
        {
                grow(chars_len);
                utf32* pt = ptr();

                for (size_type i = 0; i < chars_len; ++i)
                {
                        *pt++ = static_cast<utf32>(static_cast<unsigned char>(*chars++));
                }

                setlen(chars_len);
                return *this;
        }


        /*!
        \brief
                Swaps the value of this String with the given String \a str

        \param str
                String object whos value is to be swapped with this String.

        \return
                Nothing
        */
        void    swap(String& str)
        {
                size_type       temp_len        = d_cplength;
                d_cplength = str.d_cplength;
                str.d_cplength = temp_len;

                size_type       temp_res        = d_reserve;
                d_reserve = str.d_reserve;
                str.d_reserve = temp_res;

                utf32*          temp_buf        = d_buffer;
                d_buffer = str.d_buffer;
                str.d_buffer = temp_buf;

                // see if we need to swap 'quick buffer' data
                if (temp_res <= STR_QUICKBUFF_SIZE)
                {
                        utf32           temp_qbf[STR_QUICKBUFF_SIZE];

                        memcpy(temp_qbf, d_quickbuff, STR_QUICKBUFF_SIZE * sizeof(utf32));
                        memcpy(d_quickbuff, str.d_quickbuff, STR_QUICKBUFF_SIZE * sizeof(utf32));
                        memcpy(str.d_quickbuff, temp_qbf, STR_QUICKBUFF_SIZE * sizeof(utf32));
                }

        }

        //////////////////////////////////////////////////////////////////////////
        // Appending Functions
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Appends the String \a str

        \param str
                String object that is to be appended

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& operator+=(const String& str)
        {
                return append(str);
        }

        /*!
        \brief
                Appends a sub-string of the String \a str

        \param str
                String object containing data to be appended

        \param str_idx
                Index of the first code point to be appended

        \param str_num
                Maximum number of code points to be appended

        \return
                This String after the append operation

        \exception std::out_of_range    Thrown if \a str_idx is invalid for \a str.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& append(const String& str, size_type str_idx = 0, size_type str_num = npos)
        {
                if (str.d_cplength < str_idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (str_num == npos)
                        str_num = str.d_cplength - str_idx;

                grow(d_cplength + str_num);
                memcpy(&ptr()[d_cplength], &str.ptr()[str_idx], str_num * sizeof(utf32));
                setlen(d_cplength + str_num);
                return *this;
        }


        /*!
        \brief
                Appends the std::string \a std_str

        \param std_str
                std::string object that is to be appended

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& operator+=(const std::string& std_str)
        {
                return append(std_str);
        }

        /*!
        \brief
                Appends a sub-string of the std::string \a std_str

        \param std_str
                std::string object containing data to be appended

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param str_idx
                Index of the first character to be appended

        \param str_num
                Maximum number of characters to be appended

        \return
                This String after the append operation

        \exception std::out_of_range    Thrown if \a str_idx is invalid for \a std_str.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& append(const std::string& std_str, size_type str_idx = 0, size_type str_num = npos)
        {
                if (std_str.size() < str_idx)
                        throw std::out_of_range("Index is out of range for std::string");

                if (str_num == npos)
                        str_num = (size_type)std_str.size() - str_idx;

                size_type newsze = d_cplength + str_num;

                grow(newsze);
                utf32* pt = &ptr()[newsze-1];

                while(str_num--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(std_str[str_num]));

                setlen(newsze);
                return *this;
        }


        /*!
        \brief
                Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.

        \param utf8_str
                buffer holding the null-terminated utf8 encoded data that is to be appended

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& operator+=(const utf8* utf8_str)
        {
                return append(utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.

        \param utf8_str
                Buffer holding the null-terminated utf8 encoded data that is to be appended

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& append(const utf8* utf8_str)
        {
                return append(utf8_str, utf_length(utf8_str));
        }


        /*!
        \brief
                Appends to the String the utf8 encoded data in the buffer utf8_str.

        \param utf8_str
                Buffer holding the utf8 encoded data that is to be appended

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param len
                Number of code units (not code points) in the buffer to be appended

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large, or if \a len was 'npos'
        */
        String& append(const utf8* utf8_str, size_type len)
        {
                if (len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                size_type encsz = encoded_size(utf8_str, len);
                size_type newsz = d_cplength + encsz;

                grow(newsz);
                encode(utf8_str, &ptr()[d_cplength], encsz, len);
                setlen(newsz);

                return *this;
        }


        /*!
        \brief
                Appends a single code point to the string

        \param code_point
                utf32 Unicode code point that is to be appended

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too long.
        */
        String& operator+=(utf32 code_point)
        {
                return append(1, code_point);
        }

        /*!
        \brief
                Appends a single code point multiple times to the string

        \param num
                Number of copies of the code point to be appended

        \param code_point
                utf32 Unicode code point that is to be appended

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too long, or if \a num was 'npos'.
        */
        String& append(size_type num, utf32 code_point)
        {
                if (num == npos)
                        throw std::length_error("Code point count can not be 'npos'");

                size_type newsz = d_cplength + num;
                grow(newsz);

                utf32* p = &ptr()[d_cplength];

                while(num--)
                        *p++ = code_point;

                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Appends a single code point to the string

        \param code_point
                utf32 Unicode code point that is to be appended

        \return
                Nothing

        \exception std::length_error    Thrown if resulting String would be too long.
        */
        void    push_back(utf32 code_point)
        {
                append(1, code_point);
        }

        /*!
        \brief
                Appends the code points in the reange [beg, end)

        \param beg
                Iterator describing the start of the range to be appended

        \param end
                Iterator describing the (exclusive) end of the range to be appended.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if the resulting string would be too large.
        */
        String& append(const_iterator beg, const_iterator end)
        {
                return replace(this->end(), this->end(), beg, end);
        }


        /*!
        \brief
                Appends to the String the given c-string.

        \param c_str
                c-string that is to be appended.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& operator+=(const char* c_str)
        {
                return append(c_str, strlen(c_str));
        }


        /*!
        \brief
                Appends to the String the given c-string.

        \param c_str
                c-string that is to be appended.

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& append(const char* c_str)
        {
                return append(c_str, strlen(c_str));
        }


        /*!
        \brief
                Appends to the String chars from the given char array.

        \param chars
                char array holding the chars that are to be appended

        \param chars_len
                Number of chars to be appended

        \return
                This String after the append operation

        \exception std::length_error    Thrown if resulting String would be too large, or if \a chars_len was 'npos'
        */
        String& append(const char* chars, size_type chars_len)
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                size_type newsz = d_cplength + chars_len;

                grow(newsz);

                utf32* pt = &ptr()[newsz-1];

                while(chars_len--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(chars[chars_len]));

                setlen(newsz);

                return *this;
        }


        //////////////////////////////////////////////////////////////////////////
        // Insertion Functions
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Inserts the given String object at the specified position.

        \param idx
                Index where the string is to be inserted.

        \param str
                String object that is to be inserted.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const String& str)
        {
                return insert(idx, str, 0, npos);
        }

        /*!
        \brief
                Inserts a sub-string of the given String object at the specified position.

        \param idx
                Index where the string is to be inserted.

        \param str
                String object containing data to be inserted.

        \param str_idx
                Index of the first code point from \a str to be inserted.

        \param str_num
                Maximum number of code points from \a str to be inserted.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx or \a str_idx are out of range.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const String& str, size_type str_idx, size_type str_num)
        {
                if ((d_cplength < idx) || (str.d_cplength < str_idx))
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (str_num == npos)
                        str_num = str.d_cplength - str_idx;

                size_type newsz = d_cplength + str_num;
                grow(newsz);
                memmove(&ptr()[idx + str_num], &ptr()[idx], (d_cplength - idx) * sizeof(utf32));
                memcpy(&ptr()[idx], &str.ptr()[str_idx], str_num * sizeof(utf32));
                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Inserts the given std::string object at the specified position.

        \param idx
                Index where the std::string is to be inserted.

        \param std_str
                std::string object that is to be inserted.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const std::string& std_str)
        {
                return insert(idx, std_str, 0, npos);
        }

        /*!
        \brief
                Inserts a sub-string of the given std::string object at the specified position.

        \param idx
                Index where the string is to be inserted.

        \param std_str
                std::string object containing data to be inserted.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param str_idx
                Index of the first character from \a std_str to be inserted.

        \param str_num
                Maximum number of characters from \a str to be inserted.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx or \a str_idx are out of range.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const std::string& std_str, size_type str_idx, size_type str_num)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (std_str.size() < str_idx)
                        throw std::out_of_range("Index is out of range for std::string");

                if (str_num == npos)
                        str_num = (size_type)std_str.size() - str_idx;

                size_type newsz = d_cplength + str_num;
                grow(newsz);

                memmove(&ptr()[idx + str_num], &ptr()[idx], (d_cplength - idx) * sizeof(utf32));

                utf32* pt = &ptr()[idx + str_num - 1];
                
                while(str_num--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(std_str[str_idx + str_num]));

                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Inserts the given null-terminated utf8 encoded data at the specified position.

        \param idx
                Index where the data is to be inserted.

        \param utf8_str
                Buffer containing the null-terminated utf8 encoded data that is to be inserted.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const utf8* utf8_str)
        {
                return insert(idx, utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Inserts the given utf8 encoded data at the specified position.

        \param idx
                Index where the data is to be inserted.

        \param utf8_str
                Buffer containing the utf8 encoded data that is to be inserted.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param len
                Length of the data to be inserted in uf8 code units (not code points)

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large, or if \a len is 'npos'
        */
        String& insert(size_type idx, const utf8* utf8_str, size_type len)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (len == npos)
                        throw std::length_error("Length of utf8 encoded string can not be 'npos'");

                size_type encsz = encoded_size(utf8_str, len);
                size_type newsz = d_cplength + encsz;

                grow(newsz);
                memmove(&ptr()[idx + encsz], &ptr()[idx], (d_cplength - idx) * sizeof(utf32));
                encode(utf8_str, &ptr()[idx], encsz, len);
                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Inserts a code point multiple times into the String

        \param idx
                Index where the code point(s) are to be inserted

        \param num
                The number of times to insert the code point

        \param code_point
                The utf32 code point that is to be inserted

        \return
                This String after the insertion.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large, or if \a num is 'npos'
        */
        String& insert(size_type idx, size_type num, utf32 code_point)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (num == npos)
                        throw std::length_error("Code point count can not be 'npos'");

                size_type newsz = d_cplength + num;
                grow(newsz);

                memmove(&ptr()[idx + num], &ptr()[idx], (d_cplength - idx) * sizeof(utf32));

                utf32* pt = &ptr()[idx + num - 1];

                while(num--)
                        *pt-- = code_point;

                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Inserts a code point multiple times into the String

        \param pos
                Iterator describing the position where the code point(s) are to be inserted

        \param num
                The number of times to insert the code point

        \param code_point
                The utf32 code point that is to be inserted

        \return
                This String after the insertion.

        \exception std::length_error    Thrown if resulting String would be too large, or if \a num is 'npos'
        */
        void insert(iterator pos, size_type num, utf32 code_point)
        {
                insert(safe_iter_dif(pos, begin()), num, code_point);
        }

        /*!
        \brief
                Inserts a single code point into the String

        \param pos
                Iterator describing the position where the code point is to be inserted

        \param code_point
                The utf32 code point that is to be inserted

        \return
                This String after the insertion.

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        iterator insert(iterator pos, utf32 code_point)
        {
                insert(pos, 1, code_point);
                return pos;
        }

        /*!
        \brief
                Inserts code points specified by the range [beg, end).

        \param pos
                Iterator describing the position where the data is to be inserted

        \param beg
                Iterator describing the begining of the range to be inserted

        \param end
                Iterator describing the (exclusive) end of the range to be inserted.

        \return
                Nothing.

        \exception std::length_error    Thrown if resulting String would be too large.
        */
        void    insert(iterator pos, const_iterator beg, const_iterator end)
        {
                replace(pos, pos, beg, end);
        }


        /*!
        \brief
                Inserts the given c-string at the specified position.

        \param idx
                Index where the c-string is to be inserted.

        \param c_str
                c-string that is to be inserted.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large.
        */
        String& insert(size_type idx, const char* c_str)
        {
                return insert(idx, c_str, strlen(c_str));
        }


        /*!
        \brief
                Inserts chars from the given char array at the specified position.

        \param idx
                Index where the data is to be inserted.

        \param chars
                char array containing the chars that are to be inserted.

        \param chars_len
                Length of the char array to be inserted.

        \return
                This String after the insert.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        \exception std::length_error    Thrown if resulting String would be too large, or if \a chars_len is 'npos'
        */
        String& insert(size_type idx, const char* chars, size_type chars_len)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (chars_len == npos)
                        throw std::length_error("Length of char array can not be 'npos'");

                size_type newsz = d_cplength + chars_len;

                grow(newsz);
                memmove(&ptr()[idx + chars_len], &ptr()[idx], (d_cplength - idx) * sizeof(utf32));

                utf32* pt = &ptr()[idx + chars_len - 1];

                while(chars_len--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(chars[chars_len]));

                setlen(newsz);

                return *this;
        }


        //////////////////////////////////////////////////////////////////////////
        // Erasing characters
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Removes all data from the String

        \return
                Nothing
        */
        void    clear(void)
        {
                setlen(0);
                trim();
        }

        /*!
        \brief
                Removes all data from the String

        \return
                The empty String (*this)
        */
        String& erase(void)
        {
                clear();
                return *this;
        }

        /*!
        \brief
                Erase a single code point from the string

        \param idx
                The index of the code point to be removed.

        \return
                This String after the erase operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        String& erase(size_type idx)
        {
                return erase(idx, 1);
        }

        /*!
        \brief
                Erase a range of code points

        \param idx
                Index of the first code point to be removed.

        \param len
                Maximum number of code points to be removed.

        \return
                This String after the erase operation.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        String& erase(size_type idx, size_type len = npos)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range foe CEGUI::String");

                if (len == npos)
                        len = d_cplength - idx;

                size_type newsz = d_cplength - len;

                memmove(&ptr()[idx], &ptr()[idx + len], (d_cplength - idx - len) * sizeof(utf32));
                setlen(newsz);
                return  *this;
        }

        /*!
        \brief
                Erase the code point described by the given iterator

        \param pos
                Iterator describing the code point to be erased

        \return
                This String after the erase operation.
        */
        String& erase(iterator pos)
        {
                return erase(safe_iter_dif(pos, begin()), 1);
        }

        /*!
        \brief
                Erase a range of code points described by the iterators [beg, end).

        \param beg
                Iterator describing the postion of the beginning of the range to erase

        \param end
                Iterator describing the postion of the (exclusive) end of the range to erase

        \return
                This String after the erase operation.
        */
        String& erase(iterator beg, iterator end)
        {
                return erase(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg));
        }

        //////////////////////////////////////////////////////////////////////////
        // Resizing
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Resizes the String either by inserting default utf32 code points to make it larger, or by truncating to make it smaller

        \param num
                The length, in code points, that the String is to be made.

        \return
                Nothing.

        \exception std::length_error    Thrown if the String would be too large.
        */
        void    resize(size_type num)
        {
                resize(num, utf32());
        }

        /*!
        \brief
                Resizes the String either by inserting the given utf32 code point to make it larger, or by truncating to make it smaller

        \param num
                The length, in code points, that the String is to be made.

        \param code_point
                The utf32 code point that should be used when majing the String larger

        \return
                Nothing.

        \exception std::length_error    Thrown if the String would be too large.
        */
        void    resize(size_type num, utf32 code_point)
        {
                if (num < d_cplength)
                {
                        setlen(num);
                }
                else
                {
                        append(num - d_cplength, code_point);
                }

        }

        //////////////////////////////////////////////////////////////////////////
        // Replacing Characters
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Replace code points in the String with the specified String object

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param str
                The String object that is to replace the specified code points

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(size_type idx, size_type len, const String& str)
        {
                return replace(idx, len, str, 0, npos);
        }

        /*!
        \brief
                Replace the code points in the range [beg, end) with the specified String object

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param str
                The String object that is to replace the specified range of code points

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(iterator beg, iterator end, const String& str)
        {
                return replace(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg), str, 0, npos);
        }

        /*!
        \brief
                Replace code points in the String with a specified sub-string of a given String object.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced.  If this is 0, the operation is an insert at position \a idx.

        \param str
                String object containing the data that will replace the specified range of code points

        \param str_idx
                Index of the first code point of \a str that is to replace the specified code point range

        \param str_num
                Maximum number of code points of \a str that are to replace the specified code point range

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if either \a idx, or \a str_idx are invalid
        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& replace(size_type idx, size_type len, const String& str, size_type str_idx, size_type str_num)
        {
                if ((d_cplength < idx) || (str.d_cplength < str_idx))
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (((str_idx + str_num) > str.d_cplength) || (str_num == npos))
                        str_num = str.d_cplength - str_idx;

                if (((len + idx) > d_cplength) || (len == npos))
                        len = d_cplength - idx;

                size_type newsz = d_cplength + str_num - len;

                grow(newsz);

                if ((idx + len) < d_cplength)
                        memmove(&ptr()[idx + str_num], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                memcpy(&ptr()[idx], &str.ptr()[str_idx], str_num * sizeof(utf32));
                setlen(newsz);

                return *this;
        }


        /*!
        \brief
                Replace code points in the String with the specified std::string object

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param std_str
                The std::string object that is to replace the specified code points

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(size_type idx, size_type len, const std::string& std_str)
        {
                return replace(idx, len, std_str, 0, npos);
        }

        /*!
        \brief
                Replace the code points in the range [beg, end) with the specified std::string object

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param std_str
                The std::string object that is to replace the specified range of code points

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(iterator beg, iterator end, const std::string& std_str)
        {
                return replace(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg), std_str, 0, npos);
        }

        /*!
        \brief
                Replace code points in the String with a specified sub-string of a given std::string object.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced.  If this is 0, the operation is an insert at position \a idx.

        \param std_str
                std::string object containing the data that will replace the specified range of code points

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \param str_idx
                Index of the first code point of \a std_str that is to replace the specified code point range

        \param str_num
                Maximum number of code points of \a std_str that are to replace the specified code point range

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if either \a idx, or \a str_idx are invalid
        \exception std::length_error    Thrown if the resulting String would have been too large.
        */
        String& replace(size_type idx, size_type len, const std::string& std_str, size_type str_idx, size_type str_num)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (std_str.size() < str_idx)
                        throw std::out_of_range("Index is out of range for std::string");

                if (((str_idx + str_num) > std_str.size()) || (str_num == npos))
                        str_num = (size_type)std_str.size() - str_idx;

                if (((len + idx) > d_cplength) || (len == npos))
                        len = d_cplength - idx;

                size_type newsz = d_cplength + str_num - len;

                grow(newsz);

                if ((idx + len) < d_cplength)
                        memmove(&ptr()[idx + str_num], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                utf32* pt = &ptr()[idx + str_num - 1];

                while (str_num--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(std_str[str_idx + str_num]));

                setlen(newsz);

                return *this;
        }


        /*!
        \brief
                Replace code points in the String with the specified null-terminated utf8 encoded data.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param utf8_str
                Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(size_type idx, size_type len, const utf8* utf8_str)
        {
                return replace(idx, len, utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param utf8_str
                Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(iterator beg, iterator end, const utf8* utf8_str)
        {
                return replace(beg, end, utf8_str, utf_length(utf8_str));
        }

        /*!
        \brief
                Replace code points in the String with the specified utf8 encoded data.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param utf8_str
                Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large, or if \a str_len was 'npos'.
        */
        String& replace(size_type idx, size_type len, const utf8* utf8_str, size_type str_len)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if (((len + idx) > d_cplength) || (len == npos))
                        len = d_cplength - idx;

                size_type encsz = encoded_size(utf8_str, str_len);
                size_type newsz = d_cplength + encsz - len;

                grow(newsz);

                if ((idx + len) < d_cplength)
                        memmove(&ptr()[idx + encsz], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                encode(utf8_str, &ptr()[idx], encsz, str_len);

                setlen(newsz);
                return *this;
        }

        /*!
        \brief
                Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param utf8_str
                Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                This String after the replace operation

                \exception std::length_error    Thrown if the resulting String would be too large, or if \a str_len was 'npos'.
        */
        String& replace(iterator beg, iterator end, const utf8* utf8_str, size_type str_len)
        {
                return replace(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg), utf8_str, str_len);
        }

        /*!
        \brief
                Replaces a specified range of code points with occurrences of a given code point

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to replace.  If this is 0 the operation is an insert

        \param num
                Number of occurrences of \a code_point that are to replace the specified range of code points

        \param code_point
                Code point that is to be used when replacing the specified range of code points

        \return
                This String after the replace operation.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if resulting String would have been too long, or if \a num was 'npos'.
        */
        String& replace(size_type idx, size_type len, size_type num, utf32 code_point)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (num == npos)
                        throw std::length_error("Code point count can not be 'npos'");

                if (((len + idx) > d_cplength) || (len == npos))
                        len = d_cplength - idx;

                size_type newsz = d_cplength + num - len;

                grow(newsz);

                if ((idx + len) < d_cplength)
                        memmove(&ptr()[idx + num], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                utf32* pt = &ptr()[idx + num - 1];

                while (num--)
                        *pt-- = code_point;

                setlen(newsz);

                return *this;
        }

        /*!
        \brief
                Replace the code points in the range [beg, end) with occurrences of a given code point

        \note
                If \a beg == \a end, the operation is an insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param num
                Number of occurrences of \a code_point that are to replace the specified range of code points

        \param code_point
                Code point that is to be used when replacing the specified range of code points

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if resulting String would have been too long, or if \a num was 'npos'.
        */
        String& replace(iterator beg, iterator end, size_type num, utf32 code_point)
        {
                return replace(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg), num, code_point);
        }


        /*!
        \brief
                Replace the code points in the range [beg, end) with code points from the range [newBeg, newEnd).

        \note
                If \a beg == \a end, the operation is an insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param newBeg
                Iterator describing the beginning of the range to insert.

        \param newEnd   
                Iterator describing the (exclusive) end of the range to insert.

        \return
                This String after the insert operation.

        \exception std::length_error    Thrown if the resulting string would be too long.
        */
        String& replace(iterator beg, iterator end, const_iterator newBeg, const_iterator newEnd)
        {
                if (beg == end)
                {
                        erase(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg));
                }
                else
                {
                        size_type str_len = safe_iter_dif(newEnd, newBeg);
                        size_type idx = safe_iter_dif(beg, begin());
                        size_type len = safe_iter_dif(end, beg);

                        if ((len + idx) > d_cplength)
                                len = d_cplength - idx;

                        size_type newsz = d_cplength + str_len - len;

                        grow(newsz);

                        if ((idx + len) < d_cplength)
                                memmove(&ptr()[idx + str_len], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                        memcpy(&ptr()[idx], newBeg.d_ptr, str_len * sizeof(utf32));
                        setlen(newsz);
                }

                return *this;
        }


        /*!
        \brief
                Replace code points in the String with the specified c-string.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param c_str
                c-string that is to replace the specified code points

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(size_type idx, size_type len, const char* c_str)
        {
                return replace(idx, len, c_str, strlen(c_str));
        }


        /*!
        \brief
                Replace the code points in the range [beg, end) with the specified c-string.

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param c_str
                c-string that is to replace the specified range of code points

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if the resulting String would be too large.
        */
        String& replace(iterator beg, iterator end, const char* c_str)
        {
                return replace(beg, end, c_str, strlen(c_str));
        }


        /*!
        \brief
                Replace code points in the String with chars from the given char array.

        \param idx
                Index of the first code point to be replaced

        \param len
                Maximum number of code points to be replaced (if this is 0, operation is an insert at position \a idx)

        \param chars
                char array containing the cars that are to replace the specified code points

        \param chars_len
                Number of chars in the char array.

        \return
                This String after the replace operation

        \exception std::out_of_range    Thrown if \a idx is invalid for this String
        \exception std::length_error    Thrown if the resulting String would be too large, or if \a chars_len was 'npos'.
        */
        String& replace(size_type idx, size_type len, const char* chars, size_type chars_len)
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for CEGUI::String");

                if (chars_len == npos)
                        throw std::length_error("Length for the char array can not be 'npos'");

                if (((len + idx) > d_cplength) || (len == npos))
                        len = d_cplength - idx;

                size_type newsz = d_cplength + chars_len - len;

                grow(newsz);

                if ((idx + len) < d_cplength)
                        memmove(&ptr()[idx + chars_len], &ptr()[len + idx], (d_cplength - idx - len) * sizeof(utf32));

                utf32* pt = &ptr()[idx + chars_len - 1];

                while (chars_len--)
                        *pt-- = static_cast<utf32>(static_cast<unsigned char>(chars[chars_len]));

                setlen(newsz);
                return *this;
        }


        /*!
        \brief
                Replace the code points in the range [beg, end) with chars from the given char array.

        \note
                If \a beg == \a end, the operation is a insert at iterator position \a beg

        \param beg
                Iterator describing the start of the range to be replaced

        \param end
                Iterator describing the (exclusive) end of the range to be replaced.

        \param chars
                char array containing the chars that are to replace the specified range of code points

        \param chars_len
                Number of chars in the char array.

        \return
                This String after the replace operation

        \exception std::length_error    Thrown if the resulting String would be too large, or if \a chars_len was 'npos'.
        */
        String& replace(iterator beg, iterator end, const char* chars, size_type chars_len)
        {
                return replace(safe_iter_dif(beg, begin()), safe_iter_dif(end, beg), chars, chars_len);
        }


        //////////////////////////////////////////////////////////////////////////
        // Find a code point
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Search forwards for a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the first occurrence of \a code_point travelling forwards from \a idx.
                - npos if the code point could not be found
        */
        size_type       find(utf32 code_point, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        while (idx < d_cplength)
                        {
                                if (*pt++ == code_point)
                                        return idx;

                                ++idx;
                        }

                }

                return npos;
        }

        /*!
        \brief
                Search backwards for a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the first occurrence of \a code_point travelling backwards from \a idx.
                - npos if the code point could not be found
        */
        size_type       rfind(utf32 code_point, size_type idx = npos) const
        {
                if (idx >= d_cplength)
                        idx = d_cplength - 1;

                if (d_cplength > 0)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (*pt-- == code_point)
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        //////////////////////////////////////////////////////////////////////////
        // Find a substring
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Search forwards for a sub-string

        \param str
                String object describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a str travelling forwards from \a idx.
                - npos if the sub-string could not be found
        */
        size_type       find(const String& str, size_type idx = 0) const
        {
                if ((str.d_cplength == 0) && (idx < d_cplength))
                        return idx;

                if (idx < d_cplength)
                {
                        // loop while search string could fit in to search area
                        while (d_cplength - idx >= str.d_cplength)
                        {
                                if (0 == compare(idx, str.d_cplength, str))
                                        return idx;

                                ++idx;
                        }

                }

                return npos;
        }

        /*!
        \brief
                Search backwards for a sub-string

        \param str
                String object describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a str travelling backwards from \a idx.
                - npos if the sub-string could not be found
        */
        size_type       rfind(const String& str, size_type idx = npos) const
        {
                if (str.d_cplength == 0)
                        return (idx < d_cplength) ? idx : d_cplength;

                if (str.d_cplength <= d_cplength)
                {
                        if (idx > (d_cplength - str.d_cplength))
                                idx = d_cplength - str.d_cplength;

                        do
                        {
                                if (0 == compare(idx, str.d_cplength, str))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        /*!
        \brief
                Search forwards for a sub-string

        \param std_str
                std::string object describing the sub-string to search for

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a std_str travelling forwards from \a idx.
                - npos if the sub-string could not be found
        */
        size_type       find(const std::string& std_str, size_type idx = 0) const
        {
                std::string::size_type sze = std_str.size();

                if ((sze == 0) && (idx < d_cplength))
                        return idx;

                if (idx < d_cplength)
                {
                        // loop while search string could fit in to search area
                        while (d_cplength - idx >= sze)
                        {
                                if (0 == compare(idx, (size_type)sze, std_str))
                                        return idx;

                                ++idx;
                        }

                }

                return npos;
        }

        /*!
        \brief
                Search backwards for a sub-string

        \param std_str
                std::string object describing the sub-string to search for

        \note
                Characters from \a std_str are considered to represent Unicode code points in the range 0x00..0xFF.  No translation of
                the encountered data is performed.

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a std_str travelling backwards from \a idx.
                - npos if the sub-string could not be found
        */
        size_type       rfind(const std::string& std_str, size_type idx = npos) const
        {
                std::string::size_type sze = std_str.size();

                if (sze == 0)
                        return (idx < d_cplength) ? idx : d_cplength;

                if (sze <= d_cplength)
                {
                        if (idx > (d_cplength - sze))
                                idx = d_cplength - sze;

                        do
                        {
                                if (0 == compare(idx, (size_type)sze, std_str))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        /*!
        \brief
                Search forwards for a sub-string

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the sub-string to search for

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a utf8_str travelling forwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find(const utf8* utf8_str, size_type idx = 0) const
        {
                return find(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Search backwards for a sub-string

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the sub-string to search for

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a utf8_str travelling backwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       rfind(const utf8* utf8_str, size_type idx = npos) const
        {
                return rfind(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Search forwards for a sub-string

        \param utf8_str
                Buffer containing utf8 encoded data describing the sub-string to search for

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the code point where the search is to start

        \param str_len
                Length of the utf8 encoded sub-string in utf8 code units (not code points)

        \return
                - Index of the first occurrence of sub-string \a utf8_str travelling forwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::length_error    Thrown if \a str_len is 'npos'
        */
        size_type       find(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                size_type sze = encoded_size(utf8_str, str_len);

                if ((sze == 0) && (idx < d_cplength))
                        return idx;

                if (idx < d_cplength)
                {
                        // loop while search string could fit in to search area
                        while (d_cplength - idx >= sze)
                        {
                                if (0 == compare(idx, sze, utf8_str, sze))
                                        return idx;

                                ++idx;
                        }

                }

                return npos;
        }

        /*!
        \brief
                Search backwards for a sub-string

        \param utf8_str
                Buffer containing utf8 encoded data describing the sub-string to search for

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the code point where the search is to start

        \param str_len
                Length of the utf8 encoded sub-string in utf8 code units (not code points)

        \return
                - Index of the first occurrence of sub-string \a utf8_str travelling backwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::length_error    Thrown if \a str_len is 'npos'
        */
        size_type       rfind(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                size_type sze = encoded_size(utf8_str, str_len);

                if (sze == 0)
                        return (idx < d_cplength) ? idx : d_cplength;

                if (sze <= d_cplength)
                {
                        if (idx > (d_cplength - sze))
                                idx = d_cplength - sze;

                        do
                        {
                                if (0 == compare(idx, sze, utf8_str, sze))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Search forwards for a sub-string

        \param c_str
                c-string describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a c_str travelling forwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find(const char* c_str, size_type idx = 0) const
        {
                return find(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Search backwards for a sub-string

        \param c_str
                c-string describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \return
                - Index of the first occurrence of sub-string \a c_str travelling backwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       rfind(const char* c_str, size_type idx = npos) const
        {
                return rfind(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Search forwards for a sub-string

        \param chars
                char array describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \param chars_len
                Number of chars in the char array.

        \return
                - Index of the first occurrence of sub-string \a chars travelling forwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::length_error    Thrown if \a chars_len is 'npos'
        */
        size_type       find(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if ((chars_len == 0) && (idx < d_cplength))
                        return idx;

                if (idx < d_cplength)
                {
                        // loop while search string could fit in to search area
                        while (d_cplength - idx >= chars_len)
                        {
                                if (0 == compare(idx, chars_len, chars, chars_len))
                                        return idx;

                                ++idx;
                        }

                }

                return npos;
        }


        /*!
        \brief
                Search backwards for a sub-string

        \param chars
                char array describing the sub-string to search for

        \param idx
                Index of the code point where the search is to start

        \param chars_len
                Number of chars in the char array.

        \return
                - Index of the first occurrence of sub-string \a chars travelling backwards from \a idx.
                - npos if the sub-string could not be found

        \exception std::length_error    Thrown if \a chars_len is 'npos'
        */
        size_type       rfind(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if (chars_len == 0)
                        return (idx < d_cplength) ? idx : d_cplength;

                if (chars_len <= d_cplength)
                {
                        if (idx > (d_cplength - chars_len))
                                idx = d_cplength - chars_len;

                        do
                        {
                                if (0 == compare(idx, chars_len, chars, chars_len))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        //////////////////////////////////////////////////////////////////////////
        // Find first of different code-points
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Find the first occurrence of one of a set of code points.

        \param str
                String object describing the set of code points.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first occurrence of any one of the code points in \a str starting from from \a idx.
                - npos if none of the code points in \a str were found.
        */
        size_type       find_first_of(const String& str, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != str.find(*pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }

        /*!
        \brief
                Find the first code point that is not one of a set of code points.

        \param str
                String object describing the set of code points.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first code point that does not match any one of the code points in \a str starting from from \a idx.
                - npos if all code points matched one of the code points in \a str.
        */
        size_type       find_first_not_of(const String& str, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == str.find(*pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }


        /*!
        \brief
                Find the first occurrence of one of a set of code points.

        \param std_str
                std::string object describing the set of code points.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first occurrence of any one of the code points in \a std_str starting from from \a idx.
                - npos if none of the code points in \a std_str were found.
        */
        size_type       find_first_of(const std::string& std_str, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(std_str, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }

        /*!
        \brief
                Find the first code point that is not one of a set of code points.

        \param std_str
                std::string object describing the set of code points.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first code point that does not match any one of the code points in \a std_str starting from from \a idx.
                - npos if all code points matched one of the code points in \a std_str.
        */
        size_type       find_first_not_of(const std::string& std_str, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(std_str, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }


        /*!
        \brief
                Find the first occurrence of one of a set of code points.

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first occurrence of any one of the code points in \a utf8_str starting from from \a idx.
                - npos if none of the code points in \a utf8_str were found.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_first_of(const utf8* utf8_str, size_type idx = 0) const
        {
                return find_first_of(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Find the first code point that is not one of a set of code points.

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
                - npos if all code points matched one of the code points in \a utf8_str.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_first_not_of(const utf8* utf8_str, size_type idx = 0) const
        {
                return find_first_not_of(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Find the first occurrence of one of a set of code points.

        \param utf8_str
                Buffer containing utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                - Index of the first occurrence of any one of the code points in \a utf8_str starting from from \a idx.
                - npos if none of the code points in \a utf8_str were found.

        \exception std::length_error    Thrown if \a str_len was 'npos'.
        */
        size_type       find_first_of(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if (idx < d_cplength)
                {
                        size_type encsze = encoded_size(utf8_str, str_len);

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(utf8_str, encsze, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }

        /*!
        \brief
                Find the first code point that is not one of a set of code points.

        \param utf8_str
                Buffer containing utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                - Index of the first code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
                - npos if all code points matched one of the code points in \a utf8_str.

        \exception std::length_error    Thrown if \a str_len was 'npos'.
        */
        size_type       find_first_not_of(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if (idx < d_cplength)
                {
                        size_type encsze = encoded_size(utf8_str, str_len);

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(utf8_str, encsze, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }


        /*!
        \brief
                Search forwards for a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the first occurrence of \a code_point starting from from \a idx.
                - npos if the code point could not be found
        */
        size_type       find_first_of(utf32 code_point, size_type idx = 0) const
        {
                return find(code_point, idx);
        }

        /*!
        \brief
                Search forwards for the first code point that does not match a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the first code point that does not match \a code_point starting from from \a idx.
                - npos if all code points matched \a code_point

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_first_not_of(utf32 code_point, size_type idx = 0) const
        {
                if (idx < d_cplength)
                {
                        do
                        {
                                if ((*this)[idx] != code_point)
                                        return idx;

                        } while(idx++ < d_cplength);

                }

                return npos;
        }


        /*!
        \brief
                Find the first occurrence of one of a set of chars.

        \param c_str
                c-string describing the set of chars.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first occurrence of any one of the chars in \a c_str starting from from \a idx.
                - npos if none of the chars in \a c_str were found.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_first_of(const char* c_str, size_type idx = 0) const
        {
                return find_first_of(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Find the first code point that is not one of a set of chars.

        \param c_str
                c-string describing the set of chars.

        \param idx
                Index of the start point for the search

        \return
                - Index of the first code point that does not match any one of the chars in \a c_str starting from from \a idx.
                - npos if all code points matched any of the chars in \a c_str.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_first_not_of(const char* c_str, size_type idx = 0) const
        {
                return find_first_not_of(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Find the first occurrence of one of a set of chars.

        \param chars
                char array containing the set of chars.

        \param idx
                Index of the start point for the search

        \param chars_len
                Number of chars in the char array.

        \return
                - Index of the first occurrence of any one of the chars in \a chars starting from from \a idx.
                - npos if none of the chars in \a chars were found.

        \exception std::length_error    Thrown if \a chars_len was 'npos'.
        */
        size_type       find_first_of(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(chars, chars_len, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }


        /*!
        \brief
                Find the first code point that is not one of a set of chars.

        \param chars
                char array containing the set of chars.

        \param idx
                Index of the start point for the search

        \param chars_len
                Number of chars in the car array.

        \return
                - Index of the first code point that does not match any one of the chars in \a chars starting from from \a idx.
                - npos if all code points matched any of the chars in \a chars.

        \exception std::length_error    Thrown if \a chars_len was 'npos'.
        */
        size_type       find_first_not_of(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if (idx < d_cplength)
                {
                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(chars, chars_len, *pt++))
                                        return idx;

                        } while (++idx != d_cplength);

                }

                return npos;
        }


        //////////////////////////////////////////////////////////////////////////
        // Find last of different code-points
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Find the last occurrence of one of a set of code points.

        \param str
                String object describing the set of code points.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last occurrence of any one of the code points in \a str starting from \a idx.
                - npos if none of the code points in \a str were found.
        */
        size_type       find_last_of(const String& str, size_type idx = npos) const
        {
                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != str.find(*pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        /*!
        \brief
                Find the last code point that is not one of a set of code points.

        \param str
                String object describing the set of code points.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last code point that does not match any one of the code points in \a str starting from \a idx.
                - npos if all code points matched one of the code points in \a str.
        */
        size_type       find_last_not_of(const String& str, size_type idx = npos) const
        {
                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == str.find(*pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Find the last occurrence of one of a set of code points.

        \param std_str
                std::string object describing the set of code points.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last occurrence of any one of the code points in \a std_str starting from \a idx.
                - npos if none of the code points in \a std_str were found.
        */
        size_type       find_last_of(const std::string& std_str, size_type idx = npos) const
        {
                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(std_str, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        /*!
        \brief
                Find the last code point that is not one of a set of code points.

        \param std_str
                std::string object describing the set of code points.

        \note
                The characters of \a std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF.  No translation of
                the provided data will occur.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last code point that does not match any one of the code points in \a std_str starting from \a idx.
                - npos if all code points matched one of the code points in \a std_str.
        */
        size_type       find_last_not_of(const std::string& std_str, size_type idx = npos) const
        {
                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(std_str, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Find the last occurrence of one of a set of code points.

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last occurrence of any one of the code points in \a utf8_str starting from \a idx.
                - npos if none of the code points in \a utf8_str were found.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_last_of(const utf8* utf8_str, size_type idx = npos) const
        {
                return find_last_of(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Find the last code point that is not one of a set of code points.

        \param utf8_str
                Buffer containing null-terminated utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last code point that does not match any one of the code points in \a utf8_str starting from \a idx.
                - npos if all code points matched one of the code points in \a utf8_str.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_last_not_of(const utf8* utf8_str, size_type idx = npos) const
        {
                return find_last_not_of(utf8_str, idx, utf_length(utf8_str));
        }

        /*!
        \brief
                Find the last occurrence of one of a set of code points.

        \param utf8_str
                Buffer containing utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                - Index of the last occurrence of any one of the code points in \a utf8_str starting from from \a idx.
                - npos if none of the code points in \a utf8_str were found.

        \exception std::length_error    Thrown if \a str_len was 'npos'.
        */
        size_type       find_last_of(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        size_type encsze = encoded_size(utf8_str, str_len);

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(utf8_str, encsze, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }

        /*!
        \brief
                Find the last code point that is not one of a set of code points.

        \param utf8_str
                Buffer containing utf8 encoded data describing the set of code points.

        \note
                A basic string literal (cast to utf8*) can be passed to this function, provided that the string is
                comprised only of code points 0x00..0x7f.  The use of extended ASCII characters (with values >0x7f)
                would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable
                results.

        \param idx
                Index of the start point for the search

        \param str_len
                Length of the utf8 encoded data in utf8 code units (not code points).

        \return
                - Index of the last code point that does not match any one of the code points in \a utf8_str starting from from \a idx.
                - npos if all code points matched one of the code points in \a utf8_str.

        \exception std::length_error    Thrown if \a str_len was 'npos'.
        */
        size_type       find_last_not_of(const utf8* utf8_str, size_type idx, size_type str_len) const
        {
                if (str_len == npos)
                        throw std::length_error("Length for utf8 encoded string can not be 'npos'");

                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        size_type encsze = encoded_size(utf8_str, str_len);

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(utf8_str, encsze, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Search for last occurrence of a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the last occurrence of \a code_point starting from \a idx.
                - npos if the code point could not be found
        */
        size_type       find_last_of(utf32 code_point, size_type idx = npos) const
        {
                return rfind(code_point, idx);
        }

        /*!
        \brief
                Search for the last code point that does not match a given code point

        \param code_point
                The utf32 code point to search for

        \param idx
                Index of the code point where the search is to start.

        \return
                - Index of the last code point that does not match \a code_point starting from from \a idx.
                - npos if all code points matched \a code_point
        */
        size_type       find_last_not_of(utf32 code_point, size_type idx = npos) const
        {
                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        do
                        {
                                if ((*this)[idx] != code_point)
                                        return idx;

                        } while(idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Find the last occurrence of one of a set of chars.

        \param c_str
                c-string describing the set of chars.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last occurrence of any one of the chars in \a c_str starting from \a idx.
                - npos if none of the chars in \a c_str were found.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_last_of(const char* c_str, size_type idx = npos) const
        {
                return find_last_of(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Find the last code point that is not one of a set of chars.

        \param c_str
                c-string describing the set of chars.

        \param idx
                Index of the start point for the search

        \return
                - Index of the last code point that does not match any one of the chars in \a c_str starting from \a idx.
                - npos if all code points matched any of the chars in \a c_str.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        size_type       find_last_not_of(const char* c_str, size_type idx = npos) const
        {
                return find_last_not_of(c_str, idx, strlen(c_str));
        }


        /*!
        \brief
                Find the last occurrence of one of a set of chars.

        \param chars
                char array containing the set of chars.

        \param idx
                Index of the start point for the search

        \param chars_len
                Number of chars in the char array.

        \return
                - Index of the last occurrence of any one of the chars in \a chars, starting from from \a idx.
                - npos if none of the chars in \a chars were found.

        \exception std::length_error    Thrown if \a chars_len was 'npos'.
        */
        size_type       find_last_of(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos != find_codepoint(chars, chars_len, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        /*!
        \brief
                Find the last code point that is not one of a set of chars.

        \param chars
                char array containing the set of chars.

        \param idx
                Index of the start point for the search

        \param chars_len
                Number of chars in the char array.

        \return
                - Index of the last code point that does not match any one of the chars in \a chars, starting from from \a idx.
                - npos if all code points matched any of the chars in \a chars.

        \exception std::length_error    Thrown if \a chars_len was 'npos'.
        */
        size_type       find_last_not_of(const char* chars, size_type idx, size_type chars_len) const
        {
                if (chars_len == npos)
                        throw std::length_error("Length for char array can not be 'npos'");

                if (d_cplength > 0)
                {
                        if (idx >= d_cplength)
                                idx = d_cplength - 1;

                        const utf32* pt = &ptr()[idx];

                        do
                        {
                                if (npos == find_codepoint(chars, chars_len, *pt--))
                                        return idx;

                        } while (idx-- != 0);

                }

                return npos;
        }


        //////////////////////////////////////////////////////////////////////////
        // Substring
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Returns a substring of this String.

        \param idx
                Index of the first code point to use for the sub-string.

        \param len
                Maximum number of code points to use for the sub-string

        \return
                A String object containing the specified sub-string.

        \exception std::out_of_range    Thrown if \a idx is invalid for this String.
        */
        String  substr(size_type idx = 0, size_type len = npos) const
        {
                if (d_cplength < idx)
                        throw std::out_of_range("Index is out of range for this CEGUI::String");

                return String(*this, idx, len);
        }

        //////////////////////////////////////////////////////////////////////////
        // Iterator creation
        //////////////////////////////////////////////////////////////////////////
        /*!
        \brief
                Return a forwards iterator that describes the beginning of the String

        \return
                iterator object that describes the beginning of the String.
        */
        iterator                begin(void)
        {
                return iterator(ptr());
        }

        /*!
        \brief
                Return a constant forwards iterator that describes the beginning of the String

        \return
                const_iterator object that describes the beginning of the String.
        */
        const_iterator  begin(void) const
        {
                return const_iterator(ptr());
        }

        /*!
        \brief
                Return a forwards iterator that describes the end of the String

        \return
                iterator object that describes the end of the String.
        */
        iterator                end(void)
        {
                return iterator(&ptr()[d_cplength]);
        }

        /*!
        \brief
                Return a constant forwards iterator that describes the end of the String

        \return
                const_iterator object that describes the end of the String.
        */
        const_iterator  end(void) const
        {
                return const_iterator(&ptr()[d_cplength]);
        }

        /*!
        \brief
                Return a reverse iterator that describes the beginning of the String

        \return
                reverse_iterator object that describes the beginning of the String (so is actually at the end)
        */
        reverse_iterator                rbegin(void)
        {
                return reverse_iterator(end());
        }

        /*!
        \brief
                Return a constant reverse iterator that describes the beginning of the String

        \return
                const_reverse_iterator object that describes the beginning of the String (so is actually at the end)
        */
        const_reverse_iterator  rbegin(void) const
        {
                return const_reverse_iterator(end());
        }

        /*!
        \brief
                Return a reverse iterator that describes the end of the String

        \return
                reverse_iterator object that describes the end of the String (so is actually at the beginning)
        */
        reverse_iterator                rend(void)
        {
                return reverse_iterator(begin());
        }

        /*!
        \brief
                Return a constant reverse iterator that describes the end of the String

        \return
                const_reverse_iterator object that describes the end of the String (so is actually at the beginning)
        */
        const_reverse_iterator  rend(void) const
        {
                return const_reverse_iterator(begin());
        }

private:
        /*************************************************************************
                Implementation Functions
        *************************************************************************/
        // string management

        // change size of allocated buffer so it is at least 'new_size'.
        // May or may not cause re-allocation and copy of buffer if size is larger
        // will never re-allocate to make size smaller.  (see trim())
    bool        grow(size_type new_size);

        // perform re-allocation to remove wasted space.
    void        trim(void);

        // set the length of the string, and terminate it, according to the given value (will not re-allocate, use grow() first).
        void    setlen(size_type len)
        {
                d_cplength = len;
                ptr()[len] = (utf32)(0);
        }

        // return a ptr to the buffer in use.
        utf32*  ptr(void)
        {
                return (d_reserve > STR_QUICKBUFF_SIZE) ? d_buffer : d_quickbuff;
        }

        // return a ptr tot he buffer in use (const version)
        const utf32*    ptr(void) const
        {
                return (d_reserve > STR_QUICKBUFF_SIZE) ? d_buffer : d_quickbuff;
        }

        // initialise string object
        void    init(void)
        {
                d_reserve                       = STR_QUICKBUFF_SIZE;
                d_encodedbuff           = NULL;
                d_encodedbufflen        = 0;
                d_encodeddatlen         = 0;
                setlen(0);
        }

        // return true if the given pointer is inside the string data
        bool    inside(utf32* inptr)
        {
                if (inptr < ptr() || ptr() + d_cplength <= inptr)
                        return false;
                else
                        return true;
        }

        // compute distance between two iterators, returning a 'safe' value
        size_type safe_iter_dif(const const_iterator& iter1, const const_iterator& iter2) const
        {
                return (iter1.d_ptr == 0) ? 0 : (iter1 - iter2);
        }
        
        // encoding functions
        // for all:
        //      src_len is in code units, or 0 for null terminated string.
        //      dest_len is in code units.
        //      returns number of code units put into dest buffer.
        size_type encode(const utf32* src, utf8* dest, size_type dest_len, size_type src_len = 0) const
        {
                // count length for null terminated source...
                if (src_len == 0)
                {
                        src_len = utf_length(src);
                }

                size_type destCapacity = dest_len;

                // while there is data in the source buffer,
                for (uint idx = 0; idx < src_len; ++idx)
                {
                        utf32   cp = src[idx];

                        // check there is enough destination buffer to receive this encoded unit (exit loop & return if not)
                        if (destCapacity < encoded_size(cp))
                        {
                                break;
                        }

                        if (cp < 0x80)
                        {
                                *dest++ = (utf8)cp;
                                --destCapacity;
                        }
                        else if (cp < 0x0800)
                        {
                                *dest++ = (utf8)((cp >> 6) | 0xC0);
                                *dest++ = (utf8)((cp & 0x3F) | 0x80);
                                destCapacity -= 2;
                        }
                        else if (cp < 0x10000)
                        {
                                *dest++ = (utf8)((cp >> 12) | 0xE0);
                                *dest++ = (utf8)(((cp >> 6) & 0x3F) | 0x80);
                                *dest++ = (utf8)((cp & 0x3F) | 0x80);
                                destCapacity -= 3;
                        }
                        else
                        {
                                *dest++ = (utf8)((cp >> 18) | 0xF0);
                                *dest++ = (utf8)(((cp >> 12) & 0x3F) | 0x80);
                                *dest++ = (utf8)(((cp >> 6) & 0x3F) | 0x80);
                                *dest++ = (utf8)((cp & 0x3F) | 0x80);
                                destCapacity -= 4;
                        }

                }

                return dest_len - destCapacity;
        }

        size_type encode(const utf8* src, utf32* dest, size_type dest_len, size_type src_len = 0) const
        {
                // count length for null terminated source...
                if (src_len == 0)
                {
                        src_len = utf_length(src);
                }

                size_type destCapacity = dest_len;

                // while there is data in the source buffer, and space in the dest buffer
                for (uint idx = 0; ((idx < src_len) && (destCapacity > 0));)
                {
                        utf32   cp;
                        utf8    cu = src[idx++];

                        if (cu < 0x80)
                        {
                                cp = (utf32)(cu);
                        }
                        else if (cu < 0xE0)
                        {
                                cp = ((cu & 0x1F) << 6);
                                cp |= (src[idx++] & 0x3F);
                        }
                        else if (cu < 0xF0)
                        {
                                cp = ((cu & 0x0F) << 12);
                                cp |= ((src[idx++] & 0x3F) << 6);
                                cp |= (src[idx++] & 0x3F);
                        }
                        else
                        {
                                cp = ((cu & 0x07) << 18);
                                cp |= ((src[idx++] & 0x3F) << 12);
                                cp |= ((src[idx++] & 0x3F) << 6);
                                cp |= (src[idx++] & 0x3F);
                        }

                        *dest++ = cp;
                        --destCapacity;
                }

                return dest_len - destCapacity;
        }

        // return the number of utf8 code units required to encode the given utf32 code point
        size_type encoded_size(utf32 code_point) const
        {
                if (code_point < 0x80)
                        return 1;
                else if (code_point < 0x0800)
                        return 2;
                else if (code_point < 0x10000)
                        return 3;
                else
                        return 4;
        }

        // return number of code units required to re-encode given null-terminated utf32 data as utf8.  return does not include terminating null.
        size_type encoded_size(const utf32* buf) const
        {
                return encoded_size(buf, utf_length(buf));
        }

        // return number of code units required to re-encode given utf32 data as utf8.   len is number of code units in 'buf'.
        size_type encoded_size(const utf32* buf, size_type len) const
        {
                size_type count = 0;

                while (len--)
                {
                        count += encoded_size(*buf++);
                }

                return count;
        }

        // return number of utf32 code units required to re-encode given utf8 data as utf32.  return does not include terminating null.
        size_type encoded_size(const utf8* buf) const
        {
                return encoded_size(buf, utf_length(buf));
        }

        // return number of utf32 code units required to re-encode given utf8 data as utf32.  len is number of code units in 'buf'.
        size_type encoded_size(const utf8* buf, size_type len) const
        {
                utf8 tcp;
                size_type count = 0;

                while (len--)
                {
                        tcp = *buf++;
                        ++count;

                        if (tcp < 0x80)
                        {
                        }
                        else if (tcp < 0xE0)
                        {
                                --len;
                                ++buf;
                        }
                        else if (tcp < 0xF0)
                        {
                                len -= 2;
                                buf += 2;
                        }
                        else
                        {
                                len -= 2;
                                buf += 3;
                        }

                }

                return count;
        }

        // return number of code units in a null terminated string
        size_type utf_length(const utf8* utf8_str) const
        {
                size_type cnt = 0;
                while (*utf8_str++)
                        cnt++;

                return cnt;
        }

        // return number of code units in a null terminated string
        size_type utf_length(const utf32* utf32_str) const
        {
                size_type cnt = 0;
                while (*utf32_str++)
                        cnt++;

                return cnt;
        }

        // build an internal buffer with the string encoded as utf8 (remains valid until string is modified).
    utf8* build_utf8_buff(void) const;

        // compare two utf32 buffers
        int     utf32_comp_utf32(const utf32* buf1, const utf32* buf2, size_type cp_count) const
        {
                if (!cp_count)
                        return 0;

                while ((--cp_count) && (*buf1 == *buf2))
                        buf1++, buf2++;
                
                return *buf1 - *buf2;
        }

        // compare utf32 buffer with char buffer (chars are taken to be code-points in the range 0x00-0xFF)
        int utf32_comp_char(const utf32* buf1, const char* buf2, size_type cp_count) const
        {
                if (!cp_count)
                        return 0;

                while ((--cp_count) && (*buf1 == static_cast<utf32>(static_cast<unsigned char>(*buf2))))
                        buf1++, buf2++;

                return *buf1 - static_cast<utf32>(static_cast<unsigned char>(*buf2));
        }

        // compare utf32 buffer with encoded utf8 data
        int utf32_comp_utf8(const utf32* buf1, const utf8* buf2, size_type cp_count) const
        {
                if (!cp_count)
                        return 0;

                utf32   cp;
                utf8    cu;

                do
                {
                        cu = *buf2++;

                        if (cu < 0x80)
                        {
                                cp = (utf32)(cu);
                        }
                        else if (cu < 0xE0)
                        {
                                cp = ((cu & 0x1F) << 6);
                                cp |= (*buf2++ & 0x3F);
                        }
                        else if (cu < 0xF0)
                        {
                                cp = ((cu & 0x0F) << 12);
                                cp |= ((*buf2++ & 0x3F) << 6);
                                cp |= (*buf2++ & 0x3F);
                        }
                        else
                        {
                                cp = ((cu & 0x07) << 18);
                                cp |= ((*buf2++ & 0x3F) << 12);
                                cp |= ((*buf2++ & 0x3F) << 6);
                                cp |= (*buf2++ & 0x3F);
                        }

                } while ((*buf1++ == cp) && (--cp_count));

                return (*--buf1) - cp;
        }

        // return index of first occurrence of 'code_point' in std::string 'str', or npos if none
        size_type find_codepoint(const std::string& str, utf32 code_point) const
        {
                size_type idx = 0, sze = (size_type)str.size();

                while (idx != sze)
                {
                        if (code_point == static_cast<utf32>(static_cast<unsigned char>(str[idx])))
                                return idx;

                        ++idx;
                }

                return npos;
        }

        // return index of first occurrence of 'code_point' in utf8 encoded string 'str', or npos if none.  len is in code points.
        size_type find_codepoint(const utf8* str, size_type len, utf32 code_point) const 
        {
                size_type idx = 0;

                utf32   cp;
                utf8    cu;

                while (idx != len) {
                        cu = *str++;

                        if (cu < 0x80)
                        {
                                cp = (utf32)(cu);
                        }
                        else if (cu < 0xE0)
                        {
                                cp = ((cu & 0x1F) << 6);
                                cp |= (*str++ & 0x3F);
                        }
                        else if (cu < 0xF0)
                        {
                                cp = ((cu & 0x0F) << 12);
                                cp |= ((*str++ & 0x3F) << 6);
                                cp |= (*str++ & 0x3F);
                        }
                        else
                        {
                                cp = ((cu & 0x07) << 18);
                                cp |= ((*str++ & 0x3F) << 12);
                                cp |= ((*str++ & 0x3F) << 6);
                                cp |= (*str++ & 0x3F);
                        }

                        if (code_point == cp)
                                return idx;

                        ++idx;
                }

                return npos;
        }


        // return index of first occurrence of 'code_point' in char array 'chars', or npos if none
        size_type find_codepoint(const char* chars, size_type chars_len, utf32 code_point) const
        {
                for (size_type idx = 0; idx != chars_len; ++idx)
                {
                        if (code_point == static_cast<utf32>(static_cast<unsigned char>(chars[idx])))
                                return idx;
                }

                return npos;
        }

};


//////////////////////////////////////////////////////////////////////////
// Comparison operators
//////////////////////////////////////////////////////////////////////////
/*!
\brief
        Return true if String \a str1 is equal to String \a str2
*/
bool CEGUIEXPORT        operator==(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator==(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator==(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator==(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator==(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str1 is not equal to String \a str2
*/
bool CEGUIEXPORT        operator!=(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is not equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator!=(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is not equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator!=(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is not equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator!=(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is not equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator!=(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str1 is lexicographically less than String \a str2
*/
bool CEGUIEXPORT        operator<(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is lexicographically less than std::string \a std_str
*/
bool CEGUIEXPORT        operator<(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is lexicographically less than std::string \a std_str
*/
bool CEGUIEXPORT        operator<(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically less than null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator<(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is lexicographically less than null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator<(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str1 is lexicographically greater than String \a str2
*/
bool CEGUIEXPORT        operator>(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is lexicographically greater than std::string \a std_str
*/
bool CEGUIEXPORT        operator>(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is lexicographically greater than std::string \a std_str
*/
bool CEGUIEXPORT        operator>(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically greater than null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator>(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is lexicographically greater than null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator>(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str1 is lexicographically less than or equal to String \a str2
*/
bool CEGUIEXPORT        operator<=(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is lexicographically less than or equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator<=(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is lexicographically less than or equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator<=(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically less than or equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator<=(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is lexicographically less than or equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator<=(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str1 is lexicographically greater than or equal to String \a str2
*/
bool CEGUIEXPORT        operator>=(const String& str1, const String& str2);

/*!
\brief
        Return true if String \a str is lexicographically greater than or equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator>=(const String& str, const std::string& std_str);

/*!
\brief
        Return true if String \a str is lexicographically greater than or equal to std::string \a std_str
*/
bool CEGUIEXPORT        operator>=(const std::string& std_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically greater than or equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator>=(const String& str, const utf8* utf8_str);

/*!
\brief
        Return true if String \a str is lexicographically greater than or equal to null-terminated utf8 data \a utf8_str
*/
bool CEGUIEXPORT        operator>=(const utf8* utf8_str, const String& str);

/*!
\brief
        Return true if String \a str is equal to c-string \a c_str
*/
bool CEGUIEXPORT        operator==(const String& str, const char* c_str);

/*!
\brief
        Return true if c-string \a c_str is equal to String \a str
*/
bool CEGUIEXPORT        operator==(const char* c_str, const String& str);

/*!
\brief
        Return true if String \a str is not equal to c-string \a c_str
*/
bool CEGUIEXPORT        operator!=(const String& str, const char* c_str);

/*!
\brief
        Return true if c-string \a c_str is not equal to String \a str
*/
bool CEGUIEXPORT        operator!=(const char* c_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically less than c-string \a c_str
*/
bool CEGUIEXPORT        operator<(const String& str, const char* c_str);

/*!
\brief
        Return true if c-string \a c_str is lexicographically less than String \a str
*/
bool CEGUIEXPORT        operator<(const char* c_str, const String& str);

/*!
\brief
Return true if String \a str is lexicographically greater than c-string \a c_str
*/
bool CEGUIEXPORT        operator>(const String& str, const char* c_str);

/*!
\brief
Return true if c-string \a c_str is lexicographically greater than String \a str
*/
bool CEGUIEXPORT        operator>(const char* c_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically less than or equal to c-string \a c_str
*/
bool CEGUIEXPORT        operator<=(const String& str, const char* c_str);

/*!
\brief
        Return true if c-string \a c_str is lexicographically less than or equal to String \a str
*/
bool CEGUIEXPORT        operator<=(const char* c_str, const String& str);

/*!
\brief
        Return true if String \a str is lexicographically greater than or equal to c-string \a c_str
*/
bool CEGUIEXPORT        operator>=(const String& str, const char* c_str);

/*!
\brief
        Return true if c-string \a c_str is lexicographically greater than or equal to String \a str
*/
bool CEGUIEXPORT        operator>=(const char* c_str, const String& str);

//////////////////////////////////////////////////////////////////////////
// Concatenation operator functions
//////////////////////////////////////////////////////////////////////////
/*!
\brief
        Return String object that is the concatenation of the given inputs

\param str1
        String object describing first part of the new string

\param str2
        String object describing the second part of the new string

\return
        A String object that is the concatenation of \a str1 and \a str2

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const String str1, const String& str2);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param str
        String object describing first part of the new string

\param std_str
        std::string object describing the second part of the new string

\return
        A String object that is the concatenation of \a str and \a std_str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const String str, const std::string& std_str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param std_str
        std::string object describing the first part of the new string

\param str
        String object describing the second part of the new string

\return
        A String object that is the concatenation of \a std_str and \a str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const std::string& std_str, const String& str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param str
        String object describing first part of the new string

\param utf8_str
        Buffer containing null-terminated utf8 encoded data describing the second part of the new string

\return
        A String object that is the concatenation of \a str and \a utf8_str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const String str, const utf8* utf8_str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param utf8_str
        Buffer containing null-terminated utf8 encoded data describing the first part of the new string

\param str
        String object describing the second part of the new string

\return
        A String object that is the concatenation of \a str and \a utf8_str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const utf8* utf8_str, const String& str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param str
        String object describing the first part of the new string

\param code_point
        utf32 code point describing the second part of the new string

\return
        A String object that is the concatenation of \a str and \a code_point

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const String str, utf32 code_point);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param code_point
        utf32 code point describing the first part of the new string

\param str
        String object describing the second part of the new string

\return
        A String object that is the concatenation of \a code_point and \a str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(utf32 code_point, const String& str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param str
        String object describing first part of the new string

\param c_str
        c-string describing the second part of the new string

\return
        A String object that is the concatenation of \a str and \a c_str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const String str, const char* c_str);

/*!
\brief
        Return String object that is the concatenation of the given inputs

\param c_str
        c-string describing the first part of the new string

\param str
        String object describing the second part of the new string

\return
        A String object that is the concatenation of \a c_str and \a str

\exception std::length_error    Thrown if the resulting String would be too large.
*/
String CEGUIEXPORT      operator+(const char* c_str, const String& str);


//////////////////////////////////////////////////////////////////////////
// Output (stream) functions
//////////////////////////////////////////////////////////////////////////
std::ostream& operator<<(std::ostream& s, const String& str);


//////////////////////////////////////////////////////////////////////////
// Modifying operations
//////////////////////////////////////////////////////////////////////////
/*!
\brief
        Swap the contents for two String objects

\param str1
        String object who's contents are to be swapped with \a str2

\param str2
        String object who's contents are to be swapped with \a str1

\return
        Nothing
*/
void CEGUIEXPORT swap(String& str1, String& str2);


} // End of  CEGUI namespace section


#endif  // end of guard _CEGUIString_h_