vector-set!(3scm)

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

💅 vector-set! (3scm) — from the Scheme Programmer's Manual, bestie ✨

okay so. we're doing vector-set! today and honestly? she's iconic. small procedure, big main character energy. this page lives in the Scheme Programmer's Manual (that's the 3scm part, iykyk) and she's here to help you poke at vectors. let's go 🫶

🌸 NAME 🌸

vector-set! — modify an element of a vector. that's it. that's the whole gig. she changes one little slot and dips 💅

📚 LIBRARY 📚

import her from whichever flavour of Scheme you're living in, no judgement:

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

✨ SYNOPSIS ✨

(vector-set! vector k obj)

three arguments, one very important job 🎀

💖 DESCRIPTION 💖

Stores obj in element k of vector. that's the whole thing, no cap. you point at a slot, you drop a new value in it. slay 🔥

🧠 IMPLEMENTATION NOTES 🧠

okay this is the juicy part, pay attention bestie 👑

Constants in the source code are not supposed to be modified by the program — that's the rule — but programs may still be able to do so anyway. like, the vibes are illegal but the door is unlocked 😭

A compiler that creates executable files can place the constants in read-only pages, where the processor will automatically report attempts to mutate them. so the hardware itself snitches on you. iconic behaviour fr fr 💀

Interpreters and online compilers normally skip this step and tend to not detect mutation of constants. they simply don't check. living their truth 🙈

Implementations can also mark a vector as immutable using various strategies like special memory ranges, a special immutable vector tag or an immutable bit next to the length field. lots of ways to say "don't touch" 💅

Implementations may also do different things in different modes, so just testing at the REPL is not a reliable method to check if constants are always mutable or not in a particular implementation. do NOT trust a single REPL vibe check, bestie, she lies 😭

🎀 RETURN VALUES 🎀

  • R6RS — Returns unspecified values. (plural! she's fancy)
  • R7RS — Returns an unspecified value. (singular, humble)

either way, don't count on getting anything useful back 🦋

🌈 EXAMPLES 🌈

first one, the classic. mutate a slot in a real live vector:

(let ((vec (vector 0 '(2 2 2 2) "Anna")))
   (vector-set! vec 1 '("Sue" "Sue"))
   vec)
            =>  #(0 ("Sue" "Sue") "Anna")

Anna stays, slot 1 gets a whole new duo. periodt.

second one, the chaotic one — this is mutation of a constant vector. Constants are allowed to be immutable, but implementations do not always check this. It should raise an &assertion exception:

;; This example shows mutation of a constant vector. Constants are
;; allowed to be immutable, but implementations do not always check
;; this. It should raise an &assertion exception.
(vector-set! '#(0 1 2) 1 "doe")
            => unspecified
              ; should raise &assertion exception

so she says unspecified, but she should be throwing hands with &assertion. chaotic queen 💀

🦋 APPLICATION USAGE 🦋

ok so the specification of vectors does not actually require constant access time, but in practice they are always implemented as flat arrays. always. no cap.

Therefore this procedure is used in algorithms that perform random-access operations on arrays. Such algorithms would not have the same time complexity if lists were used instead. so if you tried this with lists you'd be sitting there waiting forever and the vibe would be ruined 😭

🌸 COMPATIBILITY 🌸

This procedure works the same everywhere. universal queen. no notes. 💖

💀 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, vector should be a mutable vector, and k must be an exact nonnegative integer less than the length of vector. read that again: exact, nonnegative, less than the length. all three. don't test her 🙈
  • 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 and yes I'm screaming 😭💀

👀 SEE ALSO 👀

the whole friend group honestly 🫶

👑 STANDARDS 👑

R4RS, IEEE Scheme, R5RS, R6RS, R7RS — she's been certified by literally everyone ⭐

🧚 HISTORY 🧚

This procedure first appeared in R2RS, where the vector notation was optional. yeah. optional. the vector notation was optional. can you imagine 😭 ancient times fr

💜 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/. love them, thank them, go look at the repo 🌷

🍓 BUGS 🍓

Programs should not modify constants.

that's it. that's the bug section. one line. she said what she said and she's right 💅

🎀✨ and that's the page bestie!! written up in the manual on 2023-01-28, coming to you straight from the scheme-manpages project (that's the source + version at the bottom of the original, folded in all cute for you). go set some vector elements, but like... responsibly. mwah 💋🌈⭐
📦 where this page comes from