(doc-group string
  «Strings and runes.»)

(defdoc (rune (n #xfffd))
  «Construct a rune from a Unicode code point.  Without code point
   specified, an "invalid" rune (`#xFFFD`) is returned.»
  :doc-group string
  :doc-see rune?)

(defdoc (rune->codepoint r)
  «Return a rune's Unicode code point as a fixnum.»
  :doc-example
  «(rune->codepoint #\й)
   ; ↳ 1081»
  :doc-group string)

(defdoc (rune-alphabetic? r)
  «Return `T` if the rune is alphabetic, `NIL` otherwise.»
  :doc-example
  «(rune-alphabetic? #\9)
   ; ↳ NIL»
  :doc-example
  «(rune-alphabetic? #\й)
   ; ↳ T»
  :doc-group string
  :doc-see rune-numeric?
  :doc-see rune-whitespace?)

(defdoc (rune-numeric? r)
  «Return `T` if the rune is numeric, `NIL` otherwise.»
  :doc-example
  «(rune-numeric? #\9)
   ; ↳ T»
  :doc-example
  «(rune-numeric? #\й)
   ; ↳ NIL»
  :doc-group string
  :doc-see rune-alphabetic?
  :doc-see rune-whitespace?)

(defdoc (rune-whitespace? r)
  «Return `T` if the rune is whitespace, `NIL` otherwise.»
  :doc-example
  «(rune-whitespace? #\newline)
   ; ↳ T»
  :doc-example
  «(rune-whitespace? #\_)
   ; ↳ NIL»
  :doc-group string
  :doc-see rune-alphabetic?
  :doc-see rune-numeric?)

(defdoc (rune-downcase r)
  «Return the lowercase version of the rune.

   The rune is returned unchanged if it has no case.»
  :doc-example
  «(rune-downcase #\ä)
   ; ↳ #\ä»
  :doc-example
  «(rune-downcase #\DŽ)
   ; ↳ #\dž»
  :doc-group string
  :doc-see rune-lower-case?
  :doc-see rune-upcase
  :doc-see rune-titlecase)

(defdoc (rune-upcase r)
  «Return the higher case version of the rune.

   The rune is returned unchanged if it has no case.»
  :doc-example
  «(rune-upcase #\ä)
   ; ↳ #\ä»
  :doc-example
  «(rune-upcase #\dž)
   ; ↳ #\DŽ»
  :doc-group string
  :doc-see rune-upper-case?
  :doc-see rune-downcase
  :doc-see rune-titlecase)

(defdoc (rune-titlecase r)
  «Return the title case version of the rune.

   For most runes the result is the same as with `rune-upcase`.»
  :doc-example
  «(rune-titlecase #\й)
   ; ↳ #\Й»
  :doc-example
  «(rune-titlecase #\dž)
   ; ↳ #\Dž»
  :doc-group string
  :doc-see rune-title-case?
  :doc-see rune-downcase
  :doc-see rune-upcase)

(defdoc (rune-title-case? r)
  «Return `T` if the rune is a title case one, `NIL` otherwise.

   For most runes the result is the same as with `rune-upper-case?`.»
  :doc-example
  «(rune-title-case? #\DŽ)
   ; ↳ NIL»
  :doc-example
  «(rune-title-case? #\Dž)
   ; ↳ T»
  :doc-group string
  :doc-see rune-titlecase
  :doc-see rune-lower-case?
  :doc-see rune-upper-case?)

(defdoc (rune-upper-case? r)
  «Return `T` if the rune is an uppercase one, `NIL` otherwise.»
  :doc-example
  «(rune-upper-case? #\DŽ)
   ; ↳ T»
  :doc-example
  «(rune-upper-case? #\Dž)
   ; ↳ NIL»
  :doc-group string
  :doc-see rune-upcase
  :doc-see rune-lower-case?
  :doc-see rune-title-case?)

(defdoc (rune-lower-case? r)
  «Return `T` if the rune is a lowercase one, `NIL` otherwise.»
  :doc-example
  «(rune-lower-case? #\dž)
   ; ↳ T»
  :doc-example
  «(rune-lower-case? #\Dž)
   ; ↳ NIL»
  :doc-group string
  :doc-see rune-downcase
  :doc-see rune-upper-case?
  :doc-see rune-title-case?)

(defdoc (str . terms)
  «Return concatenation of terms formatted as strings.

   This is equivalent to `(princ terms…)`, except the string is
   _returned_, rather than printed.»
  :doc-example
  «(str "a" 'b 1 #(0))
   ; ↳ "ab1#(0)"»
  :doc-group string)

(defdoc (str-width s)
  «Return the number of columns needed to represent a string or a rune.

   If a non-printable control rune is encountered, the result is `NIL`,
   else it is a non-negative integer. Rune `#\null` is considered of width zero.»
  :doc-example
  «(str-width #\й)
   ; ↳ 1»
  :doc-example
  «(str-width "⌛!")
   ; ↳ 3»
  :doc-example
  «(str-width "nope\n")
   ; ↳ NIL»
  :doc-group string)

(defdoc (str-rune s n)
  «Return the nth rune of the string.

   Throws an exception if the index `n` is out of bounds.»
  :doc-example
  «(str-rune "йцукен" 3)
   ; ↳ #\к»
  :doc-group string
  :doc-see str-sub)

(defdoc (str-sub s start (end NIL))
  «Return the portion of the string within the specified bounds.

   The `start` and `end` index by rune. Specifying any index out of bounds
   of the string will result in an exception thrown.

   If `end` isn't specified the portion is assumed to begin at `start`
   until the end of the original string.»
  :doc-example
  «(str-sub "hello" 2)
   ; ↳ "llo"»
  :doc-example
  «(str-sub "hello" 3 3)
   ; ↳ ""»
  :doc-example
  «(str-sub "hello" 2 4)
   ; ↳ "ll"»
  :doc-group string
  :doc-see str-rune)

(defdoc (str-utf8? s)
  «Return `T` if `s` is a valid UTF-8 string, `NIL` otherwise.»
  :doc-example
  «(str-utf8? "привет")
   ; ↳ T»
  :doc-example
  «(str-utf8? "при\xffвет")
   ; ↳ NIL»
  :doc-group string
  :doc-see str?)

(defdoc (str->num s (:base NIL))
  «Return the number using the radix `base` in the string `s`.

   Returns `NIL` if the number could not be parsed. Any number of leading
   and/or trailing whitespace runes is allowed and those will be ignored.»
  :doc-example
  «(str->num "1.2")
   ; ↳ 1.2»
  :doc-example
  «(str->num "#x123")
   ; ↳ 291»
  :doc-example
  «(str->num "ffff" :base 16)
   ; ↳ 65535»
  :doc-example
  «(str->num "777" :base 8)
   ; ↳ 511»
  :doc-group string
  :doc-see num->str)

(defdoc (str-split str (sep " \n\t\v\f") (:trim NIL))
  «Return a list of substrings of `str` by splitting at any character in
   the string `sep`. The splitting characters are removed.

   By default the string is split on space, line feed (newline),
   horizontal and vertical tab, and form feed.

   Trim removes empty strings from the list.»
  :doc-example
  «(str-split "hello world")
   ; ↳ ("hello" "world")»
  :doc-example
  «(str-split "multiple   spaces ")
   ; ↳ ("multiple" "" "" "spaces" "")»
  :doc-example
  «(str-split "multiple   spaces " :trim T)
   ; ↳ ("multiple" "spaces")»
  :doc-example
  «(str-split "too many vowels" "aeiou")
   ; ↳ ("t" "" " m" "ny v" "w" "ls")»
  :doc-group string)