string.tem

(page "String operations"
(newtable "String operations"
  (op newstring "length [char]" "Creates a string of the given length."
    (tests (newstring 5 #\a)))
(def predicate whitec "c" "Predicate to test if a character is whitespace (space, newline, tab, or return)." (tests (whitec #\tab) (whitec "  ")))
(def predicate nonwhite "c" "Predicate to test if a character is not whitespace (space, newline, tab, or return)." (tests (nonwhite #\tab) (nonwhite #\a)))
(def predicate letter "c" "Predicate to test if a character is alphabetic.  New in arc3." (tests (letter #\A) (letter #\2)))
(def predicate alphadig "c" "Predicate to test if a character is alphabetic or a digit." (tests (alphadig #\A) (alphadig #\2)))
(def predicate punc "c" "Predicate to detemine if c is a punctuation character in the set: .,;:!?" (tests (punc #\.) (punc #\a) (punc ".")))
(def downcase "str" "Converts a string, character, or symbol to lower case.  This only converts ASCII; Unicode is unchanged." (tests (downcase "abcDEF123") (downcase #\A) (downcase 'abcDEF123)))
(def upcase "str" "Converts a string, character, or symbol to lower case.  This only converts ASCII; Unicode is unchanged." (tests (upcase "abcDEF123") (upcase #\a) (upcase 'abcDEF123)))

(def ellipsize "str [limit]" "If str is longer than the limit (default 80), truncate it and append ellipses ('...')." (tests (ellipsize "Too long" 6)))
(def rand-string "n" "Generates a random string of alphanumerics of length n." (tests (rand-string 10)))
(def string "arg [...]" "Converts the args into a string.  The args must be coerce-able to a string." (tests (string 2 'a '(#\b #\c))))
(def recstring "f string [start]" "Recursively steps through the string until f returns a non-nil value, and returns that value.  Returns nil otherwise.  The values passed to f are integer indices; the indices start at 0, or start if specified."
 (tests "(let str \"abcde\"
  (recstring
    (fn (idx) (if (is (str idx) #\\c) (+ 10 idx)))
      str))"))
(mac w/bars "[statement ...]" "Executes each statement and collects the output.  A vertical bar is placed between the output of statements producing output." (tests (w/bars (pr "a") 42 (pr "b") (pr "c") nil)))
  (var bar* "" "The separator string used by <code>w/bars</code>." (tests bar*))
)

(newtable "strings.arc library"
(def tokens "str [sep]" "Splits <code>str</code> into tokens based on the separator (default <code>whitec</code>). <code>sep</code> is either a predicate function on a character, or a character." (tests (tokens " cat dog bird  lizard\nrat\tmouse")
(tokens "foo.bar..baz" #\.) (tokens "a!bc%de@f" (fn (c) (pos c "!@%")))))
(def urldecode "str" "Decodes a string in URL encoding.  The string is assumed to be UTF-8" (tests (urldecode "abc+def %c2%a9")))
(mac litmatch "pat seq [start]" "Tests if <code>seq</code> starting at offset <code>start</code> begins with <code>pat</code>.
 Because of the macro expansion, <code>pat</code> must be a literal string or list of characters and not a variable.  <code>seq</code> can be a string or list of characters." (tests  (litmatch "abc" "abcde") (litmatch "abc" "xabcde") (litmatch "abc" "xabcde" 1) (litmatch (#\a #\b #\c) "abcde")))
(mac endmatch "pat seq" "Tests if <code>seq</code> ends with <code>pat</code>.
 Because of the macro expansion, <code>pat</code> must be a literal string or list of characters and not a variable.  <code>seq</code> can be a string or list of characters." (tests  (endmatch "abc" "abcde") (endmatch "cde" "abcde") (endmatch (#\c #\d #\e) "abcde")))
(def posmatch "pat seq [start]" "If <code>pat</code> is a string or list of characters, return the index (from <code>start</code>) where <code>pat</code> appears in <code>seq</code>.  If <code>pat</code> is a predicate function on one character, it is applied to the characters of <code>seq</code> (starting from <code>start</code>), and returns the index of the first true result. <code>seq</code> is a string or list of characters." (tests (posmatch "abc" "junk") (posmatch "a" "banana" 2) (posmatch (fn (c) (in c #\a #\b)) "foobar") (posmatch '(#\a #\b) '(#\c #\a #\b))))
(def findsubseq "pat seq [start]" "Finds the index where <code>pat</code> is a subsequence of <code>seq</code>, starting at <code>start</code>.  Both <code>pat</code> and <code>seq</code> can be strings or lists of characters.  <code>findsubseq</code> is similar to <code>posmatch</code>, except it doesn't accept a function for <code>pat</code>." (tests
(findsubseq "abc" "fooabcbar") (findsubseq "abc" "x") (findsubseq "an" "banana" 2)))
(def predicate headmatch "pat seq [start]" "Tests if <code>seq</code> from offset <code>start</code> onwards starts with <code>pat</code>.  <code>pat</code> and <code>seq</code> can be strings or lists of characters. <code>headmatch</code> will die if <code>pat</code> is longer than <code>seq</code> and matches up to the end of <code>seq</code>."
(tests (headmatch "abc" "abcde") (headmatch "cd" "abcde") (headmatch "cd" "abcde" 2) (headmatch '(#\a #\b) '(#\a #\b #\c))))
(def begins "seq pat [start]" "Tests if <code>seq</code> begins with <code>pat</code>.  <code>begins</code> is the same as <code>headmatch</code> with the first two arguments reversed, except <code>begins</code> doesn't die if matching goes past the end of <code>seq</code>."
(tests (begins "abcde" "abc") (begins "abc" "abcde") (begins "abcde" "cd" 2)))
(def subst "new old seq" "Substitutes <code>new</code> for <code>old</code> in <code>seq</code>.  <code>new</code> can be any printable object.  <code>old</code> and <code>seq</code> can be strings or lists of characters."
(tests (subst "bar" "foo" "catfood dogfood") (subst '(1 2) "a" "banana")))
(def multisubst "pairs seq" "Performs multiple substitutions on <code>seq</code>.  <code>pairs</code> is a list of pairs of old and new values." (tests  (multisubst '(("a" 1) ("b" "B")) "banana")))
(def predicate blank "str" "Tests if <code>str</code> is blank (whitespace)." (tests (blank "a b") (blank " ")(blank '(#\ #\tab#\newline))))
(def trim "str where [test]" "Trims whitespace (or arbitrary expression) from <code>str</code>.  <code>where</code> can have the value <code>'front</code>, to trim the front of the string (currently broken); <code>'end</code>, to trim the end of the string; or </code>'both</code> to trim both ends of the string.  If specified, <code>test</code> is either a character or a predicate function on characters." (tests (trim " abc " 'end) (trim " abc " 'both) (trim "aabcaa" 'both #\a) (trim "aabcaa" 'both [in _ #\a #\b])))
(def num "m [digits [trail-zeros [init-zero]]]" "Formats a real number. <code>digits</code> is the number of digits after the decimal point, <code>trail-zeros</code> is a Boolean indicating if trailing zeros should be included, and <code>init-zero</code> is a Boolean indicating if there should be a 0 before the decimal point.  " (tests (num 123456) (num -123456) (num 1.2345 2) (num 1.2 4 t) (num .3 4 t t)))
(def pluralize "n str" "Returns str pluralized; if n is 1 or a list of length 1, str is returned unchanged; otherwise an 's' is appended. Renamed from plural in arc3."
(tests (pluralize 2 "fox") (pluralize '() "fish")))
(def plural "n str" "Returns n and str pluralized. New in arc3."
(tests (plural 2 "fox") (plural '() "fish")))
(def halve "str" "Splits a string in two on whitespace.  New in arc3." (tests (halve "ab cd ef") (halve "abc")))
(def positions "test seq" "Returns a list of positions in seq where test is true.  Works on sequences in general.  New in arc3." (tests (positions #\a "That abacus") (positions odd '(1 2 4 5 7))))
(def lines "str" "Splits str into lines.  New in arc3." (tests (lines "a b\nc d\n\ne f")))
(def urlencode "str" "Completely url-encodes str.  Doesn't work with unicode.  New in arc3."  (tests (urlencode "abc") (urlencode "\u2603")))
(def predicate nonblank "str" "Returns str if it is nonblank, nil otherwise.  New in arc3." (tests (nonblank "a b") (nonblank "\n\t ")))

)
)
)