/usr/share/doc/stl-manual/html/Rope.html

<HTML>
<!--
  -- Copyright (c) 1996-1999
  -- Silicon Graphics Computer Systems, Inc.
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Silicon Graphics makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -- Copyright (c) 1994
  -- Hewlett-Packard Company
  --
  -- Permission to use, copy, modify, distribute and sell this software
  -- and its documentation for any purpose is hereby granted without fee,
  -- provided that the above copyright notice appears in all copies and
  -- that both that copyright notice and this permission notice appear
  -- in supporting documentation.  Hewlett-Packard Company makes no
  -- representations about the suitability of this software for any
  -- purpose.  It is provided "as is" without express or implied warranty.
  --
  -->
<Head>
<Title>rope&lt;T, Alloc&gt;</Title>
<!-- Generated by htmldoc -->
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
	ALINK="#ff0000"> 
<IMG SRC="CorpID.gif" 
     ALT="SGI" HEIGHT="43" WIDTH="151"> 
<!--end header-->
<BR Clear>
<H1>rope&lt;T, Alloc&gt;</H1>

<Table CellPadding=0 CellSpacing=0 width=100%>
<TR>
<TD Align=left><Img src = "containers.gif" Alt=""   WIDTH = "194"  HEIGHT = "38" ></TD>
<TD Align=right><Img src = "type.gif" Alt=""   WIDTH = "194"  HEIGHT = "39" ></TD>
</TR>
<TR>
<TD Align=left VAlign=top><b>Category</b>: containers</TD>
<TD Align=right VAlign=top><b>Component type</b>: type</TD>
</TR>
</Table>

