SCLS Foundation Binary

Presentation

SCLS Foundamental Binary allows the user to do some simple, but secure binary manipulation.</br></br> WARNING : Using binary can cause troubles if you don't know what you do. Be very careful with that.

The "Bytes_Set" class

The main thing about this part of SCLS Foundamental is the "Bytes_Set" class. It represents a class allowing to do some binary manipulation very easily.</br> To be simple, it is a char array enhanced in all points. It can manipulate bytes, convert others types to bytes, extract bytes datas to other types datas, do binary file manipulation... It provides a protection against buffer overflow error (if you use it correctly) and against data loss. It is used in a lot of features in SCLS, and even in others Aster System codes.</br> Some types, like double, need a conversion to another type, with EXACTLY the same bit pattern, but without the same value according to their type. For double, it is converted to an int64_t to be stored, and reconverted to be used.

Bytes_Set methods

The methods are documented in alphabetical order, which may not be their place in the code.</br> Excepting the constructors, which is at the start, and the destructor, at the end.

Bytes_Set()

Most simple Bytes_Set constructor, which does not allocate datas in the memory.
This function was added in the version 0.1 and last edited in the version 0.1.

Bytes_Set(unsigned int new_datas_size)

Advanced Bytes_Set constructor, creating the datas empty of the object of size "new_datas_size".
This function was added in the version 0.1 and last edited in the version 0.1.

Bytes_Set(char* new_datas, unsigned int new_datas_size)

Advanced Bytes_Set constructor, putting the datas of the object to "new_datas" and the size of the datas to "new_datas_size".
This function was added in the version 0.1 and last edited in the version 0.1.

Bytes_Set(const Bytes_Set& byte_set)

Bytes_Set copy constructor, putting the datas of the object to copied "byte_set" datas, same for the size of the datas.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_data(char data)

Add "data" at the end of the datas in the object.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_datas(char* datas_to_add, unsigned int datas_to_add_size)

Add copied "datas_to_add" of size "datas_to_add_size" at the end of the datas in the object.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_datas(const char* datas_to_add, unsigned int datas_to_add_size)

Add copied "datas_to_add" of size "datas_to_add_size" at the end of the datas in the object.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_double(double data, bool big_endian = false)

Add the double "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_float(float data, bool big_endian = false)

Add the float "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.</br> WARNING : for now, this function only convert the float to a double and use "add_double". So, it can occurs to unexpected behaviors in some cases.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_int(int data, bool big_endian = false)

Add the int "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_int64(int64_t data, bool big_endian = false)

Add the int64_t "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_short(short data, bool big_endian = false)

Add the short "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_string(std::string data)

Add the std::string "data" at the end of the datas in the object, by default encoded in UTF-8 (if you well configured your encoder).
This function was added in the version 0.1 and last edited in the version 0.1.

void add_uint(unsigned int data, bool big_endian = false)

Add the unsigned int "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

void add_ushort(unsigned short data, bool big_endian = false)

Add the unsigned short "data" at the end of the datas in the object, in big-endian or not depending to "big_endian" value.
This function was added in the version 0.1 and last edited in the version 0.1.

char* datas() const

Return the datas into the object.
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int datas_size() const

Return the size of the datas into the object.
This function was added in the version 0.1 and last edited in the version 0.1.

char data_at(unsigned int position)

Return the data at the position "position" in the datas.</br> If the position is not in the datas field, the SCLS print function is used to tell it to the user, and the function return 0.</br> It is HIGLY RECOMMENDED to use this function to access datas without the "extract" functions, because it can avoid buffer overflow.
This function was added in the version 0.1 and last edited in the version 0.1.

char extract_data(unsigned int offset = 0)

Extract and return a byte, with a position offset of "offset".
This function was added in the version 0.1 and last edited in the version 0.1.

char* extract_datas(unsigned int extract_size, unsigned int offset = 0, bool inverse = false)

Extract and return a "extract_size" sized amount of data, with a position offset of "offset", inversed or not depending to "inverse".
This function was added in the version 0.1 and last edited in the version 0.1.

