#define  M_STRING(x)    ((M_String)(x))

a macro to cast anything to a string handle

#define  M_STRING_P(x)  ((M_String*)(x))

a macro to cast anything to a pointer to a string handle

#define  M_CSTRING(x)    ((M_CString)(x))

a macro to cast anything to a constant string handle

#define  M_CSTRING_P(x)  ((M_CString*)(x))

a macro to cast anything to a pointer to a constant string handle

#define    m_string_compare( s1, s2 )  \
               strcmp ( M_CSTRING(s1), M_CSTRING(s2) )

a convenient macro used to compare two strings. returns 0 when the strings are equal

#define    m_string_len( s )          \
               strlen ( M_CSTRING(s) )

a convenient macro used to return the length of a string in characters.

#define    m_string_equal( s1, s2 )      \
               ( m_string_compare( s1, s2 ) == 0 )

a convenient macro that returns TRUE iff two strings are equal.

  MLIB_API(M_String)   m_string_new( M_Memory     memory,
                                     M_Size       length,
                                     M_Bool       push );

a function used to allocate a new string

pointer to new string

the function allocates 'length+1' bytes and always sets the string's buffer to 0

m_err_out_of_memory

  MLIB_API(M_String)   m_string_dup( M_CString   source,
                                     M_Memory    memory,
                                     M_Bool      push );

a function used to duplicate a given string

string copy. its size is "source.length+1" bytes

m_err_out_of_memory

  MLIB_API(M_String)   m_stringn_dup( M_CString   source,
                                      M_Size      maxlen,
                                      M_Memory    memory,
                                      M_Bool      push );

a function used to duplicate a given bounded string

string copy. its size is "source.length+1" bytes

m_err_out_of_memory

  MLIB_API(void)   m_string_destroy( M_CString   string,
                                     M_Memory    memory );

destroy a given string

  MLIB_API(void)   m_string_push( M_CString   string,
                                  M_Memory    memory );

push a given string on top of the cleanup stack

  MLIB_API(void)   m_string_pop( M_CString   string,
                                 M_Memory    memory,
                                 M_Bool      keep_it );

pops a string that was previously pushed on the cleanup stack, either with m_string_push , m_string_new or ?m_string_copy

  MLIB_API(void)    m_string_toupper( M_String  string );

converts a given input string to uppercase

  MLIB_API(void)    m_string_tolower( M_String  string );

converts a given input string to lowercase

  MLIB_API(M_ULong)   m_string_hash( M_CString  string );

a simple function used to hash strings.

hash value, as unsigned long

#define    m_stringn_compare( s1, s2, n )  \
               strncmp( M_CSTRING(s1), M_CSTRING(s2), n )

a convenient macro used to compare the first 'n' characters of two strings.

returns 0 in case of success.

#define    m_stringn_equal( s1, s2, n )   \
               ( m_stringn_compare( s1, s2, n ) == 0 )

a convenient macro that returns TRUE iff the first 'n' characters of two strings are equal.

  MLIB_API(M_Size)  m_stringn_len( M_CString  string,
                                   M_Size     maxlen );

compute the length of a bounded string

length of string, always <= maxlen

  MLIB_API(void)    m_stringn_toupper( M_String  string,
                                       M_Size    maxlen );

converts a given bounded string to uppercase

  MLIB_API(void)    m_stringn_tolower( M_String  string,
                                       M_Size    maxlen );

converts a given bounded string to lowercase

  MLIB_API(M_ULong)   m_stringn_hash( M_CString  string,
                                      M_Size     maxlen );

a simple function used to hash bounded strings.

hash value, as unsigned long

  typedef enum  M_Struct_Op_
  {
    m_struct_op_end        = 0,
    m_struct_op_start      = M_MAKE_STRUCT_OP( M_STRUCT_OP_START, 0, 0 ),

    m_struct_op_byte       = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT8,  0, 0 ),
    m_struct_op_schar      = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT8,  0, 1 ),

    m_struct_op_uint16_be  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT16, 0, 0 ),
    m_struct_op_int16_be   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT16, 0, 1 ),
    m_struct_op_uint16_le  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT16, 1, 0 ),
    m_struct_op_int16_le   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT16, 1, 1 ),

    m_struct_op_uint32_be  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT32, 0, 0 ),
    m_struct_op_uint32_le  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT32, 0, 1 ),
    m_struct_op_int32_be   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT32, 1, 0 ),
    m_struct_op_int32_le   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT32, 1, 1 ),

    m_struct_op_uint24_be  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT24, 0, 0 ),
    m_struct_op_uint24_le  = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT24, 0, 1 ),
    m_struct_op_int24_be   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT24, 1, 0 ),
    m_struct_op_int24_le   = M_MAKE_STRUCT_OP( M_STRUCT_OP_INT24, 1, 1 ),

    m_struct_op_bytes      = M_MAKE_STRUCT_OP( M_STRUCT_OP_BYTES, 0, 0 ),
    m_struct_op_skip       = M_MAKE_STRUCT_OP( M_STRUCT_OP_BYTES, 0, 1 )

  } M_Struct_Op;

