core/sbufs/sbufs-docs.factor

   1 USING: help.markup help.syntax ;
   2 IN: sbufs
   3
   4 ARTICLE: "sbufs" "String buffers"
   5 "The " { $vocab-link "sbufs" } " vocabulary implements resizable mutable sequence of characters. The literal syntax is covered in " { $link "syntax-sbufs" } "."
   6 $nl
   7 "String buffers implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them. String buffers can be used to construct new strings by accumulating substrings and characters, however usually they are only used indirectly, since the sequence construction words are more convenient to use in most cases (see " { $link "namespaces-make" } ")."
   8 $nl
   9 "String buffers form a class of objects:"
  10 { $subsections
  11     sbuf
  12     sbuf?
  13 }
  14 "Words for creating string buffers:"
  15 { $subsections
  16     >sbuf
  17     <sbuf>
  18 }
  19 "If you don't care about initial capacity, a more elegant way to create a new string buffer is to write:"
  20 { $code "SBUF\" \" clone" } ;
  21
  22 ABOUT: "sbufs"
  23
  24 HELP: sbuf
  25 { $class-description "The class of resizable character strings. See " { $link "syntax-sbufs" } " for syntax and " { $link "sbufs" } " for general information." } ;
  26
  27 HELP: <sbuf>
  28 { $values { "n" "a positive integer specifying initial capacity" } { "sbuf" sbuf } }
  29 { $description "Creates a new string buffer that can hold " { $snippet "n" } " characters before resizing." } ;
  30
  31 HELP: >sbuf
  32 { $values { "seq" { $sequence "non-negative integers" } } { "sbuf" sbuf } }
  33 { $description "Outputs a freshly-allocated string buffer with the same elements as a given sequence." }
  34 { $errors "Throws an error if the sequence contains elements other than real numbers." } ;