basis/bitstreams/bitstreams-docs.factor

   1 USING: help.markup help.syntax kernel math byte-arrays accessors ;
   2 IN: bitstreams
   3
   4
   5
   6 HELP: <lsb0-bit-reader>
   7 { $values { "bytes" byte-array } { "bs" bit-reader } }
   8 { $description "Creates a bitreader object, reading from the given bytearray, which counts the LSB as bit position 0. The cursor is placed at the start of the array. Note that this does not affect the order in which read bits are returned, only the order in which the cursor visits them." } ;
   9
  10 HELP: <msb0-bit-reader>
  11 { $values { "bytes" byte-array } { "bs" bit-reader } }
  12 { $description "Creates a bitreader object, reading from the given bytearray, which counts the MSB as bit position 0. The cursor is placed at the start of the array. Note that this does not affect the order in which read bits are returned, only the order in which the cursor visits them." } ;
  13
  14 HELP: peek
  15 { $values { "n" integer } { "bitstream" bit-reader } { "value" integer } }
  16 { $description "Reads the next n bits ahead of the cursor. Does not move the cursor; to read bits and move the cursor on use " { $link read } "." } ;
  17
  18 HELP: read
  19 { $values { "n" integer } { "bitstream" bit-reader } { "value" integer } }
  20 { $description "Reads the next n bits ahead of the cursor, and then moves the cursor on by n bits. To read bits without moving the cursor, use " { $link peek } ". This word shadows the read word in the " { $vocab-link "io" } " vocabulary, so you may need to alias it if you are using file IO as well as bitstreams." } ;
  21
  22 HELP: seek
  23 { $values { "n" integer } { "bitstream" bit-reader } }
  24 { $description "Moves the read cursor of the bit-reader forward by n bits. Use a negative value of n to move the cursor back." } ;
  25
  26 HELP: align
  27 { $values { "n" integer } { "bitstream" bit-reader } }
  28 { $description "Moves the read cursor of the bit-reader forward until its position in bits from the start of the stream is an even multiple of n. If it is already such a multiple, the cursor is not moved at all." } ;
  29
  30 HELP: enough-bits?
  31 { $values { "n" integer } { "bs" bit-reader } { "?" boolean } }
  32 { $description "Returns a true value if at least n bits remain to be read from the bit-reader." } ;
  33
  34
  35 HELP: set-abp
  36 { $values { "abp" integer } { "bitstream" bit-reader } }
  37 { $description "Moves the read cursor of the bit-reader to abp bits from the start of the stream. The position of the cursor in terms of bytes and bits can be changed by directly updating the bit-reader tuple using " { $link >>byte-pos } " and " { $link >>bit-pos } "." } ;
  38
  39 HELP: get-abp
  40 { $values { "bitstream" bit-reader } { "abp" integer } }
  41 { $description "Returns the current position of the bit-reader's read cursor as a number of bits from the start of the stream. The position of the cursor in terms of bytes and bits can be read directly from the bit-reader tuple using " { $link byte-pos>> } " and " { $link bit-pos>> } "." } ;