BLString Class Reference

Byte string [C++ API].

Blend2D always uses UTF-8 encoding in public APIs so all strings are assumed UTF-8 by default. However, BLString doesn't guarantee any assumptions about the encoding of the data it holds. It can hold arbitrary byte sequence and acts as a raw byte-string when this functionality is required.

Member Functions

Construction & Destruction

BLString()

BLString(BLString&& other)

BLString(const BLString& other)

BLString(BLStringView view)

BLString(const char* str, size_t size = SIZE_MAX)

~BLString()

Overloaded Operators

operator bool() const

BLString& operator=(BLString&& other)

BLString& operator=(const BLString& other)

bool operator==(const BLString& other) const

bool operator!=(const BLString& other) const

bool operator<(const BLString& other) const

bool operator<=(const BLString& other) const

bool operator>(const BLString& other) const

bool operator>=(const BLString& other) const

bool operator==(const BLStringView& view) const

bool operator!=(const BLStringView& view) const

bool operator<(const BLStringView& view) const

bool operator<=(const BLStringView& view) const

bool operator>(const BLStringView& view) const

bool operator>=(const BLStringView& view) const

bool operator==(const char* str) const

bool operator!=(const char* str) const

bool operator<(const char* str) const

bool operator<=(const char* str) const

bool operator>(const char* str) const

bool operator>=(const char* str) const

const char& operator[](size_t index) const

Common Functionality

BLResult reset()

void swap(BLString& other)

Accessors

bool empty() const

const char& at(size_t index) const

size_t size() const

size_t capacity() const

const char* data() const

const char* begin() const

const char* end() const

BLStringView view() const

Data Manipulation

BLResult clear()

BLResult shrink()

BLResult reserve(size_t n)

BLResult resize(size_t n, char fill = '\0')

BLResult makeMutable(char** dataOut)

BLResult modifyOp(BLModifyOp op, size_t n, char** dataOut)

BLResult insertOp(size_t index, size_t n, char** dataOut)

BLResult assign(char c, size_t n = 1)

BLResult assign(BLString&& other)

BLResult assign(const BLString& other)

BLResult assign(BLStringView view)

BLResult assign(const char* str, size_t n = SIZE_MAX)

BLResult assignDeep(const BLString& other)

template<typename... Args>

BLResult assignFormat(const char* fmt, Args&&... args)

BLResult assignFormatV(const char* fmt, va_list ap)

BLResult truncate(size_t n)

BLResult append(char c, size_t n = 1)

BLResult append(const BLString& other)

BLResult append(BLStringView view)

BLResult append(const char* str, size_t n = SIZE_MAX)

template<typename... Args>

BLResult appendFormat(const char* fmt, Args&&... args)

BLResult appendFormatV(const char* fmt, va_list ap)

BLResult prepend(char c, size_t n = 1)

BLResult prepend(const BLString& other)

BLResult prepend(BLStringView view)

BLResult prepend(const char* str, size_t n = SIZE_MAX)

BLResult insert(size_t index, char c, size_t n = 1)

BLResult insert(size_t index, const BLString& other)

BLResult insert(size_t index, BLStringView view)

BLResult insert(size_t index, const char* str, size_t n = SIZE_MAX)

BLResult remove(size_t index)

BLResult remove(const BLRange& range)

Equality & Comparison

bool equals(const BLString& other) const

bool equals(BLStringView view) const

bool equals(const char* str, size_t n = SIZE_MAX) const

int compare(const BLString& other) const

int compare(BLStringView view) const

int compare(const char* str, size_t n = SIZE_MAX) const

Search

size_t indexOf(char c) const

size_t indexOf(char c, size_t fromIndex) const

size_t lastIndexOf(char c) const

size_t lastIndexOf(char c, size_t fromIndex) const

Additional Inherited Members

 Public Attributes inherited from BLObjectCore

BLObjectDetail _d

Constructor & Destructor Documentation

BLString::BLString()[1/5]

Creates an empty string.

BLString::BLString(BLString&& other)[2/5]

Move constructor.

Note

The other string is always reset by a move construction, so it becomes an empty string.

BLString::BLString(const BLString& other)[3/5]

Copy constructor, performs weak copy of the data held by the other string.

BLString::BLString(BLStringView view)explicit[4/5]

Constructor that creates a string from the given string view.

Note

See other constructors for more details.

BLString::BLString(const char* str, size_t size = SIZE_MAX)explicit[5/5]

Constructor that creates a string from the given data specified by str and size. If size is SIZE_MAX the string is assumed to be null terminated.

This is a convenience function that doesn't provide error handling. If size exceeds small string capacity and dynamic allocation failed then a default empty string would be constructed.

BLString::~BLString()

Destroys the string.

Member Function Documentation

BLString::operator bool() constexplicit

Tests whether the string has a content.

Note

