Manual page for string-for-each(3scm)

string-for-each - call a procedure on each character in a string

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme base))              ;R7RS

SYNOPSIS

(string-for-each proc string ...)

DESCRIPTION

Applies proc element-wise to the characters of the strings for its side effects, in order from the first characters to the last.

Proc is always called in the same dynamic environment as string-for-each itself.

R7RS: If more than one string is given and not all strings have the same length, this procedure terminates when the shortest string runs out. It is an error for proc to mutate any of the strings.

IMPLEMENTATION NOTES

The implementation must check the restrictions on proc to the extent performed by applying it as described. An implementation may check whether proc is an appropriate argument before applying it.

RETURN VALUES

R6RS: Returns unspecified values.
R7RS: Returns an unspecified value.

EXAMPLES

(let ((v '()))
  (string-for-each
    (lambda (c) (set! v (cons (char->integer c) v)))
    "abcde")
  v)
  => (101 100 99 98 97)

APPLICATION USAGE

This procedure is used for its side-effects, so this procedure does not show up in purely functional programs. The characters are usually accumulated using mutation of a variable or a data structure, or they are written to an output port. Common usages are counting and conversion.

COMPATIBILITY

The R7RS variant of this procedure terminates early, which matches the R7RS behavior for for-each(3scm).

ERRORS

This procedure can raise exceptions with the following condition types:

&assertion (R6RS): The wrong number of arguments was passed or an argument was outside its domain. In particular, this is raised if the strings do not all have the same length, and when proc does not accept as many arguments are there are strings.
R7RS: The assertions described above are errors. Further more, it is an error for proc to mutate any of the strings. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

STANDARDS

R6RS, R7RS, SRFI-13

HISTORY

The first Scheme report to have this procedure was R6RS. It was later also added in R7RS. There is a variant in SRFI-13 that predates these two, but it has a different signature: (string-for-each proc s [start end])

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

Markup created by unroff 1.0sc, March 04, 2023.