rope.html

Standard Template Library (SOURCE + COMPLETE html man document)

<tt>void insert(size_t i, const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> immediately before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void insert(size_t i, 
            const const_iterator&amp; f, const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> immediately  before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void insert(size_t i, 
            const iterator&amp; f, const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> immediately before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void erase(size_t i, size_t n)</tt>
</TD>
<TD VAlign=top>
Erases <tt>n</tt> elements, starting with the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(const charT* s)</tt>
</TD>
<TD VAlign=top>
Adds a C string to the end of the <tt>rope</tt>.  The
   elements that are inserted are the sequence of characters
   starting with <tt>*s</tt> and up to, but not including, the first
   null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(const charT* s, size_ nt)</tt>
</TD>
<TD VAlign=top>
Adds an array of <tt>charT</tt> to the end of the <tt>rope</tt>.   The
   elements that are inserted are the range <tt>[s, s + n)</tt>.  Note 
   that this range is permitted to contain embedded null characters.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
Adds the elements in the range <tt>[f, l)</tt> to the end of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(charT c)</tt>
</TD>
<TD VAlign=top>
Adds the character <tt>c</tt> to the end of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append()</tt>
</TD>
<TD VAlign=top>
Adds the character <tt>charT()</tt> to the end of the rope.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Adds the contents of the rope <tt>x</tt> to the end of <tt>*this</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>append(size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
Adds <tt>n</tt> copies of <tt>c</tt> to the end of <tt>*this</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; f, const iterator&amp; l, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f, l)</tt> with the elements in <tt>x</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; f, const iterator&amp; l, charT c)</tt>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f, l)</tt> with the single
   character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; f, const iterator&amp; l, const charT* s)</tt>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f, l)</tt> with a C string:
   the sequence of characters beginning with <tt>*s</tt> and up to, but
   not including, the first null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; f, const iterator&amp; l, 
             const charT* s, size_t n)
</pre>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f, l)</tt> with the elements
   in the range <tt>[s, s + n)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; f1, const iterator&amp; l1, 
             const charT* f2, const charT* l2)
</pre>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f1, l1)</tt> with the elements
   in the range <tt>[f2, l2)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; f1, const iterator&amp; l1, 
             const const_iterator&amp; f2, const const_iterator&amp; l2)
</pre>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f1, l1)</tt> with the elements
   in the range <tt>[f2, l2)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; f1, const iterator&amp; l1, 
             const iterator&amp; f2, const iterator&amp; l2)
</pre>
</TD>
<TD VAlign=top>
Replaces the elements in the range <tt>[f1, l1)</tt> with the elements
   in the range <tt>[f2, l2)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; p, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the elements in <tt>x</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; p, charT c)</tt>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the single character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; p, const charT* s)</tt>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with a C string:
   the sequence of characters beginning with <tt>*s</tt> and up to, but
   not including, the first null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(const iterator&amp; p, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the elements
   in the range <tt>[s, s + n)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; p, 
             const charT* f, const charT* l)
</pre>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the elements in the
   range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; p, 
             const_iterator f, const_iterator l)
</pre>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the elements in the
   range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(const iterator&amp; p, 
             iterator f, iterator l)
</pre>
</TD>
<TD VAlign=top>
Replaces the element pointed to by <tt>p</tt> with the elements in the
   range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, size_t n, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element
   with the elements in <tt>x</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element
   with the single character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, size_t n, const charT* s)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element
   with an array of <tt>charT</tt>: the sequence of characters beginning with <tt>*s</tt> and up to, but
   not including, the first null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, size_t n1, const charT* s, size_t n2)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>n1</tt> elements beginning with the <tt>i</tt>th element
   with the elements in the range <tt>[s, s + n2)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(size_t i, size_t n, 
             const charT* f, const charT* l)
