A C++ template library for embedded applications
Designed and maintained by
Aster Consulting Ltd
Join the ETL community

string / wstring / u16string / u32string


Fixed capacity string classes.
STL equivalent: std::string, std::wstring, std::u16string, std::u32string

etl::string<const size_t SIZE>
etl::wstring<const size_t SIZE>
etl::u16string<const size_t SIZE>
etl::u32string<const size_t SIZE>

Inherits from etl::istring, etl::iwstring, etl::iu16string or etl::iu32string
The base classes may be used as a size independent pointer or reference type for any string instance.

Has the ability to be copied by low level functions such as memcpy by use of a repair() function.
See the function reference for an example of use.

The size of the instance will be (SIZE * sizeof(<char type>)) + (2 * sizeof(size_t)) + sizeof(T*)
For a 32 bit environment the overhead (compared to an array) will usually be 12 bytes.


____________________________________________________________________________________________________

Member types


value_type              T
size_type               std::size_t
difference_type         std::ptrdiff_t
reference               value_type&
const_reference         const value_type&
pointer                 value_type*
const_pointer           const value_type*
iterator                Random access iterator
const_iterator          Constant random access iterator
reverse_iterator        std::reverse_iterator<iterator>
const_reverse_iterator  std::reverse_iterator<const_iterator>


____________________________________________________________________________________________________

Constructor


etl::string<const size_t SIZE>();
etl::string<const size_t SIZE>(const istring& str);
etl::string<const size_t SIZE>(const istring& str, size_t pos, size_t len = npos);
etl::string<const size_t SIZE>(const char* s);
etl::string<const size_t SIZE>(const char* s, size_t n);
etl::string<const size_t SIZE>(size_t n, char c);

template <typename TIterator>
etl::string<const size_t SIZE>(TIterator begin, TIterator end);

Truncates the string if too long.


____________________________________________________________________________________________________

Element access


T& at(size_t i)
const T& at(size_t i) const

Returns a reference or const reference to the indexed element. Emits an etl::string_out_of_bounds if the index is
out of range of the array.
____________________________________________________________________________________________________

T& operator[](size_t i)
const T& operator[](size_t i) const

Returns a reference or const reference to the indexed element.
____________________________________________________________________________________________________

T& front()
const T& front() const

Returns a reference or const reference to the first element.
Undefined behaviour if the string is empty.
____________________________________________________________________________________________________

T& back()
const T& back() const

Returns a reference or const reference to the last element.
Undefined behaviour if the string is empty.

____________________________________________________________________________________________________

Iterators

iterator begin()
const_iterator begin() const
const_iterator cbegin() const

Returns an iterator to the beginning of the string.
____________________________________________________________________________________________________

iterator end()
const_iterator end() const
const_iterator cend() const

Returns an iterator to the end of the string.
____________________________________________________________________________________________________

iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const

Returns a reverse iterator to the beginning of the string.
____________________________________________________________________________________________________

iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const

Returns a reverse iterator to the end of the string.

____________________________________________________________________________________________________

Capacity

bool empty() const

Returns true if the size of the string is zero, otherwise false.
____________________________________________________________________________________________________

bool full() const

Returns true if the size of the string is SIZE, otherwise false.
____________________________________________________________________________________________________

size_t size() const

Returns the size of the vector.
____________________________________________________________________________________________________

void resize(size_t new_size, T value = T())

Resizes the vector, up to the maximum capacity. Emits an etl::string_full if the string does not have the capacity.
____________________________________________________________________________________________________

size_t max_size() const

Returns the maximum possible size of the string.
____________________________________________________________________________________________________

size_t capacity() const

Returns the maximum possible size of the string.
____________________________________________________________________________________________________

size_t available() const

Returns the remaining available capacity in the string.

____________________________________________________________________________________________________

Modifiers

template <typename TIterator>
void assign(TIterator begin, TIterator end);
void assign(size_t n, parameter_t value);

Fills the vector with the values. Emits etl::string_iterator if the distance between begin and end is illegal.
Truncates the string if too long.
____________________________________________________________________________________________________

void push_back(value_type value);

Pushes a value to the back of the string.
No action if the string is already full.
____________________________________________________________________________________________________

void pop_back();

Pop a value from the back of the string.
No action if the string is already empty.
____________________________________________________________________________________________________

template <typename TIterator>
void insert(iterator position, TIterator begin, TIterator end);
iterator insert(iterator position, parameter_t value);
void insert(iterator position, size_t n, parameter_t value);

Inserts values in to the string. Truncates the string if too long.
Note: Strings that insert from themselves are only supported if the insert position is after the input range.
____________________________________________________________________________________________________

template <typename TIterator>
iterator erase(TIterator begin, TIterator end);
iterator erase(iterator position);

Erases values in the string.
Iterators are not checked.
____________________________________________________________________________________________________

void clear();

Clears the string to a size of zero.
____________________________________________________________________________________________________

string& assign (const string& str);
string& assign (const string& str, size_t subpos, size_t sublen);
string& assign (const char* s);
string& assign (const char* s, size_t n);
string& assign (size_t n, char c);
template <typename TIterator>
string& assign (TIterator first, TIterator last);

Assigns to the string. Truncates the string if too long.
____________________________________________________________________________________________________

