class::var::DataReference

class var::DataReference
  : public api::WorkObject

The Data Reference class is for referring to data (if that wasn’t obvious from the name).

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

The reference includes a pointer to some data and the size of the data.

This class allows passing the data reference as an argument without passing the size separately. Here is a quick example of how this is useful (and good).

//this is good because you can't mess up the size
int write(const DataReference & data);

//this is not good because you can mess up the size
int write(const void * data, int bytes_in_data);

Now let’s see this in practice.

//md2code:main

File f;
f.open(
  arg::FilePath("/home/test.txt"),
  OpenFlags::append()
  );

u32 data[4];

f.write(
  arg::SourceData(DataReference(data))
  ); //writes 4 * sizeof(u32) bytes
//or
f.write(
  arg::SourceBuffer(data),
  //above cases needn't worry about size
  arg::Size(sizeof(data))
  );

Summary

DataReference()

DataReference(

arg::ReadOnlyBuffer buffer,
arg::Size size
)

DataReference(

arg::ReadWriteBuffer buffer,
arg::Size size
)

template<>
DataReference(

T & item
)

template<>
T & at(

arg::ImplicitPosition position
) const

char & at_char(

arg::ImplicitPosition position
) const

const char at_const_char(

arg::ImplicitPosition position
) const

float at_const_float(

arg::ImplicitPosition position
) const

s16 at_const_s16(

arg::ImplicitPosition position
) const

s32 at_const_s32(

arg::ImplicitPosition position
) const

s64 at_const_s64(

arg::ImplicitPosition position
) const

s8 at_const_s8(

arg::ImplicitPosition position
) const

u16 at_const_u16(

arg::ImplicitPosition position
) const

u32 at_const_u32(

arg::ImplicitPosition position
) const

u64 at_const_u64(

arg::ImplicitPosition position
) const

u8 at_const_u8(

arg::ImplicitPosition position
) const

float & at_float(

arg::ImplicitPosition position
) const

s16 & at_s16(

arg::ImplicitPosition position
) const

s32 & at_s32(

arg::ImplicitPosition position
) const

s64 & at_s64(

arg::ImplicitPosition position
) const

s8 & at_s8(

arg::ImplicitPosition position
) const

u16 & at_u16(

arg::ImplicitPosition position
) const

u32 & at_u32(

arg::ImplicitPosition position
) const

u64 & at_u64(

arg::ImplicitPosition position
) const

u8 & at_u8(

arg::ImplicitPosition position
) const

virtual void clear()

template<>
void fill(

const T & value,
arg::Count count
)

bool is_null() const

bool is_read_only() const

bool is_valid() const

bool operator !=(

const DataReference & a
) const

bool operator==(

const DataReference & a
) const

template<>
void refer_to(

T & item
)

void refer_to(

const arg::ReadOnlyBuffer read_only_data,
arg::Size size
)

void refer_to(

arg::ReadWriteBuffer data,
arg::Size size
)

virtual u32 size() const

void swap_byte_order(

const arg::ImplicitSize size
)

template<>
T * to() const

char * to_char() const

const char * to_const_char() const

const float * to_const_float() const

const s16 * to_const_s16() const

const s32 * to_const_s32() const

const s64 * to_const_s64() const

const s8 * to_const_s8() const

const u16 * to_const_u16() const

const u32 * to_const_u32() const

const u64 * to_const_u64() const

const void * to_const_u8() const

const void * to_const_void() const

float * to_float() const

s16 * to_s16() const

s32 * to_s32() const

s64 * to_s64() const

s8 * to_s8() const

u16 * to_u16() const

u32 * to_u32() const

u64 * to_u64() const

u8 * to_u8() const

void * to_void() const

static void memory_copy(

const arg::SourceBuffer read_data,
arg::DestinationBuffer write_data,
arg::Size size
)

static void memory_set(

arg::DestinationBuffer dest,
arg::CharacterToAssign c,
arg::Size size
)

Members

DataReference()

