Skip to content

ST::buffer

Jump to bottom
Michael Hansen edited this page Sep 8, 2021 · 24 revisions

ST::buffer<char_T>

Headers

#include <string_theory/char_buffer>

Template Parameters

Type Description
char_T Character type. Usually one of char, wchar_t, char16_t, or char32_t

Public Types

Member Type Definition
size_type size_t
difference_type ptrdiff_t
value_type char_T
pointer value_type *
const_pointer const value_type *
reference value_type &
const_reference const value_type &
iterator value_type *
const_iterator const value_type *
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>
Type Definition
ST::char_buffer ST::buffer<char>
ST::wchar_buffer ST::buffer<wchar_t>
ST::utf16_buffer ST::buffer<char16_t>
ST::utf32_buffer ST::buffer<char32_t>

Public Functions

Name Summary
(constructor) Constructor for character buffers
(destructor) Destructor for character buffers
compare Compare buffer content lexicographically
compare_n Compare N characters of buffer content lexicographically
operator= Assignment operator
operator==
operator!=
operator<		 Comparison operators
data Access the character buffer data
c_str Get a C-style pointer to the character buffer data
size Return the number of characters stored in the buffer
clear Reset the buffer to the empty state (size() == 0)
empty
is_empty		 Determine if the buffer is empty (size() == 0)
operator[] Direct character access
at Direct character access
front Access the first character in the buffer
back Access the last character in the buffer
begin
cbegin		 Get an iterator to the beginning of the buffer
end
cend		 Get an iterator to the end of the buffer
rbegin
crbegin		 Get a reverse iterator to the beginning of the buffer
rend
crend		 Get a reverse iterator to the end of the buffer
allocate Allocate uninitialized space for the buffer to be filled in
create_writable_buffer Create and return a writable pointer to the buffer
to_std_string Convert the buffer to a std::basic_string<char_T>
view Create a std::string_view of all or part of the buffer
operator std::basic_string_view<char_T> Implicit conversion to std::string_view

Static Public Members

Name Summary
strlen Generic string length utility for templates

Related Non-Members

Name Summary
struct null_t Null type for constructing empty objects efficiently
operator==
operator!=		 Comparison operator overloads
operator"" _stbuf ST::buffer user-defined literal operator

Macros

Name Summary
ST_AUTO_SIZE Special value to indicate that a size should be calculated automatically
ST_CHAR_LITERAL Efficient construction of ST::char_buffer literals
ST_UTF16_LITERAL Efficient construction of ST::utf16_buffer literals
ST_UTF32_LITERAL Efficient construction of ST::utf16_buffer literals
ST_WCHAR_LITERAL Efficient construction of ST::wchar_buffer literals

Details

The ST::buffer<char_T> class provides basic storage for a contiguous sequence of characters. This is used internally by ST::string, as well as a storage area for the various UTF conversion results. It can also be used by itself as a way to store characters in various encodings; for example, ST::wchar_buffer objects may provide convenient storage for Win32 APIs which use the wchar_t variants.

Note that ST::buffer objects are meant to be used primarily as storage, not for string manipulation. You should convert the buffer to an ST::string in order to use the normal string methods on the data. However, when constructing strings from various sources (such as reading from a file), it may be more convenient to create the buffer with the allocate() method, and then fill in the data directly before passing it off to an ST::string.

Unlike ST::string, ST::buffer objects are not necessarily immutable or re-entrant. It is not recommended to share buffer objects across multiple threads without locking.

Implementation Note: ST::buffer is a short-string optimized data type. This means that buffers smaller than the buffer size (currently 11-15 char_T code units depending on the size of char_T, plus one for the nul-terminator) will exist purely on the stack with no associated heap data.

Member Documentation

ST::buffer Constructors

Signature
buffer() noexcept (1)
buffer(const ST::null_t &) noexcept (2)
buffer(const buffer<char_T> &copy) (3)
buffer(buffer<char_T> &&move) noexcept (4)
buffer(const char_T *data, size_t size) (5)
buffer(size_t count, char_T fill) (6)
  1. Default constructor for character buffers. Creates an empty buffer.
  2. Shortcut constructor for empty character buffers. This is equivalent to the empty constructor [1].
  3. Copy constructor. Creates a new buffer with the same contents as copy.
  4. Move constructor. Moves the contents of move into this object.
  5. Creates a new buffer with a copy of the first size characters pointed to by data. This will make a copy of the data buffer, so the original is safe to delete or modify after the object is constructed.
  6. Create a buffer of size count and pre-fill it with the specified fill character.

