iox::cxx::string

string implementation with some adjustments in the API, because we are not allowed to throw exceptions or use heap. Please see iceoryx/iceoryx_utils/doc/fixedString.adoc for further information. More...

#include <string.hpp>

Public Functions

	Name
constexpr	string() =default creates an empty string with size 0
	string(const string & other) copy constructor
	string(string && other) move constructor
string &	operator=(const string & rhs) copy assignment
string &	operator=(string && rhs) move assignment
template \<uint64_t N>	string(const string< N > & other) creates a new string of given capacity as a copy of other with compile time check whether the capacity of other is less than or equal to this' capacity
template \<uint64_t N>	string(string< N > && other) moves other to this with compile time check whether the capacity of other is less than or equal to this' capacity
template \<uint64_t N> string &	operator=(const string< N > & rhs) assigns rhs fixed string to this with compile time check whether the capacity of rhs is less than or equal to this' capacity
template \<uint64_t N> string &	operator=(string< N > && rhs) moves rhs fixed string to this with compile time check whether the capacity of rhs is less than or equal to this' capacity
template \<uint64_t N>	string(const char(&) other[N]) conversion constructor for char array with compile time check if the array size is less than or equal to the string capacity
	string(TruncateToCapacity_t , const char *const other) conversion constructor for cstring to string which truncates characters if the size is greater than the string capacity
	string(TruncateToCapacity_t , const std::string & other) conversion constructor for std::string to string which truncates characters if the std::string size is greater than the string capacity
	string(TruncateToCapacity_t , const char *const other, const uint64_t count) constructor from cstring to string. Constructs the string with the first count characters of the cstring including null characters. If count is greater than the string capacity the remainder of the characters are truncated.
template \<uint64_t N> string &	operator=(const char(&) rhs[N]) assigns a char array to string with compile time check if the array size is less than or equal to the string capacity
template \<uint64_t N> string &	assign(const string< N > & str) fixed string assignment with compile time check if capacity of str is less than or equal to this' capacity
template \<uint64_t N> string &	assign(const char(&) str[N]) assigns a char array to string with compile time check if the array size is less than or equal to the string capacity
bool	unsafe_assign(const char *const str) assigns a cstring to string. The assignment fails if the cstring size is greater than the string capacity.
bool	unsafe_assign(const std::string & str) assigns a std::string to string. The assignment fails if the std::string size is greater than the string capacity.
template \<uint64_t N> int64_t	compare(const string< N > & other) const compares two strings
template \<uint64_t N> bool	operator==(const string< N > & rhs) const checks if self is equal to rhs
template \<uint64_t N> bool	operator!=(const string< N > & rhs) const checks if self is not equal to rhs
template \<uint64_t N> bool	operator<(const string< N > & rhs) const checks if self is less than rhs, in lexicographical order
template \<uint64_t N> bool	operator<=(const string< N > & rhs) const checks if self is less than or equal to rhs, in lexicographical order
template \<uint64_t N> bool	operator>(const string< N > & rhs) const checks if self is greater than rhs, in lexicographical order
template \<uint64_t N> bool	operator>=(const string< N > & rhs) const checks if self is greater than or equal to rhs, in lexicographical order
bool	operator==(const char *const rhs) const The equality operator for fixed string and char pointer is disabled via a static_assert, because it may lead to undefined behavior if the char array is not null-terminated. Please convert the char array to a fixed string with string(TruncateToCapacity_t, const char* const other, const uint64_t count) before compare it to a fixed string.
bool	operator!=(const char *const rhs) const The inequality operator for fixed string and char pointer is disabled via a static_assert, because it may lead to undefined behavior if the char array is not null-terminated. Please convert the char array to a fixed string with string(TruncateToCapacity_t, const char* const other, const uint64_t count) before compare it to a fixed string.
const char *	c_str() const returns a pointer to the char array of self
constexpr uint64_t	size() const returns the number of characters stored in the string
constexpr uint64_t	capacity() const returns the maximum number of characters that can be stored in the string
constexpr bool	empty() const returns if the string is empty or not
	operator std::string() const converts the string to a std::string
