folly::BasicFixedString

A class for holding up to N characters of type Char that is amenable to constexpr string manipulation. It is guaranteed to not perform any dynamic allocation.

Synopsis

Declared in <folly/FixedString.h>

template<
    class Char,
    std::size_t N>
class BasicFixedString;

Description

** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** *

BasicFixedString is a std::string work-alike that stores characters in an internal buffer. It has minor interface differences that make it easy to work with strings in a constexpr context.

Example:


constexpr auto hello = makeFixedString("hello");         // a FixedString<5>
constexpr auto world = makeFixedString("world");         // a FixedString<5>
constexpr auto hello_world = hello + ' ' + world + '!';  // a FixedString<12>
static_assert(hello_world == "hello world!", "neato!");

FixedString<N> is an alias for BasicFixedString<char, N>.

Constexpr and In-place Mutation

On a C++14 compiler, BasicFixedString supports the full std::string

interface as constexpr member functions. On a C++11 compiler, the mutating members are not constexpr, but non-mutating alternatives, which create a new string, can be used instead. For example, instead of this:


constexpr FixedString<10> replace_example_cpp14() {
  FixedString<10> test{"****"};
  test.replace(1, 2, "!!!!");
  return test; // returns "*!!!!*"
}

You might write this instead:


constexpr FixedString<10> replace_example_cpp11() {
  // GNU compilers have an extension that make it possible to create
  // FixedString objects with a `""_fs` user-defined literal.
  using namespace folly;
  return makeFixedString("****").creplace(1, 2, "!!!!"); // "*!!!!*"
}

User-defined Literals

Instead of using the folly::makeFixedString helper function, you can use a user-defined literal to make FixedString instances. The UDL feature of C++ has some limitations that make this less than ideal; you must tell the compiler roughly how many characters are in the string. The suffixes _fs4, _fs8, _fs16, _fs32, _fs64, and _fs128 exist to create instances of types FixedString<4>, FixedString<8>, etc. For example:


using namespace folly::string_literals;
constexpr auto hello = "hello"_fs8; // A FixedString<8> containing "hello"

See Error Handling below for what to expect when you try to exceed the

capacity of a FixedString by storing too many characters in it.

If your compiler supports GNU extensions, there is one additional suffix you

can use: _fs. This suffix always creates FixedString objects of exactly the right size. For example:


using namespace folly::string_literals;
// NOTE: Only works on compilers with GNU extensions enabled. Clang and
// gcc support this (-Wgnu-string-literal-operator-template):
constexpr auto hello = "hello"_fs; // A FixedString<5> containing "hello"

Error Handling:

The capacity of a BasicFixedString is set at compile time. When the user asks the string to exceed its capacity, one of three things will happen, depending on the context:

-# If the attempt is made while evaluating a constant expression, the

program will fail to compile. -# Otherwise, if the program is being run in debug mode, it will assert. -# Otherwise, the failed operation will throw a std::out_of_range exception.

This is also the case if an invalid offset is passed to any member function,

or if pop_back or cpop_back is called on an empty BasicFixedString.

Member functions documented as having preconditions will assert in Debug mode (!defined(NDEBUG)) on precondition failures. Those documented with Throws clauses will throw the specified exception on failure. Those with both a precondition and a Throws clause will assert in Debug and throw in Release mode.

Type Aliases

NameDescription
const_iterator A random-access iterator over the constant characters.
const_pointer A pointer to a constant character element.
const_reference A reference to a constant character element.
const_reverse_iterator A reverse iterator over the constant characters.
difference_type The signed integer type used for iterator differences.
iterator A random-access iterator over the characters.
pointer A pointer to a character element.
reference A reference to a character element.
reverse_iterator A reverse iterator over the characters.
size_type The unsigned integer type used for sizes and indices.

Member Functions

NameDescription
BasicFixedString [constructor]Constructors
operator= Assignment operators
append append overloads
assign assign overloads
at Accesses the character at a given index with bounds checking.
back Accesses the last character of the string.
begin ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
c_str ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
cappend cappend overloads
cbegin ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
cend ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
cerase cerase overloads
clear Clears the contents of this string.
compare compare overloads
copy copy overloads
cpop_back Returns a new string with the first size()-1 characters from this string.
cpush_back Returns a new string with a single character appended to the end.
crbegin Returns a const reverse iterator to the beginning of the reversed string.
crend Returns a const reverse iterator to the end of the reversed string.
creplace creplace overloads
data ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Return a pointer to a range of size()+1 characters, the last of which is Char(0).
empty Checks whether the string is empty.
end ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
erase erase overloads
find find overloads
find_first_not_of find_first_not_of overloads
find_first_of find_first_of overloads
find_last_not_of find_last_not_of overloads
find_last_of find_last_of overloads
front Accesses the first character of the string.
length Returns the number of characters in the string.
operator+= Addition assignment operators
operator[] Accesses the character at a given index.
pop_back Removes the last character from the string.
push_back Appends a single character to the end of the string.
rbegin ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Returns a reverse iterator to the first character of the reversed string. It corresponds to the last + 1 character of the non-reversed string.
rend ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Returns a reverse iterator to the last + 1 character of the reversed string. It corresponds to the first character of the non-reversed string.
replace replace overloads
resize resize overloads
rfind rfind overloads
size Returns the number of characters in the string.
substr substr overloads
swap ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Swap the contents of this string with that.
toRange ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Conversion to folly::Range
toStdString Converts this string to a std::basic_string<Char>.
operator std::basic_string<Char> ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Conversion to std::basic_string<Char>
operator std::basic_string_view<Char> ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Conversion to std::basic_string_view<Char>

Static Member Functions

NameDescription
capacity Returns the maximum number of characters the string can hold.
max_size Returns the maximum number of characters the string can hold.

Using Declarations

NameDescription
npos The sentinel value returned by search functions when no match is found.

Friends

NameDescription
folly::operator+Addition operator
folly::operator+Addition operator
folly::operator+Addition operator
folly::operator+** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Asymmetric concatenation
folly::operator<=>Three-way comparison operator
folly::operator<=>Three-way comparison operator
folly::operator<=>Three-way comparison operator
folly::operator<=>Orders a BasicFixedString against a null-terminated string or a character range.
folly::operator!=Inequality operator
folly::operator!=Inequality operator
folly::operator!=Inequality operator
folly::operator!=Compares a BasicFixedString against a null-terminated string or a character range for inequality.
folly::operator==Equality operator
folly::operator==Equality operator
folly::operator==Equality operator
folly::operator==** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Asymmetric relational operators
folly::BasicFixedStringA class for holding up to N characters of type Char that is amenable to constexpr string manipulation. It is guaranteed to not perform any dynamic allocation.

Non-Member Functions

NameDescription
makeFixedString** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Construct a BasicFixedString object from a null-terminated array of characters. The capacity and size of the string will be equal to one less than the size of the array.
operator!=Compares two BasicFixedString objects for inequality.
operator""_fs** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** * User-defined literals for creating FixedString objects from string literals on the compilers that support it.
operator+** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Symmetric concatenation
operator<=>Orders two BasicFixedString objects.
operator==** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Symmetric relational operators
swap** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** Swap function

Template Parameters

NameDescription
CharThe character type. Must be a scalar type.
NThe capacity and max size of string instances of this type.