double extract_double(unsigned int offset = 0, bool big_endian = false)

Extract and return a double, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

float extract_float(unsigned int offset = 0, bool big_endian = false)

Extract and return a float, with a position offset of "offset", in big_endian or not depending to "big_endian".</br> WARNING : for now, this function only convert the float to a double and use "extract_double". So, it can occurs to unexpected behaviors in some cases.
This function was added in the version 0.1 and last edited in the version 0.1.

int extract_int(unsigned int offset = 0, bool big_endian = false)

Extract and return an int, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

int extract_int64(unsigned int offset = 0, bool big_endian = false)

Extract and return an int64_t, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

short extract_short(unsigned int offset = 0, bool big_endian = false)

Extract and return a short, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

std::string extract_string(unsigned int extract_size, unsigned int offset = 0)

Extract and return a std::string of size "extract_size", with a position offset of "offset".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int extract_uint(unsigned int offset = 0, bool big_endian = false)

Extract and return an unsigned int, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned short extract_ushort(unsigned int offset = 0, bool big_endian = false)

Extract and return an unsigned short, with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void free_memory()

Free the memory of the datas, and reset the datas.</br> If the datas are a "0" pointer, then the memory is freed.
This function was added in the version 0.1 and last edited in the version 0.1.

bool load_from_file(std::string path)

Load the datas of the object from a file at the path "path" and return file is all is good.</br> If the path does not exist, the object is not loaded and "false" is returned.
This function was added in the version 0.1 and last edited in the version 0.1.

void save(std::string path)

Save the datas of the object in a file at the path "path".
This function was added in the version 0.1 and last edited in the version 0.1.

void set_data_at(unsigned int position, char new_data)

Set the data at the position "position" at "new_data".
This function was added in the version 0.1 and last edited in the version 0.1.

~Bytes_Set()

Bytes_Set class destructor, calling the "free_memory" function.
This function was added in the version 0.1 and last edited in the version 0.1.

CRC manipulation

This file contains a way to handle simple CRC manipulation. CRC is an algorithm allowing to check datas, to know if their transmission was successfull or not.</br> The only sized algorithm handled is 32 bits for now. Each algorithm has a name, made to easily use them.</br> If you want more information about CRC, see A PAINLESS GUIDE TO CRC ERROR DETECTION ALGORITHMS.

Built-in algorithms

PNG CRC algorithm

The file has a built-in CRC, called "png", made to use the CRC algorithm of the PNG format.

Functions

bool contains_crc_32b(std::string name)

Returns if the CRC 32 bits algorithm "name" is loaded or not.
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int crc_32b(char* buf, int len, std::string crc_name)

Return the CRC value of the char* "buf" of size "len", with the datas of the loaded CRC_32B_Datas named "name".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int crc_32b(unsigned char* buf, int len, std::string crc_name)

Return the CRC value of the unsigned char* "buf" of size "len", with the datas of the loaded CRC_32B_Datas named "name".
This function was added in the version 0.1 and last edited in the version 0.1.

CRC_32B_Datas* get_crc_32b_data(std::string name)

Returns a pointer to the CRC_32B_Datas named "name".</br> If is does not exists, it returns 0 or it creates it if the name is built-in.
This function was added in the version 0.1 and last edited in the version 0.1.

void make_crc_32b_table(std::string name, unsigned int polymonial, bool reflect_input, bool reflect_output, unsigned int starting_value, unsigned int xor_final)

Create a CRC 32 bits algorithm with the passed values.</br> Each values directly goes into the same named CRC_32B_Datas attribute.
This function was added in the version 0.1 and last edited in the version 0.1.

Hidden things

std::map<std::string, CRC_32B_Datas> _loaded_crc32_algorithms

This variable stores the loaded CRC 32 bits algorithms.</br> It's not recommended to use it directly. Use "get_crc_32b_data" instead.
This function was added in the version 0.1 and last edited in the version 0.1.

Macros

#define PNG_CRC_POLYMONIAL 0x04c11db7

Polymonial of the PNG CRC algorithm.
This function was added in the version 0.1 and last edited in the version 0.1.