<h3>Description</h3>
<tt>Rope</tt>s are a scalable string implementation: they are designed
for efficient operation that involve the string as a whole.  Operations
such as assignment, concatenation, and substring take time that is
nearly independent of the length of the string.  Unlike C strings,
<tt>rope</tt>s are a reasonable representation for very long strings such as
edit buffers or mail messages. <A href="#1">[1]</A>
<P>
Though <tt>rope</tt>s can be treated as <A href="Container.html">Container</A>s of characters, and are
almost <A href="Sequence.html">Sequence</A>s, this is rarely the most efficient way to
accomplish a task.  Replacing an individual character in a <tt>rope</tt> is
slow: each character replacement essentially consists of two substring
operations followed by two concatenation operations.  <tt>Rope</tt>s
primarily target a more functional programming style.
<P>
They differ from <tt><A href="Vector.html">vector</A>&lt;char&gt;</tt> or reference-counted string
implementations in the following ways.
<P>
Advantages:
<UL>
<LI>
Much faster concatenation and substring operations involving long
strings.  Inserting a character in the middle of a 10 megabyte rope
should take on the order of 10s of microseconds, even if a copy of the
original is kept, <i>e.g.</i> as part of an edit history.  In contrast,
this would take on the order of a second for conventional &quot;flat&quot;
string representation.  The time required for concatenation can be
viewed as constant for most applications.  It is perfectly reasonable
to use a <tt>rope</tt> as the representation of a file inside a text editor.
<LI>
Potentially much better space performance.  Minor modifications of a
<tt>rope</tt> can share memory with the original.  <tt>Rope</tt>s are allocated in small
chunks, significantly reducing memory fragmentation problems introduced
by large blocks.
<LI>
Assignment is simply a (possibly reference counted) pointer
assignment.  Unlike reference-counted copy-on-write implementations,
this remains largely true even if one of the copies is subsequently
slightly modified. It is very inexpensive to checkpoint old versions
of a string, <i>e.g.</i> in an edit history.
<LI>
It is possible to view a function producing characters as a <tt>rope</tt>.  Thus
a piece of a rope may be a 100MByte file, which is read only when that section
of the string is examined.  Concatenating a string to the end of such a file
does not involve reading the file.  (Currently the implementation of this
facility is incomplete.)
</UL>
Disadvantages:
<UL>
<LI>
Single character replacements in a <tt>rope</tt> are expensive.  A character
update requires time roughly logarithmic in the length of the string.
It is implemented as two substring operations followed by two
concatenations.
<LI>
A <tt>rope</tt> can be examined a character at a time through a
<tt>const_iterator</tt> in amortized constant time, as for
<tt><A href="Vector.html">vector</A>&lt;char&gt;</tt>.  However this is slower than for
<tt><A href="Vector.html">vector</A>&lt;char&gt;</tt> by a significant constant factor (roughly a factor
of 5 or 10 if little processing is done on each character and the
string is long).  Nonconst iterators involve additional checking, and
are hence a bit slower still.  (We expect that eventually some common
algorithms will be specialized so that this cost is not encountered.
Currently only output, conversion to a C string, and the
single-character find member function are treated in this way.)
<LI>
Iterators are on the order of a dozen words in size.  This means that
copying them, though not tremendously expensive, is not a trivial
operation.  Avoid postincrementing iterators; use preincrement
whenever possible. (The interface also provides primitives for
indexing into a string using integer character positions.  Passing
positions around is clearly much cheaper, but this makes the indexing
operation expensive, again roughly logarithmic in the length of the
rope.)
</UL>
Experience with previous implementations for other programming
languages suggests that <tt>rope</tt>s are a good choice as the normal or
default representation of strings in a program.  It will occasionally
be necessary to use some type of character array, such as
<tt><A href="Vector.html">vector</A>&lt;char&gt;</tt>, in places that are particularly sensitive to the
performance of traversals or in-place updates.  But the use of <tt>rope</tt>s
minimizes the number of cases in which program running times become
intolerable due to unexpectedly long string inputs.
<P>
A <tt>rope</tt> is almost, but not quite, a <A href="Sequence.html">Sequence</A>. It supports random
access const_iterators.  Forward or backward traversals take constant
time per operation.  Nonconstant iterators are also provided.
However, assignment through a nonconst iterator is an expensive
operation (basically logarithmic time, but with a large constant).  It
should be avoided in frequently executed code.
<P>
In order to discourage accidental use of expensive operations,
the <tt>begin</tt> and <tt>end</tt> member functions on ropes return <tt>const_iterator</tt>.
If non-const iterators are desired, the member functions
<tt>mutable_begin</tt> and <tt>mutable_end</tt> should be used.
<P>
Any modification of a <tt>rope</tt> invalidates const iterators referring to
the rope.  Mutable iterators refer to the same position in the same
<tt>rope</tt> after an update.  (This may be surprising if the iterators refers
to a position after an insertion point.)  They remain valid unless the
iterator refers to a position that is more than one past the end of the
resulting <tt>rope</tt>.  
<h3>Definition</h3>
Defined in the header <A href="rope">rope</A>, and in the backward-compatibility
header <A href="rope.h">rope.h</A>.  The <tt>rope</tt> class, and the <A href="rope">rope</A> header, are SGI
extensions; they are not part of the C++ standard.
<h3>Example</h3>
<pre>
crope r(1000000, 'x');          // crope is rope&lt;char&gt;. wrope is rope&lt;wchar_t&gt;
                                // Builds a rope containing a million 'x's.
                                // Takes much less than a MB, since the
                                // different pieces are shared.
crope r2 = r + &quot;abc&quot; + r;       // concatenation; takes on the order of 100s
                                // of machine instructions; fast
crope r3 = r2.substr(1000000, 3);       // yields &quot;abc&quot;; fast.
crope r4 = r2.substr(1000000, 1000000); // also fast.
reverse(r2.mutable_begin(), r2.mutable_end());
                                // correct, but slow; may take a
                                // minute or more.
