factor/library/collections/strings.facts

USING: arrays help kernel strings vectors ;

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 } ;