<!--
    Licensed to the Apache Software  Foundation (ASF) under one or more
    contributor  license agreements.  See  the NOTICE  file distributed
    with  this  work  for  additional information  regarding  copyright
    ownership.   The ASF  licenses this  file to  you under  the Apache
    License, Version  2.0 (the  License); you may  not use  this file
    except in  compliance with the License.   You may obtain  a copy of
    the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the  License is distributed on an  "AS IS" BASIS,
    WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
    implied.   See  the License  for  the  specific language  governing
    permissions and limitations under the License.

    Copyright 1999-2007 Rogue Wave Software, Inc.
-->

<HTML>
<HEAD>
<TITLE>basic_string</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="basic-streambuf.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="basic-stringbuf.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>basic_string</H2>
<P><B>Library:</B>&nbsp;&nbsp;<A HREF="2-5.html">Strings</A></P>

<PRE><HR><B><I>Does not inherit</I></B><HR></PRE>

<UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Description</A></LI>
<LI><A HREF="#sec5">Interface</A></LI>
<LI><A HREF="#sec6">Constructors</A></LI>
<LI><A HREF="#sec7">Destructors</A></LI>
<LI><A HREF="#sec8">Operators</A></LI>
<LI><A HREF="#sec9">Iterators</A></LI>
<LI><A HREF="#sec10">Allocator</A></LI>
<LI><A HREF="#sec11">Member Functions</A></LI>
<LI><A HREF="#sec12">Nonmember Operators</A></LI>
<LI><A HREF="#sec13">Nonmember Functions</A></LI>
<LI><A HREF="#sec14">Example</A></LI>
<LI><A HREF="#sec15">See Also</A></LI>
<LI><A HREF="#sec16">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
<H4>Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx338">append()</A><BR>
<A HREF="#idx340">assign()</A><BR>
<A HREF="#idx341">at()</A><BR>
<A HREF="#idx320">basic_string()</A><BR>
<A HREF="#idx333">begin()</A><BR>
<A HREF="#idx342">capacity()</A><BR>
<A HREF="#idx343">clear()</A><BR>
<A HREF="#idx344">compare()</A><BR>
<A HREF="#idx346">copy()</A><BR>
<A HREF="#idx347">c_str()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx347">data()</A><BR>
<A HREF="#idx348">empty()</A><BR>
<A HREF="#idx334">end()</A><BR>
<A HREF="#idx349">erase()</A><BR>
<A HREF="#idx350">find()</A><BR>
<A HREF="#idx352">find_first_not_of()</A><BR>
<A HREF="#idx354">find_first_of()</A><BR>
<A HREF="#idx356">find_last_not_of()</A><BR>
<A HREF="#idx358">find_last_of()</A><BR>
<A HREF="#idx337">get_allocator()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx360">insert()</A><BR>
<A HREF="#idx362">length()</A><BR>
<A HREF="#idx363">max_size()</A><BR>
<A HREF="#idx332">operator+=()</A><BR>
<A HREF="#idx328">operator=()</A><BR>
<A HREF="#idx331">operator[]()</A><BR>
<A HREF="#idx339">push_back()</A><BR>
<A HREF="#idx335">rbegin()</A><BR>
<A HREF="#idx336">rend()</A><BR>
<A HREF="#idx366">replace()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx368">reserve()</A><BR>
<A HREF="#idx369">resize()</A><BR>
<A HREF="#idx364">rfind()</A><BR>
<A HREF="#idx370">size()</A><BR>
<A HREF="#idx371">substr()</A><BR>
<A HREF="#idx372">swap()</A><BR>
<A HREF="#idx327">~basic_string()</A><BR>
</TD></TR>
</TABLE></UL>
<H4>Non-Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx390">getline()</A><BR>
<A HREF="#idx377">operator!=()</A><BR>
<A HREF="#idx388">operator&gt;&gt;()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx381">operator&gt;()</A><BR>
<A HREF="#idx385">operator&gt;=()</A><BR>
<A HREF="#idx389">operator&lt;&lt;()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx379">operator&lt;()</A><BR>
<A HREF="#idx383">operator&lt;=()</A><BR>
<A HREF="#idx373">operator+()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx375">operator==()</A><BR>
<A HREF="#idx387">swap()</A><BR>
</TD></TR>
</TABLE></UL>

<A NAME="sec2"><H3>Summary</H3></A>
<P>A templatized class for handling sequences of character-like entities. <B><I>string&nbsp;</I></B>and <B><I><A HREF="wstring.html">wstring</A></I></B> are specialized variations of <B><I>basic_string</I></B> for <SAMP>char</SAMP>s and <SAMP>wchar_t</SAMP>s, respectively.<SAMP>typedef basic_string &lt;char&gt; string;typedef basic_string &lt;wchar_t&gt; wstring;</SAMP></P>
<A NAME="sec3"><H3>Synopsis</H3></A>

<PRE>#include &lt;string&gt;

namespace std {
  template &lt;class charT,
            class traits = char_traits&lt;charT&gt;,
            class Allocator = allocator&lt;charT&gt; &gt;
  class basic_string;
}
</PRE>
<A NAME="sec4"><H3>Description</H3></A>
<P>Class <B><I>basic_string</I></B> is a homogeneous collection of character-like entities that includes string functions such as <SAMP>compare()</SAMP>, <SAMP>append()</SAMP>, <SAMP>assign()</SAMP>, <SAMP>insert()</SAMP>, <SAMP>remove()</SAMP>, and <SAMP>replace()</SAMP>, along with various searches. The class also functions as an STL sequence container that provides random access iterators. This allows some of the generic algorithms to apply to strings.</P>
<P>Any underlying character-like type may be used as long as an appropriate <B><I><A HREF="char-traits.html">char_traits</A></I></B> class is included or the default <B><I>traits</I></B> class is applicable. </P>
<A NAME="sec5"><H3>Interface</H3></A>

