Buffer Struct Reference


Public Methods

struct Buffer* Buffer_ctor (struct Buffer *ptr_buffer, size_t size, size_t increment)
struct Buffer* Buffer_ctor_Ex (struct Buffer *ptr_buffer, struct Buffer *templ)
void Buffer_store (struct Buffer *ptr_buffer, void *ptr_data, size_t offset, size_t length)
void Buffer_store_string (struct Buffer *ptr_buffer, char *str, size_t offset)
void* Buffer_load (struct Buffer *ptr_buffer, void *ptr_data, size_t offset, size_t length)
char* Buffer_load_string (struct Buffer *ptr_buffer, char *str, size_t offset, size_t length)
size_t Buffer_get_size (struct Buffer *ptr_buffer)
size_t Buffer_get_allocated_size (struct Buffer *ptr_buffer)
void Buffer_compact (struct Buffer *ptr_buffer)
bool Buffer_set_size (struct Buffer *ptr_buffer, size_t size)
void Buffer_free (struct Buffer *ptr_buffer)
bool Buffer_ensure_size (struct Buffer *ptr_buffer, size_t test_size)
char Buffer_get_char (struct Buffer *ptr_buffer, size_t offset)
void Buffer_set_char (struct Buffer *ptr_buffer, size_t offset, char data)
int Buffer_get_int (struct Buffer *ptr_buffer, size_t offset)
void Buffer_set_int (struct Buffer *ptr_buffer, size_t offset, int data)
long Buffer_get_long (struct Buffer *ptr_buffer, size_t offset)
void Buffer_set_long (struct Buffer *ptr_buffer, size_t offset, long data)
bool Buffer_is_locked (struct Buffer *ptr_buffer)
void* Buffer_lock (struct Buffer *ptr_buffer)
void Buffer_unlock (struct Buffer *ptr_buffer)
void Buffer_dtor (struct Buffer *ptr_buffer, int)

Detailed Description

This object provides a movable memory buffer that can be dynamically created, resized, and used as a plain memory block or as storage with access helpers.

For CyOS, buffers are better than plain dynamic memory - allocated chunks because they can be locked and unlocked. While they are unlocked, the OS may move them in order to organize memory more efficiently, and may even drop the buffer to the flash so it may be used as a kind of virtual memory.

The best way to work with this object is to keep the buffer unlocked and use access helpers methods Buffer_load, Buffer_load_string, Buffer_store, Buffer_store_string, Buffer_get_byte, Buffer_set_byte, Buffer_get_char, Buffer_set_char, Buffer_get_int, Buffer_set_int, Buffer_get_long, Buffer_set_long and so on.

The difference between store_ and set_ methods is that store_* automatically resizes the buffer to fit the size required, while set_ methods check and treat " out of bounds " as an error.

Please note that the offsets for all helpers get_* and set_* are ALWAYS IN BYTES. The Buffers have a size/increment/capacity space strategy. This means that when a Buffer needs to expand its storage, it uses an increment and stores both the actual data size and the current capacity to minimize the load on the dynamic memory subsystem.

Use Buffer_set_size, Buffer_ensure_size and Buffer_compact methods to manage the buffer's capacity.

See also:
Messaging

Member Function Documentation

void Buffer_compact ( struct Buffer * ptr_buffer )
 

Resizes storage to the current data size.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[20];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 20 );
       ...
       Buffer_compact( &buffer );
       // The real_size value will be equal to 20.
       // Without calling the Buffer_compact function
       // the real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

struct Buffer * Buffer_ctor ( struct Buffer * ptr_buffer,
size_t size,
size_t increment )
 

Create an empty buffer of a specified data_size.

Parameters:
ptr_buffer   A pointer to the Buffer structure
size   The initial buffer size
increment   An increment value
Returns:
A pointer to the initialized Buffer object 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       char** sz_string_array;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer, sz_string_array[index],
                              Buffer_get_size( &buffer ) );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_ctor_Ex.

struct Buffer * Buffer_ctor_Ex ( struct Buffer * ptr_buffer,
struct Buffer * templ )
 

Creates a copy of the existing buffer.

Parameters:
ptr_buffer   A pointer to the Buffer structure
templ   A pointer to the template Buffer object
Returns:
A pointer to the initialized Buffer object 
       #include <cywin.h>                                       
       ...
       struct Buffer buffer;
       struct Buffer buffer_temp;
       int index;
       char** sz_string_array;
       ...
       Buffer_ctor( &buffer_temp, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer_temp, sz_string_array[index],
                              Buffer_get_size( &buffer_temp ) );
       }
       Buffer_ctor_Ex( &buffer, &buffer_temp );
       ...
       Buffer_dtor( &buffer_temp, LEAVE_MEMORY );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_ctor.