template \<typename T > string &	operator+=(const T & ) since there are two valid options for what should happen when appending a string larger than this' capacity (failing or truncating), the fixed string does not support operator+=; use append for truncating or unsafe_append for failing in that case
template \<typename T > std::enable_if< internal::IsCharArray< T >::value
template \<typename T > std::enable_if< internal::IsCharArray< T >::value
iox::cxx::optional< string< Capacity > >	substr(const uint64_t pos, const uint64_t count) const creates a substring containing the characters from pos until count; if pos+count is greater than the size of the original string the returned substring only contains the characters from pos until size(); iox::cxx::nullopt is returned if pos is greater than the size of the original string;
iox::cxx::optional< string< Capacity > >	substr(const uint64_t pos =0U) const creates a substring containing the characters from pos until size(); iox::cxx::nullopt is returned if pos is greater than the size of the original string
template \<typename T > std::enable_if< std::is_same< T, std::string >::value
template \<typename T > std::enable_if< std::is_same< T, std::string >::value
template \<typename T > std::enable_if< std::is_same< T, std::string >::value
template \<uint64_t N> string< Capacity > &	operator=(const string< N > & rhs)
template \<uint64_t N> string< Capacity > &	operator=(string< N > && rhs)
template \<uint64_t N> string< Capacity > &	operator=(const char(&) rhs[N])
template \<uint64_t N> string< Capacity > &	assign(const string< N > & str)
template \<uint64_t N> string< Capacity > &	assign(const char(&) str[N])
template \<uint64_t N> string< Capacity > &	copy(const string< N > & rhs)
template \<uint64_t N> string< Capacity > &	move(string< N > && rhs)
template \<typename T > string< Capacity > &	operator+=(const T & )

Friends

	Name
class	string
std::enable_if<(internal::IsCharArray< T1 >::value

Detailed Description

template <uint64_t Capacity>
class iox::cxx::string;

string implementation with some adjustments in the API, because we are not allowed to throw exceptions or use heap. Please see iceoryx/iceoryx_utils/doc/fixedString.adoc for further information.

Public Functions Documentation

function string

constexpr string() =default

creates an empty string with size 0

function string

inline string(
    const string & other
)

copy constructor

Parameters:

• other is the copy origin

function string

inline string(
    string && other
)

move constructor

Parameters:

• other is the move origin

function operator=

inline string & operator=(
    const string & rhs
)

copy assignment

Parameters:

• rhs is the copy origin

Return: reference to self

function operator=

inline string & operator=(
    string && rhs
)

move assignment

Parameters:

• rhs is the move origin

Return: reference to self

function string

template <uint64_t N>
inline string(
    const string< N > & other
)

creates a new string of given capacity as a copy of other with compile time check whether the capacity of other is less than or equal to this' capacity

Parameters:

• other is the copy origin

function string

template <uint64_t N>
inline string(
    string< N > && other
)

moves other to this with compile time check whether the capacity of other is less than or equal to this' capacity

Parameters:

• other is the move origin

function operator=

template <uint64_t N>
string & operator=(
    const string< N > & rhs
)

assigns rhs fixed string to this with compile time check whether the capacity of rhs is less than or equal to this' capacity

Parameters:

• rhs is the copy origin

Return: reference to self

function operator=

template <uint64_t N>
string & operator=(
    string< N > && rhs
)

moves rhs fixed string to this with compile time check whether the capacity of rhs is less than or equal to this' capacity

Parameters:

• rhs is the move origin

Return: reference to self

function string

template <uint64_t N>
inline string(
    const char(&) other[N]
)

conversion constructor for char array with compile time check if the array size is less than or equal to the string capacity

Parameters:

• other is the char array

Template Parameters:

• N is the implicit template parameter for the char array size

Note: if the array is not zero-terminated, the last value will be overwritten with 0

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    string<4> fuu("abcd");
}

function string

inline string(
    TruncateToCapacity_t ,
    const char *const other
)

conversion constructor for cstring to string which truncates characters if the size is greater than the string capacity

