PByteArray Class Reference

Detailed Description

The PByteArray class represents a resizable array of bytes.

Index of the first element of a PByteArray is 0.

PByteArray offers all standard methods of a dynamic bytes array.

Definition at line 40 of file PByteArray.h.

#include <PByteArray.h>

Constructor & Destructor Documentation

◆ PByteArray() [1/5]

PByteArray::PByteArray ( )

Constructs an empty byte array.

◆ PByteArray() [2/5]

PByteArray::PByteArray ( papillon::int32  capacity)
explicit

Constructs an empty byte array with the specified capacity.

◆ PByteArray() [3/5]

PByteArray::PByteArray ( const void *  buffer,
papillon::int32  numBytes 
)
explicit

Constructs a byte array by copying the given buffer.

◆ PByteArray() [4/5]

PByteArray::PByteArray ( const std::vector< papillon::uint8 > &  array)
explicit

Constructs a byte array by copying the specified std::vector.

◆ PByteArray() [5/5]

PByteArray::PByteArray ( const PByteArray other)

Constructs a shared copy of other.

See also
Clone()

◆ ~PByteArray()

virtual PByteArray::~PByteArray ( )
virtual

Destroys this object.

Member Function Documentation

◆ Append()

PByteArray& PByteArray::Append ( const PByteArray other)

Appends the specified array to this array (merge).

This increases the container size by other.Size(), which causes an automatic reallocation of the allocated storage space if -and only if- the new array size surpasses the current array capacity.

Returns this result itself, for chaining.

◆ AsConstPtr()

template<typename T >
const T* PByteArray::AsConstPtr ( papillon::int32  offsetInBytes = 0) const
inline

UNSAFE: returns a raw pointer to read values stored in this array, starting at the specified offset, in bytes (0 by default).

Returns NULL if index is invalid.

WARNING: the pointer becomes invalid when the array is reallocated.

Definition at line 382 of file PByteArray.h.

◆ AsPtr()

template<typename T >
T* PByteArray::AsPtr ( papillon::int32  offsetInBytes = 0)
inline

UNSAFE: returns a raw pointer to read/write values stored in this array, starting at the specified offset, in bytes (0 by default).

Returns NULL if the specified offset is invalid.

WARNING: the pointer becomes invalid when the array is reallocated.

Definition at line 368 of file PByteArray.h.

◆ c_str()

const char* PByteArray::c_str ( ) const

UNSAFE: returns a raw pointer to read values stored in this array.

WARNING:

  • The pointer becomes invalid when the array is reallocated.
  • The buffer might NOT be zero terminated. If you need to retrieve a zero terminated string from this buffer, do not forget to make sure there is a 0-character at the end of your buffer first. E.g. with PByteArray::PushBack(0)

◆ Capacity()

papillon::int32 PByteArray::Capacity ( ) const

Returns the size of the storage space currently allocated for this array, expressed in terms of bytes.

This capacity is not necessarily equal to the Size(). It can be equal or greater, with the extra space allowing to accommodate for growth without the need to reallocate on each insertion.

◆ Clear()

void PByteArray::Clear ( )

Removes all elements from this array, leaving the container with a size of 0.

A reallocation is not guaranteed to happen, and the array capacity is not guaranteed to change due to calling this method. A typical alternative that forces a reallocation is to use Swap().

◆ Clone()

PByteArray PByteArray::Clone ( ) const

Returns a deep copy of this byte array.

See also
Clone()

◆ CopyFromRawBuffer()

PResult PByteArray::CopyFromRawBuffer ( const void *  sourceBuffer,
papillon::int32  destinationOffset,
papillon::int32  numBytes 
)

UNSAFE: Copies a subpart of the specified raw buffer to this byte array.

Returns PResult::C_OK if success, another result otherwise.

◆ CopyToRawBuffer()

papillon::PResult PByteArray::CopyToRawBuffer ( void *  destinationBuffer,
int32  sourceOffset,
papillon::int32  numBytes 
)

UNSAFE: Copies a subpart of this byte array to the specified raw buffer.

Returns PResult::C_OK if success, another result otherwise, e.g. not enough data to copy.

◆ CRC16()

papillon::uint16 PByteArray::CRC16 ( ) const

Returns the CRC-16 checksum of this buffer.

CRC16 is an error-detecting code.

◆ DecodeFromBase64()

static PByteArray PByteArray::DecodeFromBase64 ( const PByteArray base64)
static

Returns a decoded copy of the Base64 array base64.

Input is not checked for validity; invalid characters in the input are skipped, enabling the decoding process to continue with subsequent characters. The algorithm used to decode Base64-encoded data is defined in RFC 4648.

◆ EncodeToBase64()

PByteArray PByteArray::EncodeToBase64 ( ) const

Returns a copy of the byte array encoded as Base64.

The algorithm used to Base64-encoded data is defined in RFC 4648.

◆ Fill()

void PByteArray::Fill ( papillon::uint8  value)

Fills this array with the specified byte (Size() bytes are set to 'value').

◆ FromFile()

PResult PByteArray::FromFile ( const PString filename)

Reads the specified binary file and put its content into this buffer.

The buffer is cleared if any error occurs. Returns PResult::C_OK if success, another result otherwise.

◆ FromString()

static PResult PByteArray::FromString ( const PString s,
PByteArray a 
)
static

Parses the specified string to build the related PByteArray.

(FromString is a named constructor). Assumes the string has been generated by ToString(). Returns PResult::C_OK if success, another result otherwise. In case of failure, the output PByteArray is cleared.

See also
ToString()

◆ Get()

papillon::int32 PByteArray::Get ( papillon::int32  index) const

Returns the byte (8-bit unsigned int) stored at the specified index, (absolute Get method for reading) or -1 if the index is invalid.

