Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Byte Buffers
[Simple Objects C API]


Detailed Description

Buffers for exchanging binary data with the simple objects API.

The buffer objects provided by this module are used to exchange binary data with the simple objects API. These buffers are not synchronized for use by multiple threads, so the application has to make sure an instance if a buffer object is used by at most one thread at once.


Data Structures

struct  sobj_buffer
 Structure representing a variable byte array. More...

Defines

#define SOBJ_BUFFER_SIZE_STATIC   (1024)
 Size of the static buffer used in struct sobj_buffer.
#define SOBJ_BUFFER_INIT(BUFFER)
 Initialize a byte buffer instance.
#define SOBJ_BUFFER_DEINIT(BUFFER)
 De-initialize a byte buffer instance.
#define SOBJ_BUFFER_CLEAR(BUFFER)
 Clear a byte buffer instance.
#define SOBJ_BUFFER_LENGTH(BUFFER)   ((size_t)((BUFFER).so_length + 0))
 Return the length of a byte buffer.
#define SOBJ_BUFFER_BYTES(BUFFER)   ((const unsigned char *)((BUFFER).so_buffer + 0))
 Return a pointer to the byte array held by a byte buffer instance.
#define SOBJ_BUFFER_PUTC(BUFFER, X)
 Append a single character to the end of a byte buffer.

Functions

void sobj_buffer_init (struct sobj_buffer *sobj_buffer)
 Initialize a byte buffer instance.
void sobj_buffer_deinit (struct sobj_buffer *sobj_buffer)
 De-initialize a byte buffer instance.
void sobj_buffer_clear (struct sobj_buffer *sobj_buffer)
 Clear a byte buffer instance.
size_t sobj_buffer_length (const struct sobj_buffer *sobj_buffer)
 Return the length of a byte buffer.
const unsigned char * sobj_buffer_bytes (const struct sobj_buffer *sobj_buffer)
 Return a pointer to the byte array held by a byte buffer instance.
unsigned char * sobj_buffer_append (struct sobj_buffer *sobj_buffer, ptrdiff_t count)
 Append to a byte buffer.
void sobj_buffer_putc (struct sobj_buffer *sobj_buffer, unsigned char x)
 Append a single character to the end of a byte buffer.
void sobj_buffer_puts (struct sobj_buffer *sobj_buffer, const char *string)
 Append a null-terminated string to the end of a buffer.
void sobj_buffer_truncate (struct sobj_buffer *sobj_buffer, size_t length)
 Truncate a buffer instance to the specified size.
void sobj_buffer_remove (struct sobj_buffer *sobj_buffer, size_t offset, ptrdiff_t count)
 Remove a sequence of bytes from the buffer.
size_t sobj_buffer_line_start (const struct sobj_buffer *sobj_buffer)
 Find the beginning of the current line.


Define Documentation

#define SOBJ_BUFFER_BYTES BUFFER   )     ((const unsigned char *)((BUFFER).so_buffer + 0))
 

Return a pointer to the byte array held by a byte buffer instance.

Parameters:
BUFFER The struct sobj_buffer instance.
Returns:
A pointer to the byte array.
See also:
sobj_buffer_bytes().

#define SOBJ_BUFFER_CLEAR BUFFER   ) 
 

Value:

do {                                                                    \
    (BUFFER).so_length = 0;                                             \
  } while (false)
Clear a byte buffer instance.

Parameters:
BUFFER The struct sobj_buffer instance.
Note:
The parameter BUFFER may be evaluated multiple times. The heap storage referenced by the byte buffer is not released.
See also:
sobj_buffer_clear().

#define SOBJ_BUFFER_DEINIT BUFFER   ) 
 

Value:

do {                                                                    \
    if ((BUFFER).so_buffer != (BUFFER).so_static)                       \
      sobj_free((char *)((BUFFER).so_buffer));                          \
    (BUFFER).so_buffer = 0;                                             \
    (BUFFER).so_length = -1;                                            \
  } while (false)
De-initialize a byte buffer instance.

All heap storage referenced by the byte buffer is released. The byte buffer may not be used after this macro was called.

Parameters:
BUFFER The struct sobj_buffer instance.
Note:
The parameter BUFFER may be evaluated multiple times.
See also:
sobj_buffer_deinit().

#define SOBJ_BUFFER_INIT BUFFER   ) 
 

Value:

do {                                                                    \
    (BUFFER).so_length = 0;                                             \
    (BUFFER).so_size = sizeof (BUFFER).so_static;                       \
    (BUFFER).so_buffer = (BUFFER).so_static;                            \
  } while (false)
Initialize a byte buffer instance.

Parameters:
BUFFER The struct sobj_buffer instance.
Note:
The parameter BUFFER may be evaluated multiple times.
See also:
sobj_buffer_init().

