[ceph.git] / ceph / src / boost / libs / mpl / doc / src / refmanual / string.rst

.. Sequences/Classes//string |100

string
======

Description
-----------

``string`` is a |variadic|, `bidirectional`__, `extensible`__ |Integral Sequence Wrapper| of
characters that supports amortized constant-time insertion and removal of elements at both ends,
and linear-time insertion and removal of elements in the middle. The parameters to ``string``
are multi-character literals, giving a somewhat readable syntax for compile-time strings.
``string`` can also be an argument to the ``c_str`` metafunction, which generates a
null-terminated character array that facilitates interoperability with runtime string
processing routines.

__ `Bidirectional Sequence`_
__ `Extensible Sequence`_

Header
------

+-------------------+-------------------------------------------------------+
| Sequence form     | Header                                                |
+===================+=======================================================+
| Variadic          | ``#include <boost/mpl/string.hpp>``                   |
+-------------------+-------------------------------------------------------+

Model of
--------

* |Integral Sequence Wrapper|
* |Variadic Sequence|
* |Bidirectional Sequence|
* |Extensible Sequence|
* |Back Extensible Sequence|
* |Front Extensible Sequence|

Expression semantics
--------------------

In the following table, ``s`` is an instance of ``string``, ``pos`` and ``last`` are iterators 
into ``s``, ``r`` is a |Forward Sequence| of characters, ``n`` and ``x`` are |Integral Constant|\ s,
and |c1...cn| are arbitrary (multi-)characters.

+---------------------------------------+-----------------------------------------------------------+
| Expression                            | Semantics                                                 |
+=======================================+===========================================================+
| .. parsed-literal::                   | ``string`` of characters |c1...cn|; see                   |
|                                       | |Variadic Sequence|.                                      |
|    string<|c1...cn|>                  |                                                           |
+---------------------------------------+-----------------------------------------------------------+
| .. parsed-literal::                   | Identical to ``string<``\ |c1...cn|\ ``>``;               |
|                                       | see |Variadic Sequence|.                                  |
|    string<|c1...cn|>::type            |                                                           |
+---------------------------------------+-----------------------------------------------------------+
| ``begin<s>::type``                    | An iterator pointing to the beginning of ``s``;           |
|                                       | see |Bidirectional Sequence|.                             |
+---------------------------------------+-----------------------------------------------------------+
| ``end<s>::type``                      | An iterator pointing to the end of ``s``;                 |
|                                       | see |Bidirectional Sequence|.                             |
+---------------------------------------+-----------------------------------------------------------+
| ``size<s>::type``                     | The size of ``s``; see |Bidirectional Sequence|.          |
+---------------------------------------+-----------------------------------------------------------+
| ``empty<s>::type``                    | |true if and only if| the sequence is empty;              |
|                                       | see |Bidirectional Sequence|.                             |
+---------------------------------------+-----------------------------------------------------------+
| ``front<s>::type``                    | The first element in ``s``; see                           |
|                                       | |Bidirectional Sequence|.                                 |
+---------------------------------------+-----------------------------------------------------------+
| ``back<s>::type``                     | The last element in ``s``; see                            |
|                                       | |Bidirectional Sequence|.                                 |
+---------------------------------------+-----------------------------------------------------------+
| ``insert<s,pos,x>::type``             | A new ``string`` of following elements:                   |
|                                       | [``begin<s>::type``, ``pos``), ``x``,                     |
|                                       | [``pos``, ``end<s>::type``); see |Extensible Sequence|.   |
+---------------------------------------+-----------------------------------------------------------+
| ``insert_range<s,pos,r>::type``       | A new ``string`` of following elements:                   |
|                                       | [``begin<s>::type``, ``pos``),                            |
|                                       | [``begin<r>::type``, ``end<r>::type``)                    |
|                                       | [``pos``, ``end<s>::type``); see |Extensible Sequence|.   |
+---------------------------------------+-----------------------------------------------------------+
| ``erase<s,pos>::type``                | A new ``string`` of following elements:                   |
|                                       | [``begin<s>::type``, ``pos``),                            |
|                                       | [``next<pos>::type``, ``end<s>::type``); see              |
|                                       | |Extensible Sequence|.                                    |
+---------------------------------------+-----------------------------------------------------------+
| ``erase<s,pos,last>::type``           | A new ``string`` of following elements:                   |
|                                       | [``begin<s>::type``, ``pos``),                            |
|                                       | [``last``, ``end<s>::type``); see |Extensible Sequence|.  |
+---------------------------------------+-----------------------------------------------------------+
| ``clear<s>::type``                    | An empty ``string``; see |Extensible Sequence|.           |
+---------------------------------------+-----------------------------------------------------------+
| ``push_back<s,x>::type``              | A new ``string`` of following elements:                   | 
|                                       | |begin/end<s>|, ``x``;                                    |
|                                       | see |Back Extensible Sequence|.                           |
+---------------------------------------+-----------------------------------------------------------+
| ``pop_back<s>::type``                 | A new ``string`` of following elements:                   |
|                                       | [``begin<s>::type``, ``prior< end<s>::type >::type``);    |
|                                       | see |Back Extensible Sequence|.                           |
+---------------------------------------+-----------------------------------------------------------+
| ``push_front<s,x>::type``             | A new ``string`` of following elements:                   |
|                                       | |begin/end<s>|, ``x``; see |Front Extensible Sequence|.   |
+---------------------------------------+-----------------------------------------------------------+
| ``pop_front<s>::type``                | A new ``string`` of following elements:                   |
|                                       | [``next< begin<s>::type >::type``, ``end<s>::type``);     |
|                                       | see |Front Extensible Sequence|.                          |
+---------------------------------------+-----------------------------------------------------------+
| ``c_str<s>::value``                   | A null-terminated byte string such that                   |
|                                       | ``c_str<s>::value[``\ *n*\ ``]`` is equal to the *n*\ -th |
|                                       | character in ``s``, and                                   |
|                                       | ``c_str<s>::value[size<s>::type::value]`` is ``'\0'``.    |
+---------------------------------------+-----------------------------------------------------------+


Example
-------

.. parsed-literal::
   
    typedef mpl::string<'hell','o wo','rld'> hello;
    typedef mpl::push_back<hello, mpl::char_<'!'> >::type hello2;

    BOOST_ASSERT(0 == std::strcmp(mpl::c_str<hello2>::value, "hello world!"));


See also
--------

|Sequences|, |Variadic Sequence|, |Bidirectional Sequence|, |Extensible Sequence|, |Integral Sequence Wrapper|, |char_|, |c_str|
Commit	Line	Data
7c673cae FG	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