Constructs an empty data reference.

is_valid() will return false until refer_to() is called.


DataReference(

arg::ReadOnlyBuffer buffer,
arg::Size size
)

Constructs a read-only data reference to buffer with the specified size.

//md2code:main
const char buffer[16] = {0};
DataReference read_only_data =
  DataReference(
    arg::ReadOnlyBuffer(buffer),
    arg::Size(16)
  );

if( read_only_data.to_char() == nullptr ){
  printf("this will print (data is read-only)\n");
}

if( read_only_data.to_const_char() == nullptr ){
  printf("this won't print\n");
}

DataReference(

arg::ReadWriteBuffer buffer,
arg::Size size
)

Constructs a read-write data reference to a buffer with the specified size.

//md2code:main
char buffer[16] = {0};
DataReference read_write_data =
  DataReference(
    arg::ReadWriteBuffer(buffer),
    arg::Size(16)
  );

if( read_write_data.to_char() == nullptr ){
  printf("this won't print\n");
}

if( read_write_data.to_const_char() == nullptr ){
  printf("this won't print\n");
}

template<>

DataReference(

T & item
)

Constructs a read-write data reference to some other item. The target item can be of any type. The size will be figured out.

If the item is a const item, the data reference will be read only.

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

DataReference data_structure(pio_attributes);
data_structure.fill<u8>(0);

if( data_structure.to_void() == (void*)&pio_attributes ){
  printf("this will print\n");
}

template<>

T & at(

arg::ImplicitPosition position
) const

Accesses a value in the data.

If the index exceeds the size of the data, the index is set to 0.

//md2code:main
char buffer[64];
DataReference a(buffer); //a is 64 bytes
a.at<char>(arg::Position(0)) = 'a'; //assign 'a' to the first char location
a.at<u32>(arg::Position(4)) = 0xAAAA5555; //assigns a u32 value assuming a is a u32 array
u32 value = a.at<u32>(arg::Position(4)); //reads a value as if a is a u32 array
printf("value is 0x%lx\n", value);

char & at_char(

arg::ImplicitPosition position
) const


const char at_const_char(

arg::ImplicitPosition position
) const


float at_const_float(

arg::ImplicitPosition position
) const


s16 at_const_s16(

arg::ImplicitPosition position
) const


s32 at_const_s32(

arg::ImplicitPosition position
) const


s64 at_const_s64(

arg::ImplicitPosition position
) const


s8 at_const_s8(

arg::ImplicitPosition position
) const


u16 at_const_u16(

arg::ImplicitPosition position
) const


u32 at_const_u32(

arg::ImplicitPosition position
) const


u64 at_const_u64(

arg::ImplicitPosition position
) const


u8 at_const_u8(

arg::ImplicitPosition position
) const


float & at_float(

arg::ImplicitPosition position
) const


s16 & at_s16(

arg::ImplicitPosition position
) const


s32 & at_s32(

arg::ImplicitPosition position
) const


s64 & at_s64(

arg::ImplicitPosition position
) const


s8 & at_s8(

arg::ImplicitPosition position
) const


u16 & at_u16(

arg::ImplicitPosition position
) const


u32 & at_u32(

arg::ImplicitPosition position
) const


u64 & at_u64(

arg::ImplicitPosition position
) const


u8 & at_u8(

arg::ImplicitPosition position
) const


virtual void clear()

Fill the data with zeros.


template<>

void fill(

const T & value,
arg::Count count
)

Fill the data with the specified value. This will not attempt to write read-only data.

//md2code:main
char buffer[16];

DataReference data_reference(buffer);

data_reference.fill<u8>(0xaa);
data_reference.fill<u32>(0xaabbccdd);
data_reference.fill((u16)0xaa55);

bool is_null() const

Returns true if the data object is not valid.


bool is_read_only() const

Returns true if the data object is read only.


bool is_valid() const

Returns true if the data reference is valid.

If the read and write pointers are both nullptr, this will return false.

//md2code:main
pio_attr_t pio_attributes;

