Skip to content

ST::buffer

Jump to bottom
Michael Hansen edited this page Jan 5, 2018 · 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
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.

Member Documentation

ST::buffer Constructors

buffer() noexcept                       // [1]
buffer(const null_t &) noexcept         // [2]
buffer(const buffer<char_T> &copy)      // [3]
buffer(buffer<char_T> &&move)           // [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

~buffer() noexcept

Destroys the buffer, freeing any associated memory.

ST::buffer::at

char_T &at(size_t index)
const char_T &at(size_t index) const

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.

ST::buffer::allocate

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

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

char_T *data() noexcept
const char_T *data() const noexcept

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

ST::buffer::empty()

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. Synonym for empty(). Note that is_empty is deprecated as of string_theory 2.0 and should not be used in new code.

See also size()

ST::buffer::operator=

buffer<char_T> &operator=(const null_t &) noexcept
buffer<char_T> &operator=(const buffer<char_T> &copy)
buffer<char_T> &operator=(buffer<char_T> &&move) noexcept
  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==

bool operator==(const null_t &) const noexcept                          // [1]
bool operator==(const buffer<char_T> &other) const noexcept             // [2]
bool operator==(const null_t &, const buffer<char_T> &right) noexcept   // [3]
  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.
  3. Returns true if right is empty.

ST::buffer::operator!=

bool operator!=(const null_t &) const noexcept
bool operator!=(const buffer<char_T> &other) const noexcept
bool operator!=(const null_t &, const buffer<char_T> &right) noexcept
  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.
  3. Returns true if right is not empty.

ST::buffer::operator[]

char_T &operator[](size_t index) noexcept
const char_T &operator[](size_t index) const noexcept

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

ST::buffer::size

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]

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.

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);
Clone this wiki locally