Parameters:

• TruncateToCapacity_t is a compile time variable which is used to distinguish between constructors with certain behavior
• other is the cstring to convert

Attention: truncates characters if the size is greater than the string capacity

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    string<4> fuu(TruncateToCapacity, "abcd");
}

function string

inline string(
    TruncateToCapacity_t ,
    const std::string & other
)

conversion constructor for std::string to string which truncates characters if the std::string size is greater than the string capacity

Parameters:

• TruncateToCapacity_t is a compile time variable which is used to distinguish between constructors with certain behavior
• other is the std::string to convert

Attention: truncates characters if the std::string size is greater than the string capacity

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    std::string bar = "bar";
    string<4> fuu(TruncateToCapacity, bar);
}

function string

inline string(
    TruncateToCapacity_t ,
    const char *const other,
    const uint64_t count
)

constructor from cstring to string. Constructs the string with the first count characters of the cstring including null characters. If count is greater than the string capacity the remainder of the characters are truncated.

Parameters:

• TruncateToCapacity_t is a compile time variable which is used to distinguish between constructors with certain behavior
• other is the cstring to convert
• count is the number of characters for constructing the string

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    string<4> fuu(TruncateToCapacity, "abcd", 2);
}

function operator=

template <uint64_t N>
string & operator=(
    const char(&) rhs[N]
)

assigns a char array to string with compile time check if the array size is less than or equal to the string capacity

Parameters:

• rhs is the char array

Template Parameters:

• [in] N is the implicit template parameter for the char array size

Return: reference to self

Note: if the array is not zero-terminated, the last value will be overwritten with 0

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    string<4> fuu = "abcd";
}

function assign

template <uint64_t N>
string & assign(
    const string< N > & str
)

fixed string assignment with compile time check if capacity of str is less than or equal to this' capacity

Parameters:

• str is the fixed string object to assign

Return: reference to self

function assign

template <uint64_t N>
string & assign(
    const char(&) str[N]
)

assigns a char array to string with compile time check if the array size is less than or equal to the string capacity

Parameters:

• str is the char array

Template Parameters:

• [in] N is the implicit template parameter for the char array size

Return: reference to self

Note: if the array is not zero-terminated, the last value will be overwritten with 0

#include "iceoryx_utils/cxx/string.hpp"
using namespace iox::cxx;

int main()
{
    string<4> fuu;
    char bar[] = "abcd";
    fuu.assign(bar);
}

function unsafe_assign

inline bool unsafe_assign(
    const char *const str
)

assigns a cstring to string. The assignment fails if the cstring size is greater than the string capacity.

Parameters:

• str is the cstring to assign

Return: true if the assignment succeeds, otherwise false

function unsafe_assign

inline bool unsafe_assign(
    const std::string & str
)

assigns a std::string to string. The assignment fails if the std::string size is greater than the string capacity.

Parameters:

• str is the std::string to assign

Return: true if the assignment succeeds, otherwise false

function compare

template <uint64_t N>
inline int64_t compare(
    const string< N > & other
) const

compares two strings

Parameters:

• other is the string to compare with self

Return: an integer < 0 if the first character that does not match has a lower value in self than in other, 0 if the contents of both strings are equal, an integer > 0 if the first character that does not match has a greater value in self than in other

function operator==

template <uint64_t N>
inline bool operator==(
    const string< N > & rhs
) const

checks if self is equal to rhs

Parameters:

• rhs is the string to compare with self

Return: true if both strings are equal, otherwise false

function operator!=

template <uint64_t N>
inline bool operator!=(
    const string< N > & rhs
) const

checks if self is not equal to rhs

Parameters:

• rhs is the string to compare with self

Return: true if both strings are not equal, otherwise false

function operator<

template <uint64_t N>
inline bool operator<(
    const string< N > & rhs
) const

checks if self is less than rhs, in lexicographical order

Parameters:

• rhs is the string to compare with self

Return: true if self is less than rhs, otherwise false

function operator<=

template <uint64_t N>
inline bool operator<=(
    const string< N > & rhs
) const

