[/
    Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/vinniefalco/fixed_string
]

[library Boost.FixedString
    [id json]
    [quickbook 1.6]
    [copyright 2016 - 2019 Vinnie Falco]
    [purpose String Library]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt])
    ]
    [authors [Falco, Vinnie]]
    [category template]
    [category generic]
]

[template mdash[] '''— ''']
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']

[template path_link[path name] '''<ulink url="../../'''[path]'''">'''[name]'''</ulink>''']
[template include_file[path][^<'''<ulink url="../../../../'''[path]'''">'''[path]'''</ulink>'''>]]
[template issue[n] '''<ulink url="https://github.com/boostorg/beast/issues/'''[n]'''">#'''[n]'''</ulink>''']

[/-----------------------------------------------------------------------------]

[section Introduction]

This library provides a dynamically resizable string of characters with
compile-time fixed capacity and contiguous embedded storage in which the
characters are placed within the string object itself. Its API closely
resembles that of `std::string`

[endsect]

[/-----------------------------------------------------------------------------]

[section Motivation]

A fixed capacity string is useful when:

* Memory allocation is not possible, e.g., embedded environments without a free
  store, where only a stack and the static memory segment are available.
* Memory allocation imposes an unacceptable performance penalty.
  e.g., with respect to latency.
* Allocation of objects with complex lifetimes in the static-memory
  segment is required.
* A dynamically-resizable string is required within `constexpr` functions.
* The storage location of the static_vector elements is required to be
  within the string object itself (e.g. to support memcopy for serialization
  purposes).

[endsect]

[/-----------------------------------------------------------------------------]

[section Design]

The over-arching design goal is to resemble the interface and behavior of
`std::string` as much as possible. When any operation would exceed the
maximum allowed size of the string, `std::length_error` is thrown. All
algorithms which throw exceptions provide the strong exception safety
guarantee.

[endsect]

[/-----------------------------------------------------------------------------]

[section Iterators]

The iterator invalidation rules are different than those for `std::string`,
since:

* Moving a string invalidates all iterators
* Swapping two strings invalidates all iterators

[endsect]

[/-----------------------------------------------------------------------------]

[section:ref Reference]
[include reference.qbk]
[endsect]

[/-----------------------------------------------------------------------------]

[xinclude index.xml]