a enumeration used to list the various ?M_Struct_Field types.

  typedef const struct M_StructFieldRec_*   M_StructField;

a handle to a _constant_ M_StructFieldRec , used to describe a stored structure field

  typedef struct  M_StructFieldRec_
  {
    M_Byte       value;
    M_Byte       size;
    M_UShort     offset;

  } M_StructFieldRec;

a simple structure used to model the layout of a single field in a given structure. Note that each field has a "memory size" and a "structure size".

the first is the size in bytes used to pack the field in memory (see m_struct_write_fields ).

the second is the field size in its structure

M_Struct_Field elements are grouped in constant tables named "structure layout" tables.

#define M_STRUCT_START( size )   { m_struct_op_start, 0, size }

this macro is used to define a new ?M_Struct_Field in a structure layout table.

its role is to give the total size in bytes of the stored structure it should only appear at the start of a given layout table, though is is optional.

#define M_STRUCT_END             { m_struct_op_end,   0, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table.

it should _ALWAYS_ appear as the last element of a layout table, as it indicates its end.

#define M_STRUCT_INT32( f )       M_STRUCT_FIELD( m_struct_op_int32_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 4-byte signed word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT32( f )      M_STRUCT_FIELD( m_struct_op_uint32_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 4-byte unsigned word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_INT24( f )       M_STRUCT_FIELD( m_struct_op_int24_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 3-byte signed word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT24( f )      M_STRUCT_FIELD( m_struct_op_uint24_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 3-byte unsigned word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_INT16( f )       M_STRUCT_FIELD( m_struct_op_int16_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 2-byte signed word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT16( f )      M_STRUCT_FIELD( m_struct_op_uint16_be, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 2-byte unsigned word in memory with big endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT8( f )       M_STRUCT_FIELD( m_struct_op_uint8, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 1-byte unsigned word in memory

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_INT8( f )        M_STRUCT_FIELD( m_struct_op_int8, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 1-byte signed word in memory

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_INT32_LE( f )    M_STRUCT_FIELD( m_struct_op_int32_le, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 4-byte signed word in memory with little endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT32_LE( f )   M_STRUCT_FIELD( m_struct_op_uint32_le, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 4-byte unsigned word in memory with little endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_INT16_LE( f )    M_STRUCT_FIELD( m_struct_op_int16_le, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 2-byte signed word in memory with little endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_UINT16_LE( f )   M_STRUCT_FIELD( m_struct_op_uint16_le, f )

this macro is used to define a new ?M_Struct_Field in a structure layout table. it describes a field that is stored as a 2-byte unsigned word in memory with little endianess

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_BYTES( field, count )     \
          {                                \
            m_struct_op_bytes,             \
            count,                         \
            M_STRUCT_FIELD_OFFSET( field ) \
          }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to a sequence of "count" contiguous bytes

the field is taken from the structure defined by the _implicit_ ?M_STRUCTURE macro

#define M_STRUCT_SKIP_INT32       { m_struct_op_int32_be, 0, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to an ignored 4-byte long in memory.

#define M_STRUCT_SKIP_INT24       { m_struct_op_int24_be, 0, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to an ignored 3-byte word in memory.

#define M_STRUCT_SKIP_INT16       { m_struct_op_int16_be, 0, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to an ignored 2-byte word in memory.

#define M_STRUCT_SKIP_INT8        { m_struct_op_int8,     0, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to an ignored 1-byte word in memory.

#define M_STRUCT_SKIP_BYTES( count )  { m_struct_op_skip, count, 0 }

this macro is used to define a new ?M_Struct_Field in a structure layout table, corresponding to a ignored sequence of "count" bytes in memory.

#define M_PEEK_INT16_BE(p)   ((M_Int16)( ((M_Int8)(p)[0] << 8) | \
                                          (M_Byte)(p)[1] ))

peeks the big-endian 16-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT16_BE(p)  ((M_UInt16)( ((M_Byte)(p)[0] << 8) | \
                                           (M_Byte)(p)[1] ))

peeks the big-endian 16-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_INT24_BE(p)   ((M_Int32) ( ((M_Int32)(M_Int8)(p)[0] << 16) | \
                                          ((M_Int32)(M_Byte)(p)[1] <<  8) | \
                                           (M_Int32)(M_Byte)(p)[2] ))

peeks the big-endian 24-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT24_BE(p)  ((M_UInt32)( ((M_UInt32)(M_Byte)(p)[0] << 16) | \
                                          ((M_UInt32)(M_Byte)(p)[1] <<  8) | \
                                           (M_UInt32)(M_Byte)(p)[2] ))

peeks the big-endian 24-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_INT32_BE(p)   ((M_Int32) ( ((M_Int32)(M_Int8)(p)[0] << 24) | \
                                          ((M_Int32)(M_Byte)(p)[1] << 16) | \
                                          ((M_Int32)(M_Byte)(p)[2] <<  8) | \
                                           (M_Int32)(M_Byte)(p)[3] ))

peeks the big-endian 32-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT32_BE(p)  ((M_UInt32)( ((M_UInt32)(M_Byte)(p)[0] << 24) | \
                                          ((M_UInt32)(M_Byte)(p)[1] << 16) | \
                                          ((M_UInt32)(M_Byte)(p)[2] <<  8) | \
                                           (M_UInt32)(M_Byte)(p)[3] ))

peeks the big-endian 32-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_INT16_LE(p)   ((M_Int16)( ((M_Int16)(M_Int8)(p)[1] << 8) | \
                                          (M_Int16)(M_Byte)(p)[0] ))

peeks the little-endian 16-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT16_LE(p)  ((M_UInt16)( ((M_UInt16)(M_Byte)(p)[1] << 8) | \
                                           (M_UInt16)(M_Byte)(p)[0] ))

peeks the little-endian 16-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_INT24_LE(p)   ((M_Int32) ( ((M_Int32)(M_Int8)(p)[2] << 16) | \
                                          ((M_Int32)(M_Byte)(p)[1] <<  8) | \
                                           (M_Int32)(M_Byte)(p)[0] ))

peeks the little-endian 24-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT24_LE(p)  ((M_UInt32)( ((M_UInt32)(M_Byte)(p)[2] << 16) | \
                                          ((M_UInt32)(M_Byte)(p)[1] <<  8) | \
                                           (M_UInt32)(M_Byte)(p)[0] ))

peeks the little-endian 24-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_INT32_LE(p)   ((M_Int32) ( ((M_Int32)(M_Int8)(p)[3] << 24) | \
                                          ((M_Int32)(M_Byte)(p)[2] << 16) | \
                                          ((M_Int32)(M_Byte)(p)[1] <<  8) | \
                                           (M_Int32)(M_Byte)(p)[0] ))

peeks the little-endian 32-bit signed integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_PEEK_UINT32_LE(p)  ((M_UInt32)( ((M_UInt32)(M_Byte)(p)[3] << 24) | \
                                          ((M_UInt32)(M_Byte)(p)[2] << 16) | \
                                          ((M_UInt32)(M_Byte)(p)[1] <<  8) | \
                                           (M_UInt32)(M_Byte)(p)[0] ))

peeks the little-endian 32-bit unsigned integer from the memory location given by "buffer"

"buffer" must be a byte/char pointer

#define M_NEXT_INT8( buffer )            \
          ( (M_Int8)*buffer++ )

read the next signed byte from "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT8( buffer )            \
          ( (M_Byte)*buffer++ )

read the next unsigned byte from "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT16( buffer )                      \
          ((M_Int16)( buffer += 2, M_PEEK_INT16_BE(buffer-2) ))

read the next signed 2-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT16( buffer )                     \
          ((M_UInt16)( buffer += 2, M_PEEK_UINT16_BE(buffer-2) ))

read the next unsigned 2-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT24( buffer )                                  \
          ((M_Int32)( buffer += 3, M_PEEK_INT24_BE(buffer-3) ))

read the next signed 3-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT24( buffer )                                    \
          ((M_UInt32)( buffer += 3, M_PEEK_UINT24_BE(buffer-3) ))

read the next unsigned 3-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT32( buffer )                                  \
          ((M_Int32)( buffer += 4, M_PEEK_INT32_BE(buffer-4) ))

read the next signed 4-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT32( buffer )                    \
          ((M_UInt32)( buffer += 4, M_PEEK_UINT32_BE(buffer-4) ))

read the next unsigned 4-byte big-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT16_LE( buffer )                           \
          ((M_Int16)( buffer += 2, M_PEEK_INT16_LE(buffer-2) ))

read the next signed 2-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT16_LE( buffer )                      \
          ((M_UInt16)( buffer += 2, M_PEEK_UINT16_LE(buffer-2) ))

read the next unsigned 2-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT24_LE( buffer )                            \
          ((M_Int32)( buffer += 3, M_PEEK_INT24_LE(buffer-3) ))

read the next signed 3-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT24_LE( buffer )                     \
          ((M_UInt32)( buffer += 3, M_PEEK_UINT24_LE(buffer-3) ))

read the next unsigned 3-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_INT32_LE( buffer )                            \
          ((M_Int32)( buffer += 4, M_PEEK_INT32_LE(buffer-4) ))

read the next signed 4-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_UINT32_LE( buffer )                     \
          ((M_UInt32)( buffer += 4, M_PEEK_UINT32_LE(buffer-4) ))

read the next unsigned 4-byte little-endian word starting at "buffer". this macro increments the pointer.

'buffer' must be a variable whose type is M_Byte*

#define M_NEXT_BYTE(buffer)   M_NEXT_UINT8(buffer)

this macro is equivalent to M_NEXT_UINT8 , but is there for convenience

'buffer' must be a variable whose type is M_Byte*

  MLIB_API(void)   m_struct_read_fields( M_StructField  fields,
                                         M_Pointer      object,
                                         M_Byte*       *buffer );

read a structure's fields from memory (unmarshalling)

  MLIB_API(void)   m_struct_write_fields( M_StructField  fields,
                                          M_Pointer      object,
                                          M_Byte*       *abuffer );

write a structure's fields to memory (marshalling)