checks if self is less than or equal to rhs, in lexicographical order

Parameters:

• rhs is the string to compare with self

Return: true if self is less than or equal to rhs, otherwise false

function operator>

template <uint64_t N>
inline bool operator>(
    const string< N > & rhs
) const

checks if self is greater than rhs, in lexicographical order

Parameters:

• rhs is the string to compare with self

Return: true if self is greater than rhs, otherwise false

function operator>=

template <uint64_t N>
inline bool operator>=(
    const string< N > & rhs
) const

checks if self is greater than or equal to rhs, in lexicographical order

Parameters:

• rhs is the string to compare with self

Return: true if self is greater than or equal to rhs, otherwise false

function operator==

inline bool operator==(
    const char *const rhs
) const

The equality operator for fixed string and char pointer is disabled via a static_assert, because it may lead to undefined behavior if the char array is not null-terminated. Please convert the char array to a fixed string with string(TruncateToCapacity_t, const char* const other, const uint64_t count) before compare it to a fixed string.

Parameters:

• rhs is the char pointer to the array to compare

Return: false

Todo: consider implementing the equality operator for a char array for which the size is known at compile time; it could have the following signature template bool operator==(const char (&rhs)[N]) const noexcept

function operator!=

inline bool operator!=(
    const char *const rhs
) const

The inequality operator for fixed string and char pointer is disabled via a static_assert, because it may lead to undefined behavior if the char array is not null-terminated. Please convert the char array to a fixed string with string(TruncateToCapacity_t, const char* const other, const uint64_t count) before compare it to a fixed string.

Parameters:

• rhs is the char pointer to the array to compare

Return: false

Todo: consider implementing the inequality operator for a char array for which the size is known at compile time; it could have the following signature template bool operator!=(const char (&rhs)[N]) const noexcept

function c_str

inline const char * c_str() const

returns a pointer to the char array of self

Return: a pointer to the char array of self

function size

inline constexpr uint64_t size() const

returns the number of characters stored in the string

Return: the number of characters stored in the string

function capacity

inline constexpr uint64_t capacity() const

returns the maximum number of characters that can be stored in the string

Return: the maximum number of characters that can be stored in the string

function empty

inline constexpr bool empty() const

returns if the string is empty or not

Return: true if size() == 0 otherwise false

function operator std::string

inline operator std::string() const

converts the string to a std::string

Return: a std::string with data equivalent to those stored in the string

function operator+=

template <typename T >
string & operator+=(
    const T & 
)

since there are two valid options for what should happen when appending a string larger than this' capacity (failing or truncating), the fixed string does not support operator+=; use append for truncating or unsafe_append for failing in that case

function append

template <typename T >
inline std::enable_if< internal::IsCharArray< T >::value||internal::IsCxxString< T >::value, string & >::type append(
    TruncateToCapacity_t ,
    const T & t
)

appends a fixed string or string literal to the end of this. If this' capacity is too small for appending the whole string (literal) the remainder of the characters are truncated.

Parameters:

• TruncateToCapacity_t is a compile time variable which is used to make the user aware of the possible truncation
• t is the fixed string/string literal to append

Return: reference to self

string<5> fuu("cde");
fuu.append(TruncateToCapacity, "fgahc");

function unsafe_append

template <typename T >
inline std::enable_if< internal::IsCharArray< T >::value||internal::IsCxxString< T >::value, bool >::type unsafe_append(
    const T & t
)

appends a fixed string or string literal to the end of this. The appending fails if the sum of both sizes is greater than this' capacity.

Parameters:

• fixed string/string literal to append

Return: true if the appending succeeds, otherwise false

function substr

inline iox::cxx::optional< string< Capacity > > substr(
    const uint64_t pos,
    const uint64_t count
) const

creates a substring containing the characters from pos until count; if pos+count is greater than the size of the original string the returned substring only contains the characters from pos until size(); iox::cxx::nullopt is returned if pos is greater than the size of the original string;

Parameters:

• pos is the position of the first character used for the substring
• count is the requested length of the substring

