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_ >:

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.

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 (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= (small_vector const &) noexcept=default
	Defaulted.

constexpr small_vector &	operator= (small_vector &&) noexcept=default
	Defaulted.

constexpr small_vector &	operator= (std::initializer_list< value_type > ilist) noexcept(is_noexcept)
	Assign from `std::initializer_list`.

	~small_vector () noexcept=default
	Defaulted.

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.

Comparison operators

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.

Additional Inherited Members
Public Types inherited from seqan3::small_vector< char, capacity_+1 >
using	value_type = char
	The value_type type.

using	reference = value_type &
	The reference type.

using	const_reference = value_type const &
	The const_reference type.

using	iterator = value_type *
	The iterator type.

using	const_iterator = value_type const *
	The const_iterator type.

using	difference_type = ptrdiff_t
	The difference_type type.

using	size_type = detail::min_viable_uint_t< capacity_ >
	The size_type type.

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-2024 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024 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"
}

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>

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

inlineconstexprnoexcept

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_>

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

inlineexplicitconstexprnoexcept

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>>

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

inlineconstexprnoexcept

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>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlinestaticconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlinestaticconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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_>

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

inlineconstexprnoexcept

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>

constexpr 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 >

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 >

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 >

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

Public Member Functions

Static Public Member Functions

Friends

Related Symbols

Additional Inherited Members

Detailed Description

Implementation notes

Constructor & Destructor Documentation

◆ small_string() [1/2]

Exceptions

◆ small_string() [2/2]

Exceptions

Member Function Documentation

◆ assign() [1/2]

Complexity

Exceptions

◆ assign() [2/2]

Complexity

Exceptions

◆ c_str()

Exceptions

Complexity

◆ capacity()

◆ clear()

Complexity

Exceptions

◆ erase()

Complexity

Exceptions

◆ max_size()

◆ operator std::string()

Exceptions

Complexity

◆ operator std::string_view()

Exceptions

Complexity

◆ operator=()

Complexity

Exceptions

◆ pop_back()

Complexity

Exceptions

◆ push_back()

Complexity

Exceptions

◆ resize() [1/2]

Complexity

Exceptions

◆ resize() [2/2]

Complexity

Exceptions

◆ str()

Exceptions

Complexity

Friends And Related Symbol Documentation

◆ operator+

Exceptions

Complexity

◆ operator<<

◆ operator>>

◆ small_string() [1/3]

◆ small_string() [2/3]

◆ small_string() [3/3]