Loading...
Searching...
No Matches
seqan3::small_string< capacity_ > Class Template Reference
Utility » Container

Implements a small string that can be used for compile time computations. More...

`#include <seqan3/utility/container/small_string.hpp>`

Inheritance diagram for seqan3::small_string< capacity_ >:
[legend]

## Public Types

Associated types
using | const_iterator
| The const_iterator type.
using | const_reference
| The const_reference type.
using | difference_type
| The difference_type type.
using | iterator
| The iterator type.
using | reference
| The reference type.
using | size_type
| The size_type type.
using | value_type
| The value_type type.
Public Types inherited from seqan3::small_vector< char, capacity_+1 >
using | value_type
| The value_type type.
using | reference
| The reference type.
using | const_reference
| The const_reference type.
using | iterator
| The iterator type.
using | const_iterator
| The const_iterator type.
using | difference_type
| The difference_type type.
using | size_type
| The size_type type.

## Public Member Functions

Constructors, destructor and assignment
template<size_t N>
constexpr | small_string (char const (&_lit)[N]) noexcept
| Construction from literal.
constexpr | small_string (char const c) noexcept
| Construction from char.
template<size_t N>
constexpr small_string & | operator= (char const (&_lit)[N]) noexcept
| Assign from literal.
template<size_t N>
constexpr void | assign (char const (&_lit)[N]) noexcept
| Assign from literal.
template<std::forward_iterator begin_it_type, typename end_it_type> requires std::sentinel_for<end_it_type, begin_it_type> && std::constructible_from<value_type, std::iter_reference_t<begin_it_type>>
constexpr void | assign (begin_it_type begin_it, end_it_type end_it) noexcept
| Assign from pair of iterators.
constexpr void | assign (std::initializer_list< value_type > ilist) noexcept(is_noexcept)
| Inherit the parent class member function assign.
constexpr void | assign (size_type const count, value_type const value) noexcept(is_noexcept)
| Inherit the parent class member function assign.
constexpr void | assign (other_range_t &&range) noexcept(is_noexcept)
| Inherit the parent class member function assign.
Modifiers
constexpr void | clear () noexcept
| Removes all elements from the container.
constexpr void | push_back (char const value) noexcept
| Appends the given element value to the end of the container.
constexpr void | pop_back () noexcept
| Removes the last element of the container.
constexpr void | resize (size_type const count) noexcept
| Resizes the container to contain count elements.
constexpr void | resize (size_type const count, char const value) noexcept
| Resizes the container to contain count elements.
constexpr small_string & | erase (size_type index=0, size_type count=max_size()) noexcept
| Removes specified elements from the container.
Conversion
std::string | str () const
| Returns the content represented as std::string.
constexpr char const * | c_str () const noexcept
| Returns the content represented as 0-terminated c-style string.
| operator std::string () const
| Implicit conversion to std::string which delegates to seqan3::small_string::str().
constexpr | operator std::string_view () const noexcept
| Implicit conversion to std::string_view.
Public Member Functions inherited from seqan3::small_vector< char, capacity_+1 >
constexpr | small_vector () noexcept=default
| Defaulted.
constexpr | small_vector (small_vector const &) noexcept=default
| Defaulted.
constexpr | small_vector (small_vector &&) noexcept=default
| Defaulted.
constexpr small_vector & | operator= (small_vector const &) noexcept=default
| Defaulted.
constexpr small_vector & | operator= (small_vector &&) noexcept=default
| Defaulted.
| ~small_vector () noexcept=default
| Defaulted.
constexpr | small_vector (std::array< value_type, capacity_ > const &array) noexcept(is_noexcept)
| Construct from an (smaller or equally sized) array over the same value type.
constexpr | small_vector (value_type const(&array)[capacity2]) noexcept(is_noexcept)
| Construct from a (smaller or equally sized) built in array over the same value type.
constexpr | small_vector (other_value_type... args) noexcept(is_noexcept)
| Construct from a list of values of value_type.
constexpr | small_vector (begin_it_type begin_it, end_it_type end_it) noexcept(is_noexcept)
| Construct from two iterators.
constexpr | small_vector (other_range_t &&range) noexcept(is_noexcept)
| Construct from a different range.
constexpr | small_vector (size_type n, value_type value) noexcept(is_noexcept)
| Construct with n times value.
constexpr small_vector & | operator= (std::initializer_list< value_type > ilist) noexcept(is_noexcept)
| Assign from std::initializer_list.
constexpr void | assign (std::initializer_list< value_type > ilist) noexcept(is_noexcept)
| Assign from std::initializer_list.
constexpr void | assign (size_type const count, value_type const value) noexcept(is_noexcept)
| Assign with count times value.
constexpr void | assign (other_range_t &&range) noexcept(is_noexcept)
| Assign from a different range.
constexpr void | assign (begin_it_type begin_it, end_it_type end_it) noexcept(is_noexcept)
| Assign from pair of iterators.
constexpr iterator | begin () noexcept
| Returns the begin to the string.
constexpr const_iterator | begin () const noexcept
| Returns the begin to the string.
constexpr const_iterator | cbegin () const noexcept
| Returns the begin to the string.
constexpr iterator | end () noexcept
| Returns iterator past the end of the vector.
constexpr const_iterator | end () const noexcept
| Returns iterator past the end of the vector.
constexpr const_iterator | cend () const noexcept
| Returns iterator past the end of the vector.
reference | at (size_type const i)
| Return the i-th element.
const_reference | at (size_type const i) const
| Return the i-th element.
constexpr reference | operator[] (size_type const i) noexcept
| Return the i-th element.
constexpr const_reference | operator[] (size_type const i) const noexcept
| Return the i-th element.
constexpr reference | front () noexcept
| Return the first element. Calling front on an empty container is undefined.
constexpr const_reference | front () const noexcept
| Return the first element. Calling front on an empty container is undefined.
constexpr reference | back () noexcept
| Return the last element.
constexpr const_reference | back () const noexcept
| Return the last element.
constexpr value_type * | data () noexcept
| Direct access to the underlying array.
constexpr value_type const * | data () const noexcept
| Direct access to the underlying array.
constexpr bool | empty () const noexcept
| Checks whether the container is empty.
constexpr size_type | size () const noexcept
| Returns the number of elements in the container, i.e. std::distance(begin(), end()).
constexpr size_type | max_size () const noexcept
| Returns the maximum number of elements the container is able to hold and resolves to capacity_.
constexpr size_type | capacity () const noexcept
| Returns the number of elements that the container is able to hold and resolves to capacity_.
constexpr void | reserve (size_type) const noexcept
| Since the capacity is fixed on compile time, this is a no-op.
constexpr void | shrink_to_fit () const noexcept
| Since the capacity is fixed on compile time, this is a no-op.
constexpr void | clear () noexcept
| Removes all elements from the container.
constexpr iterator | insert (const_iterator pos, value_type const value) noexcept(is_noexcept)
| Inserts value before position in the container.
constexpr iterator | insert (const_iterator pos, size_type const count, value_type const value) noexcept(is_noexcept)
| Inserts count copies of value before position in the container.
constexpr iterator | insert (const_iterator pos, begin_it_type begin_it, end_it_type end_it) noexcept(is_noexcept)
| Inserts elements from range [begin_it, end_it) before position in the container.
constexpr iterator | insert (const_iterator pos, std::initializer_list< value_type > const &ilist) noexcept(is_noexcept)
| Inserts elements from initializer list before position in the container.
constexpr iterator | erase (const_iterator begin_it, const_iterator end_it) noexcept
| Removes specified elements from the container.
constexpr iterator | erase (const_iterator pos) noexcept
| Removes specified elements from the container.
constexpr void | push_back (value_type const value) noexcept
| Appends the given element value to the end of the container.
constexpr void | pop_back () noexcept
| Removes the last element of the container.
constexpr void | resize (size_type const count) noexcept
| Resizes the container to contain count elements.
constexpr void | resize (size_type const count, value_type const value) noexcept
| Resizes the container to contain count elements.
constexpr void | swap (small_vector &rhs) noexcept(is_noexcept)
| Swap contents with another instance.
constexpr void | swap (small_vector &&rhs) noexcept(is_noexcept)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## Static Public Member Functions