DataReference data_structure;
if( data_structure.is_valid() ){
  printf("this won't print\n");
}

data_structure.refer_to(pio_attributes);

if( data_structure.is_valid() ){
  printf("this will print\n");
}

bool operator !=(

const DataReference & a
) const

Returns true if the contents of the data objects are not the same.


bool operator==(

const DataReference & a
) const

Returns true if the contents of both DataReference objects are the same.


template<>

void refer_to(

T & item
)

Refers to an item.

//md2code:main
pio_attr_t pio_attributes;

DataReference data_structure;
data_structure.refer_to(pio_attributes);
data_structure.fill<u8>(0);

if( data_structure.to_void() == (void*)&pio_attributes ){
  printf("this will print\n");
}

void refer_to(

const arg::ReadOnlyBuffer read_only_data,
arg::Size size
)

Refers to a readonly buffer with the specified size.

//md2code:main
char buffer[16];

DataReference data_reference =
  DataReference(
    arg::ReadOnlyBuffer(buffer),
    arg::Size(16)
  );

if( data_reference.to_void() == nullptr ){
  printf("this will print\n");
}

if( data_reference.to_const_void() == nullptr ){
  printf("this won't print\n");
}

void refer_to(

arg::ReadWriteBuffer data,
arg::Size size
)

Refers to a read-write buffer with the specified size.

//md2code:main
char buffer[16];

DataReference data_reference =
  DataReference(
    arg::ReadWriteBuffer(buffer),
    arg::Size(16)
  );

if( data_reference.to_void() == nullptr ){
  printf("this won't print\n");
}

if( data_reference.to_const_void() == nullptr ){
  printf("this won't print\n");
}

virtual u32 size() const

Returns the effective size of the data.


void swap_byte_order(

const arg::ImplicitSize size
)

Swaps the byte order of the data.

Parameters

  • size 4 to swap as 32-bit words, otherwise swap 16-bit words (default is 4)

If the data is read-only, no change is made and error_number() is set to EINVAL.

On Cortex-M chips this method makes use of the built-in byte swapping instructions (so it is fast).

//md2code:include
#include <sapi/var.hpp>
#include <sapi/hal.hpp>
//md2code:main
char buffer[16];
DataReference data_reference(buffer);

//assume the spi outputs big endian data -- swaps 32-bit words
data_reference.swap_byte_order();
data_reference.swap_byte_order(4); //this is the same as calling swap_byte_order()

//or for swapping bytes in 16-bit words
data_reference.swap_byte_order(2);

template<>

T * to() const

Returns a pointer to the data (read/write) This will return zero if the data is readonly.

//md2code:main
char buffer[64];
DataReference a(buffer); //allocate 64 bytes of data
u32 * value = a.to<u32>(); //casts data as u32*
const u32 * const_value = a.to<const u32>(); //works with read only data
if( value == const_value ){
  printf("prints for read-write objects but not read-only\n");
}

Many common types are implemented as a non-template function.

See to_u8(), to_u16(), to_s32(), etc


char * to_char() const

const char * to_const_char() const

const float * to_const_float() const

const s16 * to_const_s16() const

const s32 * to_const_s32() const

const s64 * to_const_s64() const

const s8 * to_const_s8() const

const u16 * to_const_u16() const

const u32 * to_const_u32() const

const u64 * to_const_u64() const

const void * to_const_u8() const

const void * to_const_void() const

float * to_float() const

s16 * to_s16() const

s32 * to_s32() const

s64 * to_s64() const

s8 * to_s8() const

u16 * to_u16() const

u32 * to_u32() const

u64 * to_u64() const

u8 * to_u8() const

void * to_void() const

static void memory_copy(

const arg::SourceBuffer read_data,
arg::DestinationBuffer write_data,
arg::Size size
)


static void memory_set(

arg::DestinationBuffer dest,
arg::CharacterToAssign c,
arg::Size size
)


X

Thanks for Coming!

Subscribe to news and updates