Recognize 'escape' character name, per R7RS.

[bpt/guile.git] / doc / ref / api-compound.texi

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 699e760..0b14c48 100644 (file)
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -459,8 +459,8 @@ list results if the last argument is not a proper list.
 @end lisp
 
 @code{append} doesn't modify the given lists, but the return may share
-structure with the final @var{obj}.  @code{append!} modifies the
-given lists to form its return.
+structure with the final @var{obj}.  @code{append!} is permitted, but
+not required, to modify the given lists to form its return.
 
 For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
 of the list operands @var{lst} @dots{} @var{obj}.  That @var{lstlst}
@@ -474,8 +474,8 @@ itself is not modified or used in the return.
 @deffnx {C Function} scm_reverse_x (lst, newtail)
 Return a list comprising the elements of @var{lst}, in reverse order.
 
-@code{reverse} constructs a new list, @code{reverse!} modifies
-@var{lst} in constructing its return.
+@code{reverse} constructs a new list.  @code{reverse!} is permitted, but
+not required, to modify @var{lst} in constructing its return.
 
 For @code{reverse!}, the optional @var{newtail} is appended to the
 result.  @var{newtail} isn't reversed, it simply becomes the list
@@ -689,22 +689,18 @@ Vectors can literally be entered in source code, just like strings,
 characters or some of the other data types.  The read syntax for vectors
 is as follows: A sharp sign (@code{#}), followed by an opening
 parentheses, all elements of the vector in their respective read syntax,
-and finally a closing parentheses.  The following are examples of the
-read syntax for vectors; where the first vector only contains numbers
-and the second three different object types: a string, a symbol and a
-number in hexadecimal notation.
+and finally a closing parentheses.  Like strings, vectors do not have to
+be quoted.
+
+The following are examples of the read syntax for vectors; where the
+first vector only contains numbers and the second three different object
+types: a string, a symbol and a number in hexadecimal notation.
 
 @lisp
 #(1 2 3)
 #("Hello" foo #xdeadbeef)
 @end lisp
 
-Like lists, vectors have to be quoted:
-
-@lisp
-'#(a b c) @result{} #(a b c)
-@end lisp
-
 @node Vector Creation
 @subsubsection Dynamic Vector Creation and Validation
 
@@ -735,7 +731,7 @@ The inverse operation is @code{vector->list}:
 Return a newly allocated list composed of the elements of @var{v}.
 
 @lisp
-(vector->list '#(dah dah didah)) @result{}  (dah dah didah)
+(vector->list #(dah dah didah)) @result{}  (dah dah didah)
 (list->vector '(dididit dah)) @result{}  #(dididit dah)
 @end lisp
 @end deffn
@@ -796,8 +792,8 @@ Return the number of elements in @var{vec} as a @code{size_t}.
 Return the contents of position @var{k} of @var{vec}.
 @var{k} must be a valid index of @var{vec}.
 @lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
+(vector-ref #(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref #(1 1 2 3 5 8 13 21)
     (let ((i (round (* 2 (acos -1)))))
       (if (inexact? i)
         (inexact->exact i)
@@ -3833,6 +3829,27 @@ then it can use @var{size} to avoid rehashing when initial entries are
 added.
 @end deffn
 
+@deffn {Scheme Procedure} alist->hash-table alist
+@deffnx {Scheme Procedure} alist->hashq-table alist
+@deffnx {Scheme Procedure} alist->hashv-table alist
+@deffnx {Scheme Procedure} alist->hashx-table hash assoc alist
+Convert @var{alist} into a hash table. When keys are repeated in
+@var{alist}, the leftmost association takes precedence.
+
+@example
+(use-modules (ice-9 hash-table))
+(alist->hash-table '((foo . 1) (bar . 2)))
+@end example
+
+When converting to an extended hash table, custom @var{hash} and
+@var{assoc} procedures must be provided.
+
+@example
+(alist->hashx-table hash assoc '((foo . 1) (bar . 2)))
+@end example
+
+@end deffn
+
 @deffn {Scheme Procedure} hash-table? obj
 @deffnx {C Function} scm_hash_table_p (obj)
 Return @code{#t} if @var{obj} is a abstract hash table object.