Binary Data
===========

A new datatype has been introduced to LPMOO, called a buffer. Buffers are
containers for arbitrary blocks of binary data.

Buffers have the following properties:

  - typeof(buffer) == BUF
  - length(buffer) == len	/* number of characters in buffer */
  - typeof(buffer[n]) == NUM	/* for all n in [1..length(buffer)] */
  - buffer[n] == char		/* 8-bit binary value (0-255) in position n */

Buffers contain a known number of elements, where each element is an 8-bit
character representable by an integer in the range 0-255.

In MOO code, buffers can be created with this syntax:

  [char1, char2, char3, ...]

where each `char' must evaluate to an integer in the range 0-255. Numbers
outside this range will be truncated modulo 256.

The splice operator (@) may be used to embed other buffers:

  ["foo", @[65, "bar"], 10]  =>  [102, 111, 111, 65, 98, 97, 114, 10]

The tobuf() builtin may be used to create a buffer value from other datatypes:

  tobuf("foo", 65, "bar", 10)  =>  [102, 111, 111, 65, 98, 97, 114, 10]

It is possible to replace characters, or a range of characters, in a buffer
using indexed-assignments:

  x = y = ["foobar"];
  x[3] = 65;
  y[2..4] = [10, 0];
  return {x, y};

  => {[102, 111, 65, 98, 97, 114], [102, 10, 0, 97, 114]}

The tostr() builtin may be used to extract printable characters from a buffer
and return them as a string:

  tostr(["foo", 65, 10, "bar", 0, 90])  =>  "fooAbarZ"

Note that the buffer construction syntax, buffer indexing, and the tostr() and
tobuf() builtins are all that are necessary to convert numbers to ASCII
characters and vice versa:

  tostr([65])    =>  "A"
  tobuf("A")[1]  =>  65

The notify() builtin may be used to send the raw binary information in a
buffer to a connection. Newline characters will NOT automatically be appended;
the best way to send the newline sequence would be to follow the binary
notify() with notify(player, "").

The read() builtin may be used to read binary data input from a connection. An
optional second argument, if true, will cause the read binary data to be
returned in a buffer. To be most useful, this should be called for a binary
connection; telnet connections can still return binary data, but some
characters (particularly newline characters) will be stripped.