basis/io/buffers/buffers-docs.factor

   1 USING: alien byte-arrays destructors help.markup help.syntax
   2 kernel ;
   3 IN: io.buffers
   4
   5 ARTICLE: "buffers" "Locked I/O buffers"
   6 "I/O buffers are first-in-first-out queues of bytes."
   7 $nl
   8 "Buffers are backed by manually allocated storage that does not get moved by the garbage collector; they are also low-level and sacrifice error checking for efficiency."
   9 $nl
  10 "Buffers are used to implement native I/O backends."
  11 $nl
  12 "Buffer words are found in the " { $vocab-link "io.buffers" } " vocabulary."
  13 { $subsections
  14     buffer
  15     <buffer>
  16 }
  17 "Buffers must be manually deallocated by calling " { $link dispose } "."
  18 $nl
  19 "Buffer operations:"
  20 { $subsections
  21     buffer-reset
  22     buffer-length
  23     buffer-empty?
  24     buffer-capacity
  25     buffer@
  26 }
  27 "Reading from the buffer:"
  28 { $subsections
  29     buffer-peek
  30     buffer-pop
  31     buffer-read
  32 }
  33 "Writing to the buffer:"
  34 { $subsections
  35     byte>buffer
  36     >buffer
  37     n>buffer
  38 } ;
  39
  40 ABOUT: "buffers"
  41
  42 HELP: buffer
  43 { $class-description "The class of I/O buffers, which resemble FIFO queues, but are optimized for holding bytes, are have underlying storage allocated at a fixed address. Buffers must be de-allocated manually."
  44 $nl
  45 "Buffers have two internal pointers:"
  46 { $list
  47     { { $snippet "fill" } " - the fill pointer, a write index where new data is added" }
  48     { { $snippet "pos" } " - the position, a read index where data is consumed" }
  49 } } ;
  50
  51 HELP: <buffer>
  52 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  53 { $description "Allocates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ;
  54
  55 HELP: buffer-reset
  56 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  57 { $description "Resets the fill pointer to 0 and the position to " { $snippet "count" } "." } ;
  58
  59 HELP: buffer-consume
  60 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  61 { $description "Moves the position forward by " { $snippet "n" } " bytes. If it exceeds the fill pointer, both are reset to 0." } ;
  62
  63 HELP: buffer@
  64 { $values { "buffer" buffer } { "alien" alien } }
  65 { $description "Outputs the memory address of the current buffer position." } ;
  66
  67 HELP: buffer-end
  68 { $values { "buffer" buffer } { "alien" alien } }
  69 { $description "Outputs the memory address of the current fill-pointer." } ;
  70
  71 HELP: buffer-read
  72 { $values { "n" "a non-negative integer" } { "buffer" buffer } { "byte-array" byte-array } }
  73 { $description "Collects a byte array of " { $snippet "n" } " bytes starting from the buffer's current position, and advances the position accordingly. If there are less than " { $snippet "n" } " bytes available, the output is truncated." }
  74 { $examples
  75   { $example
  76     "USING: destructors io.buffers kernel prettyprint ;"
  77     "5 100 <buffer> [ B{ 7 14 21 } over >buffer buffer-read ] with-disposal ."
  78     "B{ 7 14 21 }"
  79   }
  80 } ;
  81
  82 HELP: buffer-length
  83 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  84 { $description "Outputs the number of unconsumed bytes in the buffer." }
  85 { $examples
  86   { $example
  87     "USING: destructors io.buffers kernel prettyprint ;"
  88     "100 <buffer> [ B{ 7 14 21 } over >buffer buffer-length ] with-disposal ."
  89     "3"
  90   }
  91 } ;
  92
  93 HELP: buffer-capacity
  94 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  95 { $description "Outputs the buffer's maximum capacity before growing." }
  96 { $examples
  97   { $example
  98     "USING: destructors io.buffers prettyprint ;"
  99     "100 <buffer> [ buffer-capacity ] with-disposal ."
 100     "100"
 101   }
 102 } ;
 103
 104 HELP: buffer-empty?
 105 { $values { "buffer" buffer } { "?" boolean } }
 106 { $description "Tests if the buffer contains no more data to be read or written." } ;
 107
 108 HELP: >buffer
 109 { $values { "byte-array" byte-array } { "buffer" buffer } }
 110 { $description "Copies a byte array to the buffer's fill pointer, and advances it accordingly." }
 111 { $warning "This word will corrupt memory if the byte array is larger than the space available in the buffer." } ;
 112
 113 HELP: byte>buffer
 114 { $values { "byte" "a byte" } { "buffer" buffer } }
 115 { $description "Appends a single byte to a buffer." }
 116 { $warning "This word will corrupt memory if the buffer is full." }
 117 { $examples
 118   { $example
 119     "USING: destructors io.buffers kernel prettyprint ;"
 120     "100 <buffer> [ 237 over byte>buffer buffer-pop ] with-disposal ."
 121     "237"
 122   }
 123 } ;
 124
 125 HELP: n>buffer
 126 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
 127 { $description "Advances the fill pointer by " { $snippet "n" } " bytes." }
 128 { $warning "This word will leave the buffer in an invalid state if it does not have " { $snippet "n" } " bytes available." } ;
 129
 130 HELP: buffer-peek
 131 { $values { "buffer" buffer } { "byte" "a byte" } }
 132 { $description "Outputs the byte at the buffer position." } ;
 133
 134 HELP: buffer-pop
 135 { $values { "buffer" buffer } { "byte" "a byte" } }
 136 { $description "Outputs the byte at the buffer position and advances the position." } ;