string-ref(3scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💖 string-ref — get a character from a string 💖

okay bestie, welcome to the Scheme Programmer's Manual ✨ (yes that's the manual name, i'm folding it in here so it doesn't get lonely at the top). this one's about string-ref, and it's honestly so much cuter than it sounds, stick with me 🫶

🌸 NAME 🌸

string-ref — get a character from a string. that's it. that's the whole job. iconic behavior honestly 💅

📚 LIBRARY 📚

like, you gotta import the right thing first, and the vibe depends on which standard you're living in:

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

pick your fighter, they all work 🎀

✨ SYNOPSIS ✨

(string-ref string k)

💫 DESCRIPTION 💫

Returns character k of string, using zero-origin indexing — meaning the first character is at index 0, not 1. yes bestie, counting from zero, we been knew 🧚

  • R6RS — implementors should make string-ref run in constant time. should! it's a should, not a must, don't come for me 😭
  • R7RS — there is no requirement for this procedure to execute in constant time. it's giving "we're keeping our options open" 🙈

🛠️ IMPLEMENTATION NOTES 🛠️

  • Chibi Scheme — Chibi supports O(1) string access if the SEXP_USE_STRING_INDEX_TABLE feature is enabled. so like, flip that flag and you're speedrunning ⭐

🎁 RETURN VALUES 🎁

Returns a single value, which is a character object. it's eqv?(3scm) to the one that was last placed in the string at index k — so the exact same character object you put in there, no copies, no cap 💜

🌈 EXAMPLES 🌈

(string-ref "abc" 1)  =>  #\b

ate. no crumbs. 🔥

🦋 APPLICATION USAGE 🦋

This procedure is used to implement algorithms that read strings in non-linear access patterns — like, jumping around, main character energy, no order, just vibes. if your program reads strings at increasing indices though, you can use open-string-input-port(3scm) instead. (that's the chill sequential way, highly recommend if that's your thing 🍓)

👑 RATIONALE 👑

The choice of R7RS to not require execution in constant time opens the possibility for implementations to use UTF-8 or UTF-16 as the internal string representation. so like, it's a trade-off bestie, and honestly? understandable 💀

💅 COMPATIBILITY 💅

This procedure is functionally the same in all RnRS revisions after R2RS. the differences are in:

  • which characters an implementation can represent
  • how errors are signalled
  • the time complexity of doing the lookup

so the what is the same, the how is a whole personality difference 😌

💀 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. raised if k is not a valid index of string.
  • 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 😭 (yeah. that's a real quote. buckle up.)
bestie please don't pass a bad index. "fail catastrophically" is not a cute look, i'm begging 🙏

🔗 SEE ALSO 🔗

  • string-set!(3scm)
  • vector-ref(3scm)
  • open-string-input-port(3scm)

go read those next, i'll wait 💖

⭐ STANDARDS ⭐

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — it's certified, it's legit, it's in all of them 👑

🕰️ HISTORY 🕰️

First introduced in R2RS. Scheme before R2RS, running on MacLISP, had a similar getchar function — but plot twist: it used one-origin indexing and worked on atomic symbols instead of character strings. so like, the ancestor of this function was a whole different creature 😭 we've come so far 🦋

🫶 AUTHORS 🫶

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. more info lives at https://github.com/schemedoc/manpages/ — go show them love, they made this whole thing ✨

🙈 BUGS 🙈

It is easy to get the index validity check wrong. like, really easy. for example: GNU Guile 3.0.8 segfaults on evaluating (string-ref "" -1). segfaults!! on a one-liner!! that's not slay, that's a crash bestie 💀💀

ngl this whole page is a mood: constant-time should, constant-time not required, and one very famous Scheme that absolutely fumbled the boundary check. remember the vibes, remember the facts 💜

🌸 that's the whole glow-up! sourced from the scheme-manpages project, dated 2022-04-04, and the page itself is string-ref(3scm) — mwah, go read a string, character by character, responsibly 🎀✨🫶

📦 where this page comes from