vector-map(3scm)

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

💖 vector-map — bestie's guide to mapping over vectors 💖

okay so you found the vector-map(3scm) page in the Scheme Programmer's Manual and you're like "what is this beautiful little function" — don't worry, i got you. this is the whole thing, no skips, no cap. 🫶

✨ NAME ✨

vector-map — maps a procedure over the elements of vectors. that's it. that's the vibe. 🌸

📚 LIBRARY 📚

import it like this, depending on which scheme you're living in:

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

🎀 SYNOPSIS 🎀

(vector-map proc vector1 vector2 ...)

💅 DESCRIPTION 💅

so vector-map applies proc element-wise to the elements of the vectors and returns a vector of the results, in order. literally the glow-up machine: vector in, vector out, each element gets the proc treatment. ✨

proc is always called in the same dynamic environment as vector-map itself. same vibe, same surroundings, no swaps. 🦋

the order in which proc is applied to the elements of the vectors is unspecified. so don't go assuming anything about order, bestie, that's not the flex you think it is. 🙈

if multiple returns occur from vector-map, the return values returned by earlier returns are not mutated. (ngl this is the kind of caveat you only care about when you're doing something unhinged with continuations, but it's here, so it's here. 💀)

R6RS — the vectors must all have the same length. all of them. no exceptions. 💯

R7RS — if more than one vector is given and not all vectors have the same length, vector-map terminates when the shortest vector runs out. shortest one decides when the party's over. 🎉

⭐ RETURN VALUES ⭐

returns a single value which is a vector object. one value. a vector. iconic. 👑

🌈 EXAMPLES 🌈

grab the second element of each pair, easy:

(vector-map cadr '#((a b) (d e) (g h)))
        => #(b e h)

exponentiate each number by itself, my beloved:

(vector-map (lambda (n) (expt n n))
            '#(1 2 3 4 5))
        => #(1 4 27 256 3125)

now here's the messy one — different lengths, fresh drama:

(vector-map + '#(1 2 3) '#(4 5 6 7))
        => #(5 7 9)          ; R7RS
        raises &assertion    ; R6RS

and the order-is-unspecified demo, watch the counter do its little dance:

(let ((count 0))
  (vector-map
   (lambda (ignored)
     (set! count (+ count 1))
     count)
   '#(a b)))

=>   #(1 2) or #(2 1)

either result is legit! that's the whole point! 💫

🧚 APPLICATION USAGE 🧚

this procedure is used in place of map(3scm) when vectors are used instead of lists. same energy, different container. 🍓

🔥 COMPATIBILITY 🔥

the R6RS version is consistent with the R6RS version of map(3scm) in that it requires all vectors to be the same length, and R7RS is likewise consistent with its version of map(3scm) in instead using the shortest vector. the two standards just have different opinions and honestly, both are valid. 💜

💀 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. likewise this is raised if proc does not accept a single value, and may be raised if it does not return a single value. 😭
  • R7RS — the assertions described above are errors. additionally it is an error if proc does not return a single value. implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically. (yes. catastrophically. it says that. be careful out there. 🙏)

👀 SEE ALSO 👀

🏆 STANDARDS 🏆

R6RS, R7RS, SRFI-43. all three, collectively stanning. 💖

📜 HISTORY 📜

the first RnRS report to carry this procedure was R6RS. R7RS also included it, basing it on the semantics from SRFI-43. a little origin story for your girl. ✨

🫶 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!! 🎀 this one's from 2022-03-29, part of the scheme-manpages project (source/version energy, you know how it is), and it lives at vector-map(3scm) in the Scheme Programmer's Manual. now go map something pretty. 💅✨

📦 where this page comes from