string-for-each(3scm)

💖 string-for-each(3scm) 💖

okay bestie, welcome to the Scheme Programmer's Manual — yes that's the manual name, and yes this page is gonna be your new fave. we're talking about string-for-each, and it lowkey slays.

---

✨ NAME ✨

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

🫶 LIBRARY 🫶

import these, depending on your vibe:

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

🎀 SYNOPSIS 🎀

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

🌸 DESCRIPTION 🌸

so what it does is: it applies proc element-wise to the characters of the strings, for its side effects, going in order from the first characters to the last. slay, in order, no skipping 💅

proc is always called in the same dynamic environment as string-for-each itself. same vibe, same surroundings, periodt.

R7RS — okay this is important: if more than one string is given and not all strings have the same length, this procedure terminates when the shortest string runs out. yes, it just dips when the shortest one is done, that's the rule. also: it is an error for proc to mutate any of the strings. don't do it, bestie, hands off 😭

🦋 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. so like, it's allowed to do a little vibe check upfront — that's fair.

⭐ RETURN VALUES ⭐

• R6RS — returns unspecified values.
• R7RS — returns an unspecified value.

(plural vs singular, iconic attention to detail fr fr)

🧚 EXAMPLES 🧚

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

look at that beautiful reversed list of char codes. we ate. 👑

🌈 APPLICATION USAGE 🌈

this procedure is used for its side-effects, which means it does not show up in purely functional programs. ngl, it's a side-effect girlie through and through. 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. very demure, very useful.

👑 COMPATIBILITY 👑

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

💀 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. 💀 like, catastrophic catastrophic. so maybe just don't mutate the strings, bestie.

🔥 SEE ALSO 🔥

for-each(3scm), string-map(3scm), vector-for-each(3scm)

(yes the original listing has the comma going the silly way, we keep it exactly as-is, iykyk)

🍓 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]). so like, the og version had extra snackable arguments. history is giving evolution. 🦋

🌟 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/.

---

that's the whole page, bestie — signed, sealed, dated 2022-05-12, from the string-for-each(3scm) corner of the Scheme Programmer's Manual. mwah 💋 go forth and iterate those characters 🎀