From d4d5ea638d25f5b7abe6ce194ccab938baac2b8f Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Fri, 17 Feb 2017 14:27:27 -0800
Subject: [PATCH] document push! and pop!

---
 beautiful-racket-lib/br/scribblings/br.scrbl | 36 +++++++++++++++-----
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/beautiful-racket-lib/br/scribblings/br.scrbl b/beautiful-racket-lib/br/scribblings/br.scrbl
index c098666..f08b0b4 100644
--- a/beautiful-racket-lib/br/scribblings/br.scrbl
+++ b/beautiful-racket-lib/br/scribblings/br.scrbl
@@ -108,6 +108,15 @@ Like @racket[format-datum], but applies @racket[datum-form] to the lists of @rac
 ]
 }
 
+@defproc[(datum? [x any/c]) boolean?]{
+Return @racket[#t] if @racket[x] is a @racket[list?] or a @racket[symbol?].
+
+ @examples[#:eval my-eval
+(datum? '(a b c d e f))
+(datum? 'a)
+(datum? "a")
+]
+}
 
 @section{Debugging}
 
@@ -637,15 +646,26 @@ Convert @racket[values] to a simple list.
 ]
 }
 
+@defform[(push! list-id val)]{
+Mutate @racket[list-id] by putting @racket[val] on top.
 
-@defmodule[br/datum]
+@examples[#:eval my-eval
+(define xs '(2 3 4))
+(push! xs 1)
+xs
+]
+}
 
-@defproc[(datum? [x any/c]) boolean?]{
-Return @racket[#t] if @racket[x] is a @racket[list?] or a @racket[symbol?].
+@defform[(pop! list-id)]{
+Mutate @racket[list-id] by removing the topmost element, and return this element as the result.
 
- @examples[#:eval my-eval
-(datum? '(a b c d e f))
-(datum? 'a)
-(datum? "a")
+@examples[#:eval my-eval
+(define xs '(1 2 3 4))
+(define top (pop! xs))
+top
+xs
 ]
-}
\ No newline at end of file
+}
+
+
+