/src/poco/Foundation/include/Poco/Buffer.h

Source
//
// Buffer.h
//
// Library: Foundation
// Package: Core
// Module:  Buffer
//
// Definition of the Buffer class.
//
// Copyright (c) 2012, Applied Informatics Software Engineering GmbH.
// and Contributors.
//
// SPDX-License-Identifier: BSL-1.0
//


#ifndef Foundation_Buffer_INCLUDED
#define Foundation_Buffer_INCLUDED


#include "Poco/Foundation.h"
#include "Poco/Exception.h"
#include <cstring>
#include <cstddef>


namespace Poco {


template <class T>
class Buffer
  /// A buffer class that allocates a buffer of a given type and size
  /// in the constructor and deallocates the buffer in the destructor.
  ///
  /// This class is useful everywhere where a temporary buffer
  /// is needed.
  ///
  /// Note: A Buffer has both a size and a capacity, similar to
  /// std::vector and std::string. However, upon creation of the
  /// Buffer, the size always equals the capacity (provided via the
  /// length argument of the constructor), as the Buffer is meant
  /// to be filled by directly writing to its contents,
  /// i.e., by passing the pointer to the first element
  /// of the buffer obtained via begin() to a function expecting
  /// a pointer to a buffer.
  ///
  /// Therefore, calling append() on a newly created Buffer will
  /// always expand the buffer size and capacity.
  /// If you need to create a Buffer and want to write data to it
  /// by calling append(), the correct steps are to first create
  /// the Buffer, then call resize(0), and then call append().
{
public:
  Buffer(std::size_t length):
    _capacity(length),
    _used(length),
    _ptr(nullptr),
    _ownMem(true)
    /// Creates and allocates the Buffer.
  {
    if (length > 0)
    {
      _ptr = new T[length];
    }
  }

  Buffer(T* pMem, std::size_t length):
    _capacity(length),
    _used(length),
    _ptr(pMem),
    _ownMem(false)
    /// Creates the Buffer. Length argument specifies the length
    /// of the supplied memory pointed to by pMem in the number
    /// of elements of type T. Supplied pointer is considered
    /// blank and not owned by Buffer, so in this case Buffer
    /// only acts as a wrapper around externally supplied
    /// (and lifetime-managed) memory.
  {
  }

  Buffer(const T* pMem, std::size_t length):
    _capacity(length),
    _used(length),
    _ptr(nullptr),
    _ownMem(true)
    /// Creates and allocates the Buffer; copies the contents of
    /// the supplied memory into the buffer. Length argument specifies
    /// the length of the supplied memory pointed to by pMem in the
    /// number of elements of type T.
  {
    if (_capacity > 0)
    {
      _ptr = new T[_capacity];
      std::memcpy(_ptr, pMem, _used * sizeof(T));
    }
  }

  Buffer(const Buffer& other):
    /// Copy constructor.
    _capacity(other._used),
    _used(other._used),
    _ptr(nullptr),
    _ownMem(true)
  {
    if (_used)
    {
      _ptr = new T[_used];
      std::memcpy(_ptr, other._ptr, _used * sizeof(T));
    }
  }

  Buffer(Buffer&& other) noexcept:
    /// Move constructor.
    _capacity(other._capacity),
    _used(other._used),
    _ptr(other._ptr),
    _ownMem(other._ownMem)
  {
    other._capacity = 0;
    other._used = 0;
    other._ownMem = false;
    other._ptr = nullptr;
  }

  Buffer& operator = (const Buffer& other)
    /// Assignment operator.
  {
    if (this != &other)
    {
      Buffer tmp(other);
      swap(tmp);
    }

    return *this;
  }

  Buffer& operator = (Buffer&& other) noexcept
    /// Move assignment operator.
  {
    if (_ownMem) delete [] _ptr;

    _capacity = other._capacity;
    _used = other._used;
    _ptr = other._ptr;
    _ownMem = other._ownMem;

    other._capacity = 0;
    other._used = 0;
    other._ownMem = false;
    other._ptr = nullptr;

    return *this;
  }

  ~Buffer()
    /// Destroys the Buffer.
  {
    if (_ownMem) delete [] _ptr;
  }

  Buffer() = delete;

  void resize(std::size_t newCapacity, bool preserveContent = true)
    /// Resizes the buffer capacity and size. If preserveContent is true,
    /// the content of the old buffer is copied over to the
    /// new buffer. The new capacity can be larger or smaller than
    /// the current one; if it is smaller, capacity will remain intact.
    /// Size will always be set to the new capacity.
    ///
    /// Buffers only wrapping externally owned storage can not be
    /// resized. If resize is attempted on those, IllegalAccessException
    /// is thrown.
  {
    if (!_ownMem) throw Poco::InvalidAccessException("Cannot resize buffer which does not own its storage.");

    if (newCapacity > _capacity)
    {
      T* ptr = new T[newCapacity];
      if (preserveContent && _ptr)
      {
        std::memcpy(ptr, _ptr, _used * sizeof(T));
      }
      delete [] _ptr;
      _ptr = ptr;
      _capacity = newCapacity;
    }

    _used = newCapacity;
  }

  void setCapacity(std::size_t newCapacity, bool preserveContent = true)
    /// Sets the buffer capacity. If preserveContent is true,
    /// the content of the old buffer is copied over to the
    /// new buffer. The new capacity can be larger or smaller than
    /// the current one; size will be set to the new capacity only if
    /// new capacity is smaller than the current size, otherwise it will
    /// remain intact.
    ///
    /// Buffers only wrapping externally owned storage can not be
    /// resized. If resize is attempted on those, IllegalAccessException
    /// is thrown.
  {
    if (!_ownMem) throw Poco::InvalidAccessException("Cannot resize buffer which does not own its storage.");

    if (newCapacity != _capacity)
    {
      T* ptr = nullptr;
      if (newCapacity > 0)
      {
        ptr = new T[newCapacity];
        if (preserveContent && _ptr)
        {
          std::size_t newSz = _used < newCapacity ? _used : newCapacity;
          std::memcpy(ptr, _ptr, newSz * sizeof(T));
        }
      }
      delete [] _ptr;
      _ptr = ptr;
      _capacity = newCapacity;

      if (newCapacity < _used) _used = newCapacity;
    }
  }

  void assign(const T* buf, std::size_t sz)
    /// Assigns the argument buffer to this buffer.
    /// If necessary, resizes the buffer.
  {
    if (0 == sz) return;
    if (sz > _capacity) resize(sz, false);
    std::memcpy(_ptr, buf, sz * sizeof(T));
    _used = sz;
  }

  void append(const T* buf, std::size_t sz)
    /// Resizes this buffer and appends the argument buffer.
  {
    if (0 == sz) return;
    resize(_used + sz, true);
    std::memcpy(_ptr + _used - sz, buf, sz * sizeof(T));
  }

  void append(T val)
    /// Resizes this buffer by one element and appends the argument value.
  {
    resize(_used + 1, true);
    _ptr[_used - 1] = val;
  }

  void append(const Buffer& buf)
    /// Resizes this buffer and appends the argument buffer.
  {
    append(buf.begin(), buf.size());
  }

  std::size_t capacity() const
    /// Returns the allocated memory size in elements.
  {
    return _capacity;
  }

  std::size_t capacityBytes() const
    /// Returns the allocated memory size in bytes.
  {
    return _capacity * sizeof(T);
  }

  void swap(Buffer& other) noexcept
  /// Swaps the buffer with another one.
  {
    using std::swap;

    swap(_ptr, other._ptr);
    swap(_capacity, other._capacity);
    swap(_used, other._used);
    swap(_ownMem, other._ownMem);
  }

  bool operator == (const Buffer& other) const
    /// Compare operator.
  {
    if (this != &other)
    {
      if (_used == other._used)
      {
        if (_ptr && other._ptr && std::memcmp(_ptr, other._ptr, _used * sizeof(T)) == 0)
        {
          return true;
        }
        else return _used == 0;
      }
      return false;
    }

    return true;
  }

  bool operator != (const Buffer& other) const
    /// Compare operator.
  {
    return !(*this == other);
  }

  void clear()
    /// Sets the contents of the buffer to zero.
  {
    std::memset(_ptr, 0, _used * sizeof(T));
  }

  std::size_t size() const
    /// Returns the used size of the buffer in elements.
  {
    return _used;
  }

  std::size_t sizeBytes() const
    /// Returns the used size of the buffer in bytes.
  {
    return _used * sizeof(T);
  }

  T* begin()
    /// Returns a pointer to the beginning of the buffer.
  {
    return _ptr;
  }

  const T* begin() const
    /// Returns a pointer to the beginning of the buffer.
  {
    return _ptr;
  }

  T* end()
    /// Returns a pointer to end of the buffer.
  {
    return _ptr + _used;
  }

  const T* end() const
    /// Returns a pointer to the end of the buffer.
  {
    return _ptr + _used;
  }

  bool empty() const
    /// Return true if buffer is empty.
  {
    return 0 == _used;
  }

  T& operator [] (std::size_t index)
  {
    poco_assert (index < _used);

    return _ptr[index];
  }

  const T& operator [] (std::size_t index) const
  {
    poco_assert (index < _used);

    return _ptr[index];
  }

private:
  std::size_t _capacity;
  std::size_t _used;
  T*          _ptr;
  bool        _ownMem;
};


} // namespace Poco


#endif // Foundation_Buffer_INCLUDED

Coverage Report

Created: 2025-11-13 07:06