Struct CRC_32B_Datas

By default, all the values permit to load the CRC datas of the PNG CRC algorithm.

unsigned int crc_values[256]

All 256 CRC values possible for this algorithm.
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int polymonial

Value of the polymonial of the CRC, by default to PNG_CRC_POLYMONIAL.
This function was added in the version 0.1 and last edited in the version 0.1.

bool reflect_input = true

If the input should be reflected by the algorithm or not.
This function was added in the version 0.1 and last edited in the version 0.1.

bool reflect_output = true

If the output should be reflected by the algorithm or not.
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int starting_value = 0xffffffff

Starting value of the CRC algorithm calculation, by default to a binary full of "1", or an hexadecimal full of "f".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int xor_final = 0xffffffff

Value which the is apply by XOR to the final CRC, by default to a binary full of "1", or an hexadecimal full of "f".
This function was added in the version 0.1 and last edited in the version 0.1.

Binary manipulation

Even if the Bytes_Set class exists, there are some binary manipulation functions. They do the same things that in the Bytes_Set class, but in a less optimized way (even if they are used in the class). Excluding if you have no choice, it is recommended to use the Bytes_Set class instead of this functions.</br> The only thing added only by this part is the reflection feature, allowing to reflect bits into a char, an int, an unsigned char or an unsigned int.

Functions

short extract_2bytes_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract a short from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned short extract_u2bytes_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract an unsigned short from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

int extract_4bytes_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract an int from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned int extract_u4bytes_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract an unsigned int from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

int64_t extract_8bytes_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract an int64_t from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

double extract_double_from_char_array(char* result, unsigned int offset = 0, bool big_endian = false)

Extract a double from the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_2bytes_to_char_array(short n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the short "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_2bytes_to_char_array(unsigned short n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the unsigned short "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_4bytes_to_char_array(int n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the int "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_4bytes_to_char_array(unsigned int n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the unsigned int "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_8bytes_to_char_array(int64_t n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the int64_t "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

void put_8bytes_double_to_char_array(double n, char* result, unsigned int offset = 0, bool big_endian = false)

Put the double "n" in the char array "result", with a position offset of "offset", in big_endian or not depending to "big_endian".
This function was added in the version 0.1 and last edited in the version 0.1.

char reflect_char(char x)

Reflect the char "x" and return it.
This function was added in the version 0.1 and last edited in the version 0.1.

unsigned char reflect_char(unsigned char x)

Reflect the unsigned char "x" and return it.
This function was added in the version 0.1 and last edited in the version 0.1.

int reflect_int(int x)

Reflect the int "x" and return it.
This function was added in the version 0.1 and last edited in the version 0.1.

int reflect_int(unsigned int x)

Reflect the unsigned int "x" and return it.
This function was added in the version 0.1 and last edited in the version 0.1.

Binary file manipulation

Even if the Bytes_Set class exists, there are some binary file manipulation functions. They do the same things that in the Bytes_Set class, but in a less optimized way (even if they are used in the class). Excluding if you have no choice, it is recommended to use the Bytes_Set class instead of this functions.

Functions

void read_file_binary(std::string path, char* datas, unsigned int size, unsigned int start_pos = 0)

Put "size" bytes of the file at the path "path" into the char array "datas", starting at the pos "start_pos" in the file.
This function was added in the version 0.1 and last edited in the version 0.1.

char* read_entire_file_binary(std::string path, unsigned int& total_size)

Put the entire content of the file at the path "path" into the char array returned, and put into the referenced variable "total_size" the size of the datas.
This function was added in the version 0.1 and last edited in the version 0.1.

void write_in_file_binary(std::string path, char* to_write, unsigned int size, std::ios::openmode opening_mode = std::ios::out | std::ios::binary)

Write "size" bytes of the char array "to_write", in the file at the path "path", opened with the mode defined by "opening_mode".
This function was added in the version 0.1 and last edited in the version 0.1.

Code specification

This file define the macro "SCLS_FOUNDATION_BINARY".