# Poco

# template < class T >

# class Buffer

Library: Foundation
Package: Core
Header: Poco/Buffer.h

## Description

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

## Member Summary

Member Functions: append, assign, begin, capacity, capacityBytes, clear, empty, end, operator !=, operator =, operator ==, operator [], resize, setCapacity, size, sizeBytes, swap

## Constructors

### Buffer

Buffer() = delete;

### Buffer

Buffer(
std::size_t length
);

Creates and allocates the Buffer.

### Buffer

Buffer(
const Buffer & other
);

Copy constructor.

### Buffer

Buffer(
Buffer && other
) noexcept;

Move constructor.

### Buffer

Buffer(
T * pMem,
std::size_t length
);

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

Buffer(
const T * pMem,
std::size_t length
);

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.

## Destructor

### ~Buffer

~Buffer();

Destroys the Buffer.

## Member Functions

### append

void append(
const T * buf,
std::size_t sz
);

Resizes this buffer and appends the argument buffer.

### append

void append(
T val
);

Resizes this buffer by one element and appends the argument value.

### append

void append(
const Buffer & buf
);

Resizes this buffer and appends the argument buffer.

### assign

void assign(
const T * buf,
std::size_t sz
);

Assigns the argument buffer to this buffer. If necessary, resizes the buffer.

### begin

T * begin();

Returns a pointer to the beginning of the buffer.

### begin

const T * begin() const;

Returns a pointer to the beginning of the buffer.

### capacity

std::size_t capacity() const;

Returns the allocated memory size in elements.

### capacityBytes

std::size_t capacityBytes() const;

Returns the allocated memory size in bytes.

### clear

void clear();

Sets the contents of the buffer to zero.

### empty

bool empty() const;

Return true if buffer is empty.

### end

T * end();

Returns a pointer to end of the buffer.

### end

const T * end() const;

Returns a pointer to the end of the buffer.

### operator !=

bool operator != (
const Buffer & other
) const;

Compare operator.

### operator =

Buffer & operator = (
const Buffer & other
);

Assignment operator.

### operator =

Buffer & operator = (
Buffer && other
) noexcept;

Move assignment operator.

### operator ==

bool operator == (
const Buffer & other
) const;

Compare operator.

### operator []

T & operator[] (
std::size_t index
);

### operator []

const T & operator[] (
std::size_t index
) const;

### resize

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.

### setCapacity

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.

### size

std::size_t size() const;

Returns the used size of the buffer in elements.

### sizeBytes

std::size_t sizeBytes() const;

Returns the used size of the buffer in bytes.

### swap

void swap(
Buffer & other
) noexcept;

Swaps the buffer with another one.