◆ Insert()

PResult PByteArray::Insert ( papillon::int32  index,
const PByteArray ba 
)

Inserts the specified byte array at index position i.

Returns PResult::C_OK if success, another result otherwise (e.g. invalid index).

◆ IsEmpty()

bool PByteArray::IsEmpty ( ) const

Returns true is this array is empty, false otherwise.

◆ MD5()

PString PByteArray::MD5 ( ) const

Computes the MD5 hash sum of the data contained in this array.

The result is a 32 hexadecimal characters string (e.g. "54b0c58c7ce9f2a8b551351102ee0938"). MD5 is a cryptographic hash function. Note: MD5 of an empty buffer is "d41d8cd98f00b204e9800998ecf8427e"

◆ operator!=()

bool PByteArray::operator!= ( const PByteArray other) const

Returns false if this object is the same than other (same size and same data), true otherwise.

Do not compare capacity (i.e. capacity can be equal).

◆ operator=()

PByteArray& PByteArray::operator= ( const PByteArray other)

Performs a shared copy of other to this object.

See also
Clone()

◆ operator==()

bool PByteArray::operator== ( const PByteArray other) const

Returns true if this object is the same than other (same size and same data), false otherwise.

Do not compare capacity (i.e. capacity can be different).

◆ PopBack()

papillon::uint8 PByteArray::PopBack ( )

Returns and removes the last byte in the array, effectively reducing the container size by one.

Array's current position is decreased by 1 if position was set on last element. If the array is empty, then do nothing and returns 255.

◆ PushBack()

void PByteArray::PushBack ( papillon::uint8  value)

Appends the specified value to this array.

This increases the container size by one, which causes an automatic reallocation of the allocated storage space if -and only if- the new array size surpasses the current array capacity.

◆ PushBackDouble()

void PByteArray::PushBackDouble ( double  value)

Appends the specified 64-bit float value to this array.

This increases the container size by 8 bytes, which causes an automatic reallocation of the allocated storage space if -and only if- the new array size surpasses the current array capacity.

◆ PushBackFloat()

void PByteArray::PushBackFloat ( float  value)

Appends the specified 32-bit float value to this array.

This increases the container size by 4 bytes, which causes an automatic reallocation of the allocated storage space if -and only if- the new array size surpasses the current array capacity.

◆ PushBackInt32()

void PByteArray::PushBackInt32 ( papillon::int32  value)

Appends the specified 32-bit int value to this array.

This increases the container size by 4 bytes, which causes an automatic reallocation of the allocated storage space if -and only if- the new array size surpasses the current array capacity.

◆ Reserve()

PResult PByteArray::Reserve ( papillon::int32  n)

Requests that the array capacity be at least enough to contain n elements.

If n is greater than the current array capacity, the method causes the container to reallocate its storage increasing its capacity to n (or greater).

In all other cases, the function call does not cause a reallocation and the array capacity is not affected.

This method has no effect on the array size and cannot alter its elements.

Returns PResult::C_OK if success, another result otherwise.

See also
Resize()

◆ Resize()

PResult PByteArray::Resize ( papillon::int32  n)

Resizes this array so that it contains n bytes.

Automatic memory reallocation is only performed if n exceeds the current capacity of this buffer.

Do nothing is n is negative.

If n is smaller than the current array size, the content is reduced to its first n elements, removing those beyond.

If n is greater than the current array size, the content is expanded by inserting at the end as many bytes (initialized to 0) as needed to reach a size of n.

If n is also greater than the current container capacity, an automatic reallocation of the allocated storage space takes place.

Notice that this method changes the actual content of the container by inserting or erasing elements from it.

The inner position used for relative access is not changed, except if it is not in the valid range; in this case, the position is clamped.

Returns PResult::C_OK if success, another result otherwise.

See also
Reserve()

◆ Set()

PResult PByteArray::Set ( papillon::int32  index,
papillon::int32  value 
)

Sets the byte (8-bit unsigned int) at the specified index.

Index must be in 0..Size()-1, otherwise Set() will fail (you can use Resize() before to enlarge the container and be sure it contains enough elements). Returns PResult::C_OK if success, another result otherwise (e.g. invalid index).

◆ SHA256()

PString PByteArray::SHA256 ( ) const

Computes the SHA-256 hash sum of the data contained in this array.

The result is a 64 hexadecimal characters string (e.g. "44bd7ae60f478fae1061e11a7739f4b94d1daf917982d33b6fc8a01a63f89c21") SHA256 is a cryptographic hash function.

◆ Size()

papillon::int32 PByteArray::Size ( ) const

Returns the number of bytes contained in this array.

◆ ToFile()

PResult PByteArray::ToFile ( const PString filename) const

Writes this buffer into the specified binary file.

Returns PResult::C_OK if success, another result otherwise.

◆ ToStringBase64()

PString PByteArray::ToStringBase64 ( ) const

Returns a Base64 string representation of the byte array.

The algorithm used to Base64-encoded data is defined in RFC 4648.

◆ Unzip()

PByteArray PByteArray::Unzip ( )

Returns an uncompressed copy (unzip) of the PByteArray.

Returns an empty byte array if data are corrupted.

◆ Zip()

PByteArray PByteArray::Zip ( papillon::int32  compressionLevel = -1)

Returns a compressed copy (zip) of this PByteArray.

The compressionLevel parameter specifies how much compression should be used. Valid values are between 0 and 9, with 9 corresponding to the greatest compression (i.e. smaller compressed data) at the cost of using a slower algorithm. Smaller values (8, 7, ..., 1) provide successively less compression at slightly faster speeds. The value 0 corresponds to no compression at all. The default value is -1, which specifies zlib's default compression.