Capacity
static constexpr size_type | max_size () noexcept
| Returns the maximal size which equals the capacity.
static constexpr size_type | capacity () noexcept
| Returns the maximal capacity.

## Friends

Concatenation
template<size_t capacity2>
constexpr friend small_string< capacity_+capacity2 > | operator+ (small_string const &lhs, small_string< capacity2 > const &rhs) noexcept
| Concatenates two small_strings by returning a new small_string.
Input/output
std::ostream & | operator<< (std::ostream &os, small_string const &str)
| Formatted output for the seqan3::small_string.
std::istream & | operator>> (std::istream &is, small_string &str)
| Formatted input for the seqan3::small_string.
Friends inherited from seqan3::small_vector< char, capacity_+1 >

## Related Symbols

(Note that these are not member symbols.)
Deduction guides
template<size_t N>
| small_string (char const(&)[N]) -> small_string< N - 1 >
| Deduces small_string from string literals.
template<size_t N>
| small_string (std::array< char, N > const &) -> small_string< N >
| Deduces small_string from std::array of type char.
| small_string (char const) -> small_string< 1 >
| Deduces small_string from char.

## Detailed Description

template<size_t capacity_>
class seqan3::small_string< capacity_ >

Implements a small string that can be used for compile time computations.

Template Parameters

  capacity_ | The capacity of the small string.

