Skip to content

ST::string_stream

Jump to bottom
Michael Hansen edited this page Jan 28, 2020 · 11 revisions

ST::string_stream

Headers

#include <string_theory/string_stream>

Public Functions

Name Summary
(constructor) ST::string_stream constructors
(destructor) ST::string_stream destructor
operator= Move assignment operator
append Directly append some text to the stream
append_char Append one or more copies of a character to the stream
operator<< Stream operator for various formattable types
raw_buffer Retrieve the raw (unterminated) string data pointer
size Return the current size of the stream
to_string Convert the stream data to an ST::string
truncate Reset the stream's size and position to 0
erase Erase characters from the back of the stream

Details

ST::string_stream provides an efficient way to append text and numbers (with limited formatting options) to a memory buffer. The buffer will grow automatically as more text is added. If the data stored in the stream is short enough, it will remain completely on the stack.

The string_stream is particularly useful for building strings incrementally through various pieces that have some sort of logic or looping involved, as it is much more efficient than adding strings with operator+ or operator+=.

Example:

// Slow way -- allocates several "fit length" strings:
ST::string s1 = "There are " + ST::string::from_int(count) + " items in boxes (";
for (auto box : boxes)
    s1 += box + ", ";
s1 = s1.left(s1.size() - 2);  // Erase last comma
s1 += ")";

// Fast way, construct only one string.
ST::string_stream ss;
ss << "There are " << count << " items in boxes (";
for (auto box : boxes)
    ss << box << ", ";
s1.erase(2);  // Erase last comma
ss << ")";
ST::string s2 = ss.to_string();

Note that for more control over formatting, you should use ST::format instead. However, because ST::string_stream can take ST::string objects, it is possible to combine ST::format with ST::string_stream:

ST::string_stream ss;
ss << "Some fancy formatting " << ST::format("{<40x}", number);

Member Documentation

ST::string_stream constructors

Signature
string_stream() noexcept (1)
string_stream(string_stream &&move) noexcept (2)
  1. Creates an empty stream (size() == 0).
  2. Moves the stream content from move into this string_stream.

Note that string_streams are not copyable.

See also operator=()

ST::string_stream destructor

Signature
~string_stream() noexcept

Destroys the string_stream, freeing any allocated memory.

ST::string_stream::append

Signature
string_stream &append(const char *data, size_t size = ST_AUTO_SIZE)

Append the first size bytes of the string data from data to the end of this stream. If size is ST_AUTO_SIZE, then the length of data is determined with strlen.

ST::string_stream::append_char

Signature
string_stream &append(char ch, size_t count = 1)

Append count copies of the character ch to the end of this stream.

ST::string_stream::erase

Signature
void erase(size_t count) noexcept

Remove count bytes from the end of the stream. If count is greater than the current stream size, this will truncate the stream to 0 bytes. This will not cause a buffer reallocation, so it is essentially free to use.

See also size(), truncate()

ST::string_stream::operator=

Signature
string_stream &operator=(string_stream &&move) noexcept

Move operator. Moves the string content from move into this string_stream.

See also (constructor)

ST::string_stream::operator<<

Signature Notes
string_stream &operator<<(const char *text) Expected to be encoded as UTF-8. Must be nul-terminated.
string_stream &operator<<(const wchar_t *text) Must be nul-terminated.

Since string_theory 3.0
string_stream &operator<<(const char8_t *text) Must be nul-terminated.

Since string_theory 3.0
string_stream &operator<<(const char16_t *text) Must be nul-terminated.

Since string_theory 3.0
string_stream &operator<<(const char32_t *text) Must be nul-terminated.

Since string_theory 3.0
string_stream &operator<<(int num)
string_stream &operator<<(unsigned int num)
string_stream &operator<<(long num)
string_stream &operator<<(unsigned long num)
string_stream &operator<<(long long num)
string_stream &operator<<(unsigned long long num)
string_stream &operator<<(float num)
string_stream &operator<<(double num)
string_stream &operator<<(char ch) 7-bit ASCII character or UTF-8 code point
string_stream &operator<<(signed char ch) = delete Disabled to to potential type aliasing. Cast to int instead.

Since string_theory 3.1
string_stream &operator<<(unsigned char ch) = delete Disabled to to potential type aliasing. Cast to unsigned int instead.

Since string_theory 3.1
string_stream &operator<<(const ST::string &text)
string_stream &operator<<(const std::string &text) Expected to be encoded as UTF-8

Since string_theory 3.0
string_stream &operator<<(const std::wstring &text) Since string_theory 3.0
string_stream &operator<<(const std::u8string &text) Since string_theory 3.0
string_stream &operator<<(const std::u16string &text) Since string_theory 3.0
string_stream &operator<<(const std::u32string &text) Since string_theory 3.0
string_stream &operator<<(const std::filesystem::path &path) Since string_theory 3.0
string_stream &operator<<(const std::string_view &text) Expected to be encoded as UTF-8

Since string_theory 3.0
string_stream &operator<<(const std::wstring_view &text) Since string_theory 3.0
string_stream &operator<<(const std::u8string_view &text) Since string_theory 3.0
string_stream &operator<<(const std::u16string_view &text) Since string_theory 3.0
string_stream &operator<<(const std::u32string_view &text) Since string_theory 3.0

Append a UTF-8 representation of the object to the end of this stream. ST::string_stream is designed to be fast, so it does not support the formatting options of ST::format nor any I/O manipulators like those used by std::stringstream.

Numeric types are formatted in signed decimal notation, and floating point values are formatted as if by printf's %g format specifier. For more advanced formatting, you can use ST::format and append the result to the string_stream:

ST::string_stream ss;
ss << "Unformatted: " << 42 << "\n";
ss << "Formatted: " << ST::format("{#x}", 42) << "\n";

Changed in 3.0: Added the std::*string, std::*string_view, and std::filesystem::path overloads. Added C-style string overloads for non const char * string types. Removed single char overload.

ST::string_stream::raw_buffer

Signature
const char *raw_buffer() const noexcept

Return a pointer to the beginning of the stream data. Note that this buffer is NOT nul-terminated, so it should not be used directly in functions that expect C-style strings.

See also size(), to_string()

ST::string_stream::size

Signature
size_t size() const noexcept

Returns the size of the data currently stored in the stream, in bytes.

See also raw_buffer()

ST::string_stream::to_string

Signature
ST::string to_string(bool utf8_encoded = true, ST::utf_validation_t validation = ST::assert_validity) const
ST::string to_string(bool utf8_encoded = true, ST::utf_validation_t validation = ST_DEFAULT_VALIDATION) const

Construct an ST::string object from the string data. This will return a copy of the data in the string (properly nul-terminated), so you can continue to manipulate the string_stream after creating a string.

If utf8_encoded is true, the data in the stream is converted with ST::string::from_utf8 with the specified validation. If false, the data is converted as Latin-1 with ST::string::from_latin_1, and validation is ignored.

Changed in 3.0: The default value for the validation parameter is changed to ST_DEFAULT_VALIDATION

See also raw_buffer()

ST::string_stream::truncate

Signature
void truncate(size_t size = 0) noexcept

This will reset the stream's size to size. If size is greater than the current stream size, this method does nothing. It will not reallocate its internal buffer, so this may be useful when building multiple strings using the same string_stream object to construct multiple strings.

See also size(), erase()

Clone this wiki locally