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 can hold arbitrary byte sequence and act as a raw byte-string when this functionality is required.

Member Functions

Construction & Destruction
Overloaded Operators
Common Functionality
Accessors
String Manipulation
Equality & Comparison
Search

Static Functions

Additional Inherited Members

- Public Attributes inherited from BLStringCore

Constructor & Destructor Documentation

BLString::BLString()[1/6]

Creates a default constructed string.

Default constructed strings share a built-in "none" instance.

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

Move constructor.

Note
The other string is reset by move construction, so its state after the move operation is the same as a default constructed string.

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

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

BLString::BLString(BLStringImpl* impl)explicit[4/6]

Constructor that creates a string from the given impl.

Note
The reference count of the passed impl is not increased.

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

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. The only way to check whether the string allocation failed is to call isNone() after the string has been constructed. If size is non-zero and isNone() returns true then the initialization failed on out of memory condition.

BLString::BLString(const BLStringView& view)explicit[6/6]

Constructor that creates a string from the given string view.

Note
See other constructors for more details.

BLString::~BLString()

Destroys the string.

Member Function Documentation

BLString::operator bool() constexplicit

Tests whether the string has any 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 assignment, so its state after the move operation is the same as a default constructed 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.

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(const 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).

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, otherwise the result is undefined and would trigger an assertion failure in debug mode.

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 null terminator, the data still can be read, but it's not considered as string data by Blend2D anymore.

const 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::truncate(size_t n)

Truncates the string length to n.

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

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.

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(const 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(const 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.