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

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)

Member Enumeration Documentation

◆ AppendHexCase

◆ 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 ( Buffer & stringData,
StringEncoding encoding,
Flags flags = DoNotClear )

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

Parameters
stringDataDestination buffer where code points will be pushed
encodingThe encoding to be used
flagsSpecifies 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
strDestination buffer where code points will be pushed
flagsSpecifies 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 )
inlinenodiscard

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

Template Parameters
TypesType of Args
Parameters
fmtThe format strings
argsarguments 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!!!");
#define SC_ASSERT_RELEASE(e)
Assert expression e to be true.
Definition Assert.h:66
#define SC_TRY(expression)
Checks the value of the given expression and if failed, returns this value to caller.
Definition Result.h:48
@ Ascii
Encoding is ASCII.
Builds String out of a sequence of StringView or formatting through StringFormat.
Definition StringBuilder.h:16
A non-modifiable owning string with associated encoding.
Definition String.h:29

◆ append() [2/2]

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

Appends StringView to destination buffer.

Parameters
strStringView 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
dataBinary data to append to destination buffer
casingSpecifies 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 )
nodiscard

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

Parameters
sourceThe StringView to be appended
occurrencesOfThe StringView to be searched inside source
withThe 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 )
nodiscard

Appends source to destination buffer, replacing multiple substitutions pairs.

Parameters
sourceThe StringView to be appended
substitutionsFor 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 )
inlinenodiscard

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

Template Parameters
TypesType of Args
Parameters
fmtThe format strings
argsarguments 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)
nodiscard

Assigns StringView to destination buffer.

Parameters
textStringView to assign to destination buffer
Returns
true if assign succeeded

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