This class provides a string type for small strings and compile-time contexts. It has fixed capacity, but variable size within the capacity. It is always allocated on the stack and most of it's members are constexpr-qualified. The underlying data can be exposed as a null-terminated c-style string (without copying) and conversion operators to std::string are provided (this involves copying).

### Implementation notes

Internally the string stores a null-terminated array of size capacity_ + 1 and the size of the string as a member. The smallest possible type is used for storage of the size. For example, small_string<30> uses 32bytes of memory (one byte extra for the null-terminator and one byte to save the size).

Usage:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/container/small_string.hpp>
int main()
{
constexpr seqan3::small_string sm{"hello"}; // construct from string literal at compile time!
static_assert(sm[0] == 'h'); // This way I can also test it at compile-time
seqan3::debug_stream << sm.size() << '\n'; // prints 5! (the null character is only stored internally)
// conversion to a normal string:
std::string sm_string{sm.str()};
// access data directly with a pointer to the underlying zero-terminated array:
char const * sm_cstr{sm.c_str()};
seqan3::debug_stream << sm << sm_string << sm_cstr << '\n'; // prints "hellohellohello"
}
std::string
seqan3::small_string
Implements a small string that can be used for compile time computations.
Definition small_string.hpp:43
seqan3::small_string::str
std::string str() const
Returns the content represented as std::string.
Definition small_string.hpp:325
seqan3::small_string::c_str
constexpr char const * c_str() const noexcept
Returns the content represented as 0-terminated c-style string.
Definition small_string.hpp:344
seqan3::small_vector::size
constexpr size_type size() const noexcept
Returns the number of elements in the container, i.e. std::distance(begin(), end()).
Definition small_vector.hpp:571
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:38
small_string.hpp
A constexpr string implementation to manipulate string literals at compile time.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## Member Typedef Documentation

## const_iterator

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::const_iterator

The const_iterator type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## const_reference

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::const_reference

The const_reference type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## difference_type

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::difference_type

The difference_type type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## iterator

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::iterator

The iterator type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## reference

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::reference

The reference type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## size_type

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::size_type

The size_type type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## value_type

template<size_t capacity_>

using seqan3::small_vector< char, capacity_ >::value_type

The value_type type.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## Constructor & Destructor Documentation

## small_string() [1/2]

template<size_t capacity_>
template<size_t N>

seqan3::small_string< capacity_ >::small_string | ( | char const (&) | _lit[N] | ) |

inline constexpr noexcept

Construction from literal.

Parameters

  _lit | The literal to construct the string for.