This is essentially the opposite of empty().

BLString& BLString::operator=(BLString&& other)[1/2]

Move assignment.

Note

The other string is reset by move construction, so it becomes an empty string.

BLString& BLString::operator=(const BLString& other)[2/2]

Copy assignment, performs weak copy of the data held by the other string.

const char& BLString::operator[](size_t index) const

Returns a character at the given index.

Note

This is the same as calling at(index).

BLResult BLString::reset()

Clears the content of the string and releases its data.

After reset the string content matches a default constructed string.

void BLString::swap(BLString& other)

Swaps the content of this string with the other string.

bool BLString::empty() const

Tests whether the string is empty (has no content).

Returns true if the string's length is zero.

const char& BLString::at(size_t index) const

Returns a character at the given index.

Note

Index must be valid and cannot be out of bounds - there is an assertion.

size_t BLString::size() const

Returns the size of the string [in bytes].

size_t BLString::capacity() const

Returns the capacity of the string [in bytes].

const char* BLString::data() const

Returns a pointer to the data of the string.

const char* BLString::begin() const

Returns a pointer to the beginning of string data (iterator compatibility).

const char* BLString::end() const

Returns a pointer to the end of string data (iterator compatibility).

The returned pointer points to the string null terminator.

BLStringView BLString::view() const

Returns the content of the string as BLStringView.

BLResult BLString::clear()

Clears the content of the string without releasing its dynamically allocated data, if possible.

BLResult BLString::shrink()

Shrinks the capacity of the string to match the actual content.

BLResult BLString::reserve(size_t n)

Reserves at least n bytes in the string for further manipulation (most probably appending).

BLResult BLString::resize(size_t n, char fill = '\0')

Resizes the string to n and fills the additional data by fill pattern.

BLResult BLString::makeMutable(char** dataOut)

Makes the string mutable.

This operation checks whether the string is mutable and if not it makes a deep copy of its content so it can be modified. Please note that you can only modify the content that is defined by its length property. Even if the string had higher capacity before makeMutable() it's not guaranteed that the possible new data would match that capacity.

If you want to make the string mutable for the purpose of appending or making other modifications please consider using modifyOp() and insertOp() instead.

BLResult BLString::assign(char c, size_t n = 1)[1/5]

Replaces the content of the string by c character or multiple characters if n is greater than one.

BLResult BLString::assign(BLString&& other)[2/5]

Move assignment, the same as operator=(), but returns a BLResult instead of this.

BLResult BLString::assign(const BLString& other)[3/5]

Copy assignment, the same as operator=(), but returns a BLResult instead of this.

BLResult BLString::assign(BLStringView view)[4/5]

Replaces the string by the content described by the given string view.

BLResult BLString::assign(const char* str, size_t n = SIZE_MAX)[5/5]

Replaces the string by str data of the given length n.

Note

The implementation assumes null terminated string if n equals to SIZE_MAX.

BLResult BLString::assignDeep(const BLString& other)

Copy assignment, but creates a deep copy of the other string instead of weak copy.

template<typename... Args>

BLResult BLString::assignFormat(const char* fmt, Args&&... args)

Replaces the content of the string by a result of calling snprintf(fmt, args...).

BLResult BLString::assignFormatV(const char* fmt, va_list ap)

Replaces the content of the string by a result of calling vsnprintf(fmt, ap).

BLResult BLString::truncate(size_t n)

Truncates the string length to n.

It does nothing if the the string length is less than n.

bool BLString::equals(const BLString& other) const[1/3]

Returns whether this string and other are equal (i.e. their contents match).

bool BLString::equals(BLStringView view) const[2/3]

Returns whether this string and other string view are equal.

bool BLString::equals(const char* str, size_t n = SIZE_MAX) const[3/3]

Returns whether this string and the given string data str of length n are equal.

int BLString::compare(const BLString& other) const[1/3]

Compares this string with other and returns either -1, 0, or 1.

int BLString::compare(BLStringView view) const[2/3]

Compares this string with other string view and returns either -1, 0, or 1.

int BLString::compare(const char* str, size_t n = SIZE_MAX) const[3/3]

Compares this string with other string data and returns either -1, 0, or 1.

size_t BLString::indexOf(char c) const[1/2]

Returns the first index at which a given character c can be found in the string, or SIZE_MAX if not present.

size_t BLString::indexOf(char c, size_t fromIndex) const[2/2]

Returns the index at which a given character c can be found in the string starting from fromIndex, or SIZE_MAX if not present.

size_t BLString::lastIndexOf(char c) const[1/2]

Returns the last index at which a given character c can be found in the string, or SIZE_MAX if not present.

size_t BLString::lastIndexOf(char c, size_t fromIndex) const[2/2]

Returns the index at which a given character c can be found in the string starting from fromIndex and ending at 0, or SIZE_MAX if not present.