SC::StringBuilder Struct Reference

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

#include <StringBuilder.h>

Classes
struct	ReplacePair
	Holds a search / replace pair for StringBuilder::appendReplaceMultiple. More...

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
	StringBuilder (Vector< char > &stringData, StringEncoding encoding, Flags flags=DoNotClear)
	Create a StringBuilder that will push to given Vector, with specific encoding. More...
	StringBuilder (String &str, Flags flags=DoNotClear)
	Create a StringBuilder that will push to given String, with specific encoding. More...
template<typename... Types>
bool	format (StringView fmt, Types &&... args)
	Uses StringFormat to format the given StringView against args, replacing destination contents. More...
template<typename... Types>
bool	append (StringView fmt, Types &&... args)
	Uses StringFormat to format the given StringView against args, appending to destination contents. More...
bool	format (StringView text)
	Assigns StringView to destination buffer. More...
bool	append (StringView str)
	Appends StringView to destination buffer. More...
bool	appendReplaceAll (StringView source, StringView occurrencesOf, StringView with)
	Appends source to destination buffer, replacing occurrencesOf StringView with StringView with More...
bool	appendReplaceMultiple (StringView source, Span< const ReplacePair > substitutions)
	Appends source to destination buffer, replacing multiple substitutions pairs. More...
bool	appendHex (Span< const uint8_t > data, AppendHexCase casing)
	Appends given binary data escaping it as hexadecimal ASCII characters. More...

Detailed Description

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

The output can be a SC::Vector (or a SC::SmallVector, see Containers)

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]

SC::StringBuilder::StringBuilder	(	Vector< char > &	stringData,
		StringEncoding	encoding,
		Flags	flags = DoNotClear
	)

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

Parameters

stringData	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]

SC::StringBuilder::StringBuilder	(	String &	str,
		Flags	flags = DoNotClear
	)

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

Parameters

str	Destination buffer where code points will be pushed
flags	Specifies if destination buffer must be emptied or not before pushing

Member Function Documentation

append() [1/2]

template<typename... Types>

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

inline

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.view() == "Salve a tutti!!!");

append() [2/2]

bool SC::StringBuilder::append

(

StringView

str

)

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
	)

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(buffer.view() == "12345678");

appendReplaceAll()

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

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(buffer == "1234 456 1234 10");
    buffer = String();
    SC_TEST_EXPECT(builder.appendReplaceAll("088123", "123", "1"));
    SC_TEST_EXPECT(buffer == "0881");

appendReplaceMultiple()

bool SC::StringBuilder::appendReplaceMultiple	(	StringView	source,
		Span< const ReplacePair >	substitutions
	)

Appends source to destination buffer, replacing multiple substitutions pairs.

Parameters

source	The StringView to be appended
substitutions	For each substitution in the span, the first is searched and replaced with the second.

Returns

true if append succeeded

Example:

    String        buffer(StringEncoding::Utf8);
    StringBuilder sb(buffer);
    SC_TEST_EXPECT(sb.appendReplaceMultiple("asd\\salve\\bas"_u8, {{"asd", "un"}, {"bas", "a_tutti"}, {"\\", "/"}}));
    SC_TEST_EXPECT(buffer == "un/salve/a_tutti");

format() [1/2]

template<typename... Types>

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

inline

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

Template Parameters

Types

Type of Args

Parameters

fmt	The format strings
args	arguments to format

Returns

true if format succeeded

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

format() [2/2]

bool SC::StringBuilder::format

(

StringView

text

)

Assigns StringView to destination buffer.

Parameters

text	StringView to assign to destination buffer

Returns

true if assign succeeded

---

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

• StringBuilder.h