Skip to content

The `utf::string` class API

Jump to bottom
Alex Qzminsky edited this page Mar 30, 2020 · 37 revisions

Contents

  1. Member types
  2. Public member functions
    1. Constructors
    2. Destructor
    3. Convertors
    4. Transforming algorithms

Member types

Public member functions

Constructors

string::string ()

Default constructor. Does not allocate any memory in the heap.

string::string (string const&)

Copy constructor.

string::string (string&&)

Move constructor.

string::string (const char*)

Converting constructor from a C-string.

string::string (view const&)

Converting constructor from a string view. The effect is equivalent to invoke view::to_string ().

string::string (string::char_type Ch, string::size_type N)

Constructs a string as a copy of Ch character N times.

string::from_bytes (std::vector<uint8_t> const&) -> string static

Converting constructor from a vector of UTF-8 bytes. For example,

utf::string::from_bytes({ 0b11000010, 0b10100101, '1', '0' })

is equal to "¥10".

string::from_unicode (std::initializer_list<string::char_type>) -> string static

Converting constructor from a list of Unicode codepoints. For example,

utf::string::from_unicode({ 0xA5, '1', '0' });

is equal to "¥10".

string::from_std_string (std::string const&) -> string static

Converting constructor from an STL string object.

Destructor

string::~string ()

Frees an allocated memory chunk.

Convertors

string::as_bytes () -> std::vector<uint8_t> const

Creates and returns an std::vector object containing UTF-8-encoded bytes of the string.

string::as_unicode () -> std::vector<string::char_type> const

Creates and returns an std::vector object containing the Unicode codepoints of the string's characters.

Transforming algorithms

string::clear () -> string&

Completely clears the string by deallocating its owned memory.

Returns *this.

string::clone () -> string const

Returns the copy of the original string. Useful for chaining, e.g.,

auto ModifiedCopy = StayOriginal.clone().insert(5, "substring");
string::erase (string::size_type pos, string::size_type N = 1) -> string&

Removes N characters starting from the given index pos.

⚠ Throws:

  • utf::invalid_argument if pos is negative;
  • utf::length_error if N is negative.

Returns *this.

string::erase (string_view const& vi) -> string&

Removes all characters in the given range.

⚠ Throws utf::out_of_range if vi ⊄ *this.

Returns *this.

string::erase (string_view::iterator const& iter) -> string&

Removes one character by an iterator iter.

⚠ Throws utf::out_of_range if iter ∉ *this.

Returns *this.

string::insert (string::size_type pos, string::char_type ucode) -> string&

Inserts a character ucode into the string before the pos-th.

⚠ Throws:

  • utf::invalid_argument if pos is negative;
  • utf::unicode_error in case of ucodes invalid codepoint.

Returns *this.

string::insert (string::size_type pos, string_view const&) -> string&

Inserts a substring into the string before the pos-th.

⚠ Throws utf::invalid_argument if pos is negative.

Returns *this.

string::insert (string_view::iterator const& iter, string::char_type ucode) -> string&

Inserts a character ucode into the string before the character pointing by iter.

⚠ Throws:

  • utf::out_of_range if iter ∉ *this;
  • utf::unicode_error in case of ucodes invalid codepoint.

Returns *this.

string::insert (string_view::iterator const& iter, string_view const&) -> string&

Inserts a substring into the string before the character pointing by iter.

⚠ Throws utf::out_of_range if iter ∉ *this.

Returns *this.

string::pop () -> string::char_type

Removes the last character from the string and returns its codepoint.

⚠ Throws utf::underflow_error if *this was empty before modifying.

string::push (string::char_type ucode) -> string&

Appends a given Unicode character to the end of the string.

⚠ Throws utf::unicode_error in case of ucodes invalid codepoint.

Returns *this.

string::push (string_view const&) -> string&

Appends a given substring to the end of current string.

Returns *this.

string::remove_if (Functor&&) -> string& template noexcept

Removes all characters satisfying specified criteria from the string.

Template constraints:

  • cpp17 std::is_invocable<Functor, string::char_type>;
  • cpp20 std::predicate<Functor, string::char_type>.

Returns *this.

string::remove (string::char_type, Char...) -> string& template

Removes all occurrences of the every character in the string.

Template constraints:

  • cpp17 std::is_convertible<Char, string::char_type>...;
  • cpp20 std::convertible_to<Char, string::char_type>....

⚠ Throws utf::unicode_error in case of any character's invalid codepoint.

Returns *this.

string::remove (string_view const&, View const&...) -> string& template noexcept

Removes all occurences of the every substring in the string.

Template constraints:

  • cpp17 std::is_convertible<View, string_view>...;
  • cpp20 std::convertible_to<View, string_view>....

Returns *this.

string::replace_all_if (Functor&&, string::char_type ucode) -> string& template

Replaces all characters satisfying specified criteria by another one.

Template constraints:

  • cpp17 std::is_invocable<Functor, string::char_type>;
  • cpp20 std::predicate<Functor, string::char_type>.

⚠ Throws utf::unicode_error in case of ucodes invalid codepoint.

Returns *this.

Clone this wiki locally