pool
----
  a pool of memory

pool traversal position
-----------------------
  - used with the 'read' and 'write' types of functions
  - always set to 1 for new pools

poolref
-------
  - refer to their source's data, they do not copy it
  - have their own pool position for traversal

pool permissions
----------------
  r: read
  w: write
  s: sizing
  c: control (of the getpermfunc() function)

pool metamethods
----------------
  - all metamethods can be set except for __gc and __metatable
  - metatables can be copied between base pool objects

net and swap functions
----------------------
  - the 'readnet' and 'writenet' functions read data in
    the network byte order (most significant byte first,
    aka: big endian). The 'swap<N>' functions can be used
    to convert blocks of data between native and network
    byte orderering.


--------------------------------------------------------------------------------

range := pool |
         string |
         { <pool | string> [,number start [,number end]] }

TYPE := "i8" | "i16" | "i32" | "i64" |
        "u8" | "u16" | "u32" | "u64" |
        "f32" | "f64" |
        "str"

--------------------------------------------------------------------------------

userdata metamethods:
  __gc
  __index
  __newindex
  __len
  __concat
  __tostring
  __eq
  __lt
  __le

--------------------------------------------------------------------------------

(range r | number size) -> pool

create(range r | number size) -> pool

copy(range r) -> pool ??? (use p:get(1) instead? -- rename to clone()?)

ref(pool p [, number start=1 [,number end=-1]]) -> poolref


setsize(pool p, number size) -> <pool p>

getsize(pool p) -> number size

setcapacity(pool p, number size) -> <pool p> | nil,err

getcapacity(pool p) -> number


setpos(pool p, number pos) -> <pool>

getpos(pool) -> number | nil,err

read_<TYPE>(pool p [,number count=1]) -> nil, err | <count x TYPE>

write_<TYPE>(pool p, TYPE...) -> <pool p>

readnet_<TYPE>(pool p [,number count=1]) -> nil, err | <count x TYPE>

writenet_<TYPE>(pool p, TYPE...) -> <pool p>


set(pool p, number pos, range r) -> <pool p>

get(pool p, number start [, number end=-1] ) -> pool

set_<TYPE>(pool p, number pos, TYPE...) -> <pool>

get_<TYPE>(pool p, number pos [,number count=1]) -> nil,err | <count x TYPE>

setnet_<TYPE>(pool p, number pos, TYPE...) -> <pool>

getnet_<TYPE>(pool p, number pos [,number count=1]) -> nil,err | <count x TYPE>


insert(pool dst, range src [,number start=1 [,number end=-1]]) -> <pool dst>

delete(pool p [, number start=1 [,number end=-1]]) -> <pool p>

fill(pool p [,number start=1 [,number end=-1 [,number value=0]]]) -> <pool p>

swap2(pool p [,number start=1 [,number end=-1]) -> <pool p>

swap4(pool p [,number start=1 [,number end=-1]) -> <pool p>

swap8(pool p [,number start=1 [,number end=-1]) -> <pool p>


tostring(pool p) -> string

find(pool p, range pattern [,number start=1 [,number end=-1]]) -> number pos | nil

appendfile(pool p, string filename) -> <pool p> | nil,err


getpermfunc(pool p) -> nil,err |
   permfunc(string perms) -> <pool p>

setmetamethod(pool p, string name, object) -> <pool p> | nil,err

copymetatable(pool dst, pool src) -> <pool dst>