</pre>
<h3>Template parameters</h3>
<Table border>
<TR>
<TH>
Parameter
</TH>
<TH>
Description
</TH>
<TH>
Default
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>T</tt>
</TD>
<TD VAlign=top>
The <tt>rope</tt>'s value type: usually <tt>char</tt> or <tt>wchar_t</tt>. <A href="#2">[2]</A>
</TD>
<TD VAlign=top>
&nbsp;
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>Alloc</tt>
</TD>
<TD VAlign=top>
The <tt>rope</tt>'s allocator, used for all internal memory management.
</TD>
<TD VAlign=top>
<tt><A href="Allocators.html">alloc</A></tt>
</TD>
</tr>
</table>
<h3>Model of</h3>
<A href="RandomAccessContainer.html">Random Access Container</A>.  Almost, but not quite, a model of
<A href="FrontInsertionSequence.html">Front Insertion Sequence</A> and <A href="BackInsertionSequence.html">Back Insertion Sequence</A>.
<h3>Type requirements</h3>
None, except for those imposed by the requirements of 
<A href="RandomAccessContainer.html">Random Access Container</A>.
<h3>Public base classes</h3>
None.
<h3>Members</h3>
<Table border>
<TR>
<TH>
Member
</TH>
<TH>
Where defined
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt>value_type</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
The <tt>rope</tt>'s value type <tt>T</tt>, usually <tt>char</tt> or <tt>wchar_t</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>difference_type</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
A signed integral type.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>size_type</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
An unsigned integral type.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reference</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Reference to a <tt>rope</tt> element. <A href="#3">[3]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_reference</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Const reference to <tt>T</tt>. <A href="#3">[3]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>pointer</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Pointer to <tt>T</tt>. <A href="#3">[3]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_pointer</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Const pointer to <tt>T</tt>. <A href="#3">[3]</A>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_reverse_iterator</tt>
</TD>
<TD VAlign=top>
 <A href="ReversibleContainer.html">Reversible Container</A>
</TD>
<TD VAlign=top>
Const iterator used to iterate backwards through a <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reverse_iterator</tt>
</TD>
<TD VAlign=top>
 <A href="ReversibleContainer.html">Reversible Container</A>
</TD>
<TD VAlign=top>
Mutable iterator used to iterate backwards through a <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Mutable <A href="RandomAccessIterator.html">random access iterator</A> used to iterate through a <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_iterator</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Const <A href="RandomAccessIterator.html">random access iterator</A> used to iterate through a <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>.
</TD>
<TD VAlign=top>
Constructs a <tt>rope</tt> from a C string.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>.
</TD>
<TD VAlign=top>
Constructs a <tt>rope</tt> from a (not necessarily null-terminated)
   array of <tt>charT</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const const_iterator&amp; f, const const_iterator&amp; l)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Creates a <tt>rope</tt> with a copy of a range.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const iterator&amp; f, const iterator&amp; l)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Creates a <tt>rope</tt> with a copy of a range.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Creates a <tt>rope</tt> with a copy of a range.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>.
</TD>
<TD VAlign=top>
Single-character constructor.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Default constructor.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(<A href="char_producer.html">char_producer</A>&lt;charT&gt;*, size_t, bool)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
The copy constructor.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>~rope</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
The destructor.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; <b>operator=</b>(const rope&amp;x)</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
The assignment operator.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>swap</b>(rope&amp; x)</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Swaps the contents of two <tt>rope</tt>s.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>size_type <b>size</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Returns the size of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>size_type <b>length</b>() const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Same as <tt>size</tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>size_type <b>max_size</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Size of longest <tt>rope</tt> guaranteed to be representable.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>bool <b>empty</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Equivalent to <tt>size() == 0</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_iterator <b>begin</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Returns an <tt>const_iterator</tt> pointing to the beginning of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_iterator <b>end</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Container.html">Container</A>
</TD>
<TD VAlign=top>
Returns an <tt>const_iterator</tt> pointing to the end of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_begin</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Returns an <tt>iterator</tt> pointing to the beginning of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_end</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Returns an <tt>iterator</tt> pointing to the end of the <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_reverse_iterator <b>rbegin</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="ReversibleContainer.html">Reversible Container</A>
</TD>
<TD VAlign=top>
Returns a <tt>const_reverse_iterator</tt> pointing to the beginning of the
   reversed <tt>rope</tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const_reverse_iterator <b>rend</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="ReversibleContainer.html">Reversible Container</A>
</TD>
<TD VAlign=top>
Returns a <tt>const_reverse_iterator</tt> pointing to the end of the
   reversed <tt>rope</tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_rbegin</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reverse_iterator</tt> pointing to the beginning of the
   reversed <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_rend</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reverse_iterator</tt> pointing to the end of the
   reversed <tt>rope</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>charT <b>operator[]</b>(size_type n) const</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessContainer.html">Random Access Container</A>
</TD>
<TD VAlign=top>
Returns the <tt>n</tt>'th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>charT <b>at</b>(size_type pos) const</tt>
</TD>
<TD VAlign=top>
 <A href="RandomAccessContainer.html">Random Access Container</A>