<UL><PRE>namespace std {
  template &lt;class charT,
            class traits = char_traits&lt;charT&gt;,
            class Allocator = allocator&lt;charT&gt; &gt;
  class basic_string {

  public:

  // Types

  typedef traits traits_type;
  typedef typename traits::char_type value_type;
  typedef Allocator allocator_type;
  typedef typename 
          Allocator::size_type size_type;
  typedef typename
          Allocator::difference_type difference_type;
  typedef typename 
          Allocator::reference reference;
  typedef typename
          Allocator::const_reference const_reference;
  typedef typename
          Allocator::pointer pointer;
  typedef typename
          Allocator::const_pointer const_pointer;
  typedef typename
          Allocator::pointer iterator;
  typedef typename 
          Allocator::const_pointer const_iterator;
  typedef std::reverse_iterator&lt;const_iterator&gt;
                                   const_reverse_iterator;
  typedef std::reverse_iterator&lt;iterator&gt; reverse_iterator;

  static const size_type npos = -1;

  // Constructors/Destructors

  explicit basic_string(const Allocator&amp; = Allocator());
  basic_string(const basic_string&lt;charT, traits, Allocator&gt;&amp;);
  basic_string(const basic_string&amp;, size_type, 
               size_type = npos, 
               const Allocator&amp; a = Allocator());
  basic_string(const charT*, size_type,
               const Allocator&amp; = Allocator());
  basic_string(const charT*, const Allocator&amp; = Allocator());
  basic_string(size_type, charT,
               const Allocator&amp; = Allocator());
  template &lt;class InputIterator&gt;
  basic_string(InputIterator, InputIterator,
               const Allocator&amp; = Allocator());
  ~basic_string();

  // Assignment operators
   
   basic_string&amp; operator=(const basic_string&amp;);
   basic_string&amp; operator=(const charT*);
   basic_string&amp; operator=(charT);

  // Iterators
   
   iterator       begin();
   const_iterator begin() const;
   iterator       end();
   const_iterator end() const;

   reverse_iterator       rbegin();
   const_reverse_iterator rbegin() const;
   reverse_iterator       rend();
   const_reverse_iterator rend() const;

  // Capacity

     size_type       size() const;
     size_type       length() const;
     size_type       max_size() const;
     void            resize(size_type, charT);
     void            resize(size_type);
     size_type       capacity() const;
     void            reserve(size_type = 0);
     void            clear();
     bool            empty() const;

  // Element access

     const_reference operator[](size_type) const;
     reference       operator[](size_type);
     const_reference at(size_type) const;
     reference       at(size_type);

  // Modifiers

     basic_string&amp; operator+=(const basic_string&amp;);
     basic_string&amp; operator+=(const charT*);
     basic_string&amp; operator+=(charT);
   
     basic_string&amp; append(const basic_string&amp;);
     basic_string&amp; append(const basic_string&amp;,
                        size_type, size_type);
     basic_string&amp; append(const charT*, size_type);
     basic_string&amp; append(const charT*);
     basic_string&amp; append(size_type, charT);
     
     template&lt;class InputIterator&gt;
     basic_string&amp; append(InputIterator, InputIterator);
   
     void push_back(charT);
     basic_string&amp; assign(const basic_string&amp;);
     basic_string&amp; assign(const basic_string&amp;,
                          size_type, size_type);
     basic_string&amp; assign(const charT*, size_type);
     basic_string&amp; assign(const charT*);
     basic_string&amp; assign(size_type, charT);
     template&lt;class InputIterator&gt;
     basic_string&amp; assign(InputIterator, InputIterator);
   
     basic_string&amp; insert(size_type, const basic_string&amp;);
     basic_string&amp; insert(size_type, const basic_string&amp;,
                          size_type, size_type);
     basic_string&amp; insert(size_type, const charT*, size_type);
     basic_string&amp; insert(size_type, const charT*);
     basic_string&amp; insert(size_type, size_type, charT);
     iterator insert(iterator, charT = charT());
     void insert(iterator, size_type, charT);
     template&lt;class InputIterator&gt;
      void insert(iterator, InputIterator, InputIterator);

     basic_string&amp; erase(size_type = 0, size_type= npos);
     iterator erase(iterator);
     iterator erase(iterator, iterator);

     basic_string&amp; replace(size_type, size_type,
                           const basic_string&amp;);
     basic_string&amp; replace(size_type, size_type,
                           const basic_string&amp;,
                           size_type, size_type);
     basic_string&amp; replace(size_type, size_type,
                           const charT*, size_type);
     basic_string&amp; replace(size_type, size_type,
                           const charT*);
     basic_string&amp; replace(size_type, size_type,
                           size_type, charT);
     basic_string&amp; replace(iterator, iterator,
                           const basic_string&amp;);
     basic_string&amp; replace(iterator, iterator,
                           const charT*, size_type);
     basic_string&amp; replace(iterator, iterator,
                           const charT*);
     basic_string&amp; replace(iterator, iterator,
                           size_type, charT);
     template&lt;class InputIterator&gt;
      basic_string&amp; replace(iterator, iterator,
                            InputIterator, InputIterator);

     size_type copy(charT*, size_type, size_type = 0) const;
     void swap(basic_string&lt;charT, traits, Allocator&gt;&amp;);

  // String operations

     const charT* c_str() const;
     const charT* data() const;
     allocator_type&amp; get_allocator() const;
   
     size_type find(const basic_string&amp;,
                    size_type = 0) const;
     size_type find(const charT*,
                    size_type, size_type) const;
     size_type find(const charT*, size_type = 0) const;
     size_type find(charT, size_type = 0) const;
     size_type rfind(const basic_string&amp;,
                     size_type = npos) const;
     size_type rfind(const charT*,
                     size_type, size_type) const;
     size_type rfind(const charT*,
                     size_type = npos) const;
     size_type rfind(charT, size_type = npos) const;

     size_type find_first_of(const basic_string&amp;,
                             size_type = 0) const;
     size_type find_first_of(const charT*,
                             size_type, size_type) const;
     size_type find_first_of(const charT*,
                             size_type = 0) const;
     size_type find_first_of(charT, size_type = 0) const;

     size_type find_last_of(const basic_string&amp;,
                            size_type = npos) const;
     size_type find_last_of(const charT*,
                            size_type, size_type) const;
     size_type find_last_of(const charT*, size_type = npos) const;
     size_type find_last_of(charT, size_type = npos) const;

     size_type find_first_not_of(const basic_string&amp;,
                                 size_type = 0) const;
     size_type find_first_not_of(const charT*,
                                 size_type, size_type) const;
     size_type find_first_not_of(const charT*, size_type = 0)
               const;
     size_type find_first_not_of(charT, size_type = 0) const;

     size_type find_last_not_of(const basic_string&amp;,
                                size_type = npos) const;
     size_type find_last_not_of(const charT*,
                                size_type, size_type) const;
     size_type find_last_not_of(const charT*, 
                                size_type = npos) const;
     size_type find_last_not_of(charT, size_type = npos) const;

     basic_string substr(size_type = 0, size_type = npos) const;
     int compare(const basic_string&amp;) const;
     int compare(size_type, size_type, const basic_string&amp;)
         const;
     int compare(size_type, size_type, const basic_string&amp;,
                 size_type, size_type) const;
     int compare(size_type, size_type, charT*) const;
     int compare(charT*) const;
     int compare(size_type, size_type, const charT*, size_type)
         const;
  };

  // Nonmember Operators

  template &lt;class charT, class traits, class Allocator&gt;
  basic_string operator+(const basic_string&amp;,
                         const basic_string&amp;);
  
  template &lt;class charT, class traits, class Allocator&gt;
  basic_string operator+(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  basic_string operator+(charT, const basic_string&amp;);
 
  template &lt;class charT, class traits, class Allocator&gt;
  basic_string operator+(const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  basic_string operator+(const basic_string&amp;, charT);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator==(const basic_string&amp;, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator==(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits , class Allocator&gt;
  bool operator==(const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;(const basic_string&amp;, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;(const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator!=(const basic_string&amp;, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator!=(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator!=(const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;(const basic_string&amp;, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;(const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;=(const basic_string&amp;, const basic_string&amp;);
 
  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;=(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&lt;=(const basic_string&amp;, const charT*);


  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;=(const basic_string&amp;, const basic_string&amp;);
 
  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;=(const charT*, const basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  bool operator&gt;= (const basic_string&amp;, const charT*);

  template &lt;class charT, class traits, class Allocator&gt;
  void swap(basic_string&lt;charT,traits,Allocator&gt;&amp; a, 
            basic_string&lt;charT,traits,Allocator&gt;&amp; b);

  template&lt;class charT, class traits, class Allocator&gt;
  basic_istream&lt;charT, traits&gt;&amp; operator&gt;&gt;(istream&amp;,
                                           basic_string&amp;);

  template &lt;class charT, class traits, class Allocator&gt;
  basic_ostream&lt;charT, traits&gt;&amp; operator&lt;&lt;(ostream&amp;, 
                                           const basic_string&amp;);

  template &lt;class Stream, class charT,class traits, class Allocator&gt;
  basic_istream&lt;charT, traits&gt;&amp; 
  getline(Stream&amp;, basic_string&amp;, charT);
}
</PRE></UL>
<A NAME="sec6"><H3>Constructors</H3></A>
<P>In all cases, the <SAMP>Allocator</SAMP> parameter is used for storage management.</P>

<A NAME="idx320"></A><PRE>
explicit 
<B>basic_string</B> (const Allocator&amp; a = Allocator());</PRE>
<UL>
<P>The default constructor. Creates a <B><I>basic_string</I></B> with the following effects:</P>
</UL>

<P><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a non-null pointer that is copyable and can have <SAMP>0</SAMP> added to it</P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">0</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>an unspecified value</P></TD></TR>
</TABLE></P>

<A NAME="idx321"></A><PRE>
<B>basic_string</B> (const basic_string&lt;T, traits, 
               Allocator&gt;&amp; str);</PRE>
<UL>
<P>Creates a string that is a copy of <SAMP>str</SAMP>.</P>
</UL>


<A NAME="idx322"></A><PRE><B>basic_string</B> (const basic_string&amp; str, size_type pos,
              size_type n= npos, const allocator&amp;
              a=allocator());</PRE>
<UL>
<P>Creates a string of <SAMP>pos&lt;=size()</SAMP> and determines length <SAMP>rlen</SAMP> of the initial string value as the smaller of <SAMP>n</SAMP> and <SAMP>str.size() - pos</SAMP>. This has the following effects:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated copy of <SAMP>rlen</SAMP> elements of the string controlled by <SAMP>str</SAMP> beginning at position <SAMP>pos</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">rlen</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>get_allocator()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">	str.get_allocator()</SAMP></P></TD></TR>
</TABLE></UL>
<P>An <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception is thrown if <SAMP>pos</SAMP> <SAMP>&gt;</SAMP> <SAMP>str.size()</SAMP>.</P>
</UL>


<A NAME="idx323"></A><PRE><B>basic_string</B> (const charT* s, size_type n,
              const Allocator&amp; a = Allocator());</PRE>
<UL>
<P>Creates a string that contains the first <SAMP>n</SAMP> characters of <SAMP>s</SAMP>. <SAMP>s</SAMP> must not be a <SAMP>NULL</SAMP> pointer. The effects of this constructor are:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated copy of the array whose first element is pointed to by <SAMP>s</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">n</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
</TABLE></UL>
<P>A <B><I><A HREF="length-error.html">length_error</A></I></B> exception is thrown if <SAMP>n == npos.</SAMP></P>
</UL>


<A NAME="idx324"></A><PRE><B>basic_string</B> (const charT * s, 
              const Allocator&amp; a = Allocator());</PRE>
<UL>
<P>Constructs a string containing all characters in <SAMP>s</SAMP> up to, but not including, a <SAMP>traits::eos()</SAMP> character. <SAMP>s</SAMP> must not be a null pointer. The effects of this constructor are:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated copy of the array whose first element is pointed to by <SAMP>s</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">traits::length(s)</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
</TABLE></UL>
</UL>


<A NAME="idx325"></A><PRE>
<B>basic_string</B> (size_type n, charT c, 
              const Allocator&amp; a = Allocator());</PRE>
<UL>
<P>Constructs a string containing <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>. A <B><I><A HREF="length-error.html">length_error</A></I></B> exception is thrown if <SAMP>n == npos</SAMP>. The effects of this constructor are:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated array of <SAMP>n</SAMP> elements, each storing the initial value <SAMP>c</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">n</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
</TABLE></UL>
</UL>


<A NAME="idx326"></A><PRE>
template &lt;class InputIterator&gt;
<B>basic_string</B> (InputIterator start, InputIterator finish,
              const Allocator&amp; a = Allocator());</PRE>
<UL>
<P>Creates a <B><I>basic_string</I></B> of length <SAMP>finish - start</SAMP> filled with all values obtained by dereferencing the <SAMP>InputIterators</SAMP> on the range <SAMP>[start, finish)</SAMP>. The effects of this constructor are:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated copy of the elements in the range <SAMP>[start,finish)</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>distance between <SAMP>start</SAMP> and <SAMP>finish</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
</TABLE></UL>
</UL>

<A NAME="sec7"><H3>Destructor</H3></A>

<A NAME="idx327"></A><PRE><B>~basic_string</B> ();</PRE>
<UL>
<P>Releases any allocated memory for this <B><I>basic_string</I></B>.</P>
</UL>

<A NAME="sec8"><H3>Operators</H3></A>

<A NAME="idx328"></A><PRE>basic_string&amp;
<B>operator=</B>(const basic_string&amp; str);</PRE>
<UL>
<P>Sets the contents of this string to be the same as <SAMP>str</SAMP>. The effects of <SAMP>operator=</SAMP> are:</P>
<UL><TABLE CELLPADDING=3 BORDER=0>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>data()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>points to the first element of an allocated copy of the array whose first element is pointed to by <SAMP>str.size()</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>size()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST">str.size()</SAMP></P></TD></TR>
<TR CLASS="LIST"><TD VALIGN="top" CLASS="LIST"><P CLASS="LIST"><SAMP>capacity()  </P></TD>
<TD CLASS="LIST"><P CLASS="LIST"></SAMP>a value at least as large as <SAMP>size()</SAMP></P></TD></TR>
</TABLE></UL>
</UL>


<A NAME="idx329"></A><PRE>
basic_string&amp; 
<B>operator=</B>(const charT * s);</PRE>
<UL>
<P>Sets the contents of this string to be the same as <SAMP>s</SAMP> up to, but not including, the <SAMP>traits::eos()</SAMP> character.</P>
</UL>


<A NAME="idx330"></A><PRE>basic_string&amp; 
<B>operator=</B>(charT c);</PRE>
<UL>
<P>Sets the contents of this string to be equal to the single <SAMP>charT</SAMP> <SAMP>c</SAMP>.</P>
</UL>


<A NAME="idx331"></A><PRE>const_reference 
<B>operator[]</B>(size_type pos) const;
reference 
<B>operator[]</B>(size_type pos);</PRE>
<UL>
<P>If <SAMP>pos &lt; size()</SAMP>, returns the element at position <SAMP>pos</SAMP> in this string. If <SAMP>pos == size()</SAMP>, the <SAMP>const</SAMP> variation returns <SAMP>charT()</SAMP>, the behavior of the non-<SAMP>const</SAMP> variation is undefined. The reference returned by either variation is invalidated by any call to <SAMP>c_str()</SAMP>, <SAMP>data()</SAMP>, or any non-<SAMP>const</SAMP> member function for the object.</P>
</UL>


<A NAME="idx332"></A><PRE>basic_string&amp; 
<B>operator+=</B>(const basic_string&amp; s);
basic_string&amp; 
<B>operator+=</B>(const charT* s);
basic_string&amp; 
<B>operator+=</B>(charT c);</PRE>
<UL>
<P>Concatenates a string onto the current contents of this string. The second member operator uses <SAMP>traits::length()</SAMP> to determine the number of elements from <SAMP>s</SAMP> to add. The third member operator adds the single character <SAMP>c</SAMP>. All return a reference to this string after completion.</P>
</UL>

<A NAME="sec9"><H3>Iterators</H3></A>

<A NAME="idx333"></A><PRE>iterator <B>begin</B>();
const_iterator <B>begin</B>() const;</PRE>
<UL>
<P>Returns an iterator initialized to the first element of the string.</P>
</UL>


<A NAME="idx334"></A><PRE>iterator <B>end</B>();
const_iterator <B>end</B>() const;</PRE>
<UL>
<P>Returns an iterator initialized to the position after the last element of the string.</P>
</UL>


<A NAME="idx335"></A><PRE>reverse_iterator <B>rbegin</B>();
const_reverse_iterator <B>rbegin</B>() const;</PRE>
<UL>
<P>Returns an iterator equivalent to <SAMP>reverse_iterator(end())</SAMP>.</P>
</UL>


<A NAME="idx336"></A><PRE>reverse_iterator <B>rend</B>();
const_reverse_iterator <B>rend</B>() const;</PRE>
<UL>
<P>Returns an iterator equivalent to <SAMP>reverse_iterator(begin())</SAMP>.</P>
</UL>

<A NAME="sec10"><H3>Allocator</H3></A>

<A NAME="idx337"></A><PRE>allocator_type <B>get_allocator</B>() const;</PRE>
<UL>
<P>Returns a copy of the allocator used by self for storage management.</P>
</UL>

<A NAME="sec11"><H3>Member Functions</H3></A>

<A NAME="idx338"></A><PRE>basic_string&amp; 
<B>append</B>(const basic_string&amp; s, size_type pos, 
        size_type npos);
basic_string&amp;
<B>append</B>(const basic_string&amp; s);
basic_string&amp; 
<B>append</B>(const charT* s, size_type n);
basic_string&amp; 
<B>append</B>(const charT* s);
basic_string&amp; 
<B>append</B>(size_type n, charT c );
template&lt;class InputIterator&gt;
basic_string&amp; 
<B>append</B>(InputIterator start, InputIterator finish);</PRE>
<UL>
<P>Appends another string to the end of this string. </P>
</UL>

<UL>
<LI><P CLASS="LIST">The first variation appends the lesser of <SAMP>n</SAMP> and <SAMP>s.size() - pos</SAMP> characters of <SAMP>s</SAMP>, beginning at position <SAMP>pos</SAMP>, to this string. It throws an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos &gt; str.size()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The second variation appends <SAMP>s</SAMP> as in <SAMP>append (s,0,npos)</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation appends <SAMP>n</SAMP> characters of the array pointed to by <SAMP>s</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fourth variation appends elements from the array pointed to by <SAMP>s</SAMP> up to, but not including, the null character specified by <SAMP>charT()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fifth variation appends <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>. </P></LI>
<LI><P CLASS="LIST">The final variation appends the elements specified in the range <SAMP>[start, finish)</SAMP>.</P></LI>
</UL>
<UL>
<P>All functions throw a <B><I><A HREF="length-error.html">length_error</A></I></B> exception if the resulting lengths exceed <SAMP>max_size()</SAMP>. All return a reference to this string after completion.</P>
</UL>


<A NAME="idx339"></A><PRE>void 
<B>push_back</B>(charT c);</PRE>
<UL>
<P>Equivalent to <SAMP>append(static_cast&lt;size_type&gt;(1), c)</SAMP>.</P>
</UL>


<A NAME="idx340"></A><PRE>basic_string&amp;
<B>assign</B>(const basic_string&amp; s);
basic_string&amp; 
<B>assign</B>(const basic_string&amp; s,
       size_type pos, size_type n);
basic_string&amp; 
<B>assign</B>(const charT* s, size_type n);
basic_string&amp;
<B>assign</B>(const charT* s);
basic_string&amp;
<B>assign</B>(size_type n, charT c );
template&lt;class InputIterator&gt;
basic_string&amp; 
<B>assign</B>(InputIterator start, InputIterator finish);</PRE>
<UL>
<P>Replaces the value of this string with the value of another. All variations of the function assign values to this string. </P>
</UL>

<UL>
<LI><P CLASS="LIST">The first variation assigns the lesser of <SAMP>n</SAMP> and <SAMP>s.size() - pos</SAMP> characters of <SAMP>s</SAMP>, beginning at position <SAMP>pos</SAMP>. It throws an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos &gt; str.size()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The second variation assigns <SAMP>s</SAMP> as if by <SAMP>assign(s,0,npos)</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation assigns <SAMP>n</SAMP> characters of the array pointed to by <SAMP>s</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fourth variation assigns elements from the array pointed to by <SAMP>s</SAMP> up to, but not including, the null character specified by <SAMP>charT()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fifth variation assigns one or <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>. </P></LI>
<LI><P CLASS="LIST">The final variation assigns the members specified by the range <SAMP>[start, finish)</SAMP>.</P></LI>
</UL>
<UL>
<P>All functions throw a <B><I><A HREF="length-error.html">length_error</A></I></B> exception if the resulting lengths exceed <SAMP>max_size()</SAMP>. All return a reference to this string after completion.</P>
</UL>


<A NAME="idx341"></A><PRE>const_reference 
<B>at</B>(size_type pos) const;
reference 
<B>at</B>(size_type pos);</PRE>
<UL>
<P>If <SAMP>pos &lt; size()</SAMP>, returns the element at position <SAMP>pos</SAMP> in this string. Otherwise, throws an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception.</P>
</UL>


<A NAME="idx342"></A><PRE>size_type 
<B>capacity</B>() const;</PRE>
<UL>
<P>Returns the current storage capacity of the string. This is guaranteed to be at least as large as <SAMP>size()</SAMP>.</P>
</UL>


<A NAME="idx343"></A><PRE>void
<B>clear</B>();</PRE>
<UL>
<P>Removes all elements in this string. </P>
</UL>


<A NAME="idx344"></A><PRE>int 
<B>compare</B>(const basic_string&amp; str) const;</PRE>
<UL>
<P>Performs lexicographical comparison of elements controlled by <SAMP>*this</SAMP> against those controlled by <SAMP>str</SAMP>. Calls: </P>

<UL><PRE>traits_type::compare(data(), 
                     str.data(), 
                     std::min(size(), str.size())
</PRE></UL>
<P>and returns the nonzero value if the function returns nonzero. Otherwise, returns: </P>

<UL><PRE>&lt;0 if size() &lt; str.size()
0  if size() == str.size()
&gt;0 if size() &gt; str.size()
</PRE></UL>
</UL>


<A NAME="idx345"></A><PRE>
int
<B>compare</B>(size_type pos1, size_type n1, 
        const basic_string&amp; str) const;
int
<B>compare</B>(size_type pos1, size_type n1, 
        const basic_string&amp; str,
        size_type pos2, size_type n2) const;
int 
<B>compare</B>(const char_type* s) const;
int
<B>compare</B>(size_type pos, size_type n1, 
        const char_type* s) const;
int
<B>compare</B>(size_type pos, size_type n1, const char_type* s, 
        size_type n2) const;</PRE>
<UL>
<P>Returns the result of a lexicographical comparison between elements of this string and a given comparison string. The members return, respectively:</P>

<UL><PRE>basic_string(*this,pos1,n1).compare(str)
basic_string(*this,pos1,n1).compare(basic_string 
                                     (str, pos2, n2))
*this.compare(basic_string(s))
    basic_string(*this,pos,n1).compare(basic_string(s))
basic_string(*this,pos,n1).compare(basic_string(s,n2))
</PRE></UL>
</UL>


<A NAME="idx346"></A><PRE>
size_type 
<B>copy</B>(charT* s, size_type n, size_type pos = 0) const;</PRE>
<UL>
<P>The lesser of <SAMP>n</SAMP> and <SAMP>size() - pos</SAMP> elements of this string, starting at position <SAMP>pos</SAMP>, are copied into the array pointed to by <SAMP>s</SAMP>. No terminating null is appended to <SAMP>s</SAMP>. An <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception is thrown if <SAMP>pos &gt; size()</SAMP>.</P>
</UL>


<A NAME="idx347"></A><PRE>const charT* 
<B>c_str</B>() const;
const charT* 
<B>data</B>() const;</PRE>
<UL>
<P>Returns a pointer to the initial element of an array whose first <SAMP>size()</SAMP> elements are copies of the elements in this string. For the <SAMP>c_str()</SAMP> function, a <SAMP>charT()</SAMP> element is appended to the end. The elements of the array may not be altered, and the returned pointer is only valid until a non-<SAMP>const</SAMP> member function of this string is called. If <SAMP>size()</SAMP> is zero, the <SAMP>data()</SAMP> function returns a non-<SAMP>NULL</SAMP> pointer.</P>
</UL>


<A NAME="idx348"></A><PRE>bool <B>empty</B>() const;</PRE>
<UL>
<P>Returns <SAMP>size() == 0</SAMP>.</P>
</UL>


<A NAME="idx349"></A><PRE>basic_string&amp; 
<B>erase</B>(size_type pos = 0, size_type n = npos);
iterator 
<B>erase</B>(iterator p);
iterator 
<B>erase</B>(iterator start, iterator finish);</PRE>
<UL>
<P>This function removes elements from the string, collapsing the remaining elements, as necessary, to remove any space left empty. Returns a reference to the string after completion.</P>
</UL>

<UL>
<LI><P CLASS="LIST"> The first variation of the function removes the smaller of <SAMP>n</SAMP> and <SAMP>size() - pos</SAMP> starting at position <SAMP>pos</SAMP>. An <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception is thrown if <SAMP>pos &gt; size()</SAMP>. </P></LI>
<LI><P CLASS="LIST">For the second variation, <SAMP>p</SAMP> must be a valid iterator on the string, and the function removes the character referred to by <SAMP>p</SAMP>. The returned iterator refers to the element that preceded the first removed element, or <SAMP>end()</SAMP> if such an element does not exist.</P></LI>
<LI><P CLASS="LIST">For the last variation, both <SAMP>start</SAMP> and <SAMP>finish</SAMP> must be valid iterators on the string, and the function removes the characters defined by the range <SAMP>[start, finish)</SAMP>. The returned iterator refers to the element that preceded the first removed element, or <SAMP>end()</SAMP> if such an element does not exist. </P></LI>
</UL>

<A NAME="idx350"></A><PRE>
size_type 
<B>find</B>(const basic_string&amp; str, size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first occurrence of the substring specified by <SAMP>str</SAMP> in this string, starting at position <SAMP>pos</SAMP>. If found, it returns the index of the first character of the matching substring. If not found, returns <SAMP>npos</SAMP>. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx351"></A><PRE>size_type
<B>find</B>(const charT* s, size_type pos, size_type n) const;
size_type 
<B>find</B>(const charT* s, size_type pos = 0) const;
size_type 
<B>find</B>(charT c, size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first sequence of characters in this string that match a specified string. The variations of this function return, respectively:</P>

<UL><PRE>find(basic_string(s,n), pos)
find(basic_string(s), pos)
find(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx352"></A><PRE>size_type
<B>find_first_not_of</B>(const basic_string&amp; str,
                  size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first element of this string at or after position <SAMP>pos</SAMP> that is not equal to any element of <SAMP>str</SAMP>. If found, <SAMP>find_first_not_of()</SAMP> returns the index of the nonmatching character. If all the characters match, the function returns <SAMP>npos</SAMP>. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx353"></A><PRE>size_type 
<B>find_first_not_of</B> (const charT* s, 
                   size_type pos, size_type n) const;
size_type 
<B>find_first_not_of</B> (const charT* s, 
                   size_type pos = 0) const;
size_type 
<B>find_first_not_of</B>(charT c, size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first element in this string at or after position <SAMP>pos</SAMP> that is not equal to any element of a given set of characters. The members return, respectively:</P>

<UL><PRE>find_first_not_of(basic_string(s,n), pos)
find_first_not_of(basic_string(s), pos)
find_first_not_of(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx354"></A><PRE>size_type
<B>find_first_of</B>(const basic_string&amp; str,
              size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first occurrence at or after position <SAMP>pos</SAMP> of any element of <SAMP>str</SAMP> in this string. If found, the index of this matching character is returned. If not found, <SAMP>npos</SAMP> is returned. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx355"></A><PRE>size_type 
<B>find_first_of</B>(const charT* s, size_type pos,
              size_type n) const;
size_type 
<B>find_first_of</B>(const charT* s, size_type pos = 0) const;
size_type
<B>find_first_of</B>(charT c, size_type pos = 0) const;</PRE>
<UL>
<P>Searches for the first occurrence in this string of any element in a specified string. The <SAMP>find_first_of()</SAMP> variations return, respectively:</P>

<UL><PRE>find_first_of(basic_string(s,n), pos)
find_first_of(basic_string(s), pos)
find_first_of(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx356"></A><PRE>size_type 
<B>find_last_not_of</B>(const basic_string&amp; str,
                 size_type pos = npos) const;</PRE>
<UL>
<P>Searches for the last element of this string at or before position <SAMP>pos</SAMP> that is not equal to any element of <SAMP>str</SAMP>. If <SAMP>find_last_not_of()</SAMP> finds a non-matching element, it returns the index of the character. If all the elements match, the function returns <SAMP>npos</SAMP>. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx357"></A><PRE>size_type 
<B>find_last_not_of</B>(const charT* s,
                 size_type pos, size_type n) const;
size_type 
<B>find_last_not_of</B>(const charT* s, size_type pos = npos) const;
size_type 
<B>find_last_not_of</B>(charT c, size_type pos = npos) const;</PRE>
<UL>
<P>Searches for the last element in this string at or before position <SAMP>pos</SAMP> that is not equal to any element of a given set of characters. The members return, respectively:</P>

<UL><PRE>find_last_not_of(basic_string(s,n), pos)
find_last_not_of(basic_string(s), pos)
find_last_not_of(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx358"></A><PRE>size_type 
<B>find_last_of</B>(const basic_string&amp; str,
             size_type pos = npos) const; </PRE>
<UL>
<P>Searches for the last occurrence of any element of <SAMP>str</SAMP> at or before position <SAMP>pos</SAMP> in this string. If found, <SAMP>find_last_of()</SAMP> returns the index of the matching character. If not found, <SAMP>find_last_of()</SAMP> returns <SAMP>npos</SAMP>. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx359"></A><PRE>size_type
<B>find_last_of</B>(const charT* s, size_type pos,
             size_type n) const;
size_type 
<B>find_last_of</B>(const charT* s, size_type pos = npos) const;
size_type 
<B>find_last_of</B>(charT c, size_type pos = npos) const;</PRE>
<UL>
<P>Searches for the last occurrence in this string of any element in a specified string. The members return, respectively:</P>

<UL><PRE>find_last_of(basic_string(s,n), pos)
find_last_of(basic_string(s), pos)
find_last_of(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx360"></A><PRE>basic_string&amp;
<B>insert</B>(size_type pos1, const basic_string&amp; s);
basic_string&amp; 
<B>insert</B>(size_type pos, const basic_string&amp; s,
       size_type pos2 = 0, size_type n = npos);
basic_string&amp;
<B>insert</B>(size_type pos, const charT* s, size_type n);
basic_string&amp;
<B>insert</B>(size_type pos, const charT* s);
basic_string&amp; 
<B>insert</B>(size_type pos, size_type n, charT c);</PRE>
<UL>
<P>Inserts additional elements at position <SAMP>pos</SAMP> in this string. All of the variants of this function throw an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos &gt; size()</SAMP>. All variants also throw a <B><I><A HREF="length-error.html">length_error</A></I></B> if the resulting strings exceed <SAMP>max_size()</SAMP>. Elements of this string are moved apart as necessary to accommodate the inserted elements. All return a reference to this string after completion.</P>
</UL>

<UL>
<LI><P CLASS="LIST">The second variation inserts the lesser of <SAMP>n</SAMP> and <SAMP>s.size() - pos2</SAMP> characters of <SAMP>s</SAMP>, beginning at position <SAMP>pos2</SAMP> in this string. This variation throws an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos2 &gt; s.size()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation inserts <SAMP>n</SAMP> characters of the array pointed to by <SAMP>s</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fourth variation inserts elements from the array pointed to by <SAMP>s</SAMP> up to, but not including, the null character specified by <SAMP>charT()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The fifth variation inserts <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>.</P></LI>
</UL>

<A NAME="idx361"></A><PRE>
iterator 
<B>insert</B>(iterator p, charT);
void 
<B>insert</B>(iterator p, size_type n, charT c);
template&lt;class InputIterator&gt;
void
<B>insert</B>(iterator p, InputIterator start, InputIterator finish);</PRE>
<UL>
<P>Inserts additional elements in this string immediately before the character referred to by <SAMP>p</SAMP>. All of these variations of <SAMP>insert()</SAMP> require that <SAMP>p</SAMP> is a valid iterator on this string. </P>
</UL>

<UL>
<LI><P CLASS="LIST">The first variation inserts a copy of <SAMP>c</SAMP>, and returns an iterator that refers to the new character in this string. </P></LI>
<LI><P CLASS="LIST">The second variation inserts <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation inserts characters in the range <SAMP>[start, finish)</SAMP>.</P></LI>
</UL>

<A NAME="idx362"></A><PRE>
size_type 
<B>length</B>() const;</PRE>
<UL>
<P>Returns the number of elements contained in this string.</P>
</UL>


<A NAME="idx363"></A><PRE>size_type 
<B>max_size</B>() const;</PRE>
<UL>
<P>Returns the maximum possible size of the string.</P>
</UL>


<A NAME="idx364"></A><PRE>size_type 
<B>rfind</B>(const basic_string&amp; str, size_type pos = npos) const;</PRE>
<UL>
<P>Searches for the last occurrence of the substring specified by <SAMP>str</SAMP> in the string, where the index of the first character of the substring is less than <SAMP>pos</SAMP>. If found, the index of the first character that matches substring is returned. If not found, <SAMP>npos</SAMP> is returned. Equality is defined by <SAMP>traits::eq()</SAMP>.</P>
</UL>


<A NAME="idx365"></A><PRE>size_type 
<B>rfind</B>(const charT* s, size_type pos, size_type n) const;
size_type 
<B>rfind</B>(const charT* s, size_type pos = npos) const;
size_type 
<B>rfind</B>(charT c, size_type pos = npos) const;</PRE>
<UL>
<P>Searches for the last sequence of characters in this string matching a specified string. The <SAMP>rfind</SAMP> variations return, respectively:</P>

<UL><PRE>rfind(basic_string(s,n), pos)
rfind(basic_string(s), pos)
rfind(basic_string(1, c), pos)
</PRE></UL>
</UL>


<A NAME="idx366"></A><PRE>basic_string&amp;
<B>replace</B>(size_type pos, size_type n1, const basic_string&amp; s);
basic_string&amp; 
<B>replace</B>(size_type pos1, size_type n1, 
        const basic_string&amp; str,
        size_type pos2, size_type n2);
basic_string&amp; 
<B>replace</B>(size_type pos, size_type n1, const charT* s,
        size_type n2);
basic_string&amp; 
<B>replace</B>(size_type pos, size_type n1, const charT* s);
basic_string&amp; 
<B>replace</B>(size_type pos, size_type n1, size_type n2, charT c);</PRE>
<UL>
<P>The <SAMP>replace()</SAMP> function replaces selected elements of this string with an alternate set of elements. All of these variations insert the new elements in place of <SAMP>n1</SAMP> elements in this string, starting at position <SAMP>pos</SAMP>. They each throw an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos1 &gt; size()</SAMP> and a <B><I><A HREF="length-error.html">length_error</A></I></B> exception if the resulting string size exceeds <SAMP>max_size()</SAMP>.</P>
</UL>

<UL>
<LI><P CLASS="LIST">The second variation replaces elements of the original string with <SAMP>n2</SAMP> characters from string <SAMP>s</SAMP> starting at position <SAMP>pos2</SAMP>. It throws the <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos2 &gt; s.size()</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation of the function replaces elements in the original string with <SAMP>n2</SAMP> elements from the array pointed to by <SAMP>s</SAMP>.</P></LI>
<LI><P CLASS="LIST"> The fourth variation replaces elements in the string with elements from the array pointed to by <SAMP>s</SAMP>, up to, but not including, the null character specified by <SAMP>charT()</SAMP>.  </P></LI>
<LI><P CLASS="LIST">The fifth variation replaces <SAMP>n</SAMP> elements with <SAMP>n2</SAMP> repetitions of character&nbsp;<SAMP>c</SAMP>.</P></LI>
</UL>

<A NAME="idx367"></A><PRE>
basic_string&amp; 
<B>replace</B>(iterator i1, iterator i2, 
        const basic_string&amp; str);
basic_string&amp; 
<B>replace</B>(iterator i1, iterator i2, const charT* s,
        size_type n);
basic_string&amp; 
<B>replace</B>(iterator i1, iterator i2, const charT* s);
basic_string&amp; 
<B>replace</B>(iterator i1, iterator i2, size_type n,
        charT c);
template&lt;class InputIterator&gt;
basic_string&amp; 
<B>replace</B>(iterator i1, iterator i2,
        InputIterator j1, InputIterator j2);</PRE>
<UL>
<P>Replaces selected elements of this string with an alternative set of elements. All of these variations of <SAMP>replace</SAMP> require iterators <SAMP>i1</SAMP> and <SAMP>i2</SAMP> to be valid iterators on this string. The elements specified by the range <SAMP>[i1, i2)</SAMP> are replaced by the new elements.</P>
</UL>

<UL>
<LI><P CLASS="LIST">The first variation replaces all members in <SAMP>str</SAMP>. </P></LI>
<LI><P CLASS="LIST">The second variation starts at position <SAMP>i1</SAMP>, and replaces the next <SAMP>n</SAMP> characters with <SAMP>n</SAMP> characters of the array pointed to by <SAMP>s</SAMP>. </P></LI>
<LI><P CLASS="LIST">The third variation replaces string elements with elements from the array pointed to by <SAMP>s</SAMP> up to, but not including, a <SAMP>charT()</SAMP> character.</P></LI>
<LI><P CLASS="LIST">The fourth variation replaces string elements with <SAMP>n</SAMP> repetitions of <SAMP>c</SAMP>.</P></LI>
<LI><P CLASS="LIST">The last variation replaces string elements with the members specified in the range <SAMP>[j1, j2)</SAMP>.</P></LI>
</UL>

<A NAME="idx368"></A><PRE>
void 
<B>reserve</B>(size_type res_arg=0);</PRE>
<UL>
<P>Assures that the storage capacity is at least <SAMP>res_arg</SAMP>. Throws a <B><I><A HREF="length-error.html">length_error</A></I></B> exception if <SAMP>res_arg &gt; max_size()</SAMP>.</P>
</UL>


<A NAME="idx369"></A><PRE>void
<B>resize</B>(size_type n, charT c);
void
<B>resize</B>(size_type n);</PRE>
<UL>
<P>Changes the capacity of this string to <SAMP>n</SAMP>. If the new capacity is smaller than the current size of the string, then the string is truncated. If the capacity is larger, then the string is padded with <SAMP>c</SAMP> characters. The latter <SAMP>resize()</SAMP> member pads the string with default characters specified by <SAMP>charT()</SAMP>. Throws a <B><I><A HREF="length-error.html">length_error</A></I></B> exception if <SAMP>n &gt; max_size()</SAMP>.</P>
</UL>


<A NAME="idx370"></A><PRE>size type
<B>size</B>()const;</PRE>
<UL>
<P>Returns the number of elements contained in this string.</P>
</UL>


<A NAME="idx371"></A><PRE>basic_string 
<B>substr</B>(size_type pos = 0, size_type n = npos) const;</PRE>
<UL>
<P>Returns a string composed of copies of the lesser of <SAMP>n</SAMP> and <SAMP>size() - pos</SAMP> characters in this string starting at index <SAMP>pos</SAMP>. Throws an <B><I><A HREF="out-of-range.html">out_of_range</A></I></B> exception if <SAMP>pos &gt; size()</SAMP>.</P>
</UL>


<A NAME="idx372"></A><PRE>void 
<B>swap</B>(basic_string&amp; s);</PRE>
<UL>
<P>Swaps the contents of this string with the contents of <SAMP>s</SAMP>.</P>
</UL>

<A NAME="sec12"><H3>Nonmember Operators</H3></A>

<A NAME="idx373"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
basic_string&lt;charT, traits allocator&gt;
<B>operator+</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a string of length <SAMP>lhs.size() + rhs.size()</SAMP>, where the first <SAMP>lhs.size()</SAMP> elements are copies of the elements of <SAMP>lhs</SAMP>, and the next <SAMP>rhs.size()</SAMP> elements are copies of the elements of <SAMP>rhs</SAMP>.</P>
</UL>


<A NAME="idx374"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
basic_string&lt;charT, traits allocator&gt;
<B>operator+</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
basic_string&lt;charT, traits allocator&gt;
<B>operator+</B>(charT lhs, const basic_string&lt;charT, traits allocator&gt; &amp; rhs);
template&lt;class charT, class traits, class Allocator&gt;
basic_string&lt;charT, traits allocator&gt;
<B>operator+</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);
template&lt;class charT, class traits, class Allocator&gt;
basic_string&lt;charT, traits allocator&gt;
<B>operator+</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, charT rhs);</PRE>
<UL>
<P>Returns a string that represents the concatenation of two string-like entities. These functions return, respectively:</P>

<UL><PRE>basic_string(lhs) + rhs
basic_string(1, lhs) + rhs
lhs + basic_string(rhs)
lhs + basic_string(1, rhs)
</PRE></UL>
</UL>


<A NAME="idx375"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator==</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, 
            const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value of <SAMP>true</SAMP> if <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP> are equal, and <SAMP>false</SAMP> if they are not. Equality is defined by the <SAMP>compare()</SAMP> member function.</P>
</UL>


<A NAME="idx376"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool   
<B>operator==</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator==</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value indicating whether <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP> are equal. Equality is defined by the <SAMP>compare()</SAMP> member function. These functions return, respectively:</P>

<UL><PRE>basic_string(lhs) == rhs
lhs == basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx377"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator!=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs,
            const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value representing the inequality of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Inequality is defined by the <SAMP>compare()</SAMP> member function.</P>
</UL>


<A NAME="idx378"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator!=</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator!=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value representing the inequality of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Inequality is defined by the <SAMP>compare()</SAMP> member function. The functions return, respectively:</P>

<UL><PRE>basic_string(lhs) != rhs
lhs != basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx379"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&lt;</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical less-than relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Less-than is defined by the <SAMP>compare() </SAMP>member.</P>
</UL>


<A NAME="idx380"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&lt;</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&lt;</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical less-than relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Less-than is defined by the<SAMP> compare() </SAMP>member function. These functions return, respectively:</P>

<UL><PRE>basic_string(lhs) &lt; rhs
lhs &lt; basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx381"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical greater-than relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Greater-than is defined by the<SAMP> compare()</SAMP> member function.</P>
</UL>


<A NAME="idx382"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical greater-than relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Greater-than is defined by the <SAMP>compare()</SAMP> member. The functions return, respectively:</P>

<UL><PRE>basic_string(lhs) &gt; rhs
lhs &gt; basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx383"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&lt;=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs,
             const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical less-than-or-equal relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Less-than-or-equal is defined by the <SAMP>compare()</SAMP> member function.</P>
</UL>


<A NAME="idx384"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool   
<B>operator&lt;=</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&lt;=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical less-than-or-equal relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Less-than-or-equal is defined by the <SAMP>compare()</SAMP> member function. These functions return, respectively:</P>

<UL><PRE>basic_string(lhs) &lt;= rhs
lhs &lt;= basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx385"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, 
           const basic_string&lt;charT, traits allocator&gt; &amp;rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical greater-than-or-equal relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Greater-than-or-equal is defined by the <SAMP>compare()</SAMP> member function.</P>
</UL>


<A NAME="idx386"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;=</B>(const charT* lhs, const basic_string&lt;charT, traits allocator&gt; &amp;rhs);
template&lt;class charT, class traits, class Allocator&gt;
bool 
<B>operator&gt;=</B>(const basic_string&lt;charT, traits allocator&gt; &amp;lhs, const charT* rhs);</PRE>
<UL>
<P>Returns a boolean value representing the lexicographical greater-than-or-equal relationship of <SAMP>lhs</SAMP> and <SAMP>rhs</SAMP>. Greater-than-or-equal is defined by the <SAMP>compare()</SAMP> member. The functions return, respectively:</P>

<UL><PRE>basic_string(lhs) &gt;= rhs
lhs &gt;= basic_string(rhs)
</PRE></UL>
</UL>


<A NAME="idx387"></A><PRE>
template &lt;class charT, class traits, class Allocator&gt;
void <B>swap</B>(basic_string&lt;charT,traits,Allocator&gt;&amp; a, 
           basic_string&lt;charT,traits,Allocator&gt;&amp; b); </PRE>
<UL>
<P>Swaps the contents of <SAMP>a</SAMP> and <SAMP>b</SAMP> by calling <SAMP>a</SAMP>'s swap function on <SAMP>b</SAMP>.</P>
</UL>


<A NAME="idx388"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
basic_istream&lt;charT, traits&gt;&amp;
<B>operator&gt;&gt;</B>(basic_istream&lt;charT, traits&gt;&amp; is, 
            basic_string&lt;charT, traits allocator&gt; &amp;str);</PRE>
<UL>
<P>All elements read from the stream <SAMP>is</SAMP>, except the delimiter, are placed in <SAMP>str</SAMP>. After the read, the function returns <SAMP>is</SAMP>.</P>
</UL>


<A NAME="idx389"></A><PRE>
template&lt;class charT, class traits, class Allocator&gt;
basic_ostream&lt;charT, traits&gt;&amp;
<B>operator&lt;&lt;</B>(basic_ostream &lt;charT, traits&gt;&amp; os, 
            const basic_string&lt;charT, traits allocator&gt; &amp;str);</PRE>
<UL>
<P>Writes all elements of <SAMP>str</SAMP> to <SAMP>os</SAMP> in order from first to last. After the write, the function returns <SAMP>os</SAMP>.</P>
</UL>

<A NAME="sec13"><H3>Nonmember Functions</H3></A>

<A NAME="idx390"></A><PRE>
template &lt;class Stream, class charT, class traits, class Allocator&gt;
basic_istream&lt;charT, traits&gt;
<B>getline</B>(basic_istream&lt;charT, traits&gt; is, 
         basic_string&lt;charT, traits allocator&gt; &amp;str, charT delim);</PRE>
<UL>
<P>An unformatted input function that extracts characters from <SAMP>is</SAMP> into <SAMP>str</SAMP> until <SAMP>npos - 1</SAMP> characters are read, the end of the input sequence is reached, or the character read is <SAMP>delim</SAMP>.  </P>
</UL>

<A NAME="sec14"><H3>Example</H3></A>

<UL><PRE>//
//  string.cpp
//

#include &lt;string&gt;
#include &lt;iostream&gt;


int main ()
{
#ifndef _RWSTD_NO_NAMESPACE
  using namespace std;
#endif

  string test;

  // Type in a string over five characters long.

  while (test.empty() ||  test.size() &lt; 5)
  {
    cout &lt;&lt; "Type a string between 5 and 100 characters long. " 
         &lt;&lt; endl;
    cin &gt;&gt; test;
  }

  // Try operator[] access.

  cout &lt;&lt; "Changing the third character from " &lt;&lt; test[2] 
       &lt;&lt; " to * " &lt;&lt; endl;
  test[2] = '*';
  cout &lt;&lt; "now it's: " &lt;&lt; test &lt;&lt; endl &lt;&lt; endl;

  // Try the insertion member function.

  test.insert(test.size() / 2, "(the middle is here!)");
  cout &lt;&lt; "Identifying the middle: " &lt;&lt; test &lt;&lt; endl &lt;&lt; endl;

  // Try replacement.

  test.replace(test.find("middle",0), 6, "center");
  cout &lt;&lt; "I didn't like the word 'middle', so instead, "
       &lt;&lt; "I'll say: " &lt;&lt; endl &lt;&lt; test &lt;&lt; endl; 

  return 0;
}


Program output:
</PRE></UL>
<UL><PRE>Type a string between 5 and 100 characters long.
roguewave
Changing the third character from g to *
now its: ro*uewave
Identifying the middle: ro*u(the middle is here!)ewave
I didn't like the word 'middle', so instead, I'll say:
ro*u(the center is here!)ewave
</PRE></UL>
<A NAME="sec15"><H3>See Also</H3></A>
<P><B><I><A HREF="allocator.html">allocator</A></I></B>, <B><I><A HREF="basic-string.html">string</A></I></B>, <B><I><A HREF="wstring.html">wstring</A></I></B></P>
<A NAME="sec16"><H3>Standards Conformance</H3></A>
<P><I>ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 21.3</I></P>

<BR>
<HR>
<A HREF="basic-streambuf.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="basic-stringbuf.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
    _uacct = "UA-1775151-1";
    urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->

</BODY>
</HTML>