The char literal is expected to be null-terminated (asserted in debug-mode). If it is not, the last character will be lost when copying to the instance of small_string.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## small_string() [2/2]

template<size_t capacity_>

seqan3::small_string< capacity_ >::small_string | ( | char const | c | ) |

inline explicit constexpr noexcept

Construction from char.

Parameters

  c | The character to construct the small_string for.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## Member Function Documentation

## assign() [1/2]

template<size_t capacity_>
template<std::forward_iterator begin_it_type, typename end_it_type>
requires std::sentinel_for<end_it_type, begin_it_type> && std::constructible_from<value_type, std::iter_reference_t<begin_it_type>>

void seqan3::small_string< capacity_ >::assign | ( | begin_it_type | begin_it,
|  | end_it_type | end_it )

inline constexpr noexcept

Assign from pair of iterators.

Template Parameters

  begin_it_type | Must satisfy std::forward_iterator and the value_type must be constructible from the reference type of begin_it_type.
  end_it_type | Must satisfy std::sentinel_for.

Parameters

  [in] | begin_it | Begin of range to construct/assign from.
  [in] | end_it | End of range to construct/assign from.

### Complexity

Linear in the distance between begin_it and end_it.

### Exceptions

No-throw guarantee if value_type is std::is_nothrow_copy_constructible.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## assign() [2/2]

template<size_t capacity_>
template<size_t N>

void seqan3::small_string< capacity_ >::assign | ( | char const (&) | _lit[N] | ) |

inline constexpr noexcept

Assign from literal.

Parameters

  _lit | The literal to assign the string from.

The char literal is expected to be null-terminated (asserted in debug-mode). If it is not, the last character will be lost when copying to the instance of small_string.

### Complexity

Linear in the size of _lit.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## c_str()

template<size_t capacity_>

char const * seqan3::small_string< capacity_ >::c_str | ( |  | ) | const

inline constexpr noexcept

Returns the content represented as 0-terminated c-style string.

Returns
  char const * The stored string.

### Exceptions

No-throw guarantee.

### Complexity

Constant.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## capacity()

template<size_t capacity_>

constexpr size_type seqan3::small_string< capacity_ >::capacity | ( |  | ) |

inline static constexpr noexcept

Returns the maximal capacity.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## clear()

template<size_t capacity_>

void seqan3::small_string< capacity_ >::clear | ( |  | ) |

inline constexpr noexcept

Removes all elements from the container.

### Complexity

Constant.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## erase()

template<size_t capacity_>

small_string & seqan3::small_string< capacity_ >::erase | ( | size_type | index = 0,
|  | size_type | count = max_size() )

inline constexpr noexcept

Removes specified elements from the container.

Parameters

  index | Remove the elements starting at index. Defaults to 0.
  count | The number of elements to remove. Defaults to max_size().

Returns
  *this

Invalidates iterators and references at or after the point of the erase, including the end() iterator.

The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferencable) cannot be used as a value for pos.

### Complexity

Linear in size().

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## max_size()

template<size_t capacity_>

constexpr size_type seqan3::small_string< capacity_ >::max_size | ( |  | ) |

inline static constexpr noexcept

Returns the maximal size which equals the capacity.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## operator std::string()

template<size_t capacity_>

seqan3::small_string< capacity_ >::operator std::string | ( |  | ) | const

inline

Implicit conversion to std::string which delegates to seqan3::small_string::str().

### Exceptions

Strong exception guarantee. No data is modified.

### Complexity

Linear in the size of the string.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## operator std::string_view()

template<size_t capacity_>

seqan3::small_string< capacity_ >::operator std::string_view | ( |  | ) | const

inline constexpr noexcept

Implicit conversion to std::string_view.

It is the programmer's responsibility to ensure that the resulting string view does not outlive the string.

### Exceptions

Strong exception guarantee. No data is modified.

### Complexity

Constant.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

See also
  https://en.cppreference.com/w/cpp/string/basic_string/operator_basic_string_view

## operator=()

template<size_t capacity_>
template<size_t N>

small_string & seqan3::small_string< capacity_ >::operator= | ( | char const (&) | _lit[N] | ) |