Changed in 3.0: Added overload #6 to construct a buffer with a fill character.

Changed in 3.4: Deprecated null_t overload.

See also operator=()

ST::buffer Destructor

Signature
~buffer() noexcept

Destroys the buffer, freeing any associated memory.

ST::buffer::at

Signature
char_T &at(size_t index) (1)
const char_T &at(size_t index) const (2)

Returns a reference to the character at position index with bounds checking. If the provided index is >= the buffer's size(), a std::out_of_range exception will be thrown.

Since string_theory 2.0.

ST::buffer::allocate

Signature
void allocate(size_t size) (1)
void allocate(size_t size, int fill)
void allocate(size_t size, char_T fill) 		(2)
  1. Allocate (uninitialized) storage for size char_T characters, plus one space for the terminating nul character.
  2. Allocate storage for size char_T characters and initialize it with the specified fill character.

This method will allocate a new storage buffer within the ST::buffer object, with enough space for the given size plus the terminating nul character. If the buffer already had any existing content, that content will be destroyed.

This is primarily useful in constructing buffers that can be populated from external sources more efficiently than storing the data elsewhere and then converting it to a ST::buffer or ST::string.

Note that unlike create_writable_buffer from string_theory 1.0, this method will nul-terminate the internal buffer, even if the rest of the buffer is left uninitialized as with the first variant.

Example

ST::string read_string(FILE *stream)
{
    ST::char_buffer result;
    uint32_t size;
    size_t nread = fread(&size, sizeof(size), 1, stream);
    assert(nread == sizeof(size));
    result.allocate(size);
    nread = fread(result.data(), sizeof(char), size, stream);
    return ST::string::from_utf8(result);
}

Since string_theory 2.0.

Changed in 3.0: Change type of fill parameter in overload #2 to char_T.

ST::buffer::back

Signature
char_T &back() noexcept (1)
const char_T &back() const noexcept (2)

Returns a reference to the last character in the buffer. If the buffer is empty, this will be a reference to the terminating nul character.

Since string_theory 2.0.

ST::buffer::begin

Signature
iterator begin() noexcept (1)
const_iterator begin() const noexcept (2)
const_iterator cbegin() const noexcept (3)

Return an iterator to the beginning of the buffer.

Since string_theory 2.0.

See also end()

ST::buffer::c_str

Signature
const char_T *c_str() const noexcept (1)
const char_T *c_str(const char_T *substitute) const noexcept (2)

Returns a pointer to the stored character data. This buffer should always be nul-terminated, so it's safe to use in functions which require C-style string buffers.

For variant #2, If this buffer is empty, the pointer provided in substitute will be returned instead.

Since string_theory 2.3.

See also data()

ST::buffer::clear

Signature
void clear() noexcept

Clear the buffer data, resetting this buffer to the empty state.

Since string_theory 3.4

See also empty()

ST::buffer::compare

Signature
static int compare(const char_T *left, size_t lsize, const char_T *right, size_t rsize) noexcept (1)
static int compare(const char_T *left, size_t lsize, const char_T *right, size_t rsize, size_t maxlen) noexcept (2)
int compare(const buffer<char_T> &other) const noexcept (3)
int compare(const char_T *str) const noexcept (4)
  1. Compare two char_T strings lexicographically, in a manner similar to strcmp. The size of both input strings must be known and specified. This function returns a value less than, equal to or greater than 0 depending on the ordering or equality of the inputs. This comparison is safe on strings with embedded nul characters.
  2. Compare two char_T strings lexicographically. This is similar to overload #1, but also takes a maximum number of characters to compare, which may be less than the length of both input strings. This comparison is safe on strings with embedded nul characters.
  3. Compare this buffer to other lexicographically in a manner similar to strcmp. This comparison is safe on buffers with embedded nul characters.
  4. Compare this buffer to str lexicographically in a manner similar to strcmp. The array pointed to by str must be nul-terminated.

Since string_theory 3.0

See also operator==(), operator<(), compare_n()

