Skip to content

AString#

Owned UTF-8 string with rich conversion, parsing, and manipulation APIs.

Header:#include <AUI/Common/AString.h>
CMake:aui_link(my_target PUBLIC aui::core)

Detailed Description#

AString is the primary string type in AUI. It inherits from std::string and stores its data as a null-terminated UTF-8 byte sequence, making it fully compatible with standard C++ APIs while adding higher-level functionality.

Encoding model#

All content is stored as UTF-8. Positions and sizes (length(), substr(), insert(), erase(), find()) are measured in bytes, exactly as in std::string. Text-aware operations (trim() with a set of symbols, uppercase(), lowercase()) understand Unicode. To work with positions in terms of characters, use utf8(), which returns an AUtf8View. bytes() gives access to the underlying byte storage.

Construction#

AString can be constructed from any common character type: 

AString a = "hello";    // const char* (UTF-8)
AString b = u8"hello";  // const char8_t* (UTF-8)
AString c = u"hello";   // const char16_t* (UTF-16)
AString d = U"hello";   // const char32_t* (UTF-32)
AString e = AString::fromLatin1("caf\xe9"); // Latin-1 -> UTF-8

Encoding conversion#

Convert to other encodings on demand - the internal UTF-8 storage is never mutated: 

std::u16string utf16 = str.toUtf16();
AByteBuffer raw = str.encode(AStringEncoding::UTF16);

String manipulation#

AString s = "  Hello, World!  ";
s.trim();                        // "Hello, World!"
s.replaceAll("World", "AUI");    // "Hello, AUI!"
auto parts = s.split(", ");      // AStringVector{"Hello", "AUI!"}

Numeric parsing#

Parsing methods return AOptional to signal failure without exceptions: 

AOptional<int32_t>  i = AString("42").toInt();      // 42
AOptional<double>   d = AString("3.14").toDouble(); // 3.14
AOptional<int32_t>  x = AString("bad").toInt();     // nullopt

Numeric formatting#

AString s1 = AString::number(42);     // "42"
AString s2 = AString::number(3.14f);  // "3.14" (trailing zeros stripped)
AString s3 = AString::numberHex(255); // "ff"

Note

For non-owning string references, prefer AStringView. For iterating over individual Unicode code points, use AUtf8View via utf8().

See also: AStringView, AUtf8View, AByteBuffer, AStringVector.

Examples#

examples/7guis/cells/tests/FormulaTests.cpp

7GUIs Cells — Spreadsheet processor (Excel).

    EXPECT_EQ(std::get<double>(formula::evaluate(mSpreadsheet, "0")), 0.0);
}

TEST_F(Cells_Formula, String) {
    EXPECT_EQ(std::get<AString>(formula::evaluate(mSpreadsheet, "test")), "test");
}

TEST_F(Cells_Formula, EConstant) {
    EXPECT_DOUBLE_EQ(std::get<double>(formula::evaluate(mSpreadsheet, "=1")), 1.0);
}
examples/7guis/crud/src/main.cpp

7GUIs CRUD — Create/Read/Update/Delete example.

using namespace declarative;

struct User {
    AProperty<AString> name;
    AProperty<AString> surname;
    APropertyPrecomputed<AString> displayName = [this] { return "{}, {}"_format(name, surname); };
};

class CRUDWindow: public AWindow {
examples/app/minesweeper/src/CellView.cpp

Minesweeper Game — Minesweeper game implementation driven by ass.

                    break;
            }

            context.render.setColor(color);
            context.render.string({getWidth() / 3, (getHeight() - fs.size) / 2 + fs.getAscenderHeight()}, AString::number(count), fs);
        }
    }
}
examples/app/notes/src/main.cpp

Notes App — Note taking app that demonstrates usage of AListModel, AProperty, user data saving and loading.

using namespace declarative;
using namespace ass;

struct Note {
    AProperty<AString> title;
    AProperty<AString> content;
};

AJSON_FIELDS(Note, AJSON_FIELDS_ENTRY(title) AJSON_FIELDS_ENTRY(content))
examples/ui/infinite_lazy_list/src/main.cpp

Infinite Lazy List — Usage of AUI_DECLARATIVE_FOR to make an infinite lazy list.

using namespace ass;
using namespace std::chrono_literals;

struct Item {
    AProperty<AString> value;
};

struct State {
    AProperty<AVector<_<Item>>> items;
    AProperty<bool> needMore = false;
examples/7guis/cells/src/Tokens.h

7GUIs Cells — Spreadsheet processor (Excel).

#include "AUI/Util/ATokenizer.h"

namespace token {
struct Identifier {
    AString name;
};
struct Double {
    double value;
};
struct Semicolon {};   // ;
examples/7guis/cells/src/Functions.h

7GUIs Cells — Spreadsheet processor (Excel).