void Buffer_dtor ( struct Buffer * ptr_buffer,
int memory_flag )
 

Unlocks and frees a previously locked buffer.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in stack
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[20];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 20 );
       ...
       Buffer_compact( &buffer );
       // The real_size value will be equal to 20.
       // Without calling the Buffer_compact function
       // the real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool Buffer_ensure_size ( struct Buffer * ptr_buffer,
size_t test_size )
 

Reallocates and copies the buffer's contents, if needed.
Make sure the buffer's storage is not less than test_size

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
test_size   The size of the Buffer to test
Returns:
TRUE if the buffer has suffiicient capacity, FALSE if enough space can not be allocated to fit the specified size 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Frees the buffer and allocates a new buffer size.
       Buffer_free( &buffer );
       if ( Buffer_ensure_size( &buffer, 10000 ) )
       {
          Buffer_set_size( &buffer, 10000 );
          ...
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_free ( struct Buffer * ptr_buffer )
 

Clears the buffer and frees its storage.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Frees the buffer and allocates a new buffer size.
       Buffer_free( &buffer );
       Buffer_set_size( &buffer, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

size_t Buffer_get_allocated_size ( struct Buffer * ptr_buffer )
 

Returns the size of the allocated space (current capacity that may be bigger than Buffer_get_size()).

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
Size of the allocated space 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[20];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 20 );
       ...
       // The real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_size.

char Buffer_get_char ( struct Buffer * ptr_buffer,
size_t offset )
 

Reads char at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
offset   The offset in the buffer
Returns:
Char was read 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char   read_byte;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes the byte 'y' at the 12th position in the buffer.
       Buffer_set_byte( &buffer, 12, 'y' );
       ...
       // Reads a byte at the 12th position in the buffer.
       read_byte = Buffer_get_byte( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_char.

int Buffer_get_int ( struct Buffer * ptr_buffer,
size_t offset )
 

Reads the int value at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
offset   The offset in the buffer
Returns:
Int value was read 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int    read_int;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_int( &buffer, 12, 120 );
       ...
       // Reads a value at the 12th position in the buffer.
       read_int = Buffer_get_int( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_int.

long Buffer_get_long ( struct Buffer * ptr_buffer,
size_t offset )
 

Reads the long value at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
offset   The offset in the buffer
Returns:
Long value was read 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       long   read_long;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_long( &buffer, 12, 0x7FFFFFFF );
       ...
       // Reads a value at the 12th position in the buffer.
       read_long = Buffer_get_long( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_long.

size_t Buffer_get_size ( struct Buffer * ptr_buffer )
 

Returns the size of the data in the buffer.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
The size of the data in the buffer 
       #include <cywin.h>
       #define STRINGS_NUM 64
       ...
       struct Buffer buffer;
       int string_number;
       int index;
       int offset = 0;
       char** sz_text_buffer = (char**)malloc( STRINGS_NUM * sizeof( char* ) );
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores strings.
       for( string_number = 0; strlen( sz_text_buffer[string_number] ); string_number++ )
       {
         Buffer_store_string( &buffer, sz_text_buffer[string_number],
                              Buffer_get_size( &buffer ) );
       }
       ...
       //  Trace strings.
       for( index = 0; index < string_number; index++ )
       {
         Buffer_load_string( &buffer, sz_text_buffer[index], offset, 0 );
         offset += strlen( sz_text_buffer[index] ) + 1;
         TRACE( "%i string is %s", index, sz_text_buffer[index] );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_allocated_size, Buffer_set_size.

bool Buffer_is_locked ( struct Buffer * ptr_buffer )
 

Returns lock state (locked or unlocked).

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
TRUE, if the buffer is locked, FALSE otherwise 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y ';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_lock.

void * Buffer_load ( struct Buffer * ptr_buffer,
void * ptr_data,
size_t offset,
size_t length )
 

Loads 'length' bytes from the Buffer, starting at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
ptr_data   Where to store the loaded bytes
offset   The point at which to start copying bytes
length   How many bytes to copy; if 0 then all data size is supposed
Returns:
A pointer for convenience and style reasons 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[20];
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 20 );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_load_string.

char * Buffer_load_string ( struct Buffer * ptr_buffer,
char * str,
size_t offset,
size_t length )
 

Loads null terminated string.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
str   Where to store the string
offset   The offset in the buffer
length   The maximum length of the string; if 0 then all data size is supposed
Returns:
A pointer to the string 
       #include <cywin.h>
       #define STRINGS_NUM 64
       ...
       struct Buffer buffer;
       int string_number;
       int index;
       int offset = 0;
       char** sz_text_buffer = (char**)malloc( STRINGS_NUM * sizeof( char* ) );
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores strings.
       for( string_number = 0; strlen( sz_text_buffer[string_number] ); string_number++ )
       {
         Buffer_store_string( &buffer, sz_text_buffer[string_number],
                              Buffer_get_size( &buffer ) );
       }
       ...
       //  Trace strings.
       for( index = 0; index < string_number; index++ )
       {
         Buffer_load_string( &buffer, sz_text_buffer[index], offset, 0 );
         offset += strlen( sz_text_buffer[index] ) + 1;
         TRACE( "%i string is %s", index, sz_text_buffer[index] );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_load.

void * Buffer_lock ( struct Buffer * ptr_buffer )
 

Locks storage and returns the pointer to it's area.
Note that a locked buffer can not be trashed. Be very careful with this pointer and do not access more data than the number of Buffer_get_size() bytes. Do not use this pointer after Buffer_unlock() was called.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
Address of the locked buffer's data area 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_unlock, Buffer_is_locked.

void Buffer_set_char ( struct Buffer * ptr_buffer,
size_t offset,
char data )
 

Writes char value 'data' at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
offset   The offset in the buffer
data   The character to set
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char   read_byte;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes the byte 'y' at the 12th position in the buffer.
       Buffer_set_byte( &buffer, 12, 'y' );
       ...
       // Reads a byte at the 12th position in the buffer.
       read_byte = Buffer_get_byte( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_char.

void Buffer_set_int ( struct Buffer * ptr_buffer,
size_t offset,
int data )
 

Writes the int 'data' at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
offset   The offset in the buffer
data   The int to set
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int    read_int;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_int( &buffer, 12, 120 );
       ...
       // Reads a value at the 12th position in the buffer.
       read_int = Buffer_get_int( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_int.

void Buffer_set_long ( struct Buffer * ptr_buffer,
size_t offset,
long data )
 

Writes the long value 'data' at the specified 'offset'.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object.
offset   The offset in the buffer
data   The long to set
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       long   read_long;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_long( &buffer, 12, 0x7FFFFFFF );
       ...
       // Reads a value at the 12th position in the buffer.
       read_long = Buffer_get_long( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_long.

bool Buffer_set_size ( struct Buffer * ptr_buffer,
size_t size )
 

Sets the size.
If the size requested is less than the current capacity, extra space might be freed for the OS.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
size   The new buffer size
Returns:
TRUE if the buffer size is changed successfully 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[20];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 20 );
       ...
       Buffer_set_size( &buffer, 20 );
       // The real_size value will be equal to 20.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 20 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_size.

void Buffer_store ( struct Buffer * ptr_buffer,
void * ptr_data,
size_t offset,
size_t length )
 

Stores some data at the specified offset.
If needed, the buffer will expand it's storage to fit the specified 'length' of the data.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
ptr_data   A pointer to the data to store
offset   The offset in the buffer
length   The data's length; if it sets to 0 then the current size of the buffer will be used
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       char** sz_string_array;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index]); index++ )
       {
         Buffer_store( &buffer,
                       sz_string_array[index],
                       Buffer_get_size( &buffer ),
                       strlen( sz_string_array[index] ) + 1 );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_store_string ( struct Buffer * ptr_buffer,
char * str,
size_t offset )
 

Stores a null-terminated string into the buffer.
If needed, buffer will extend it's storage to fit the data's specified length.

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
str   The string to store
offset   The offset in the buffer
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       char** sz_string_array;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer, sz_string_array[index],
                              Buffer_get_size( &buffer ) );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_unlock ( struct Buffer * ptr_buffer )
 

Unlocks the buffer's storage.
Note that all references to the buffer area returned by Buffer_lock() become invalid and very dangerous to use; you can destroy the system very easily by using this pointer after Buffer_unlock().

Parameters:
ptr_buffer   A pointer to the initialized Buffer object
Returns:
None 
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_lock.