basis/io/buffers/buffers-docs.factor

   1 USING: help.markup help.syntax byte-arrays alien destructors ;
   2 IN: io.buffers
   3
   4 ARTICLE: "buffers" "Locked I/O buffers"
   5 "I/O buffers are first-in-first-out queues of bytes."
   6 $nl
   7 "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."
   8 $nl
   9 "Buffers are used to implement native I/O backends."
  10 $nl
  11 "Buffer words are found in the " { $vocab-link "io.buffers" } " vocabulary."
  12 { $subsections
  13     buffer
  14     <buffer>
  15 }
  16 "Buffers must be manually deallocated by calling " { $link dispose } "."
  17 $nl
  18 "Buffer operations:"
  19 { $subsections
  20     buffer-reset
  21     buffer-length
  22     buffer-empty?
  23     buffer-capacity
  24     buffer@
  25 }
  26 "Reading from the buffer:"
  27 { $subsections
  28     buffer-peek1
  29     buffer-pop
  30     buffer-read
  31 }
  32 "Writing to the buffer:"
  33 { $subsections
  34     byte>buffer
  35     >buffer
  36     n>buffer
  37 } ;
  38
  39 ABOUT: "buffers"
  40
  41 HELP: buffer
  42 { $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."
  43 $nl
  44 "Buffers have two internal pointers:"
  45 { $list
  46     { { $snippet "fill" } " - the fill pointer, a write index where new data is added" }
  47     { { $snippet "pos" } " - the position, a read index where data is consumed" }
  48 } } ;
  49
  50 HELP: <buffer>
  51 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  52 { $description "Creates a buffer with an initial capacity of " { $snippet "n" } " bytes." } ;
  53
  54 HELP: buffer-reset
  55 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  56 { $description "Resets the fill pointer to 0 and the position to " { $snippet "count" } "." } ;
  57
  58 HELP: buffer-consume
  59 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  60 { $description "Moves the position forward by " { $snippet "n" } " bytes. If it exceeds the fill pointer, both are reset to 0." } ;
  61
  62 HELP: buffer@
  63 { $values { "buffer" buffer } { "alien" alien } }
  64 { $description "Outputs the memory address of the current buffer position." } ;
  65
  66 HELP: buffer-end
  67 { $values { "buffer" buffer } { "alien" alien } }
  68 { $description "Outputs the memory address of the current fill-pointer." } ;
  69
  70 HELP: buffer-read
  71 { $values { "n" "a non-negative integer" } { "buffer" buffer } { "byte-array" byte-array } }
  72 { $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." } ;
  73
  74 HELP: buffer-length
  75 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  76 { $description "Outputs the number of unconsumed bytes in the buffer." } ;
  77
  78 HELP: buffer-capacity
  79 { $values { "buffer" buffer } { "n" "a non-negative integer" } }
  80 { $description "Outputs the buffer's maximum capacity before growing." } ;
  81
  82 HELP: buffer-empty?
  83 { $values { "buffer" buffer } { "?" "a boolean" } }
  84 { $description "Tests if the buffer contains no more data to be read." } ;
  85
  86 HELP: >buffer
  87 { $values { "byte-array" byte-array } { "buffer" buffer } }
  88 { $description "Copies a byte array to the buffer's fill pointer, and advances it accordingly." }
  89 { $warning "This word will corrupt memory if the byte array is larger than the space available in the buffer." } ;
  90
  91 HELP: byte>buffer
  92 { $values { "byte" "a byte" } { "buffer" buffer } }
  93 { $description "Appends a single byte to a buffer." }
  94 { $warning "This word will corrupt memory if the buffer is full." } ;
  95
  96 HELP: n>buffer
  97 { $values { "n" "a non-negative integer" } { "buffer" buffer } }
  98 { $description "Advances the fill pointer by " { $snippet "n" } " bytes." }
  99 { $warning "This word will leave the buffer in an invalid state if it does not have " { $snippet "n" } " bytes available." } ;
 100
 101 HELP: buffer-peek1
 102 { $values { "buffer" buffer } { "byte" "a byte" } }
 103 { $description "Outputs the byte at the buffer position." } ;
 104
 105 HELP: buffer-pop
 106 { $values { "buffer" buffer } { "byte" "a byte" } }
 107 { $description "Outputs the byte at the buffer position and advances the position." } ;