| <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> <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>>()</A><BR> |
| </TD> |
| <TD VALIGN=top><A HREF="#idx381">operator>()</A><BR> |
| <A HREF="#idx385">operator>=()</A><BR> |
| <A HREF="#idx389">operator<<()</A><BR> |
| </TD> |
| <TD VALIGN=top><A HREF="#idx379">operator<()</A><BR> |
| <A HREF="#idx383">operator<=()</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 </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 <char> string;typedef basic_string <wchar_t> wstring;</SAMP></P> |
| <A NAME="sec3"><H3>Synopsis</H3></A> |
| |
| <PRE>#include <string> |
| |
| namespace std { |
| template <class charT, |
| class traits = char_traits<charT>, |
| class Allocator = allocator<charT> > |
| 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 <class charT, |
| class traits = char_traits<charT>, |
| class Allocator = allocator<charT> > |
| 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<const_iterator> |
| const_reverse_iterator; |
| typedef std::reverse_iterator<iterator> reverse_iterator; |
| |
| static const size_type npos = -1; |
| |
| // Constructors/Destructors |
| |
| explicit basic_string(const Allocator& = Allocator()); |
| basic_string(const basic_string<charT, traits, Allocator>&); |
| basic_string(const basic_string&, size_type, |
| size_type = npos, |
| const Allocator& a = Allocator()); |
| basic_string(const charT*, size_type, |
| const Allocator& = Allocator()); |
| basic_string(const charT*, const Allocator& = Allocator()); |
| basic_string(size_type, charT, |
| const Allocator& = Allocator()); |
| template <class InputIterator> |
| basic_string(InputIterator, InputIterator, |
| const Allocator& = Allocator()); |
| ~basic_string(); |
| |
| // Assignment operators |
| |
| basic_string& operator=(const basic_string&); |
| basic_string& operator=(const charT*); |
| basic_string& 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& operator+=(const basic_string&); |
| basic_string& operator+=(const charT*); |
| basic_string& operator+=(charT); |
| |
| basic_string& append(const basic_string&); |
| basic_string& append(const basic_string&, |
| size_type, size_type); |
| basic_string& append(const charT*, size_type); |
| basic_string& append(const charT*); |
| basic_string& append(size_type, charT); |
| |
| template<class InputIterator> |
| basic_string& append(InputIterator, InputIterator); |
| |
| void push_back(charT); |
| basic_string& assign(const basic_string&); |
| basic_string& assign(const basic_string&, |
| size_type, size_type); |
| basic_string& assign(const charT*, size_type); |
| basic_string& assign(const charT*); |
| basic_string& assign(size_type, charT); |
| template<class InputIterator> |
| basic_string& assign(InputIterator, InputIterator); |
| |
| basic_string& insert(size_type, const basic_string&); |
| basic_string& insert(size_type, const basic_string&, |
| size_type, size_type); |
| basic_string& insert(size_type, const charT*, size_type); |
| basic_string& insert(size_type, const charT*); |
| basic_string& insert(size_type, size_type, charT); |
| iterator insert(iterator, charT = charT()); |
| void insert(iterator, size_type, charT); |
| template<class InputIterator> |
| void insert(iterator, InputIterator, InputIterator); |
| |
| basic_string& erase(size_type = 0, size_type= npos); |
| iterator erase(iterator); |
| iterator erase(iterator, iterator); |
| |
| basic_string& replace(size_type, size_type, |
| const basic_string&); |
| basic_string& replace(size_type, size_type, |
| const basic_string&, |
| size_type, size_type); |
| basic_string& replace(size_type, size_type, |
| const charT*, size_type); |
| basic_string& replace(size_type, size_type, |
| const charT*); |
| basic_string& replace(size_type, size_type, |
| size_type, charT); |
| basic_string& replace(iterator, iterator, |
| const basic_string&); |
| basic_string& replace(iterator, iterator, |
| const charT*, size_type); |
| basic_string& replace(iterator, iterator, |
| const charT*); |
| basic_string& replace(iterator, iterator, |
| size_type, charT); |
| template<class InputIterator> |
| basic_string& replace(iterator, iterator, |
| InputIterator, InputIterator); |
| |
| size_type copy(charT*, size_type, size_type = 0) const; |
| void swap(basic_string<charT, traits, Allocator>&); |
| |
| // String operations |
| |
| const charT* c_str() const; |
| const charT* data() const; |
| allocator_type& get_allocator() const; |
| |
| size_type find(const basic_string&, |
| 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&, |
| 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&, |
| 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&, |
| 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&, |
| 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&, |
| 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&) const; |
| int compare(size_type, size_type, const basic_string&) |
| const; |
| int compare(size_type, size_type, const basic_string&, |
| 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 <class charT, class traits, class Allocator> |
| basic_string operator+(const basic_string&, |
| const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| basic_string operator+(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| basic_string operator+(charT, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| basic_string operator+(const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| basic_string operator+(const basic_string&, charT); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator==(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator==(const charT*, const basic_string&); |
| |
| template <class charT, class traits , class Allocator> |
| bool operator==(const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<(const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator!=(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator!=(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator!=(const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>(const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<=(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<=(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator<=(const basic_string&, const charT*); |
| |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>=(const basic_string&, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>=(const charT*, const basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| bool operator>= (const basic_string&, const charT*); |
| |
| template <class charT, class traits, class Allocator> |
| void swap(basic_string<charT,traits,Allocator>& a, |
| basic_string<charT,traits,Allocator>& b); |
| |
| template<class charT, class traits, class Allocator> |
| basic_istream<charT, traits>& operator>>(istream&, |
| basic_string&); |
| |
| template <class charT, class traits, class Allocator> |
| basic_ostream<charT, traits>& operator<<(ostream&, |
| const basic_string&); |
| |
| template <class Stream, class charT,class traits, class Allocator> |
| basic_istream<charT, traits>& |
| getline(Stream&, basic_string&, 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& 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<T, traits, |
| Allocator>& 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& str, size_type pos, |
| size_type n= npos, const allocator& |
| a=allocator());</PRE> |
| <UL> |
| <P>Creates a string of <SAMP>pos<=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>></SAMP> <SAMP>str.size()</SAMP>.</P> |
| </UL> |
| |
| |
| <A NAME="idx323"></A><PRE><B>basic_string</B> (const charT* s, size_type n, |
| const Allocator& 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& 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& 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 <class InputIterator> |
| <B>basic_string</B> (InputIterator start, InputIterator finish, |
| const Allocator& 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>Destructors</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& |
| <B>operator=</B>(const basic_string& 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& |
| <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& |
| <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 < 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& |
| <B>operator+=</B>(const basic_string& s); |
| basic_string& |
| <B>operator+=</B>(const charT* s); |
| basic_string& |
| <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& |
| <B>append</B>(const basic_string& s, size_type pos, |
| size_type npos); |
| basic_string& |
| <B>append</B>(const basic_string& s); |
| basic_string& |
| <B>append</B>(const charT* s, size_type n); |
| basic_string& |
| <B>append</B>(const charT* s); |
| basic_string& |
| <B>append</B>(size_type n, charT c ); |
| template<class InputIterator> |
| basic_string& |
| <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 > 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<size_type>(1), c)</SAMP>.</P> |
| </UL> |
| |
| |
| <A NAME="idx340"></A><PRE>basic_string& |
| <B>assign</B>(const basic_string& s); |
| basic_string& |
| <B>assign</B>(const basic_string& s, |
| size_type pos, size_type n); |
| basic_string& |
| <B>assign</B>(const charT* s, size_type n); |
| basic_string& |
| <B>assign</B>(const charT* s); |
| basic_string& |
| <B>assign</B>(size_type n, charT c ); |
| template<class InputIterator> |
| basic_string& |
| <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 > 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 < 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& 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><0 if size() < str.size() |
| 0 if size() == str.size() |
| >0 if size() > str.size() |
| </PRE></UL> |
| </UL> |
| |
| |
| <A NAME="idx345"></A><PRE> |
| int |
| <B>compare</B>(size_type pos1, size_type n1, |
| const basic_string& str) const; |
| int |
| <B>compare</B>(size_type pos1, size_type n1, |
| const basic_string& 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 > 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& |
| <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 > 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& 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& 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& 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& 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& 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& |
| <B>insert</B>(size_type pos1, const basic_string& s); |
| basic_string& |
| <B>insert</B>(size_type pos, const basic_string& s, |
| size_type pos2 = 0, size_type n = npos); |
| basic_string& |
| <B>insert</B>(size_type pos, const charT* s, size_type n); |
| basic_string& |
| <B>insert</B>(size_type pos, const charT* s); |
| basic_string& |
| <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 > 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 > 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<class InputIterator> |
| 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& 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& |
| <B>replace</B>(size_type pos, size_type n1, const basic_string& s); |
| basic_string& |
| <B>replace</B>(size_type pos1, size_type n1, |
| const basic_string& str, |
| size_type pos2, size_type n2); |
| basic_string& |
| <B>replace</B>(size_type pos, size_type n1, const charT* s, |
| size_type n2); |
| basic_string& |
| <B>replace</B>(size_type pos, size_type n1, const charT* s); |
| basic_string& |
| <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 > 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 > 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 <SAMP>c</SAMP>.</P></LI> |
| </UL> |
| |
| <A NAME="idx367"></A><PRE> |
| basic_string& |
| <B>replace</B>(iterator i1, iterator i2, |
| const basic_string& str); |
| basic_string& |
| <B>replace</B>(iterator i1, iterator i2, const charT* s, |
| size_type n); |
| basic_string& |
| <B>replace</B>(iterator i1, iterator i2, const charT* s); |
| basic_string& |
| <B>replace</B>(iterator i1, iterator i2, size_type n, |
| charT c); |
| template<class InputIterator> |
| basic_string& |
| <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 > 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 > 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 > size()</SAMP>.</P> |
| </UL> |
| |
| |
| <A NAME="idx372"></A><PRE>void |
| <B>swap</B>(basic_string& 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<class charT, class traits, class Allocator> |
| basic_string |
| <B>operator+</B>(const basic_string& lhs, const basic_string& 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<class charT, class traits, class Allocator> |
| basic_string |
| <B>operator+</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| basic_string |
| <B>operator+</B>(charT lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| basic_string |
| <B>operator+</B>(const basic_string& lhs, const charT* rhs); |
| template<class charT, class traits, class Allocator> |
| basic_string |
| <B>operator+</B>(const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator==</B>(const basic_string& lhs, |
| const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator==</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator==</B>(const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator!=</B>(const basic_string& lhs, |
| const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator!=</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator!=</B>(const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator<</B>(const basic_string& lhs, const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator<</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator<</B>(const basic_string& 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) < rhs |
| lhs < basic_string(rhs) |
| </PRE></UL> |
| </UL> |
| |
| |
| <A NAME="idx381"></A><PRE>template<class charT, class traits, class Allocator> |
| bool |
| <B>operator></B>(const basic_string& lhs, const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator></B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator></B>(const basic_string& 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) > rhs |
| lhs > basic_string(rhs) |
| </PRE></UL> |
| </UL> |
| |
| |
| <A NAME="idx383"></A><PRE>template<class charT, class traits, class Allocator> |
| bool |
| <B>operator<=</B>(const basic_string& lhs, |
| const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator<=</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator<=</B>(const basic_string& 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) <= rhs |
| lhs <= basic_string(rhs) |
| </PRE></UL> |
| </UL> |
| |
| |
| <A NAME="idx385"></A><PRE>template<class charT, class traits, class Allocator> |
| bool |
| <B>operator>=</B>(const basic_string& lhs, |
| const basic_string& 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<class charT, class traits, class Allocator> |
| bool |
| <B>operator>=</B>(const charT* lhs, const basic_string& rhs); |
| template<class charT, class traits, class Allocator> |
| bool |
| <B>operator>=</B>(const basic_string& 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) >= rhs |
| lhs >= basic_string(rhs) |
| </PRE></UL> |
| </UL> |
| |
| |
| <A NAME="idx387"></A><PRE>template <class charT, class traits, class Allocator> |
| void <B>swap</B>(basic_string<charT,traits,Allocator>& a, |
| basic_string<charT,traits,Allocator>& 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<class charT, class traits, class Allocator> |
| basic_istream<charT, traits>& |
| <B>operator>></B>(basic_istream<charT, traits>& is, |
| basic_string& 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<class charT, class traits, class Allocator> |
| basic_ostream<charT, traits>& |
| <B>operator<<</B>(basic_ostream <charT, traits>& os, |
| const<charT, traits allocator> 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 <class Stream, class charT, class traits, |
| class Allocator> |
| basic_istream<charT, traits> |
| <B>getline</B>(basic_istream<charT, traits> is, |
| <charT, traits allocator> 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 <string> |
| #include <iostream> |
| |
| |
| 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() < 5) |
| { |
| cout << "Type a string between 5 and 100 characters long. " |
| << endl; |
| cin >> test; |
| } |
| |
| // Try operator[] access. |
| |
| cout << "Changing the third character from " << test[2] |
| << " to * " << endl; |
| test[2] = '*'; |
| cout << "now it's: " << test << endl << endl; |
| |
| // Try the insertion member function. |
| |
| test.insert(test.size() / 2, "(the middle is here!)"); |
| cout << "Identifying the middle: " << test << endl << endl; |
| |
| // Try replacement. |
| |
| test.replace(test.find("middle",0), 6, "center"); |
| cout << "I didn't like the word 'middle', so instead, " |
| << "I'll say: " << endl << test << 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> |
