SC::StringBuilder Struct Reference

Builds String out of a sequence of StringView or formatting through StringFormat. More...

#include <StringBuilder.h>

Public Types
enum	Flags {   Clear ,   DoNotClear }
	Clearing flags used when initializing destination buffer. More...
enum class	AppendHexCase {   UpperCase ,   LowerCase }
	Option for StringBuilder::appendHex. More...

Public Member Functions
template<typename T >
	StringBuilder (T &buffer, StringEncoding encoding, Flags flags=DoNotClear)
	Create a StringBuilder that will push to given Buffer, with specific encoding.
template<typename T >
	StringBuilder (T &string, Flags flags=DoNotClear)
	Create a StringBuilder that will push to given Buffer, with specific encoding.
	StringBuilder (IGrowableBuffer &bufferT, StringEncoding encoding, Flags flags)
StringView	finalize ()
	Finalizes building the string and returns a StringView with the contents.
StringView	view ()
	Obtains view after finalize has been previously called.
template<typename... Types>
bool	append (StringView fmt, Types &&... args)
	Uses StringFormat to format the given StringView against args, appending to destination contents.
bool	append (StringView str)
	Appends StringView to destination buffer.
bool	appendReplaceAll (StringView source, StringView occurrencesOf, StringView with)
	Appends source to destination buffer, replacing occurrencesOf StringView with StringView with
bool	appendHex (Span< const uint8_t > data, AppendHexCase casing)
	Appends given binary data escaping it as hexadecimal ASCII characters.

Static Public Member Functions
template<typename T , typename... Types>
static bool	format (T &buffer, StringView fmt, Types &&... args)
	Uses StringFormat to format the given StringView against args, replacing destination contents.
template<typename T >
static bool	format (T &buffer, StringView text)
	Assigns StringView to destination buffer.

Detailed Description

Builds String out of a sequence of StringView or formatting through StringFormat.

The output can be a SC::Buffer or a SC::SmallBuffer (see Foundation) One can do a:

• One-shot StringBuilder::format
• Create a StringBuilder object and do multiple appends + StringBuilder::finalize

Member Enumeration Documentation

AppendHexCase

enum class SC::StringBuilder::AppendHexCase

strong

Option for StringBuilder::appendHex.

Flags

enum SC::StringBuilder::Flags

Clearing flags used when initializing destination buffer.

Enumerator
Clear	Destination buffer will be cleared before pushing to it.
DoNotClear	Destination buffer will not be cleared before pushing to it.

Constructor & Destructor Documentation

StringBuilder() [1/2]

template<typename T >

SC::StringBuilder::StringBuilder ( T & buffer, StringEncoding encoding, Flags flags = DoNotClear )

inline

Create a StringBuilder that will push to given Buffer, with specific encoding.

Parameters

buffer	Destination buffer where code points will be pushed
encoding	The encoding to be used
flags	Specifies if destination buffer must be emptied or not before pushing

StringBuilder() [2/2]

template<typename T >

SC::StringBuilder::StringBuilder ( T & string, Flags flags = DoNotClear )

inline

Create a StringBuilder that will push to given Buffer, with specific encoding.

Parameters

string	Destination string that will be filled according to string encoding
flags	Specifies if destination string must be emptied or not before pushing

Member Function Documentation

append() [1/2]

template<typename... Types>

bool SC::StringBuilder::append ( StringView fmt, Types &&... args )

inlinenodiscard

Uses StringFormat to format the given StringView against args, appending to destination contents.

Template Parameters

Types

Type of Args

Parameters

fmt	The format strings
args	arguments to format

Returns

true if format succeeded
Example:

String        buffer(StringEncoding::Ascii); // Or SmallString<N>
StringBuilder builder(buffer);
SC_TRY(builder.append("Salve"));
SC_TRY(builder.append(" {1} {0}!!!", "tutti", "a"));
SC_ASSERT_RELEASE(builder.finalize() == "Salve a tutti!!!");

append() [2/2]

bool SC::StringBuilder::append ( StringView str )

nodiscard

Appends StringView to destination buffer.

Parameters

str	StringView to append to destination buffer

Returns

true if append succeeded

appendHex()

bool SC::StringBuilder::appendHex ( Span< const uint8_t > data, AppendHexCase casing )

nodiscard

Appends given binary data escaping it as hexadecimal ASCII characters.

Parameters

data	Binary data to append to destination buffer
casing	Specifies if it should be appended using upper case or lower case

Returns

true if append succeeded

Example:

    uint8_t bytes[4] = {0x12, 0x34, 0x56, 0x78};
 
    String        buffer;
    StringBuilder builder(buffer);
    SC_TEST_EXPECT(builder.appendHex({bytes, sizeof(bytes)}, StringBuilder::AppendHexCase::UpperCase));
    SC_TEST_EXPECT(builder.finalize() == "12345678");

appendReplaceAll()

bool SC::StringBuilder::appendReplaceAll ( StringView source, StringView occurrencesOf, StringView with )

nodiscard

Appends source to destination buffer, replacing occurrencesOf StringView with StringView with

Parameters

source	The StringView to be appended
occurrencesOf	The StringView to be searched inside source
with	The replacement StringView to be written in destination buffer

Returns

true if append succeeded

Example:

    String buffer(StringEncoding::Ascii);
    {
        StringBuilder builder(buffer);
        SC_TEST_EXPECT(builder.appendReplaceAll("123 456 123 10", "123", "1234"));
        SC_TEST_EXPECT(builder.finalize() == "1234 456 1234 10");
    }
    buffer = String();
    {
        StringBuilder builder(buffer);
        SC_TEST_EXPECT(builder.appendReplaceAll("088123", "123", "1"));
        SC_TEST_EXPECT(builder.finalize() == "0881");
    }

finalize()

StringView SC::StringBuilder::finalize

(

)

Finalizes building the string and returns a StringView with the contents.

format() [1/2]

template<typename T , typename... Types>

bool SC::StringBuilder::format ( T & buffer, StringView fmt, Types &&... args )

inlinestaticnodiscard

Uses StringFormat to format the given StringView against args, replacing destination contents.

Template Parameters

Types

Type of Args

Parameters

buffer	The destination buffer that will hold the result of format
fmt	The format strings
args	arguments to format

Returns

true if format succeeded

String buffer(StringEncoding::Ascii); // Or SmallString<N>
SC_TRY(StringBuilder::format(buffer, "[{1}-{0}]", "Storia", "Bella"));
SC_ASSERT_RELEASE(buffer.view() == "[Bella-Storia]");

format() [2/2]

template<typename T >

bool SC::StringBuilder::format ( T & buffer, StringView text )

staticnodiscard

Assigns StringView to destination buffer.

Parameters

buffer	The destination buffer that will hold the result of format
text	StringView to assign to destination buffer

Returns

true if assign succeeded

view()

StringView SC::StringBuilder::view ( )

nodiscard

Obtains view after finalize has been previously called.

Warning

Calling this method before finalize() will assert

---

The documentation for this struct was generated from the following file:

• StringBuilder.h