factor/library/collections/strings.facts

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

HELP: string f
{ $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 " { $snippet "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 " { $snippet "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? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a whitespace character." } ;

HELP: letter? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a lowercase alphabet character." } ;

HELP: LETTER? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a uppercase alphabet character." } ;

HELP: digit? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a decimal digit character." } ;

HELP: printable? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a printable ASCII character." } ;

HELP: control? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for an ASCII control character." } ;

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

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

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

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

HELP: quotable? "( ch -- ? )"
{ $values { "ch" "a character" } { "?" "a boolean" } }
{ $description "Tests for a character which may appear in a Factor string literal without escaping." } ;

HELP: padding "( str n ch -- padstr )"
{ $values { "str" "a string" } { "n" "a non-negative integer" } { "ch" "a character"} { "padstr" "a new string" } }
{ $description "Outputs a new string consisting of " { $snippet "ch" } " repeated, that when appended to " { $snippet "str" } ", yields a string of length " { $snippet "n" } ". If the length of { " { $snippet "str" } " is greater than " { $snippet "n" } ", this word outputs the empty string." } ;

HELP: pad-left "( str n ch -- padded )"
{ $values { "str" "a string" } { "n" "a non-negative integer" } { "ch" "a character"} { "padded" "a new string" } }
{ $description "Outputs a new string consisting of " { $snippet "str" } " padded on the left with enough repetitions of " { $snippet "ch" } " to have the result be of length " { $snippet "n" } "." }
{ $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-left print ] each" "---ab\n-quux" } } ;

HELP: pad-right "( str n ch -- padded )"
{ $values { "str" "a string" } { "n" "a non-negative integer" } { "ch" "a character"} { "padded" "a new string" } }
{ $description "Outputs a new string consisting of " { $snippet "str" } " padded on the right with enough repetitions of " { $snippet "ch" } " to have the result be of length " { $snippet "n" } "." }
{ $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-right print ] each" "ab---\nquux-" } } ;

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

HELP: >string "( seq -- str )"
{ $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" } "." } ;