factor/library/collections/strings.facts

USING: arrays help kernel kernel-internals sequences strings
vectors ;

HELP: string
{ $description "The class of fixed-length character strings. See " { $link "syntax-strings" } " for syntax and " { $link "strings" } " for general information." } ;

HELP: char-slot ( n string -- ch )
{ $values { "n" "a fixnum" } { "string" "a string" } { "ch" "the character at the " { $snippet "n" } "th index" } }
{ $description "Unsafe string accessor, used to define " { $link nth } " on strings." }
{ $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link nth } " instead." } ;

HELP: set-char-slot ( ch n string -- )
{ $values { "ch" "a character" } { "n" "a fixnum" } { "string" "a string" }  }
{ $description "Unsafe string mutator, used to define " { $link set-nth } " on strings." }
{ $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link set-nth } " instead." } ;

HELP: <string> ( n ch -- string )
{ $values { "n" "a positive integer specifying string length" } { "elt" "an initial character" } }
{ $description "Creates a new string with the given length and all characters initially set to " { $snippet "ch" } "." }
{ $see-also <array> <quotation> <sbuf> <vector> } ;

HELP: blank
{ $class-description "Class of integers denoting ASCII whitespace characters." } ;

HELP: letter
{ $class-description "Class of integers denoting lowercase alphabet ASCII characters." } ;

HELP: LETTER
{ $class-description "Class of integers denoting uppercase alphabet ASCII characters." } ;

HELP: digit
{ $class-description "Class of integers denoting ASCII decimal digit characters." } ;

HELP: Letter
{ $class-description "Class of integers denoting ASCII alphabet characters, both upper and lower case." } ;

HELP: alpha
{ $class-description "Class of integers denoting alphanumeric ASCII characters." } ;

HELP: alpha
{ $class-description "Class of integers denoting printable ASCII characters." } ;

HELP: alpha
{ $class-description "Class of integers denoting ASCII control characters." } ;

HELP: alpha
{ $class-description "Class of integers denoting characters which may appear in a Factor string literal without escaping." } ;

HELP: ch>lower
{ $values { "ch" "a character" } { "lower" "a character" } }
{ $description "Converts a character to lowercase." } ;

HELP: ch>upper
{ $values { "ch" "a character" } { "lower" "a character" } }
{ $description "Converts a character to uppercase." } ;

HELP: >lower
{ $values { "str" "a string" } { "lower" "a string" } }
{ $description "Converts a string to lowercase." } ;

HELP: >upper
{ $values { "str" "a string" } { "upper" "a string" } }
{ $description "Converts a string to uppercase." } ;

HELP: ch>string
{ $values { "ch" "a character"} { "str" "a new string" } }
{ $description "Outputs a string of one character." } ;

HELP: >string
{ $values { "seq" "a sequence of characters" } { "str" "a new string" } }
{ $description "Outputs a freshly-allocated string with the same elements as a given sequence." }
{ $errors "Throws an error if the sequence contains elements other than real numbers." }
{ $see-also >array >sbuf >vector >quotation } ;

HELP: resize-string ( n str -- newstr )
{ $values { "n" "a non-negative integer" } { "str" "a string" } { "newstr" "a new string" } }
{ $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 "\u0000" } "." } ;