core/sbufs/sbufs-docs.factor

   1 USING: strings arrays byte-arrays help.markup
   2 help.syntax kernel vectors ;
   3 IN: sbufs
   4
   5 ARTICLE: "sbufs" "String buffers"
   6 "A string buffer is a resizable mutable sequence of characters. The literal syntax is covered in " { $link "syntax-sbufs" } "."
   7 $nl
   8 "String buffers can be used to construct new strings by accumilating 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" } ")."
   9 $nl
  10 "String buffer words are found in the " { $vocab-link "sbufs" } " vocabulary."
  11 $nl
  12 "String buffers form a class of objects:"
  13 { $subsection sbuf }
  14 { $subsection sbuf? }
  15 "Words for creating string buffers:"
  16 { $subsection >sbuf }
  17 { $subsection <sbuf> }
  18 "If you don't care about initial capacity, a more elegant way to create a new string buffer is to write:"
  19 { $code "SBUF\" \" clone" } ;
  20
  21 ABOUT: "sbufs"
  22
  23 HELP: sbuf
  24 { $description "The class of resizable character strings. See " { $link "syntax-sbufs" } " for syntax and " { $link "sbufs" } " for general information." } ;
  25
  26 HELP: <sbuf>
  27 { $values { "n" "a positive integer specifying initial capacity" } { "sbuf" sbuf } }
  28 { $description "Creates a new string buffer that can hold " { $snippet "n" } " characters before resizing." } ;
  29
  30 HELP: >sbuf
  31 { $values { "seq" "a sequence of non-negative integers" } { "sbuf" sbuf } }
  32 { $description "Outputs a freshly-allocated string buffer with the same elements as a given sequence." }
  33 { $errors "Throws an error if the sequence contains elements other than real numbers." } ;