fcppt.container.buffer

Description

A special buffer class for uninitialized memory.

Ordinary arrays in C++ are not default-initialized, which is mostly for performance reasons. This helps in situations where you have to call functions that write into a buffer handed to them, e.g. when reading from a file. If you need a dynamically sized array instead, you could use a std::vector. However, std::vector default-initializes its values.

fcppt::container::buffer::object instead manages a partially uninitialized block of memory: It contains

• a write area, which is uninitialized, and
• a read area that has already been written.

Consider the following example in which the user wants to read 1024 integers from a file stream, using binary I/O. We have to hand a raw buffer to the ifstream::read function that counts sizeof(int) * 1024 bytes. After reading has been done, we check if it succeeded and if it has, we increase the read area size appropriately.

  using buffer_type = fcppt::container::buffer::object<int>;
 
  buffer_type raw_chars{1024};
 
  std::ifstream file{"test_file", std::ios_base::binary};
 
  if (file.read(
          // Hand the beginning of the write area to the read function.
          fcppt::cast::to_char_ptr<char *>(raw_chars.write_data()),
          fcppt::cast::size<std::streamsize>(
              fcppt::cast::to_signed(raw_chars.write_size() * sizeof(int)))))
  {
    // If reading succeeded, we have read gcount bytes and therefore
    // gcount / sizeof(int) integers.
    raw_chars.written(
        fcppt::cast::size<buffer_type::size_type>(fcppt::cast::to_unsigned(file.gcount())) /
        sizeof(int));
  }
 
  std::cout << "Integers read: ";
 
  for (int const value : raw_chars)
  {
    std::cout << value << ", ";
  }
 
  std::cout << '\n';

A buffer can be converted into an fcppt::container::raw_vector::object using fcppt::container::buffer::to_raw_vector. A raw vector acts more like a standard container and is similar to std::vector.

Classes
class	fcppt::container::buffer::object< T, A >
	A contiguous container for uninitialized data that contains a write and a read area. More...

Functions
template<typename T, typename A, typename Function>
fcppt::container::buffer::object< T, A >	fcppt::container::buffer::append_from (fcppt::container::buffer::object< T, A > &&_buffer, typename fcppt::container::buffer::object< T, A >::size_type const _size, Function const &_function)
	Appends to a buffer using a function.
template<typename T, typename A, typename Function>
fcppt::optional::object< fcppt::container::buffer::object< T, A > >	fcppt::container::buffer::append_from_opt (fcppt::container::buffer::object< T, A > &&_buffer, typename fcppt::container::buffer::object< T, A >::size_type const _size, Function const &_function)
	Appends to a buffer using a function which may fail.
template<typename Buffer, typename Function>
Buffer	fcppt::container::buffer::read_from (typename Buffer::size_type const _size, Function const &_function)
	Reads into a buffer using a function.
template<typename Buffer, typename Function>
fcppt::optional::object< Buffer >	fcppt::container::buffer::read_from_opt (typename Buffer::size_type const _size, Function const &_function)
	Reads into a buffer using a function which may fail.
template<typename T, typename A>
fcppt::container::raw_vector::object< T, A >	fcppt::container::buffer::to_raw_vector (fcppt::container::buffer::object< T, A > &&_buffer) noexcept
	Convert a buffer into a raw_vector.

Function Documentation

append_from()

template<typename T, typename A, typename Function>

fcppt::container::buffer::object< T, A > fcppt::container::buffer::append_from	(	fcppt::container::buffer::object< T, A > &&	_buffer,
		typename fcppt::container::buffer::object< T, A >::size_type const	_size,
		Function const &	_function )

Appends to a buffer using a function.

Allocates a write area for _buffer of size _size and then calls _function(_buffer.write_data(),_size). The result of the function is used to expand _buffer's read area size.

Template Parameters

Function

A function callable as size_type (pointer, size_type).

append_from_opt()

template<typename T, typename A, typename Function>

fcppt::optional::object< fcppt::container::buffer::object< T, A > > fcppt::container::buffer::append_from_opt	(	fcppt::container::buffer::object< T, A > &&	_buffer,
		typename fcppt::container::buffer::object< T, A >::size_type const	_size,
		Function const &	_function )

Appends to a buffer using a function which may fail.

Allocates a buffer buf of size _size and then calls _function(buf.write_data(),_size). If the result of the function is nothing, then nothing is returned. Otherwise, The result of the function is used to set buf's read area size.

Template Parameters

Function

A function callable as fcppt::optional::object<size_type> (pointer, size_type).

read_from()

template<typename Buffer, typename Function>

Buffer fcppt::container::buffer::read_from ( typename Buffer::size_type const _size, Function const & _function )

inline

Reads into a buffer using a function.

Allocates a buffer buf of size _size and then calls _function(buf.write_data(),_size). The result of the function is used to set buf's read area size.

Template Parameters

Buffer	An fcppt::container::buffer::object.
Function	A function callable as size_type (pointer, size_type).

read_from_opt()

template<typename Buffer, typename Function>

fcppt::optional::object< Buffer > fcppt::container::buffer::read_from_opt	(	typename Buffer::size_type const	_size,
		Function const &	_function )

Reads into a buffer using a function which may fail.

Allocates a buffer buf of size _size and then calls _function(buf.write_data(),_size). If the result of the function is nothing, then nothing is returned. Otherwise, The result of the function is used to set buf's read area size.

Template Parameters

Buffer	An fcppt::container::buffer::object.
Function	A function callable as fcppt::optional::object<size_type> (pointer, size_type).

to_raw_vector()

template<typename T, typename A>

fcppt::container::raw_vector::object< T, A > fcppt::container::buffer::to_raw_vector ( fcppt::container::buffer::object< T, A > && _buffer )

noexcept

Convert a buffer into a raw_vector.