core/strings/strings-docs.factor

   1 USING: arrays byte-arrays help.markup help.syntax
   2 kernel kernel.private strings.private sequences vectors
   3 sbufs math ;
   4 IN: strings
   5
   6 ARTICLE: "strings" "Strings"
   7 "A string is a fixed-size mutable sequence of Unicode 5.1 code points."
   8 $nl
   9 "Characters are not a first-class type; they are simply represented as integers between 0 and 16777216 (2^24). Only characters up to 2097152 (2^21) have a defined meaning in Unicode."
  10 $nl
  11 "String literal syntax is covered in " { $link "syntax-strings" } "."
  12 $nl
  13 "String words are found in the " { $vocab-link "strings" } " vocabulary."
  14 $nl
  15 "Strings form a class:"
  16 { $subsection string }
  17 { $subsection string? }
  18 "Creating strings:"
  19 { $subsection >string }
  20 { $subsection <string> }
  21 "Creating a string from a single character:"
  22 { $subsection 1string }
  23 "Since strings are sequences, basic string manipulation can be performed using sequence operations (" { $link "sequences" } "). More advanced functionality can be found in other vocabularies, including but not limited to:"
  24 { $list
  25     { { $link "ascii" } " - ASCII algorithms for interoperability with legacy applications" }
  26     { { $link "unicode" } " - Unicode algorithms for modern multilingual applications" }
  27     { { $vocab-link "regexp" } " - regular expressions" }
  28     { { $vocab-link "peg" } " - parser expression grammars" }
  29 } ;
  30
  31 ABOUT: "strings"
  32
  33 HELP: string
  34 { $description "The class of fixed-length character strings. See " { $link "syntax-strings" } " for syntax and " { $link "strings" } " for general information." } ;
  35
  36 HELP: string-nth ( n string -- ch )
  37 { $values { "n" fixnum } { "string" string } { "ch" "the character at the " { $snippet "n" } "th index" } }
  38 { $description "Unsafe string accessor, used to define " { $link nth } " on strings." }
  39 { $warning "This word is in the " { $vocab-link "strings.private" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link nth } " instead." } ;
  40
  41 HELP: set-string-nth ( ch n string -- )
  42 { $values { "ch" "a character" } { "n" fixnum } { "string" string }  }
  43 { $description "Unsafe string mutator, used to define " { $link set-nth } " on strings." }
  44 { $warning "This word is in the " { $vocab-link "strings.private" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link set-nth } " instead." } ;
  45
  46 HELP: <string> ( n ch -- string )
  47 { $values { "n" "a positive integer specifying string length" } { "ch" "an initial character" } { "string" string } }
  48 { $description "Creates a new string with the given length and all characters initially set to " { $snippet "ch" } "." } ;
  49
  50 HELP: 1string
  51 { $values { "ch" "a character"} { "str" string } }
  52 { $description "Outputs a string of one character." } ;
  53
  54 HELP: >string
  55 { $values { "seq" "a sequence of characters" } { "str" string } }
  56 { $description "Outputs a freshly-allocated string with the same elements as a given sequence, by interpreting the sequence elements as Unicode code points." }
  57 { $notes "This operation is only appropriate if the underlying sequence holds Unicode code points, which is rare unless it is a " { $link slice } " of another string. To convert a sequence of bytes to a string, use the words documented in " { $link "io.encodings.string" } "." }
  58 { $errors "Throws an error if the sequence contains elements other than integers." } ;
  59
  60 HELP: resize-string ( n str -- newstr )
  61 { $values { "n" "a non-negative integer" } { "str" string } { "newstr" string } }
  62 { $description "Creates a new string " { $snippet "n" } " characters long The contents of the existing string are copied into the new string; if the new string is shorter, only an initial segment is copied, and if the new string is longer the remaining space is filled with " { $snippet "\\u000000" } "." } ;