ceph/src/boost/libs/mpl/doc/src/refmanual/string.rst

   1 .. Sequences/Classes//string |100
   2
   3 string
   4 ======
   5
   6 Description
   7 -----------
   8
   9 ``string`` is a |variadic|, `bidirectional`__, `extensible`__ |Integral Sequence Wrapper| of
  10 characters that supports amortized constant-time insertion and removal of elements at both ends,
  11 and linear-time insertion and removal of elements in the middle. The parameters to ``string``
  12 are multi-character literals, giving a somewhat readable syntax for compile-time strings.
  13 ``string`` can also be an argument to the ``c_str`` metafunction, which generates a
  14 null-terminated character array that facilitates interoperability with runtime string
  15 processing routines.
  16
  17 __ `Bidirectional Sequence`_
  18 __ `Extensible Sequence`_
  19
  20 Header
  21 ------
  22
  23 +-------------------+-------------------------------------------------------+
  24 | Sequence form     | Header                                                |
  25 +===================+=======================================================+
  26 | Variadic          | ``#include <boost/mpl/string.hpp>``                   |
  27 +-------------------+-------------------------------------------------------+
  28
  29 Model of
  30 --------
  31
  32 * |Integral Sequence Wrapper|
  33 * |Variadic Sequence|
  34 * |Bidirectional Sequence|
  35 * |Extensible Sequence|
  36 * |Back Extensible Sequence|
  37 * |Front Extensible Sequence|
  38
  39 Expression semantics
  40 --------------------
  41
  42 In the following table, ``s`` is an instance of ``string``, ``pos`` and ``last`` are iterators
  43 into ``s``, ``r`` is a |Forward Sequence| of characters, ``n`` and ``x`` are |Integral Constant|\ s,
  44 and |c1...cn| are arbitrary (multi-)characters.
  45
  46 +---------------------------------------+-----------------------------------------------------------+
  47 | Expression                            | Semantics                                                 |
  48 +=======================================+===========================================================+
  49 | .. parsed-literal::                   | ``string`` of characters |c1...cn|; see                   |
  50 |                                       | |Variadic Sequence|.                                      |
  51 |    string<|c1...cn|>                  |                                                           |
  52 +---------------------------------------+-----------------------------------------------------------+
  53 | .. parsed-literal::                   | Identical to ``string<``\ |c1...cn|\ ``>``;               |
  54 |                                       | see |Variadic Sequence|.                                  |
  55 |    string<|c1...cn|>::type            |                                                           |
  56 +---------------------------------------+-----------------------------------------------------------+
  57 | ``begin<s>::type``                    | An iterator pointing to the beginning of ``s``;           |
  58 |                                       | see |Bidirectional Sequence|.                             |
  59 +---------------------------------------+-----------------------------------------------------------+
  60 | ``end<s>::type``                      | An iterator pointing to the end of ``s``;                 |
  61 |                                       | see |Bidirectional Sequence|.                             |
  62 +---------------------------------------+-----------------------------------------------------------+
  63 | ``size<s>::type``                     | The size of ``s``; see |Bidirectional Sequence|.          |
  64 +---------------------------------------+-----------------------------------------------------------+
  65 | ``empty<s>::type``                    | |true if and only if| the sequence is empty;              |
  66 |                                       | see |Bidirectional Sequence|.                             |
  67 +---------------------------------------+-----------------------------------------------------------+
  68 | ``front<s>::type``                    | The first element in ``s``; see                           |
  69 |                                       | |Bidirectional Sequence|.                                 |
  70 +---------------------------------------+-----------------------------------------------------------+
  71 | ``back<s>::type``                     | The last element in ``s``; see                            |
  72 |                                       | |Bidirectional Sequence|.                                 |
  73 +---------------------------------------+-----------------------------------------------------------+
  74 | ``insert<s,pos,x>::type``             | A new ``string`` of following elements:                   |
  75 |                                       | [``begin<s>::type``, ``pos``), ``x``,                     |
  76 |                                       | [``pos``, ``end<s>::type``); see |Extensible Sequence|.   |
  77 +---------------------------------------+-----------------------------------------------------------+
  78 | ``insert_range<s,pos,r>::type``       | A new ``string`` of following elements:                   |
  79 |                                       | [``begin<s>::type``, ``pos``),                            |
  80 |                                       | [``begin<r>::type``, ``end<r>::type``)                    |
  81 |                                       | [``pos``, ``end<s>::type``); see |Extensible Sequence|.   |
  82 +---------------------------------------+-----------------------------------------------------------+
  83 | ``erase<s,pos>::type``                | A new ``string`` of following elements:                   |
  84 |                                       | [``begin<s>::type``, ``pos``),                            |
  85 |                                       | [``next<pos>::type``, ``end<s>::type``); see              |
  86 |                                       | |Extensible Sequence|.                                    |
  87 +---------------------------------------+-----------------------------------------------------------+
  88 | ``erase<s,pos,last>::type``           | A new ``string`` of following elements:                   |
  89 |                                       | [``begin<s>::type``, ``pos``),                            |
  90 |                                       | [``last``, ``end<s>::type``); see |Extensible Sequence|.  |
  91 +---------------------------------------+-----------------------------------------------------------+
  92 | ``clear<s>::type``                    | An empty ``string``; see |Extensible Sequence|.           |
  93 +---------------------------------------+-----------------------------------------------------------+
  94 | ``push_back<s,x>::type``              | A new ``string`` of following elements:                   |
  95 |                                       | |begin/end<s>|, ``x``;                                    |
  96 |                                       | see |Back Extensible Sequence|.                           |
  97 +---------------------------------------+-----------------------------------------------------------+
  98 | ``pop_back<s>::type``                 | A new ``string`` of following elements:                   |
  99 |                                       | [``begin<s>::type``, ``prior< end<s>::type >::type``);    |
 100 |                                       | see |Back Extensible Sequence|.                           |
 101 +---------------------------------------+-----------------------------------------------------------+
 102 | ``push_front<s,x>::type``             | A new ``string`` of following elements:                   |
 103 |                                       | |begin/end<s>|, ``x``; see |Front Extensible Sequence|.   |
 104 +---------------------------------------+-----------------------------------------------------------+
 105 | ``pop_front<s>::type``                | A new ``string`` of following elements:                   |
 106 |                                       | [``next< begin<s>::type >::type``, ``end<s>::type``);     |
 107 |                                       | see |Front Extensible Sequence|.                          |
 108 +---------------------------------------+-----------------------------------------------------------+
 109 | ``c_str<s>::value``                   | A null-terminated byte string such that                   |
 110 |                                       | ``c_str<s>::value[``\ *n*\ ``]`` is equal to the *n*\ -th |
 111 |                                       | character in ``s``, and                                   |
 112 |                                       | ``c_str<s>::value[size<s>::type::value]`` is ``'\0'``.    |
 113 +---------------------------------------+-----------------------------------------------------------+
 114
 115
 116 Example
 117 -------
 118
 119 .. parsed-literal::
 120
 121     typedef mpl::string<'hell','o wo','rld'> hello;
 122     typedef mpl::push_back<hello, mpl::char_<'!'> >::type hello2;
 123
 124     BOOST_ASSERT(0 == std::strcmp(mpl::c_str<hello2>::value, "hello world!"));
 125
 126
 127 See also
 128 --------
 129
 130 |Sequences|, |Variadic Sequence|, |Bidirectional Sequence|, |Extensible Sequence|, |Integral Sequence Wrapper|, |char_|, |c_str|
 131
 132
 133 .. copyright:: Copyright ©  2009 Eric Niebler
 134    Distributed under the Boost Software License, Version 1.0. (See accompanying
 135    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)