Branch: Tag:

2003-03-07

2003-03-07 17:34:14 by Martin Nilsson <mani@lysator.liu.se>

Autodoc.

Rev: lib/modules/ADT.pmod/module.pmod:1.3

1:   #pike __REAL_VERSION__   inherit _ADT;    + //! String buffer with the possibility to read and write data + //! as they would be formatted in structs.   class struct { -  //! generic data structure +        string buffer;    int index;    -  //! create a new struct -  //! -  //! @param s -  //! initial data in struct +  //! Create a new buffer, optionally initialized with the +  //! value @[s].    void create(void|string s)    {    buffer = s || "";    index = 0;    }    -  //! Return data, without removing it -  //! -  //! @returns -  //! contents of struct +  //! Trims the buffer to only contain the data after the +  //! read pointer and returns the contents of the buffer.    string contents()    {    buffer = buffer[index..];
28:    return buffer;    }    -  //! Add data to struct -  //! -  //! @param s -  //! data to add to end of struct +  //! Adds the data @[s] verbatim to the end of the buffer.    void add_data(string s)    {    buffer += s;    }    -  //! Return all data in struct, emptying the struct -  //! -  //! @returns -  //! contents of struct +  //! Return all the data in the buffer and empties it.    string pop_data()    {    string res = buffer;
48:    return res;    }    -  //! Append an unsigned integer to struct +  //! Appends an unsigned integer in network order to the buffer.    //!    //! @param i -  //! unsigned integer to append +  //! Unsigned integer to append.    //! @param len -  //! length of integer in bytes +  //! Length of integer in bytes.    void put_uint(int i, int len)    {    if (i<0) -  error("ADT.struct->put_uint: negative argument.\n"); -  +  error("Negative argument.\n");    add_data(sprintf("%*c", len, i));    }    -  //! @fixme -  //! document me! +  //! Appends a variable stringĀ @[s] preceded with an unsigned integer +  //! of the size @[len_width] declaring the length of the string. The +  //! string @[s] should be 8 bits wide.    void put_var_string(string s, int len_width)    {    if ( (len_width <= 3) &&    (sizeof(s) >= ({ -1, 0x100, 0x10000, 0x1000000 })[len_width] )) -  error("ADT.struct->put_var_string: Field overflow.\n"); +  error("Field overflow.\n");    put_uint(sizeof(s), len_width);    add_data(s);    }    -  //! @fixme -  //! document me! -  void put_bignum(object i, int|void len) + #if constant(Gmp.mpz) +  //! Appends a bignum @[i] as a variable string preceded with an +  //! unsigned integer of the size @[len_width] declaring the length +  //! of the string. @[len_width] defaults to 2. +  void put_bignum(Gmp.mpz i, int|void len_width)    {    if (i<0) -  error("ADT.struct->put_bignum: negative argument.\n"); -  put_var_string(i->digits(256), len || 2); +  error("Negative argument.\n"); +  put_var_string(i->digits(256), len_width || 2);    } -  + #endif    -  //! @fixme -  //! document me! +  //! Appends the fix sized string @[s] to the buffer.    void put_fix_string(string s)    {    add_data(s);    }    -  //! @fixme -  //! document me! +  //! Appends an array of unsigned integers of width @[item_size] +  //! to the buffer.    void put_fix_uint_array(array(int) data, int item_size)    {    foreach(data, int i)    put_uint(i, item_size);    }    -  //! @fixme -  //! document me! +  //! Appends an array of unsigned integers of width @[item_size] +  //! to the buffer, preceded with an unsigned integer @[len] declaring +  //! the size of the array.    void put_var_uint_array(array(int) data, int item_size, int len)    {    put_uint(sizeof(data), len);    put_fix_uint_array(data, item_size);    }    -  //! @fixme -  //! document me! -  int get_uint(int len) +  //! Reads an unsigned integer from the buffer. +  int(0..) get_uint(int len)    {    mixed i;    if ( (sizeof(buffer) - index) < len) -  error("ADT.struct->get_uint: no data\n"); +  error("No data.\n");    sscanf(buffer, "%*" + (string) index +"s%" + (string) len + "c", i);    index += len;    return i;    }    -  //! @fixme -  //! document me! +  //! Reads a fixed sized string of length @[len] from the buffer.    string get_fix_string(int len)    { -  string res; -  +     if ((sizeof(buffer) - index) < len) -  error("ADT.struct->get_fix_string: no data\n"); -  res = buffer[index .. index + len - 1]; +  error("No data\n"); +  +  string res = buffer[index .. index + len - 1];    index += len;    return res;    }    -  //! @fixme -  //! document me! +  //! Reads a string written by @[put_var_string] from the buffer.    string get_var_string(int len)    {    return get_fix_string(get_uint(len));    }      #if constant(Gmp.mpz) -  object get_bignum(int|void len) +  //! Reads a bignum written by @[put_bignum] from the buffer. +  Gmp.mpz get_bignum(int|void len)    {    return Gmp.mpz(get_var_string(len || 2), 256);    }   #endif    -  //! get remainder of data from struct, clearing the struct -  //! -  //! @returns -  //! Remaining contents of struct +  //! Get the remaining data from the buffer and clears the buffer.    string get_rest()    {    string s = buffer[index..];
155:    return s;    }    -  //! @fixme -  //! document me! +  //! Reads an array of integers as written by @[put_fix_unit_array] +  //! from the buffer.    array(mixed) get_fix_uint_array(int item_size, int size)    {    array(mixed) res = allocate(size);
165:    return res;    }    -  //! @fixme -  //! document me! +  //! Reads an array of integers as written by @[put_var_unit_array] +  //! from the buffer.    array(mixed) get_var_uint_array(int item_size, int len)    {    return get_fix_uint_array(item_size, get_uint(len));    }    -  //! is struct empty? -  //! -  //! @returns -  //! 1 if empty, 0 otherwise -  int is_empty() +  //! Returns one of there is any more data to read. +  int(0..1) is_empty()    {    return (index == sizeof(buffer));    }   }