    AVector<formula::Value> args;
};
using Invocable = std::function<formula::Value(Ctx ctx)>;

const AMap<AString, Invocable>& predefined();
}
examples/7guis/cells/src/AST.cpp

7GUIs Cells — Spreadsheet processor (Excel).

    formula::Value evaluate(const Spreadsheet& ctx) override { return value; }
};

struct StringLiteralNode : INode {
    AString value;
    explicit StringLiteralNode(AString value) : value(std::move(value)) {}
    ~StringLiteralNode() override = default;

    formula::Value evaluate(const Spreadsheet& ctx) override { return value; }
};
examples/7guis/cells/src/Functions.cpp

7GUIs Cells — Spreadsheet processor (Excel).

    }
}
}

const AMap<AString, functions::Invocable>& functions::predefined() {
    static AMap<AString, functions::Invocable> out = {
        { "SUM",
          [](Ctx ctx) {
              double accumulator = 0.0;
              forEachArgAndRangeCell(ctx, [&](const formula::Value& v) {
examples/7guis/cells/src/main.cpp

7GUIs Cells — Spreadsheet processor (Excel).

using namespace ass;

struct State {
    Spreadsheet spreadsheet{glm::uvec2 { 'Z' - 'A' + 1, 100 }};
    AProperty<AString> currentExpression;
};

static _<AView> labelTitle(AString s) {
    return _new<ALabel>(std::move(s)) AUI_OVERRIDE_STYLE {
        Opacity { 0.5f },
examples/7guis/cells/src/Cell.cpp

7GUIs Cells — Spreadsheet processor (Excel).

 */

#include "Cell.h"

AString Cell::columnName(unsigned int index) {
    return AString(U'A') + index;
}
AString Cell::rowName(unsigned int index) {
    return AString::number(index);
}
examples/app/minesweeper/src/NewGameWindow.cpp

Minesweeper Game — Minesweeper game implementation driven by ass.

void NewGameWindow::updateDifficultyLabel() {
    mMines->setMax(mWidth->getValue() * mHeight->getValue() * 3 / 4);
    int difficulty = mWidth->getValue() * mHeight->getValue() / glm::max(mMines->getValue(), int64_t(1));

    AString text = "Difficulty: ";
    switch (difficulty) {
        default:
        case 0:
        case 1:
            text += "very low";
examples/app/fractal/src/JumpToCoordsWindow.cpp

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

    auto im = _new<ATextField>();
    auto scale = _new<ATextField>();

    auto pos = fractalView->getPlotPosition();
    re->setText(AString::number(pos.x));
    im->setText(AString::number(pos.y));
    scale->setText(AString::number(fractalView->getPlotScale()));

    setContents(Vertical {
      _form({
examples/ui/contacts/src/model/Contact.h

AUI Contacts — Usage of AUI_DECLARATIVE_FOR to make a contacts-like application.

#include <AUI/Common/AObject.h>
#include "AUI/Common/AProperty.h"

struct Contact {
    AProperty<AString> displayName;
    AProperty<AString> phone;
    AProperty<AString> address;
    AProperty<AString> email;
    AProperty<AString> homepage;
    AProperty<AString> note;
examples/ui/contacts/src/view/ContactDetailsView.cpp

AUI Contacts — Usage of AUI_DECLARATIVE_FOR to make a contacts-like application.

namespace {
_<AView> profilePhoto(const _<Contact>& contact) {
    return Centered {
        Label {
          AUI_REACT(contact->displayName->empty() ? "?" : AString(1, contact->displayName->first()).uppercase())
        } AUI_OVERRIDE_STYLE { Opacity(0.5f), FontSize { 32_dp } },
    } AUI_OVERRIDE_STYLE {
        FixedSize { 64_dp },
        BorderRadius { 32_dp },
        BackgroundGradient { AColor::GRAY.lighter(0.5f), AColor::GRAY, 163_deg },
examples/ui/contacts/src/view/ContactDetailsView.h

AUI Contacts — Usage of AUI_DECLARATIVE_FOR to make a contacts-like application.

    template<typename T>
    _<AView> presentation(AProperty<T>& property);

    template<typename T>
    _<AView> row(AString title, AProperty<T>& property);

    void drop();
    void toggleEdit();
};
examples/ui/views/src/DemoListModel.h

Views Example — All-in-one views building example.

#include <AUI/Common/AString.h>
#include <AUI/Model/IListModel.h>


class DemoListModel: public IListModel<AString> {
private:
    size_t mListSize = 3;

public:
    ~DemoListModel() override = default;
examples/ui/views/src/DemoListModel.cpp

Views Example — All-in-one views building example.

size_t DemoListModel::listSize() {
    return mListSize;
}

AString DemoListModel::listItemAt(const AListModelIndex& index) {
    return "List item #{}"_format(index.getRow() + 1);
}

void DemoListModel::addItem() {
    mListSize += 1;

Public Methods#

bytes#

constexpr bytes_type& AString::bytes()

Returns a view of the raw UTF-8 encoded byte data. See also: encode.

Examples:

examples/7guis/flight_booker/src/main.cpp

7GUIs Flight Booker — Flight Booker.

auto formatDate(system_clock::time_point date) { return "{0:%d}.{0:%m}.{0:%G}"_format(date); }

AOptional<system_clock::time_point> parseDate(AStringView s) {
    auto std = s.bytes();
    auto match = REGEX_DATE.match(std);
    if (!match) {
        return std::nullopt;
    }
    year_month_day ymd(

constexpr const bytes_type& AString::bytes()

Returns a view of the raw UTF-8 encoded byte data. See also: encode.

Examples:

encode#

AByteBuffer AString::encode(AStringEncoding encoding)

Encodes the string into a null-terminated byte buffer using the specified encoding. See also: bytes, toUtf16, toUtf32.

resizeToNullTerminator#

void AString::resizeToNullTerminator()

Resizes the string to the length of its null-terminated content while preserving capacity. See also: shrink_to_fit.

substr#

AStringView AString::substr(size_type pos = 0, size_type count = npos)

Returns a substring [pos, pos + count).

Arguments
pos
The starting position of the substring.
count
The number of bytes to include in the substring. If the requested substring extends past the end of the string, i.e. the count is greater than `size() - pos` (e.g. if `count == npos`), the returned substring is `[pos, size())`. `pos` and `count` are interpreted as byte positions. Be careful not to cut a multibyte character in half; use `utf8().substr()` to count in Unicode characters.

toBool#

bool AString::toBool()

Converts the string to boolean value.

Returns
If the string equals to "true", true returned, false otherwise.

toDouble#

AOptional<double> AString::toDouble()

Converts the string to a double number.

Returns
The string converted to a double number. If conversion to int is not possible, nullopt is returned.

Examples:

examples/7guis/cells/src/Formula.cpp

7GUIs Cells — Spreadsheet processor (Excel).

formula::Precompiled formula::precompile(const AString& expression) {
    if (expression.empty()) {
        return [](const Spreadsheet&) { return std::nullopt; };
    }
    if (auto d = expression.toDouble()) {
        return [d = *d](const Spreadsheet&) { return d; };
    }
    if (!expression.startsWith('=')) {
        return [stringConstant = expression](const Spreadsheet&) { return stringConstant; };
    }

toFloat#

AOptional<float> AString::toFloat()

Converts the string to a float number.

Returns
The string converted to a float number. If conversion to int is not possible, nullopt is returned.

toInt#

AOptional<int32_t> AString::toInt()

Converts the string to int value.

Returns
The string converted to an integer value using base 10. If the string starts with 0x or 0X, the base 16 used. If conversion to int is not possible, nullopt is returned.

toLong#

AOptional<int64_t> AString::toLong()

Converts the string to long value.

Returns
The string converted to an integer value using base 10. If the string starts with 0x or 0X, the base 16 used. If conversion to long is not possible, nullopt is returned.

toNumber#

AOptional<int> AString::toNumber(aui::ranged_number<int, 2, 36> base)

Returns the string converted to an int using base. Returns std::nullopt if the conversion fails. See also: toNumberOrException.

toStdString#

std::string& AString::toStdString()

Compatibility method. Guarantees std::string with UTF-8 See also: bytes.

Examples:

const std::string& AString::toStdString()

Compatibility method. Guarantees std::string with UTF-8 See also: bytes.

Examples:

toUInt#

AOptional<uint32_t> AString::toUInt()

Converts the string to unsigned int value.

Returns
The string converted to an integer value using base 10. If the string starts with 0x or 0X, the base 16 used. If conversion to unsigned int is not possible, exception is thrown.

toULong#

AOptional<uint64_t> AString::toULong()

Converts the string to unsigned long value.

Returns
The string converted to an integer value using base 10. If the string starts with 0x or 0X, the base 16 used. If conversion to unsigned long is not possible, exception is thrown.

toUtf16#

std::u16string AString::toUtf16()

Encodes the UTF-8 string into a UTF-16 string See also: bytes, encode.

toUtf32#

std::u32string AString::toUtf32()

Encodes the UTF-8 string into a UTF-32 string See also: bytes, encode.