</pre>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element with
   the characters in the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(size_t i, size_t n, 
             const const_iterator&amp; f,
             const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element with
   the characters in the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(size_t i, size_t n, 
             const iterator&amp; f,
             const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Replaces the <tt>n</tt> elements beginning with the <tt>i</tt>th element with
   the characters in the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, charT c)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with the character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with elements from the <tt>rope</tt> x.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, const charT* s)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with a C string: the sequence of characters beginning with <tt>*s</tt> and up to, but
   not including, the first null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with the elements in the range <tt>[s, s + n)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void replace(size_t i, const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(size_t i, 
             const const_iterator&amp; f, const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void replace(size_t i, 
             const iterator&amp; f, const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
Replaces the <tt>i</tt>th element with the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope substr(iterator f) const</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> with a single element, <tt>*f</tt>. <A href="#4">[4]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope substr(const_iterator f) const</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> with a single element, <tt>*f</tt>. <A href="#4">[4]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope substr(iterator f, iterator l) const</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> that consists of the range <tt>[f, l)</tt>. <A href="#4">[4]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope substr(const_iterator f, const_iterator l) const</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> that consists of the range <tt>[f, l)</tt>. <A href="#4">[4]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope substr(size_t i, size_t n = 1) const</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> whose elements are the <tt>n</tt> characters
   starting at the position <tt>i</tt>. <A href="#4">[4]</A>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void copy(charT* buf) const</tt>
</TD>
<TD VAlign=top>
Copies the characters in a <tt>rope</tt> into <tt>buf</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
size_type copy(size_type pos, size_type n, 
               charT* buf)
</pre>
</TD>
<TD VAlign=top>
Copies <tt>n</tt> characters, starting at position <tt>pos</tt> in the <tt>rope</tt>, into
   <tt>buf</tt>.  If the <tt>rope</tt> contains fewer than <tt>pos + n</tt> characters, 
   then instead it only copies <tt>size() - pos</tt> characters.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const charT* c_str() const</tt>
</TD>
<TD VAlign=top>
Returns a pointer to a null-terminated sequence of characters that
contains all of the characters in a <tt>rope</tt>.  <A href="#5">[5]</A> <A href="#6">[6]</A> The resulting sequence of
characters is valid at least as long as the <tt>rope</tt> remains valid and
unchanged.  Note that the first invocation of this operation on long
strings is slow: it is linear in the length of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void delete_c_str()</tt>
</TD>
<TD VAlign=top>
Reclaims the internal storage used by <tt>c_str</tt>.  Note that this
   invalidates the pointer that <tt>c_str</tt> returns.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope operator+(const rope&amp; L, const rope&amp; R)</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> consisting of the concatenation of <tt>L</tt> and <tt>R</tt>.
   This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; operator+=(rope&amp; L, const rope&amp; R)</tt>
</TD>
<TD VAlign=top>
Modifies <tt>L</tt> by appending <tt>R</tt>, and returns <tt>L</tt>.
   This is a global function, not a member function. 
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope operator+(const rope&amp; L, const charT* s)</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> consisting of the concatenation of <tt>L</tt> and all
   of the characters from <tt>s</tt> up to, but not including, the first
   null character.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; operator+=(rope&amp; L, const charT* s)</tt>
</TD>
<TD VAlign=top>
Modifies <tt>L</tt> by appending the characters from <tt>s</tt> up to, but
   not including, the first null character.  The return value is
   <tt>L</tt>. This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope operator+(const rope&amp; L, charT c)</tt>
</TD>
<TD VAlign=top>
Returns a new <tt>rope</tt> consisting of <tt>L</tt> with the character <tt>c</tt>
   appended to it. This is a global function, not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; operator+=(rope&amp; L, charT c)</tt>
</TD>
<TD VAlign=top>
Modifies <tt>L</tt> by appending the character <tt>c</tt>. This is a global function,
   not a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>ostream&amp; operator&lt;&lt;(ostream&amp; os, rope x)</tt>
</TD>
<TD VAlign=top>
Outputs <tt>x</tt> to the stream <tt>os</tt>.  This is a global function, not
   a member function.
</TD>
</tr>
</table>
<h3>Notes</h3>
<P><A name="1">[1]</A>
For a detailed discussion of the <tt>rope</tt> data structure, see
H.-J. Boehm, R. Atkinson, and M. Plass, &quot;Ropes: An Alternative to
Strings&quot;, <i>Software Practice and Experience</i> <b>25</b>(12):1315, 1995.
<P><A name="2">[2]</A>
Since the value type is usually either <tt>char</tt> or <tt>wchar_t</tt>, the library
introduces two abbreviations: <tt>crope</tt> is a <tt>typedef</tt> for <tt>rope&lt;char&gt;</tt>,
and <tt>wrope</tt> is a <tt>typedef</tt> for <tt>rope&lt;wchar_t&gt;</tt>. 
<P><A name="3">[3]</A>
<tt>Rope::reference</tt> is not <tt>value_type&amp;</tt>, but a proxy type.  In fact,
<tt>reference</tt> is a <tt>typedef</tt> for the nested class <tt>charT_ref_proxy</tt>.
<tt>Const_reference</tt>, however, is simply <tt>const value_type&amp;</tt>.  Similarly,
<tt>const_pointer</tt> is just <tt>const value_type*</tt> but <tt>pointer</tt> is 
a proxy type.  If <tt>r</tt> is an object of type <tt>reference</tt>, then
<tt>&amp;r</tt> is of type <tt>pointer</tt>.
<P><A name="4">[4]</A>
Note that the return value of <tt>substr</tt> is conceptually a distinct
<tt>rope</tt>: the two <tt>rope</tt>s may share storage, but this is a hidden
implementation detail.  If you modify a <tt>rope</tt> returned by
<tt>substr</tt>, this will not change the value of the original <tt>rope</tt>.
<P><A name="5">[5]</A>
The final <tt>const</tt> qualifier in the member function <tt>c_str()</tt> 
is conceptually slightly inaccurate in the interest of conformance to
the <tt>basic_string interface</tt> in the draft C++ standard; the rope is updated
to cache the converted string.  
<P><A name="6">[6]</A>
Concurrent calls to <tt>c_str()</tt> are allowed; the cache is updated atomically. 
<h3>See also</h3>
<A href="RandomAccessContainer.html">Random Access Container</A>, 
<A href="Sequence.html">Sequence</A>, 
<tt><A href="Vector.html">vector</A></tt>,
<tt><A href="sequence_buffer.html">sequence_buffer</A></tt>

<!-- start footer -->
<!-- Footer Begins -->

<STYLE TYPE="text/css">
<!--
TD.footer, TD.footer A{
		font-family: Arial, helvetica, sans-serif;
        	font-size: 8pt;

}

A.home {
font-family: Arial, helvetica, sans-serif;
}
-->
</STYLE>
<P>
<A CLASS="home" HREF="index.html">STL Home</A>
<P>
<TABLE WIDTH="600" CELLPADDING="0" CELLPADDING="0" BORDER="0">
	<TR>
	    <TD ALIGN="RIGHT" CLASS="footer"><A HREF="/company_info/terms.html" TARGET="_top">terms of use</A> | <A HREF="/company_info/privacy.html" TARGET="_top">privacy policy</A></TD>
	    <TD ALIGN="CENTER" CLASS="footer">&nbsp;|&nbsp;</TD>
	    <TD ALIGN="LEFT" CLASS="footer"><A HREF="/cgi-bin/feedback/" TARGET="_top">contact us</A></TD>
	</TR><TR>
	    <TD ALIGN="RIGHT" CLASS="footer">Copyright &copy; 1993-2003 Silicon Graphics, Inc. All rights reserved.</TD>
	    <TD ALIGN="CENTER" CLASS="footer">&nbsp;|&nbsp;</TD>
	    <TD ALIGN="LEFT" CLASS="footer"><A HREF="/company_info/trademarks/" TARGET="_top">Trademark Information</A></TD>
	</TR>
</TABLE>

<!-- Footer Ends -->

<!-- end footer -->
<P>
</BODY>
</HTML>