string& append (const string& str);
string& append (const string& str, size_t subpos, size_t sublen);
string& append (const char* s);
string& append (const char* s, size_t n);
string& append (size_t n, char c);
template <typename TIterator>
string& append (TIterator first, Titerator last);

Appends to the string. Truncates the string if too long.
____________________________________________________________________________________________________

string& insert (size_t pos, const string& str);
string& insert (size_t pos, const string& str, size_t subpos, size_t sublen);
string& insert (size_t pos, const char* s);
string& insert (size_t pos, const char* s, size_t n);
string& insert (size_t pos, size_t n, char c);
void insert (iterator p, size_t n, char c);
iterator insert (iterator p, char c);
template <typename TIterator>
void insert (iterator p, Titerator first, Titerator last);

Inserts into the string
Note: Strings that insert from themselves are only supported if the insert position is after the input range.
____________________________________________________________________________________________________

string& replace (size_t pos,  size_t len,  const string& str);
string& replace (iterator i1, iterator i2, const string& str);
string& replace (size_t pos,  size_t len,  const string& str, size_t subpos, size_t sublen);
string& replace (size_t pos,  size_t len,  const char* s);
string& replace (iterator i1, iterator i2, const char* s);
string& replace (size_t pos,  size_t len,  const char* s, size_t n);
string& replace (iterator i1, iterator i2, const char* s, size_t n);
string& replace (size_t pos,  size_t len,  size_t n, char c);
string& replace (iterator i1, iterator i2, size_t n, char c);
template <typename TIterator>
string& replace (iterator i1, iterator i2, Titerator first, Titerator last);

Replaces parts of the string. Truncates the string if too long.
____________________________________________________________________________________________________

void repair()

This function must be called if the string has been copied via a low level method such as memcpy.
This can only be called from an etl::string, etl::wstring, etl::u16string or etl::u32string instance, unless
ETL_ISTRING_REPAIR_ENABLE is defined. Be aware that doing this introduces a virtual function to the class.

Has no effect if the object has not been copied in this way.

Example:

typedef etl::string<10> String;

String text = "ABCDEF";

char buffer[sizeof(String)];

memcpy(&buffer, &text, sizeof(String));

String& rtext(*reinterpret_cast<String*>(buffer));

// Do not access the string in any way until you have called this.
rtext.repair();

____________________________________________________________________________________________________

Find


size_t find(const string& str, size_t pos = 0) const;
size_t find(const char* s, size_t pos = 0) const;
size_t find(const char* s, size_t pos, size_t n) const;
size_t find(char c, size_t pos = 0) const;

Find in a string
____________________________________________________________________________________________________

size_t rfind(const string& str, size_t pos = npos) const;
size_t rfind(const char* s, size_t pos = npos) const;
size_t rfind(const char* s, size_t pos, size_t n) const;
size_t rfind(char c, size_t pos = npos) const;

Reverse find in a string
____________________________________________________________________________________________________

size_t find_first_of(const string& str, size_t pos = 0) const;
size_t find_first_of(const char* s, size_t pos = 0) const;
size_t find_first_of(const char* s, size_t pos, size_t n) const;
size_t find_first_of(char c, size_t pos = 0) const;

Find first of in a string
____________________________________________________________________________________________________

size_t find_last_of(const string& str, size_t pos = npos) const;
size_t find_last_of(const char* s, size_t pos = npos) const;
size_t find_last_of(const char* s, size_t pos, size_t n) const;
size_t find_last_of(char c, size_t pos = npos) const;

Find last of in a string
____________________________________________________________________________________________________

size_t find_first_not_of(const string& str, size_t pos = 0) const;
size_t find_first_not_of(const char* s, size_t pos = 0) const;
size_t find_first_not_of(const char* s, size_t pos, size_t n) const;
size_t find_first_not_of(char c, size_t pos = 0) const;

Find first not of in a string
____________________________________________________________________________________________________

size_t find_last_not_of(const string& str, size_t pos = npos) const;
size_t find_last_not_of(const char* s, size_t pos = npos) const;
size_t find_last_not_of(const char* s, size_t pos, size_t n) const;
size_t find_last_not_of(char c, size_t pos = npos) const;

Find last not of in a string
____________________________________________________________________________________________________

string substr(size_t pos = 0, size_t len = npos) const;

Extract a substring
____________________________________________________________________________________________________

int compare(const string& str) const;
int compare(size_t pos, size_t len, const string& str) const;
int compare(size_t pos, size_t len, const string& str, size_t subpos, size_t sublen) const;
int compare(const char* s) const;
int compare(size_t pos, size_t len, const char* s) const;
int compare(size_t pos, size_t len, const char* s, size_t n) const;

Compare strings

____________________________________________________________________________________________________

Non-member functions


+   Concatenates strings
==  true if the contents of the vectors are equal, otherwise false.
!=  true if the contents of the vectors are not equal, otherwise false.
<   true if the contents of the lhs are lexicographically less than the contents of the rhs,  otherwise false.
<=  true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false.
>   true if the contents of the lhs are lexicographically greater than the contents of the rhs,  otherwise false.
>=  true if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise
false.

cstring.h / wstring.h / u16string.h / u32string.h