class::var::Data

class var::Data
  : public var::DataReference

The Data class inherits DataReference and adds dynamic memory allocation so both the reference and the target data are managed by the same class.

//md2code:include
#include <sapi/var.hpp>
//md2code:main

//allocation 64 bytes
Data block = Data( arg::Size(64) );

//use DataReference inherited methods
block.fill<u32>(0xaabbccdd);
printf("First Byte: 0x%x\n",
  block.at_const_char(
    arg::Position(0)
    )
  );

printf("Second Word: 0x%lx\n",
  block.at_u32(
    arg::Position(1)
    )
  );

//once ~Data() is called the memory is freed

Data objects can also act just like references without managing the memory internally.

//md2code:include
#include <sos/dev/pio.h>
//md2code:main
pio_attr_t pio_attributes;

Data data;
data.refer_to(pio_attributes);

if( data.is_reference() == true ){
  printf("this will print\n");
}

data.allocate( arg::Size(64) );

if( data.is_reference() == true ){
  printf("this won't print\n");
}

Summary

Data()

Data(

const Data & a
)

Data(

Data && a
)

Data(

const arg::Size size
)

virtual ~Data()

int allocate(

const arg::Size size,
const arg::IsResize is_resize
)

int append(

const arg::SourceData & a
)

template<>
int append(

const T & value
)

u32 capacity() const

int copy_contents(

const arg::SourceData a,
const arg::Size size
)

int copy_contents(

const arg::SourceData a
)

int copy_contents(

const arg::SourceData a,
const arg::Position destination,
const arg::Size size
)

int free()

bool is_reference() const

Data & operator<<(

const DataReference & a
)

Data & operator<<(

u8 a
)

Data & operator<<(

s8 a
)

Data & operator<<(

u16 a
)

Data & operator<<(

s16 a
)

Data & operator<<(

u32 a
)

Data & operator<<(

s32 a
)

Data & operator<<(

u64 a
)

Data & operator<<(

s64 a
)

Data & operator=(

const Data & a
)

Data & operator=(

Data && a
)

int resize(

const arg::ImplicitSize size
)

static u32 minimum_capacity()

static void reclaim_heap_space()

protected void copy_object(

const Data & a
)

protected void move_object(

Data & a
)

protected void set_reference(

const arg::ReadOnlyBuffer read_data,
arg::ReadWriteBuffer write_data,
arg::Size size
)

Members

Data()

Constructs a data object with no data.

The new object has zero size and is not valid.

//md2code:main
Data a;
if( a.size() == 0 ){
  printf("yep!\n");
}

if( a.is_valid() ){
  printf("nope!\n");
}

Data(

const Data & a
)

Constructs a new data object as a copy of another object.

Parameters

  • a The data that will be copied into a new object
//md2code:main
Data a = Data( arg::Size(128) );
a.fill(0);
Data b(a); //b has has a copy of a

Data(

Data && a
)

Constructs a data object by moving the target’s data to this object.

C++ uses this constructor to move data and avoid a malloc/copy/free operation sequence.

This code uses the move operator:

//md2code:main
//data is moved from unnamed object to moved_to_object
Data moved_to_object = Data( arg::Size(64) );

Data(

const arg::Size size
)

Constructs data with dynamically allocated memory with size bytes (resizeable)

Parameters

  • size The number of bytes to allocate

virtual ~Data()

Deconstructs a Data object.

This method will free any data that was allocated dynamically by this object.


int allocate(

const arg::Size size,
const arg::IsResize is_resize
)

Allocates (or reallocates) memory for the Data object.

Parameters

  • size The number of bytes to allocate

  • resize If true, the old data is copied to the new data location

Returns

Zero If the operation was successful and -1 if it failed

If the memory was specified using the set() method or constructed as statically allocated memory, this will return an error.


int append(

const arg::SourceData & a
)

Appends the contents of another data object to this object.

//md2code:main
Data source_data(arg::Size(64));
Data destination_data(arg::Size(64));
source_data.fill<u8>(0x0a);
destination_data.fill<u8>(0x0b);
destination_data.append(
  arg::SourceData(source_data)
  );

template<>

int append(

const T & value
)

Appends an arbitrary type to this data object.

//md2code:main
pio_attr_t pio_attributes;
Data destination_data(arg::Size(64));
destination_data.fill<u8>(0x0b);
destination_data.append(pio_attributes);

u32 capacity() const

Returns the current capacity of the data storage object.

The capacity of the object will always be greater than or equal to size(). When data is allocated, it is allocated in minimum_capacity() blocks. The capacity represents the actual amount of allocatd data in bytes. The size() dictates how many of those allocated bytes are effective.

//md2code:main
Data small_block(arg::Size(1));
printf(
  "Size is %ld, Capacity is %ld\n",
  small_block.size(),
  small_block.capacity()
  );

//size will be one, capacity will be minimum_capacity()

//this will just reassign size without using malloc/free
small_block.allocate(arg::Size(2));

int copy_contents(

const arg::SourceData a,
const arg::Size size
)

Copies the contents of another data object into the memory of this object.

This object will be resized if there is not enough room to fit the contents.

This object’s size won’t necessarily be equal to the copied object’s size.


int copy_contents(

const arg::SourceData a
)

Copies the contents of another data object.


int copy_contents(

const arg::SourceData a,
const arg::Position destination,
const arg::Size size
)

Copies the contents of another data object to this object.

Parameters

  • a The data object whose contents will be copied

  • destination The offset in this object for the copy destination

  • size The number of bytes to copy

Returns

Zero on success or less than zero if memory could not be allocated


int free()

Free the memory associated with this object. This will only perform any operations if the memory was dynamically allocating using this object.

Returns

Zero on success


bool is_reference() const

Returns true if the data refers to another item rather than managing memory dynamically.

//md2code:main

Data data(arg::Size(64));

if( data.is_reference() ){
  printf("this won't print\n");
}

u32 some_value = 64;
data.refer_to(some_value); //64 bytes freed

if( data.is_reference() ){
  printf("this will print: %ld\n",
    data.at_u32(0)
  );
}

Data & operator<<(

const DataReference & a
)


Data & operator<<(

u8 a
)


Data & operator<<(

s8 a
)


Data & operator<<(

u16 a
)


Data & operator<<(

s16 a
)


Data & operator<<(

u32 a
)


Data & operator<<(

s32 a
)


Data & operator<<(

u64 a
)


Data & operator<<(

s64 a
)


Data & operator=(

const Data & a
)

Constant assignment operator.

Parameters

  • a The data to assign to the object.

This works the same as the copy constructor. Data that is internally managed will be newly allocated in this object and copied. If a is externally managed, this object will point to the same data.


Data & operator=(

Data && a
)


int resize(

const arg::ImplicitSize size
)

Resizes the data (equivalent to allocate()).

Parameters

  • size The number of new bytes

Returns

Zero on success or -1 with errno set

This is the same as allocate() with resize set to true


static u32 minimum_capacity()

Returns the minimum data storage size of any Data object.


static void reclaim_heap_space()

Releases heap space back to the stack.

This method uses a special function available only on Stratify OS that tells the malloc/free system to decrease the heap space if the is free’d memory on the top of the heap.


protected void copy_object(

const Data & a
)


protected void move_object(

Data & a
)


protected void set_reference(

const arg::ReadOnlyBuffer read_data,
arg::ReadWriteBuffer write_data,
arg::Size size
)


X

Thanks for Coming!

Subscribe to news and updates