#define SOBJ_BUFFER_LENGTH BUFFER   )     ((size_t)((BUFFER).so_length + 0))
 

Return the length of a byte buffer.

Parameters:
BUFFER The struct sobj_buffer instance.
Returns:
The length of the byte array.
See also:
sobj_buffer_length().

#define SOBJ_BUFFER_PUTC BUFFER,
 ) 
 

Value:

do {                                                                    \
    if ((BUFFER).so_length < (BUFFER).so_size) {                        \
      (BUFFER).so_buffer[(BUFFER).so_length] = (unsigned char)(X);      \
      ++(BUFFER).so_length;                                             \
    } else {                                                            \
      sobj_buffer_append(&(BUFFER), 1)[0] = (unsigned char)(X);         \
    }                                                                   \
  } while (false)
Append a single character to the end of a byte buffer.

Parameters:
BUFFER The struct sobj_buffer instance.
X The character to be appended.
Note:
The parameter BUFFER may be evaluated multiple times.
See also:
sobj_buffer_putc().

#define SOBJ_BUFFER_SIZE_STATIC   (1024)
 

Size of the static buffer used in struct sobj_buffer.


Function Documentation

unsigned char* sobj_buffer_append struct sobj_buffer sobj_buffer,
ptrdiff_t  count
 

Append to a byte buffer.

Parameters:
sobj_buffer The byte buffer instance.
count The number of bytes to be appended.
Returns:
A pointer to the first byte of the bytes appended.

const unsigned char* sobj_buffer_bytes const struct sobj_buffer sobj_buffer  ) 
 

Return a pointer to the byte array held by a byte buffer instance.

Parameters:
sobj_buffer The byte buffer instance.
Returns:
A pointer to the byte array.
See also:
SOBJ_BUFFER_BYTES().

void sobj_buffer_clear struct sobj_buffer sobj_buffer  ) 
 

Clear a byte buffer instance.

Parameters:
sobj_buffer The byte buffer instance.
Note:
The heap storage referenced by the byte buffer is not released.
See also:
SOBJ_BUFFER_CLEAR().

void sobj_buffer_deinit struct sobj_buffer sobj_buffer  ) 
 

De-initialize a byte buffer instance.

All heap storage referenced by the byte buffer is released. The byte buffer may not be used after this macro was called.

Parameters:
sobj_buffer The byte buffer instance.
See also:
SOBJ_BUFFER_DEINIT().

void sobj_buffer_init struct sobj_buffer sobj_buffer  ) 
 

Initialize a byte buffer instance.

Parameters:
sobj_buffer The byte buffer instance.
See also:
SOBJ_BUFFER_INIT().

size_t sobj_buffer_length const struct sobj_buffer sobj_buffer  ) 
 

Return the length of a byte buffer.

Parameters:
sobj_buffer The byte buffer instance.
Returns:
The length of the byte array.
See also:
SOBJ_BUFFER_LENGTH().

size_t sobj_buffer_line_start const struct sobj_buffer sobj_buffer  ) 
 

Find the beginning of the current line.

The function searches backwards from the end of the buffer until a line spearator is found (either a newline or a CR), the character following the separator is the first character of the current line. If the buffer does not contain a line separator, the beginning of the line is the beginning of the buffer.

Parameters:
sobj_buffer The byte buffer instance.
Returns:
The offset of the first character of the current line.
Note:
If the last character of the buffer is a line separator, the length of the buffer is returned.

void sobj_buffer_putc struct sobj_buffer sobj_buffer,
unsigned char  x
 

Append a single character to the end of a byte buffer.

Parameters:
sobj_buffer The byte buffer instance.
x The character to be appended.
See also:
SOBJ_BUFFER_PUTC().

void sobj_buffer_puts struct sobj_buffer sobj_buffer,
const char *  string
 

Append a null-terminated string to the end of a buffer.

The terminating null-character is not appended.

Parameters:
sobj_buffer The byte buffer instance.
string The string to be appended.

void sobj_buffer_remove struct sobj_buffer sobj_buffer,
size_t  offset,
ptrdiff_t  count
 

Remove a sequence of bytes from the buffer.

Parameters:
sobj_buffer The byte buffer instance.
offset The offset of the first byte to be removed. If this is larger than the buffer size, then the function has no effect.
count The number of bytes to be removed. The value -1 indicates that everything up to the end of the buffer should be removed (eqivalent to sobj_buffer_truncate()).

void sobj_buffer_truncate struct sobj_buffer sobj_buffer,
size_t  length
 

Truncate a buffer instance to the specified size.

Parameters:
sobj_buffer The byte buffer instance.
length The desired length of the buffer. If the specified length is larger than the buffer length (or equal), the buffer remains unchanged.


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1