</TD>
<TD VAlign=top>
Returns the <tt>n</tt>'th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reference <b>mutable_reference_at</b>(size_type n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reference</tt> to the <tt>n</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>int <b>compare</b>(const rope&amp;) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>.
</TD>
<TD VAlign=top>
Three-way comparison. See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>charT <b>front</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Returns the first element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>charT <b>back</b>() const</tt>
</TD>
<TD VAlign=top>
 <A href="BackInsertionSequence.html">Back Insertion Sequence</A>
</TD>
<TD VAlign=top>
Returns the last element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>push_front</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="FrontInsertionSequence.html">Front Insertion Sequence</A>
</TD>
<TD VAlign=top>
Inserts a new element at the front.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>push_back</b>(charT)</tt>
</TD>
<TD VAlign=top>
 <A href="BackInsertionSequence.html">Back Insertion Sequence</A>
</TD>
<TD VAlign=top>
Inserts a new element at the end.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>pop_front</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="FrontInsertionSequence.html">Front Insertion Sequence</A>
</TD>
<TD VAlign=top>
Removes the first element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>pop_back</b>()</tt>
</TD>
<TD VAlign=top>
 <A href="BackInsertionSequence.html">Back Insertion Sequence</A>
</TD>
<TD VAlign=top>
Removes the last element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the contents of <tt>x</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, charT c)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts <tt>c</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts <tt>charT()</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts <tt>n</tt> copies of <tt>c</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts a C string before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts a (not necessarily null-terminated)
   array of <tt>charT</tt>  before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const charT* f, const char* l)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
