substring(3scm)

💅 substring(3scm) — from the Scheme Programmer's Manual bestie 🎀

okay so before we even start: this page lives in the Scheme Programmer's Manual, and it's about one (1) little procedure that is lowkey iconic and you use it constantly without even thinking. let's get into it ✨

🌸 NAME 🌸

substring — copy part of a string. that's it. that's the whole job. she's simple, she's reliable, she ate 💅

📚 LIBRARY 📚

import her from whichever flavour you're on, no cap:

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

✨ SYNOPSIS ✨

(substring string start end)

three arguments, no more, no less. main character energy fr 🫶

💖 DESCRIPTION 💖

so substring returns a newly allocated string, and that string is made from the characters of string starting at index start (inclusive, bestie — she's in) and ending at index end (exclusive, so end itself is not invited to the party 🙈).

the rules, and you will respect them:

string must be a string, and start and end must be exact integer objects satisfying

0 ≤ start ≤ end ≤ (string-length string)

like, that chain has to hold. no vibes-based index math, okay? 😭

and here's a cute little detail: if start = end, then the resulting empty string does not need to be newly allocated, as per eq?(3scm). so like, an empty string is still an empty string. she's reusable 🌈

🧚 IMPLEMENTATION NOTES 🧚

• Chez Scheme, Loko Scheme, (more?) — there is a unique empty string object.

(the "(more?)" is literally in the original, it's giving "we're still collecting data" 💀)

👑 RETURN VALUES 👑

returns a single string object. one and done. slay ⭐

🍓 EXAMPLES 🍓

(substring "SCHEMER" 0 6)  =>  "SCHEME"

see how she dropped the R? exclusive end, periodt 💅

🔥 COMPATIBILITY 🔥

this procedure is the same in all RnRS Scheme revisions since R2RS. like, genuinely consistent across the whole timeline. no drama, no breaking changes, we love a stable queen 👑

💀 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. i.e. you gave her something she cannot work with and she will let you know 😭
• R7RS — the assertions described above are errors. implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. yes, "fail catastrophically" is the actual wording. so like... be normal about your indices please 🙈

🦋 SEE ALSO 🦋

• string-copy(3scm)

🌟 STANDARDS 🌟

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

certified by literally everyone, iykyk 🎀

🧃 HISTORY 🧃

this procedure was introduced in R2RS. earlier revisions of Scheme ran on MacLisp, which had a substr function that it in turn copied from PL/I. instead of the end argument, it had an optional length argument. so like, the ancestor of this function was measuring lengths instead of endpoints, and honestly? we've grown as a community 💜

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

---

and that's the whole page bestie ✨ no notes, no cap, she's iconic. this was substring(3scm) from the Scheme Programmer's Manual, dated 2022-03-28 — go forth and slice your strings responsibly 💖🌸🎀