basic_string.h

来自「symbian上STL模板库的实现」· C头文件 代码 · 共 1,380 行 · 第 1/5 页

                void
                    resize(size_type __n, _CharT __c);

                /**
                 *  @brief  Resizes the %string to the specified number of characters.
                 *  @param  n  Number of characters the %string should contain.
                 *
                 *  This function will resize the %string to the specified length.  If
                 *  the new size is smaller than the %string's current size the %string
                 *  is truncated, otherwise the %string is extended and new characters
                 *  are default-constructed.  For basic types such as char, this means
                 *  setting them to 0.
                 */
                void
                    resize(size_type __n) { this->resize(__n, _CharT()); }

                /**
                 *  Returns the total number of characters that the %string can hold
                 *  before needing to allocate more memory.
                 */
                size_type
                    capacity() const { return _M_rep()->_M_capacity; }

                /**
                 *  @brief  Attempt to preallocate enough memory for specified number of
                 *          characters.
                 *  @param  n  Number of characters required.
                 *  @throw  std::length_error  If @a n exceeds @c max_size().
                 *
                 *  This function attempts to reserve enough memory for the
                 *  %string to hold the specified number of characters.  If the
                 *  number requested is more than max_size(), length_error is
                 *  thrown.
                 *
                 *  The advantage of this function is that if optimal code is a
                 *  necessity and the user can determine the string length that will be
                 *  required, the user can reserve the memory in %advance, and thus
                 *  prevent a possible reallocation of memory and copying of %string
                 *  data.
                 */
                void
                    reserve(size_type __res_arg = 0);

                /**
                 *  Erases the string, making it empty.
                 */
                void
                    clear() { _M_mutate(0, this->size(), 0); }

                /**
                 *  Returns true if the %string is empty.  Equivalent to *this == "".
                 */
                bool
                    empty() const { return this->size() == 0; }

                // Element access:
                /**
                 *  @brief  Subscript access to the data contained in the %string.
                 *  @param  n  The index of the character to access.
                 *  @return  Read-only (constant) reference to the character.
                 *
                 *  This operator allows for easy, array-style, data access.
                 *  Note that data access with this operator is unchecked and
                 *  out_of_range lookups are not defined. (For checked lookups
                 *  see at().)
                 */
                const_reference
                    operator[] (size_type __pos) const
                    {
                        _GLIBCXX_DEBUG_ASSERT(__pos <= size());
                        return _M_data()[__pos];
                    }

                /**
                 *  @brief  Subscript access to the data contained in the %string.
                 *  @param  n  The index of the character to access.
                 *  @return  Read/write reference to the character.
                 *
                 *  This operator allows for easy, array-style, data access.
                 *  Note that data access with this operator is unchecked and
                 *  out_of_range lookups are not defined. (For checked lookups
                 *  see at().)  Unshares the string.
                 */
                reference
                    operator[](size_type __pos)
                    {
                        _GLIBCXX_DEBUG_ASSERT(__pos < size());
                        _M_leak();
                        return _M_data()[__pos];
                    }

                /**
                 *  @brief  Provides access to the data contained in the %string.
                 *  @param n The index of the character to access.
                 *  @return  Read-only (const) reference to the character.
                 *  @throw  std::out_of_range  If @a n is an invalid index.
                 *
                 *  This function provides for safer data access.  The parameter is
                 *  first checked that it is in the range of the string.  The function
                 *  throws out_of_range if the check fails.
                 */
                const_reference
                    at(size_type __n) const
                    {
                        if (__n >= this->size())
                            __throw_out_of_range(__N("basic_string::at"));
                        return _M_data()[__n];
                    }

                /**
                 *  @brief  Provides access to the data contained in the %string.
                 *  @param n The index of the character to access.
                 *  @return  Read/write reference to the character.
                 *  @throw  std::out_of_range  If @a n is an invalid index.
                 *
                 *  This function provides for safer data access.  The parameter is
                 *  first checked that it is in the range of the string.  The function
                 *  throws out_of_range if the check fails.  Success results in
                 *  unsharing the string.
                 */
                reference
                    at(size_type __n)
                    {
                        if (__n >= size())
                            __throw_out_of_range(__N("basic_string::at"));
                        _M_leak();
                        return _M_data()[__n];
                    }

                // Modifiers:
                /**
                 *  @brief  Append a string to this string.
                 *  @param str  The string to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    operator+=(const basic_string& __str) { return this->append(__str); }

                /**
                 *  @brief  Append a C string.
                 *  @param s  The C string to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    operator+=(const _CharT* __s) { return this->append(__s); }

                /**
                 *  @brief  Append a character.
                 *  @param s  The character to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    operator+=(_CharT __c) { return this->append(size_type(1), __c); }

                /**
                 *  @brief  Append a string to this string.
                 *  @param str  The string to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    append(const basic_string& __str);

                /**
                 *  @brief  Append a substring.
                 *  @param str  The string to append.
                 *  @param pos  Index of the first character of str to append.
                 *  @param n  The number of characters to append.
                 *  @return  Reference to this string.
                 *  @throw  std::out_of_range if @a pos is not a valid index.
                 *
                 *  This function appends @a n characters from @a str starting at @a pos
                 *  to this string.  If @a n is is larger than the number of available
                 *  characters in @a str, the remainder of @a str is appended.
                 */
                basic_string&
                    append(const basic_string& __str, size_type __pos, size_type __n);

                /**
                 *  @brief  Append a C substring.
                 *  @param s  The C string to append.
                 *  @param n  The number of characters to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    append(const _CharT* __s, size_type __n);

                /**
                 *  @brief  Append a C string.
                 *  @param s  The C string to append.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    append(const _CharT* __s)
                    {
                        __glibcxx_requires_string(__s);
                        return this->append(__s, traits_type::length(__s));
                    }

                /**
                 *  @brief  Append multiple characters.
                 *  @param n  The number of characters to append.
                 *  @param c  The character to use.
                 *  @return  Reference to this string.
                 *
                 *  Appends n copies of c to this string.
                 */
                basic_string&
                    append(size_type __n, _CharT __c)
                    { return _M_replace_aux(this->size(), size_type(0), __n, __c); }

                /**
                 *  @brief  Append a range of characters.
                 *  @param first  Iterator referencing the first character to append.
                 *  @param last  Iterator marking the end of the range.
                 *  @return  Reference to this string.
                 *
                 *  Appends characters in the range [first,last) to this string.
                 */
                template<class _InputIterator>
                    basic_string&
                    append(_InputIterator __first, _InputIterator __last)
                    { return this->replace(_M_iend(), _M_iend(), __first, __last); }

                /**
                 *  @brief  Append a single character.
                 *  @param c  Character to append.
                 */
                void
                    push_back(_CharT __c)
                    { _M_replace_aux(this->size(), size_type(0), size_type(1), __c); }

                /**
                 *  @brief  Set value to contents of another string.
                 *  @param  str  Source string to use.
                 *  @return  Reference to this string.
                 */
                basic_string&
                    assign(const basic_string& __str);

                /**
                 *  @brief  Set value to a substring of a string.
                 *  @param str  The string to use.
                 *  @param pos  Index of the first character of str.
                 *  @param n  Number of characters to use.
                 *  @return  Reference to this string.
                 *  @throw  std::out_of_range if @a pos is not a valid index.
                 *
                 *  This function sets this string to the substring of @a str consisting
                 *  of @a n characters at @a pos.  If @a n is is larger than the number
                 *  of available characters in @a str, the remainder of @a str is used.
                 */
                basic_string&
                    assign(const basic_string& __str, size_type __pos, size_type __n)
                    { return this->assign(__str._M_data()
                            + __str._M_check(__pos, "basic_string::assign"),
                            __str._M_limit(__pos, __n)); }

                /**
                 *  @brief  Set value to a C substring.
                 *  @param s  The C string to use.
                 *  @param n  Number of characters to use.
                 *  @return  Reference to this string.
                 *
                 *  This function sets the value of this string to the first @a n
                 *  characters of @a s.  If @a n is is larger than the number of
                 *  available characters in @a s, the remainder of @a s is used.
                 */
                basic_string&
                    assign(const _CharT* __s, size_type __n);

                /**
                 *  @brief  Set value to contents of a C string.
                 *  @param s  The C string to use.
                 *  @return  Reference to this string.
                 *
                 *  This function sets the value of this string to the value of @a s.