core/io/binary/binary-docs.factor

   1 USING: help.markup help.syntax io math byte-arrays ;
   2 IN: io.binary
   3
   4 ARTICLE: "stream-binary" "Working with binary data"
   5 "Stream words on binary streams only read and write byte arrays. Packed binary integers can be read and written by converting to and from sequences of bytes. Floating point numbers can be read and written by converting them into a their bitwise integer representation (" { $link "floats" } ")."
   6 $nl
   7 "There are two ways to order the bytes making up an integer; " { $emphasis "little endian" } " byte order outputs the least significant byte first, and the most significant byte last, whereas " { $emphasis "big endian" } " is the other way around."
   8 $nl
   9 "Consider the hexadecimal integer " { $snippet "0xcafebabe" } ". Little endian byte order yields the following sequence of bytes:"
  10 { $table
  11     { "Byte:" "1" "2" "3" "4" }
  12     { "Value:" { $snippet "be" } { $snippet "ba" } { $snippet "fe" } { $snippet "ca" } }
  13 }
  14 "Compare this with big endian byte order:"
  15 { $table
  16     { "Byte:" "1" "2" "3" "4" }
  17     { "Value:" { $snippet "ca" } { $snippet "fe" } { $snippet "ba" } { $snippet "be" } }
  18 }
  19 "Two words convert a sequence of bytes into an integer:"
  20 { $subsections
  21     be>
  22     le>
  23 }
  24 "Two words convert an integer into a sequence of bytes:"
  25 { $subsections
  26     >be
  27     >le
  28 }
  29 "Words for taking larger integers apart into smaller integers:"
  30 { $subsections
  31     d>w/w
  32     w>h/h
  33     h>b/b
  34 } ;
  35
  36 ABOUT: "stream-binary"
  37
  38 HELP: be>
  39 { $values { "seq" "a sequence of bytes" } { "x" "a non-negative integer" } }
  40 { $description "Converts a sequence of bytes in big endian order into an unsigned integer." } ;
  41
  42 HELP: le>
  43 { $values { "seq" "a sequence of bytes" } { "x" "a non-negative integer" } }
  44 { $description "Converts a sequence of bytes in little endian order into an unsigned integer." } ;
  45
  46 HELP: nth-byte
  47 { $values { "x" integer } { "n" "a non-negative integer" } { "b" "a byte" } }
  48 { $description "Outputs the " { $snippet "n" } "th least significant byte of the sign-extended 2's complement representation of " { $snippet "x" } "." } ;
  49
  50 HELP: >le
  51 { $values { "x" integer } { "n" "a non-negative integer" } { "byte-array" byte-array } }
  52 { $description "Converts an integer " { $snippet "x" } " into a string of " { $snippet "n" } " bytes in little endian order. Truncation will occur if the integer is not in the range " { $snippet "[-2^(8n),2^(8n))" } "." } ;
  53
  54 HELP: >be
  55 { $values { "x" integer } { "n" "a non-negative integer" } { "byte-array" byte-array } }
  56 { $description "Converts an integer " { $snippet "x" } " into a string of " { $snippet "n" } " bytes in big endian order. Truncation will occur if the integer is not in the range " { $snippet "[-2^(8n),2^(8n))" } "." } ;
  57
  58 HELP: mask-byte
  59 { $values { "x" integer } { "y" "a non-negative integer" } }
  60 { $description "Masks off the least significant 8 bits of an integer." } ;
  61
  62 HELP: d>w/w
  63 { $values { "d" "a 64-bit integer" } { "w1" "a 32-bit integer" } { "w2" "a 32-bit integer" } }
  64 { $description "Outputs two integers, the least followed by the most significant 32 bits of the input." } ;
  65
  66 HELP: w>h/h
  67 { $values { "w" "a 32-bit integer" } { "h1" "a 16-bit integer" } { "h2" "a 16-bit integer" } }
  68 { $description "Outputs two integers, the least followed by the most significant 16 bits of the input." } ;
  69
  70 HELP: h>b/b
  71 { $values { "h" "a 16-bit integer" } { "b1" "an 8-bit integer" } { "b2" "an 8-bit integer" } }
  72 { $description "Outputs two integers, the least followed by the most significant 8 bits of the input." } ;