inline constexpr noexcept

Assign from literal.

Parameters

  _lit | The literal to assign the string from.

The char literal is expected to be null-terminated (asserted in debug-mode). If it is not, the last character will be lost when copying to the instance of small_string.

### Complexity

Linear in the size of _lit.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## pop_back()

template<size_t capacity_>

void seqan3::small_string< capacity_ >::pop_back | ( |  | ) |

inline constexpr noexcept

Removes the last element of the container.

Calling pop_back() on an empty container is undefined. In debug mode an assertion will be thrown.

No iterators or references except for back() and end() are invalidated.

### Complexity

Constant.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## push_back()

template<size_t capacity_>

void seqan3::small_string< capacity_ >::push_back | ( | char const | value | ) |

inline constexpr noexcept

Appends the given element value to the end of the container.

Parameters

  value | The value to append.

If the new size() is greater than capacity() this is undefined behaviour.

### Complexity

Constant.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## resize() [1/2]

template<size_t capacity_>

void seqan3::small_string< capacity_ >::resize | ( | size_type const | count | ) |

inline constexpr noexcept

Resizes the container to contain count elements.

Parameters

  [in] | count | The new size.

If count is greater than capacity this is undefined behaviour.

### Complexity

Constant.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## resize() [2/2]

template<size_t capacity_>

void seqan3::small_string< capacity_ >::resize | ( | size_type const | count,
|  | char const | value )

inline constexpr noexcept

Resizes the container to contain count elements.

Parameters

  | value | Append copies of value when resizing.
  [in] | count | The new size.

If count is greater than capacity this is undefined behaviour.

### Complexity

Constant.

### Exceptions

No-throw guarantee.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## str()

template<size_t capacity_>

std::string seqan3::small_string< capacity_ >::str | ( |  | ) | const

inline

Returns the content represented as std::string.

Returns
  std::string The stored string.

### Exceptions

Strong exception guarantee. No data is modified.

### Complexity

Linear in the size of the string.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## Friends And Related Symbol Documentation

## operator+

template<size_t capacity_>
template<size_t capacity2>

friend small_string< capacity_+capacity2 > operator+ | ( | small_string< capacity_ > const & | lhs,
|  | small_string< capacity2 > const & | rhs )

friend

Concatenates two small_strings by returning a new small_string.

Parameters

  lhs | The left-hand-side to concat with.
  rhs | The right-hand-side to concat with.

Returns
  small_string<capacity_ + capacity2> The new small_string with size capacity_ + capacity2.

### Exceptions

No-throw guarantee.

### Complexity

Linear in the size of the strings.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## operator<<

template<size_t capacity_>

std::ostream & operator<< | ( | std::ostream & | os,
|  | small_string< capacity_ > const & | str )

friend

Formatted output for the seqan3::small_string.

Parameters

  [in,out] | os | The std::basic_ostream to write to.
  [in] | str | The seqan3::small_string to read from.

Returns
  os.

Internally calls os << str.str().

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## operator>>

template<size_t capacity_>

std::istream & operator>> | ( | std::istream & | is,
|  | small_string< capacity_ > & | str )

friend

Formatted input for the seqan3::small_string.

Parameters

  [in,out] | is | The std::basic_istream to read from.
  [out] | str | The seqan3::small_string to write to.

Returns
  is.

Reads at most seqan3::small_string::max_size characters from the stream. If a stream error occurred or no characters could be extracted the std::ios_base::failbit is set. This may throw an exception.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## small_string() [1/3]

template<size_t N>

small_string | ( | char const | (&)[N] | ) | ->small_string< N-1 >

related

Deduces small_string from string literals.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## small_string() [2/3]

template<size_t capacity_>

small_string | ( | char const |  | ) | ->small_string< 1 >

related

Deduces small_string from char.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## small_string() [3/3]

template<size_t N>

small_string | ( | std::array< char, N > const & |  | ) | ->small_string< N >

related

Deduces small_string from std::array of type char.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

The documentation for this class was generated from the following file:

- small_string.hpp

Hide me