ST::buffer::compare_n

Signature
int compare_n(const buffer<char_T> &other, size_t count) const noexcept (1)
int compare_n(const char_T *str, size_t count) const noexcept (2)
  1. Compare up to the first count characters of this buffer to other lexicographically in a manner similar to strncmp. This comparison is safe on buffers with embedded nul characters.
  2. Compare up to the first count characters of this buffer to str lexicographically in a manner similar to strncmp. The array pointed to by str must be nul-terminated.

Since string_theory 3.0

See also compare()

ST::buffer::create_writable_buffer [removed]

Signature
char_T *create_writable_buffer(size_t size)

NOTE: This method is deprecated in 2.0 and should not be used in new code. Instead, use allocate() and directly fill in the buffer with the provided accessors.

Deprecated in string_theory 2.0.

Removed in string_theory 3.0.

ST::buffer::data()

Signature
char_T *data() noexcept (1)
const char_T *data() const noexcept (2)

Returns a pointer to the first stored character in the buffer.

Changed in 2.0: Added non-const method.

See also c_str()

ST::buffer::empty()

Signature
bool empty() const noexcept (1)
bool is_empty() const noexcept (2)

Returns true if this buffer is empty (has no characters). Note that even for an empty buffer, the first character pointed to by data() can be accessed, and should be the nul character ('\0').

Changed in 2.0: Added empty() and deprecated is_empty().

Changed in 3.0: Removed is_empty().

See also size(), clear()

ST::buffer::end

Signature
iterator end() noexcept (1)
const_iterator end() const noexcept (2)
const_iterator cend() const noexcept (3)

Return an iterator to the end of the buffer.

Since string_theory 2.0.

See also begin()

ST::buffer::front

Signature
char_T &front() noexcept (1)
const char_T &front() const noexcept (2)

Returns a reference to the first character in the buffer. If the buffer is empty, this will be a reference to the terminating nul character.

Since string_theory 2.0.

ST::buffer::operator=

Signature
buffer<char_T> &operator=(const null_t &) noexcept (1)
buffer<char_T> &operator=(const buffer<char_T> &copy) (2)
buffer<char_T> &operator=(buffer<char_T> &&) noexcept (3)
  1. Assigns an empty buffer to this object. Equivalent to calling clear().
  2. Copy the contents of copy into the current buffer object.
  3. Move the contents of move into the current buffer object.

Changed in 3.4: Deprecated null_t overload.

See also (constructor)

ST::buffer comparison operators

Signature
bool operator==(const null_t &) const noexcept (1)
bool operator==(const buffer<char_T> &other) const noexcept (2)
bool operator!=(const null_t &) const noexcept (3)
bool operator!=(const buffer<char_T> &other) const noexcept (4)
bool operator<(const buffer<char_T> &other) const noexcept (5)
  1. Returns empty().
  2. Returns true if the contents of this buffer are identical to the contents of other. This comparison is safe on buffers with embedded nul characters.
  3. Returns !empty().
  4. Returns true if the contents of this buffer are different from the contents of other. This comparison is safe on buffers with embedded nul characters.
  5. Returns true if the contents of this buffer are lexicographically sorted before other. This comparison is safe on buffers with embedded nul characters.

Changed in 3.0: Added operator<() overload.

Changed in 3.4: Deprecated null_t overloads.

See also operator==(), operator!=(), compare()

ST::buffer::operator[]

Signature
char_T &operator[](size_t index) noexcept (1)
const char_T &operator[](size_t index) const noexcept (2)

Returns a reference to the character at position index with NO bounds checking.

Since string_theory 2.0.

ST::buffer::operator std::basic_string_view<char_T> [removed]

Signature
operator std::basic_string_view<char_T>() const

This operator overload allows implicit conversion of a ST::buffer to a std::string_view into the entire contents of the buffer.

Since string_theory 2.0.

Removed in string_theory 3.0.

ST::buffer::rbegin

Signature
reverse_iterator rbegin() noexcept (1)
const_reverse_iterator rbegin() const noexcept (2)
const_reverse_iterator crbegin() const noexcept (3)

Return a reverse iterator to the reverse-start of the buffer.

Since string_theory 2.0.

See also rend()

ST::buffer::rend

