----
title: UTILS module – various utility functions
SPDX-FileCopyrightText: 2024 Norman Gray <https://nxg.me.uk>
SPDX-License-Identifier: BSD-2-Clause


This module contains a variety of utility functions which are
otherwise missing from the implementation.

Standard scheme functions
-------------------------

‘Standard’ scheme functions:

  * call-with-values
  * define-values
  * receive (ie, [SRFI-8](https://srfi.schemers.org/srfi-8/srfi-8.html))

Miscellaneous utilities:

  * define/trace
  * en-dashify
  * getopt
  * make-set/eqv
  * resolve-file
  * showbytes/hex
  * split-path
  * string->hash
  * string->page-range
  * expand-tex-accents
  * stringify
  * stringify/true
  * subprocess
  * symbol<?

Character wrangling
-------------------

Case modifications:

  * `uppercase-string/bst`, `lowercase-string/bst`, `titlecase-string/bst` :
    case modifications with the peculiarities defined by BibTeX.
  * `ustring-upcase`, `ustring-downcase`, `ustring-titlecase`,
    `uchar-upcase`, `uchar-downcase`, `uchar-titlecase` :
    more conventional case modifications.  The function names here are
    chosen to match the `string-upcase` (etc) versions built in to s7;
    `uppercase-string` might be a more attractive choice.

ctype-style character classes:

  * char-alnum? (Unicode categories L or N)
  * char-alpha? (L)
  * char-cntrl? (C)
  * char-digit? (N)
  * char-lower? (Ll)
  * char-punct? (P)
  * char-space? (Z)
  * char-upper? (Lu or Lt)

These commands take both characters and integers as arguments, and
match [`ctype(3)`](https://www.man7.org/linux/man-pages/man0/ctype.h.0p.html)
when given arguments in the ASCII range.

They will also behave correctly when given Unicode codepoints (as
integer); thus `char-alnum?` will return true for Unicode
general categories L or N, and so on.
As a special case `char-space?` will return true for category Z _plus_ the ASCII
whitespace characters below U+0020, for which `isspace` returns true
(these are category ‘C’ for Unicode).
All of these functions will return `#f` without error, if given an argument
other than a character or integer.  Also note that these functions are
(currently) Unicode-aware only for characters in the [Base Multilingual
Plane (BMP)](https://en.wikipedia.org/wiki/Plane_%28Unicode%29#Basic_Multilingual_Plane),
and will return `#f` for any codepoints beyond that (ie,
from Linear-B upwards).

The function `uchar-alphabetic?` identifies a character as
‘alphabetic’ in the Unicode sense, which is slightly broader than
`char-alnum?`.  See the [unicode module](unicode.xhtml) for more
discussion.

The following functions are analogous, but have no ctype counterparts.

  * char-other-letter? (Unicode L other than Lu, Lt or Ll)
  * char-symbol? (S)
  * char-mark? (M)

The following functions match the ctype ones, but have no
Unicode-related extensions.

  * char-blank?
  * char-graph?
  * char-print?
  * char-xdigit?

The following functions are the ones defined in R5RS.
They (currently) work _only_ on characters, and are not defined on integers.

  * char-alphabetic?
  * char-downcase
  * char-lower-case?
  * char-numeric?
  * char-upcase
  * char-upper-case?
  * char-whitespace?

SRFIs
-----

From [SRFI-1](https://srfi.schemers.org/srfi-1/srfi-1.html) (a partial
implementation, in some cases):

  * any
  * circular-list
  * drop
  * drop-right
  * every
  * filter
  * fold
  * last
  * last-pair
  * split-at
  * take
  * take-right
  * zip

...plus `intersperse`, which feels like it ought to be in SRFI-1, but isn't.

From [SRFI-13](https://srfi.schemers.org/srfi-13/srfi-13.html):

  * string-index
  * string-index-right
  * string-join
  * string-prefix?
  * string-split
  * string-suffix?
  * string-trim
  * string-trim-both
  * string-trim-right