iterator <b>insert</b>(const iterator&amp; p, 
                const const_iterator&amp; f, const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
iterator <b>insert</b>(const iterator&amp; p, 
                const iterator&amp; f, const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the contents of <tt>x</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the character <tt>c</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the character <tt>charT()</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts <tt>n</tt> copies of <tt>c</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts a C string before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts a (not necessarily null-terminated)
   array of <tt>charT</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>insert</b>(size_t i, 
            const const_iterator&amp; f, const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>insert</b>(size_t i, 
            const iterator&amp; f, const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Inserts the range <tt>[f, l)</tt> before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>erase</b>(const iterator&amp; p)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Erases the element pointed to by <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>erase</b>(const iterator&amp; f, const iterator&amp; l)</tt>
</TD>
<TD VAlign=top>
 <A href="Sequence.html">Sequence</A>
</TD>
<TD VAlign=top>
Erases the range <tt>[f, l)</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>erase</b>(size_t i, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</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><b>append</b>(const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends a C string.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(const charT* s, size_t)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends a (not necessarily null-terminated) array of <tt>charT</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends a range.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends the character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends the character <tt>charT()</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends <tt>n</tt> copies of <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends the rope <tt>x</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; f, const iterator&amp; l, const rope&amp;)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; f, const iterator&amp; l, charT)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; f, const iterator&amp; l, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; f, const iterator&amp; l, 
             const charT* s, size_t n)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; f1, const iterator&amp; l1, 
             const charT* f2, const charT* l2)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; f1, const iterator&amp; l1, 
             const const_iterator&amp; f2, const const_iterator&amp; l2)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; f1, const iterator&amp; l1, 
             const iterator&amp; f2, const iterator&amp; l2)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; p, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; p, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; p, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(const iterator&amp; p, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; p, 
             const charT* f, const charT* l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; p, 
             const_iterator f, const_iterator l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(const iterator&amp; p, 
             iterator f, iterator l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, size_t n, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, size_t n, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, size_t n, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(size_t i, size_t n, 
             const charT* f, const charT* l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(size_t i, size_t n, 
             const const_iterator&amp; f,
             const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(size_t i, size_t n, 
             const iterator&amp; f,
             const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>replace</b>(size_t i, const charT* f, const charT* l)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(size_t i, 
             const const_iterator&amp; f, const const_iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
void <b>replace</b>(size_t i, 
             const iterator&amp; f, const iterator&amp; l)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>substr</b>(iterator f) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>substr</b>(const_iterator f) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>substr</b>(iterator f, iterator l) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>substr</b>(const_iterator f, const_iterator l) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>substr</b>(size_t i, size_t n = 1) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>copy</b>(charT* buf) const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Copies a rope into an array of <tt>charT</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<pre>
size_type <b>copy</b>(size_type pos, size_type n, 
               charT* buf)
</pre>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Copies a rope into an array of <tt>charT</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>const charT* <b>c_str</b>() const</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>delete_c_str</b>()</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
See below.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>operator+</b>(const rope&amp; L, const rope&amp;R)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Concatenates <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; <b>operator+=</b>(rope&amp; L, const rope&amp; R)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends <tt>R</tt> to <tt>L</tt>.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>operator+</b>(const rope&amp; L, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Concatenates <tt>L</tt> and <tt>s</tt>.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; <b>operator+=</b>(rope&amp; L, const charT* s)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends <tt>s</tt> to <tt>L</tt>.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope <b>operator+</b>(const rope&amp; L, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Concatenates <tt>L</tt> and <tt>c</tt>.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>rope&amp; <b>operator+=</b>(rope&amp; L, charT c)</tt>
</TD>
<TD VAlign=top>
<tt>rope</tt>
</TD>
<TD VAlign=top>
Appends <tt>c</tt> to <tt>L</tt>.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>bool <b>operator&lt;</b>(const rope&amp;, const rope&amp;)</tt>
</TD>
<TD VAlign=top>
 <A href="ForwardContainer.html">Forward Container</A>
</TD>
<TD VAlign=top>
Lexicographical comparison.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>bool <b>operator==</b>(const rope&amp;, const rope*)</tt>
</TD>
<TD VAlign=top>
 <A href="ForwardContainer.html">Forward Container</A>
</TD>
<TD VAlign=top>
Tests two <tt>rope</tt>s for equality.  This is a global function, not
   a member function.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>ostream&amp; <b>operator&lt;&lt;</b>(ostream&amp; os, rope x)</tt>
</TD>
<TD VAlign=top>
<tt>rope</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>New members</h3>
These members are not defined in the 
<A href="RandomAccessContainer.html">Random Access Container</A> requirements, but are specific to <tt>rope</tt>:
<Table border>
<TR>
<TH>
Function
</TH>
<TH>
Description
</TH>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const charT* s)</tt>
</TD>
<TD VAlign=top>
Constructs a <tt>rope</tt> from a C string.  The rope consists of the
   sequence of characters starting with <tt>*s</tt> up to, but not including,
   the first null character.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
Constructs a <tt>rope</tt> from an array of <tt>charT</tt>.  The rope consists of the
   characters in 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><b>rope</b>(charT c)</tt>
</TD>
<TD VAlign=top>
Constructs a rope consisting of the single character <tt>c</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>rope</b>(<A href="char_producer.html">char_producer</A>&lt;charT&gt;* cp, size_t n, bool destroy)</tt>
</TD>
<TD VAlign=top>
Constructs a rope of size <tt>n</tt>, whose characters are computed as
   needed by <tt>cp</tt>.  The object <tt>*cp</tt> must be valid as long as any
   reference to the resulting <tt>rope</tt>, or a <tt>rope</tt> derived from it, may
   be used.  If <tt>destroy</tt> is <tt>true</tt>, then <tt>delete cp</tt> will be executed
   automatically once <tt>cp</tt> is no longer needed.  Typically <tt>destroy</tt>
   will be <tt>true</tt> unless <tt>cp</tt> is a pointer to statically allocated
   storage.  It is rarely safe to allocate <tt>*cp</tt> on the stack.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>size_type <b>length</b>() const</tt>
</TD>
<TD VAlign=top>
Synonym for <tt>size</tt>
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_begin</b>()</tt>
</TD>
<TD VAlign=top>
Returns an <tt>iterator</tt> pointing to the beginning of the <tt>rope</tt>.
   This member function exists because mutable <tt>rope</tt> iterators are
   much more expensive than constant <tt>rope</tt> iterators.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_end</b>()</tt>
</TD>
<TD VAlign=top>
Returns an <tt>iterator</tt> pointing to the end of the <tt>rope</tt>.
   This member function exists because mutable <tt>rope</tt> iterators are
   much more expensive than constant <tt>rope</tt> iterators.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_rbegin</b>()</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reverse_iterator</tt> pointing to the beginning of the
   reversed <tt>rope</tt>.
   This member function exists because mutable <tt>rope</tt> iterators are
   much more expensive than constant <tt>rope</tt> iterators.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>mutable_rend</b>()</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reverse_iterator</tt> pointing to the end of the
   reversed <tt>rope</tt>.
   This member function exists because mutable <tt>rope</tt> iterators are
   much more expensive than constant <tt>rope</tt> iterators.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>reference <b>mutable_reference_at</b>(size_type n)</tt>
</TD>
<TD VAlign=top>
Returns a <tt>reference</tt> to the <tt>n</tt>th element.  This member function
   exists because mutable references to <tt>rope</tt> elements have fairly 
   high overhead.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>int <b>compare</b>(const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Three-way comparison, much like the function <tt>strcmp</tt> from the
   standard C library.  Returns a negative number if <tt>*this</tt> is
   lexicographically less than <tt>x</tt>, a positive number if <tt>*this</tt>
   is lexicographically greater than <tt>x</tt>, and zero if neither 
   <tt>rope</tt> is lexicographically less than the other.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Inserts the contents of the <tt>rope</tt> <tt>x</tt> immediately before the
   position <tt>p</tt>.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>iterator <b>insert</b>(const iterator&amp; p, const charT* s)</tt>
</TD>
<TD VAlign=top>
Inserts a C string immediately before the position <tt>p</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>iterator <b>insert</b>(const iterator&amp; p, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
Inserts an array of <tt>charT</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>void <b>insert</b>(size_t i, const rope&amp; x)</tt>
</TD>
<TD VAlign=top>
Inserts the contents of the <tt>rope</tt> x immediately before the <tt>i</tt>th
   element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, size_t n, charT c)</tt>
</TD>
<TD VAlign=top>
Inserts <tt>n</tt> copies of <tt>c</tt> immediately before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i, const charT* s)</tt>
</TD>
<TD VAlign=top>
Inserts a C string immediately before the <tt>i</tt>th element.  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>void <b>insert</b>(size_t i, const charT* s, size_t n)</tt>
</TD>
<TD VAlign=top>
Inserts an array of <tt>charT</tt> immediately before the <tt>i</tt>th element.  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>void <b>insert</b>(size_t i, charT c)</tt>
</TD>
<TD VAlign=top>
Inserts the character <tt>c</tt> immediately before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(size_t i)</tt>
</TD>
<TD VAlign=top>
Inserts the character <tt>charT()</tt> immediately before the <tt>i</tt>th element.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt>void <b>insert</b>(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 <b>insert</b>(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 <b>insert</b>(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 <b>erase</b>(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><b>append</b>(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><b>append</b>(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><b>append</b>(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><b>append</b>(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><b>append</b>()</tt>
</TD>
<TD VAlign=top>
Adds the character <tt>charT()</tt> to the end of the rope.
</TD>
</TR>
<TR>
<TD VAlign=top>
<tt><b>append</b>(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><b>append</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>replace</b>(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 <b>substr</b>(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 <b>substr</b>(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 <b>substr</b>(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 <b>substr</b>(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 <b>substr</b>(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 <b>copy</b>(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 <b>copy</b>(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* <b>c_str</b>() 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 <b>delete_c_str</b>()</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 <b>operator+</b>(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; <b>operator+=</b>(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 <b>operator+</b>(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; <b>operator+=</b>(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 <b>operator+</b>(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; <b>operator+=</b>(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; <b>operator&lt;&lt;</b>(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--> 
<HR SIZE="6">
<A href="http://www.sgi.com/"><IMG SRC="surf.gif" HEIGHT="54" WIDTH="54" 
        ALT="[Silicon Surf]"></A>
<A HREF="index.html"><IMG SRC="stl_home.gif" 
        HEIGHT="54" WIDTH="54" ALT="[STL Home]"></A>
<BR>
<FONT SIZE="-2">
<A href="http://www.sgi.com/Misc/sgi_info.html" TARGET="_top">Copyright &copy; 
1999 Silicon Graphics, Inc.</A> All Rights Reserved.</FONT>
<FONT SIZE="-3"><a href="http://www.sgi.com/Misc/external.list.html" TARGET="_top">TrademarkInformation</A>
</FONT>
<P>
</BODY>
</HTML>
stl-manual 3.30-13 / usr / share / doc / stl-manual / html / Rope.html
