doc/modules/luaevent.core.buffer.mdwn

   1 ----
   2 Functions:
   3
   4 [[toc levels=1]]
   5
   6 ## buffer.new
   7 * Instantiates a new buffer object
   8
   9 ## buffer:add
  10 * Successively concatenates each of the arguments onto the buffer
  11 * Input: `(...)`
  12         * Sequence of strings or buffer instances
  13 * Side Effects: Buffers 'add'ed are emptied of their contents (per libevent semantics)
  14 * Output: Amount of data added
  15 (QUESTION: Should add return the buffer itself so that chaining can be easy)
  16
  17 ## buffer:length (`__len`)
  18 * Output: Length of the remaining buffer contents
  19
  20 ## buffer:get\_data (`__tostring`)
  21 * Input:
  22         * `()` and `__tostring` - Returns all data in the buffer
  23         * `(len)` - Returns data up to `len` bytes long
  24         * `(begin, len)` - Returns data beginning at `begin` up to `len` bytes long
  25         * If `begin < 0`, wraps at data length.  Ex:  (-1, 1) returns last byte, (-2, 2) returns last 2 bytes
  26 * Output: A copy of contents from the buffer
  27
  28 ## buffer:read
  29 * Reads data from a file-descriptor/socket into the buffer directly
  30 * Input: `(integer/lightuserdata fd OR socket, length)`
  31         * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer)
  32         * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle
  33         * `length` - Amount of data to attempt to read into the buffer
  34 * Output: Length of data actually read into the buffer
  35 * Side Effects: fd/socket 'drain'ed of data
  36
  37 ## buffer:write
  38 * Attempts to write out all buffer's data to a file-descriptor/socket
  39 * Input: `(integer/lightuserdata fd OR socket, length)`
  40         * `fd` - File descriptor as integer or lightuserdata 'handle' (cast to a native integer)
  41         * `socket` - [LuaSocket](http://www.luaforge.net/projects/luasocket)-based socket handle
  42 * Output: Amount of data written
  43 * Side Effects: buffer 'drain'ed of written data
  44
  45 ## buffer:readline
  46 * Reads a line terminated by either '\r\n', '\n\r', '\r', or, '\n'
  47 * Output:
  48         * If no terminator found: nil
  49         * If terminator found: Line returned without terminators
  50 * NOTE: If a '\r' or '\n' are the last characters in the buffer, then the data is returned even if the
  51 potential later data would contain the paired '\n' or '\r'. (TODO: Ask libevent list on how this is handled...)
  52
  53 ## buffer:drain
  54 * Removes data from the buffer
  55 * Input: `(amt)`
  56         * If `amt < 0` drains all data due to auto-casting to unsigned int and capping...
  57         TODO: Add code to check this condition explicitly for safety
  58         * If `amt >= 0`, drain up to amt from the buffer (no problem w/ too-large values)
  59
  60 ## buffer:close (`__gc`)
  61 * Immediately frees/closes a buffer.  Note that