core/strings/strings-docs.factor

   1 USING: help.markup help.syntax strings.private sequences math
   2 help.vocabs ;
   3 IN: strings
   4
   5 ARTICLE: "strings" "Strings"
   6 "The " { $vocab-link "strings" } " vocabulary implements a data type for storing text. Strings are represented as fixed-size mutable sequences of Unicode code points. Code points are represented as integers in the range [0,2,097,152]."
   7 $nl
   8 "Strings implement the " { $link "sequence-protocol" } ", and basic string manipulation can be performed with " { $link "sequences" } " from the " { $vocab-link "sequences" } " vocabulary. More text processing functionality can be found in vocabularies carrying the " { $link T{ vocab-tag { name "text" } } } " tag."
   9 $nl
  10 "Strings form a class:"
  11 { $subsections
  12     string
  13     string?
  14 }
  15 "Creating new strings:"
  16 { $subsections
  17     >string
  18     <string>
  19 }
  20 "Creating a string from a single character:"
  21 { $subsections 1string }
  22 "Resizing strings:"
  23 { $subsections resize-string }
  24 { $see-also "syntax-strings" "sbufs" "unicode" "io.encodings" } ;
  25
  26 ABOUT: "strings"
  27
  28 HELP: string
  29 { $class-description "The class of fixed-length character strings. See " { $link "syntax-strings" } " for syntax and " { $link "strings" } " for general information." } ;
  30
  31 HELP: string-nth
  32 { $values { "n" fixnum } { "string" string } { "ch" "the character at the " { $snippet "n" } "th index" } }
  33 { $description "Unsafe string accessor, used to define " { $link nth } " on strings." }
  34 { $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." } ;
  35
  36 HELP: set-string-nth
  37 { $values { "ch" "a character" } { "n" fixnum } { "string" string } }
  38 { $description "Unsafe string mutator, used to define " { $link set-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 set-nth } " instead." } ;
  40
  41 HELP: <string>
  42 { $values { "n" "a positive integer specifying string length" } { "ch" "an initial character" } { "string" string } }
  43 { $description "Creates a new string with the given length and all characters initially set to " { $snippet "ch" } "." } ;
  44
  45 HELP: 1string
  46 { $values { "ch" "a character" } { "str" string } }
  47 { $description "Outputs a string of one character." } ;
  48
  49 HELP: >string
  50 { $values { "seq" { $sequence "characters" } } { "str" string } }
  51 { $description "Outputs a freshly-allocated string with the same elements as a given sequence, by interpreting the sequence elements as Unicode code points." }
  52 { $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" } "." }
  53 { $errors "Throws an error if the sequence contains elements other than integers." } ;
  54
  55 HELP: resize-string
  56 { $values { "n" "a non-negative integer" } { "str" string } { "newstr" string } }
  57 { $description "Resizes the string to have a length of " { $snippet "n" } " elements. When making the string shorter, this word may either create a new string or modify the existing string in place. When making the string longer, this word always allocates a new string, filling remaining space with zeroes." }
  58 { $side-effects "str" } ;