cons*(3scm)

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

💅 cons* — the header line said cons*(3scm) and honestly? iconic. Scheme Programmer's Manual vibes only ✨

Okay bestie, pull up a chair, because today we're talking about cons* — the little procedure that conses up a whole chain of pairs for you. Yes, a chain. Like a friendship bracelet but made of pairs. 🎀

📚 LIBRARY — where to get it

Import it from either of these, depending on which flavor of Scheme you're living in:

(import (rnrs))        ;R6RS
(import (rnrs lists))  ;R6RS

Both slay, both valid. Pick your fighter. 💖

🌸 SYNOPSIS — the shape of it

(cons* obj1 ... objn obj)
(cons* obj)

Two whole forms, bestie. Two. The way that it can be a big chain or just one lonely little argument is genuinely so versatile of it. 🦋

✨ DESCRIPTION — what it actually does

So if you call cons* with at least two arguments, it hands you back a freshly allocated chain of pairs. The cars of those pairs are obj1, ..., objn, in order, and the cdr of the very last pair is obj. Lowkey elegant, ngl.

And if you call it with only one argument? It just returns that argument. That's it. No pairs, no chain, just the object itself, being its own main character. Periodt. 👑

Think of it as list's cooler cousin — the list(3scm) vibes are there, but with one crucial glow-up: the last argument (not the empty list!) becomes the cdr of the last pair in the chain. That's the whole difference and it's giving chef's kiss. 💅

🫶 RETURN VALUES

Returns a single value. That value is either obj itself, or a chain of pairs. One or the other, no ambiguity, no drama. 🌈

🔥 EXAMPLES — vibe check, passed

(cons* 1 2 '(3 4 5))  =>  (1 2 3 4 5)
(cons* 1 2 3)         =>  (1 2 . 3)
(cons* 1)             =>  1

Look at that third one. Just 1. Iconic behavior, honestly. Not me being obsessed with a one-argument return. 😭

💜 APPLICATION USAGE — where it eats

This procedure replaces constructs like (apply list a b x*). It's faster, and it handles the case where the last argument does not need to be a list. No cap, that's a real upgrade. 🔥

Depending on your Scheme implementation, it may also be used in the expansion of quasiquote(7scm) for constructs like `(,a ,b ,@x*). So it's out here doing background work behind the scenes too. iykyk. 🧚

🦋 COMPATIBILITY

This procedure is unique to R6RS. She's exclusive, she's niche, she's not showing up at every party. 💀

🚨 ERRORS — the dramatic part

This procedure can raise exceptions with the following condition types:

  • &assertion (R6RS) — the wrong number of arguments was passed. You handed her the wrong amount of stuff. It happens to the best of us, but she will let you know. 🙈
  • &implementation-restriction (R6RS) — there is not enough free memory to hold the new pairs. Real talk: if the machine is out of memory, this is the exception you get. Nothing to do with your code being cute or not. 😭

👀 SEE ALSO

Go read those too, bestie, they're the supporting cast and they understood the assignment. 💖

⭐ STANDARDS

R6RS. That's the standard. That's the whole line. 💅

🎀 HISTORY

The first RnRS report to have this procedure was R6RS. So like, it wasn't in the earlier ones. It showed up when it was ready and it showed up legendary. 🌸

👑 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/
🫶 Okay that's the whole page, you made it to the end, I'm so proud of you. Now go cons up a chain and be free. ✨

💖 Dated 2022-05-11 — scheme-manpages, and this little manpage ate and left no crumbs. Bye bestie! 💖

📦 where this page comes from