Return: an optional containing the substring, iox::cxx::nullopt if pos is greater than the size of the original string

function substr

inline iox::cxx::optional< string< Capacity > > substr(
    const uint64_t pos =0U
) const

creates a substring containing the characters from pos until size(); iox::cxx::nullopt is returned if pos is greater than the size of the original string

Parameters:

• pos is the position of the first character used for the substring

Return: an optional containing the substring, iox::cxx::nullopt if pos is greater than the size of the original string

function find

template <typename T >
inline std::enable_if< std::is_same< T, std::string >::value||internal::IsCharArray< T >::value||internal::IsCxxString< T >::value, iox::cxx::optional< uint64_t > >::type find(
    const T & t,
    const uint64_t pos =0U
) const

finds the first occurence of the given character sequence; returns the position of the first character of the found substring, returns iox::cxx::nullopt if no substring is found or if pos is greater than this' size

Parameters:

• t is the character sequence to search for; must be a cxx::string, string literal or std::string
• pos is the position at which to start the search

Return: an optional containing the position of the first character of the found substring, iox::cxx::nullopt if no substring is found

function find_first_of

template <typename T >
inline std::enable_if< std::is_same< T, std::string >::value||internal::IsCharArray< T >::value||internal::IsCxxString< T >::value, iox::cxx::optional< uint64_t > >::type find_first_of(
    const T & t,
    const uint64_t pos =0U
) const

finds the first occurence of a character equal to one of the characters of the given character sequence and returns its position; returns iox::cxx::nullopt if no character is found or if pos is greater than this' size

Parameters:

• t is the character sequence to search for; must be a cxx::string, string literal or std::string
• pos is the position at which to start the search

Return: an optional containing the position of the first character equal to one of the characters of the given character sequence, iox::cxx::nullopt if no character is found

function find_last_of

template <typename T >
inline std::enable_if< std::is_same< T, std::string >::value||internal::IsCharArray< T >::value||internal::IsCxxString< T >::value, iox::cxx::optional< uint64_t > >::type find_last_of(
    const T & t,
    const uint64_t pos =Capacity
) const

finds the last occurence of a character equal to one of the characters of the given character sequence and returns its position; returns iox::cxx::nullopt if no character is found

Parameters:

• t is the character sequence to search for; must be a cxx::string, string literal or std::string
• pos is the position at which to finish the search

Return: an optional containing the position of the last character equal to one of the characters of the given character sequence, iox::cxx::nullopt if no character is found

function operator=

template <uint64_t N>
inline string< Capacity > & operator=(
    const string< N > & rhs
)

function operator=

template <uint64_t N>
inline string< Capacity > & operator=(
    string< N > && rhs
)

function operator=

template <uint64_t N>
inline string< Capacity > & operator=(
    const char(&) rhs[N]
)

function assign

template <uint64_t N>
inline string< Capacity > & assign(
    const string< N > & str
)

function assign

template <uint64_t N>
inline string< Capacity > & assign(
    const char(&) str[N]
)

function copy

template <uint64_t N>
inline string< Capacity > & copy(
    const string< N > & rhs
)

function move

template <uint64_t N>
inline string< Capacity > & move(
    string< N > && rhs
)

function operator+=

template <typename T >
inline string< Capacity > & operator+=(
    const T & 
)

Friends

friend string

friend class string;

friend concatenate

friend std::enable_if<(internal::IsCharArray< T1 >::value||internal::IsCxxString< T1 >::value) &&(internal::IsCharArray< T2 >::value||internal::IsCxxString< T2 >::value), string< internal::GetCapa< T1 >::capa+internal::GetCapa< T2 >::capa > >::type concatenate(
    const T1 & t1,
    const T2 & t2
);

concatenates two fixed strings/string literals

Parameters:

• fixed strings/string literals to concatenate

Return: a new fixed string with capacity equal to the sum of the capacities of the concatenated strings

string<5> fuu("cdefg");
auto bar = iox::cxx::concatenate(fuu, "ahc");

---

Updated on 31 May 2022 at 15:29:15 CEST