Sane C++ Libraries
C++ Platform Abstraction Libraries
StringBuilder.h
1// Copyright (c) Stefano Cristiano
2// SPDX-License-Identifier: MIT
3#pragma once
4#include "../Strings/StringConverter.h" // popNullTermIfNotEmpty
5#include "../Strings/StringFormat.h"
6namespace SC
7{
8struct String;
11
16{
18 enum Flags
19 {
21 DoNotClear
22 };
27 StringBuilder(Vector<char>& stringData, StringEncoding encoding, Flags flags = DoNotClear);
28
32 StringBuilder(String& str, Flags flags = DoNotClear);
33
40
48 template <typename... Types>
49 [[nodiscard]] bool format(StringView fmt, Types&&... args);
50
57
67 template <typename... Types>
68 [[nodiscard]] bool append(StringView fmt, Types&&... args);
69
73 [[nodiscard]] bool format(StringView text);
74
78 [[nodiscard]] bool append(StringView str);
79
88 [[nodiscard]] bool appendReplaceAll(StringView source, StringView occurrencesOf, StringView with);
89
92 {
93 StringView searchFor;
95 };
96
104 [[nodiscard]] bool appendReplaceMultiple(StringView source, Span<const ReplacePair> substitutions);
105
107 enum class AppendHexCase
108 {
109 UpperCase,
110 LowerCase,
111 };
119 [[nodiscard]] bool appendHex(Span<const uint8_t> data, AppendHexCase casing);
120
121 private:
122 void clear();
123
124 Vector<char>& stringData;
125 StringEncoding encoding;
126};
128
129} // namespace SC
130
131//-----------------------------------------------------------------------------------------------------------------------
132// Implementations Details
133//-----------------------------------------------------------------------------------------------------------------------
134template <typename... Types>
135inline bool SC::StringBuilder::format(StringView fmt, Types&&... args)
136{
137 clear();
138 return append(fmt, forward<Types>(args)...);
139}
140
141template <typename... Types>
142inline bool SC::StringBuilder::append(StringView fmt, Types&&... args)
143{
145 {
146 return false; // UTF16 format strings are not supported
147 }
148 const bool hadNullTerminator = StringConverter::popNullTermIfNotEmpty(stringData, encoding);
149 // It's ok parsing format string '{' and '}' both for utf8 and ascii with StringIteratorASCII
150 // because on a valid UTF8 string, these chars are unambiguously recognizable
151 StringFormatOutput sfo(encoding, stringData);
152 if (StringFormat<StringIteratorASCII>::format(sfo, fmt, forward<Types>(args)...))
153 {
154 return true;
155 }
156 else
157 {
158 if (hadNullTerminator)
159 {
160 // Even if format failed, let's not leave a broken string without a null-terminator
161 (void)StringConverter::pushNullTerm(stringData, encoding);
162 }
163 return false;
164 }
165}
#define SC_COMPILER_EXPORT
Macro for symbol visibility in non-MSVC compilers.
Definition: Compiler.h:78
StringEncoding
String Encoding (Ascii, Utf8, Utf16)
Definition: StringIterator.h:17
@ Utf16
Encoding is UTF16-LE.
View over a contiguous sequence of items (pointer + size in elements).
Definition: Span.h:20
Holds a search / replace pair for StringBuilder::appendReplaceMultiple.
Definition: StringBuilder.h:92
StringView replaceWith
StringView to be searched for in source string.
Definition: StringBuilder.h:94
Builds String out of a sequence of StringView or formatting through StringFormat.
Definition: StringBuilder.h:16
bool format(StringView fmt, Types &&... args)
Uses StringFormat to format the given StringView against args, replacing destination contents.
Definition: StringBuilder.h:135
Flags
Clearing flags used when initializing destination buffer.
Definition: StringBuilder.h:19
@ Clear
Destination buffer will be cleared before pushing to it.
Definition: StringBuilder.h:20
bool append(StringView str)
Appends StringView to destination buffer.
AppendHexCase
Option for StringBuilder::appendHex.
Definition: StringBuilder.h:108
bool appendHex(Span< const uint8_t > data, AppendHexCase casing)
Appends given binary data escaping it as hexadecimal ASCII characters.
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 format(StringView text)
Assigns StringView to destination buffer.
StringBuilder(String &str, Flags flags=DoNotClear)
Create a StringBuilder that will push to given String, with specific encoding.
StringBuilder(Vector< char > &stringData, StringEncoding encoding, Flags flags=DoNotClear)
Create a StringBuilder that will push to given Vector, with specific encoding.
bool append(StringView fmt, Types &&... args)
Uses StringFormat to format the given StringView against args, appending to destination contents.
Definition: StringBuilder.h:142
Formats String with a simple DSL embedded in the format string.
Definition: StringFormat.h:79
Allows pushing results of StringFormat to a buffer or to the console.
Definition: StringFormat.h:22
A non-modifiable owning string with associated encoding.
Definition: String.h:30
Non-owning view over a range of characters with UTF Encoding.
Definition: StringView.h:47
constexpr StringEncoding getEncoding() const
Get encoding of this StringView.
Definition: StringView.h:93
A contiguous sequence of heap allocated elements.
Definition: Vector.h:51