Signature
reverse_iterator rend() noexcept (1)
const_reverse_iterator rend() const noexcept (2)
const_reverse_iterator crend() const noexcept (3)

Return a reverse iterator to the reverse-end of the buffer.

Since string_theory 2.0.

See also rbegin()

ST::buffer::size

Signature
size_t size() const noexcept

Returns the number of char_T character units stored in the buffer, not including the terminating nul ('\0') character.

ST::buffer::strlen [static]

Signature
static size_t strlen(const char_T *buffer)

Returns the number of characters up to but not including the first nul-terminator pointed to by buffer. This is equivalent to the C standard function strlen(), except that it works on arbitrary character types.

ST::buffer::to_std_string

Signature
std::basic_string<char_T> to_std_string() const

Convert this buffer to a std::basic_string type compatible with the buffer's char_T character type. Note that this conversion uses the buffer as-is; that is, it does no encoding or conversion on the buffer data.

Since string_theory 2.0.

ST::buffer::view

Signature
std::basic_string_view<char_T> view(size_t start = 0, size_t length = ST_AUTO_SIZE) const

Return a std::basic_string_view into the buffer's character data.

Since string_theory 2.0.

Related Non-Member Documentation

struct ST::null_t [deprecated]

namespace ST
{
    struct null_t { };
    extern const null_t null;
}

This tag structure is deprecated, and should not be used in new code. Instead of using this object, use the empty constructors (e.g. ST::char_buffer{} or ST::string{}), or the appropriate methods (e.g. ST::string::empty() or ST::string::clear()) for the object.

Deprecated in string_theory 3.4.

Non-member comparison operators for ST::buffer

Signature
bool operator==(const null_t &, const ST::buffer<char_T> &right) noexcept (1)
bool operator!=(const null_t &, const ST::buffer<char_T> &right) noexcept (2)
  1. Returns right.empty().
  2. Returns !right.empty().

Changed in 3.4: Deprecated null_t overloads.

See also operator==(), operator!=()

ST::literals::operator"" _stbuf

using namespace ST::literals;
Signature
ST::char_buffer operator"" _stbuf(const char *str, size_t size) (1)
ST::wchar_buffer operator"" _stbuf(const wchar_t *str, size_t size) (2)
ST::utf16_buffer operator"" _stbuf(const char16_t *str, size_t size) (3)
ST::utf32_buffer operator"" _stbuf(const char32_t *str, size_t size) (4)
ST::char_buffer operator"" _stbuf(const char8_t *str, size_t size) (5)

User-defined literal operator to convert string literals to ST::buffer<T> objects efficiently.

Since: string_theory 2.3.

Changed in 3.0: Moved these to the ST::literals namespace to avoid polluting the global namespace.

See also ST_CHAR_LITERAL(), ST_UTF16_LITERAL(), ST_UTF32_LITERAL(), ST_WCHAR_LITERAL()

Macro Documentation

ST_AUTO_SIZE

#define ST_AUTO_SIZE (static_cast<size_t>(-1))

This value is used specially by a variety of string_theory functions to indicate that a size should be determined automatically instead of by the caller.

For example, when passing arguments to functions that take a C-style string, the ST_AUTO_SIZE parameter will instruct the function to determine the length of the string with ::strlen or equivalent. For functions that take a range of characters, this may indicate to use the remainder of the string after the specified start point rather than the requiring the caller to determine the length.

ST_CHAR_LITERAL(str)

#define ST_CHAR_LITERAL(str)  ...

Construct a ST::char_literal from static string data in an efficient manner.

Since string_theory 2.3.

See also operator"" _stbuf()

ST_UTF16_LITERAL(str)

#define ST_UTF16_LITERAL(str)  ...

Construct a ST::utf16_literal from static string data in an efficient manner.

Since string_theory 2.3.

See also operator"" _stbuf()

ST_UTF32_LITERAL(str)

#define ST_UTF32_LITERAL(str)  ...

Construct a ST::utf32_literal from static string data in an efficient manner.

Since string_theory 2.3.

See also operator"" _stbuf()

ST_WCHAR_LITERAL(str)

#define ST_WCHAR_LITERAL(str)  ...

Construct a ST::wchar_literal from static string data in an efficient manner.

Since string_theory 2.3.

See also operator"" _stbuf()

Clone this wiki locally