Boost C++ Libraries Home Libraries People FAQ More

Next

Boost.StaticString

Krystian Stasiowski

Vinnie Falco

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)

Table of Contents

Reference
basic_static_string
std::hash< basic_static_string >
basic_string_view
operator==
operator!=
operator<
operator<=
operator>
operator>=
operator+
erase_if
swap
operator<<
to_static_string
to_static_wstring
hash_value
Index

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.

Motivation

A fixed capacity string is useful when:

Requirements

The library is usable in two different modes: standalone and Boost dependent. This library defaults to Boost dependent mode; standalone mode is opt-in through the use of a configuration macro.

When in Boost dependent mode, the library requires the use of at least C++11, in addition to Boost.Core, Boost.Utility, and Boost.ContainerHash. In standalone mode, C++17 is required but no libraries except for the standard library are needed.

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 if exceptions are enabled. All algorithms which throw exceptions provide the strong exception safety guarantee. This is intended to be a drop in replacement for std::string.

The API of static_string only diverges from std::string in few places, one of which is the addition of the subview function, for which this implementation returns a string view instead of static_string, and certain functions that will never throw are marked as noexcept, which diverges from those of std::string. The available overloads for static_string are identical to those of std::string.

Iterators

The iterator invalidation rules differ from those of std::string:

Optimizations

Depending on the character type and size used for a specialization of static_string, certain optimizations are used to reduce the size of the class type. Given the name of a specialization of the form basic_static_string<N, CharT, Traits>:

Configuration

Certain features can be enabled and disabled though defining configuration macros. The macros and the associated feature they control are:

Acknowledgments

Thanks to Agustín Bergé, Peter Dimov, Glen Fernandes, and Christian Mazakas for their constant feedback and guidance during the development of this library.

The development of this library is sponsored by The C++ Alliance.

Reference

Defined in namespace boost::static_strings:

basic_static_string


Next