bug#59595: [PATCH 1/3] Add examples and incomplete wordings.

bug#59595: [PATCH 1/3] Add examples and incomplete wordings.

[Yuval Langer]

---
 doc/ref/api-data.texi | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 8658b9785..8c18b4d40 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4767,7 +4767,7 @@ It also allows further properties to use the same symbols among their
 possible values without becoming ambiguous:
 
 @lisp
-(define car1-properties '((colour . red)
+(define car2-properties '((colour . red)
                           (transmission . manual)
                           (fuel . unleaded)
                           (steering . power-assisted)
@@ -4793,6 +4793,37 @@ extract or change individual pieces of information:
  (locking . manual)))
 @end lisp
 
+Notice that if we try the same @code{assq-set!} call with
+@code{car2-properties}, we get an exception:
+
+@lisp
+(assq-set! car2-properties 'seat-colour 'black)
+@end lisp
+
+This is due to the fact that literal alists are immutable. If you want
+to mutate an alist, you must define it using the @code{acons}
+constructor:
+
+@lisp
+(define car3-properties (acons 'colour 'red
+                        (acons 'transmission 'manual
+                        (acons 'fuel 'unleaded
+                        (acons 'steering 'power-assisted
+                        (acons 'seat-colour 'red
+                        (acons 'locking 'manual '())))))))
+
+(assq-ref car3-properties 'seat-colour) @result{} red
+(assq-set! car3-properties 'seat-colour 'black)
+@result{}
+((colour . red)
+ (transmission . manual)
+ (fuel . unleaded)
+ (steering . power-assisted)
+ (seat-colour . black)
+ (locking . manual)))
+(assq-ref car3-properties 'seat-colour) @result{} black
+@end lisp
+
 Hash tables also have keys, and exactly the same arguments apply to the
 use of symbols in hash tables as in association lists.  The hash value
 that Guile uses to decide where to add a symbol-keyed entry to a hash
-- 
2.30.2

bug#59596: [PATCH 2/3] Add an interactive session exception error message.

[Yuval Langer]

---
 doc/ref/api-data.texi | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 8c18b4d40..143434213 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4798,6 +4798,11 @@ Notice that if we try the same @code{assq-set!} call with
 
 @lisp
 (assq-set! car2-properties 'seat-colour 'black)
+@print{}
+ice-9/boot-9.scm:1669:16: In procedure raise-exception:
+In procedure set-cdr!: Wrong type argument in position 1 (expecting mutable pair): (seat-colour . red)
+
+Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
 @end lisp
 
 This is due to the fact that literal alists are immutable. If you want
-- 
2.30.2

bug#59597: [PATCH 3/3] Change order of the resulting alist - a new entry is added to the start of the alist.

[Yuval Langer]

---
 doc/ref/api-data.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 143434213..2f603fb8f 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4785,11 +4785,11 @@ extract or change individual pieces of information:
 
 (assq-set! car1-properties 'seat-colour 'black)
 @result{}
-((colour . red)
+((seat-colour . black)
+ (colour . red)
  (transmission . manual)
  (fuel . unleaded)
  (steering . power-assisted)
- (seat-colour . black)
  (locking . manual)))
 @end lisp
 
-- 
2.30.2