Skip to content

ST::buffer

Jump to bottom
Michael Hansen edited this page Jan 6, 2018 · 24 revisions

ST::buffer<char_T>

Headers

#include <string_theory/char_buffer>

Macros

Name Summary
ST_AUTO_SIZE Special value to indicate that a size should be calculated automatically

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
operator= Assignment operator
operator== Comparison operator
operator!= Comparison operator
data Access the character buffer data
size Return the number of characters stored in the buffer
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== Comparison operator overload
operator!= Comparison operator overload

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 15 char_T code units, plus one for the nul-terminator) will exist purely on the stack with no associated heap data.

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.

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)
  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.

See also operator=()

ST::buffer Destructor

Signature
~buffer<char_T>() 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) (2)
  1. Allocate (uninitialized) storage for size + 1 char_T characters.
  2. Allocate storage for size + 1 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.

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::create_writable_buffer

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.

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.

ST::buffer::empty()

Signature
bool empty() const noexcept (1)
bool is_empty() const noexcept (2)
  1. 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').
  2. Deprecated synonym for empty().

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

See also size()

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: 
    ST::char_buffer buf;
buf = ST::char_buffer();
  2. Copy the contents of copy into the current buffer object.
  3. Move the contents of move into the current buffer object.

See also (constructor)

ST::buffer::operator==

Signature
bool operator==(const null_t &) const noexcept (1)
bool operator==(const buffer<char_T> &other) const noexcept (2)
  1. Returns true if this buffer is 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.

See also operator==()

ST::buffer::operator!=

Signature
bool ST::buffer::operator!=(const null_t &) const noexcept (1)
bool ST::buffer::operator!=(const ST::buffer<char_T> &other) const noexcept (2)
  1. Returns true if this buffer is not empty.
  2. 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.

See also operator!=()

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>

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.

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)

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

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

This is a special type designed to provide a clean and efficient way to construct (or default) empty strings and buffers. Using it is equivalent to using the default constructor, but may be shorter to type or more clear in some situations. Note that for ST::string objects, defaulting to ST::null or ST::string{} will often produce a faster construction than defaulting to "".

Examples

// The following two declarations are equivalent:
ST::string foo = ST::null;
ST::string foo;

void bar(const ST::string &s = ST::null);

ST::operator==

Signature
bool operator==(const null_t &, const ST::buffer<char_T> &right) noexcept

Returns true if right is empty.

See also operator==()

ST::operator!=

Signature
bool operator!=(const null_t &, const ST::buffer<char_T> &right) noexcept

Returns true if right is not empty.

See also operator!=()

Clone this wiki locally