and always operated on the current buffer.)
-@defun char-after position &optional buffer
+@defun char-after &optional position buffer
This function returns the character in the buffer at (i.e.,
immediately after) position @var{position}. If @var{position} is out of
range for this purpose, either before the beginning of the buffer, or at
-or beyond the end, then the value is @code{nil}. If optional argument
-@var{buffer} is @code{nil}, the current buffer is assumed.
+or beyond the end, then the value is @code{nil}. The default for
+@var{position} is point. If optional argument @var{buffer} is
+@code{nil}, the current buffer is assumed.
In the following example, assume that the first character in the
buffer is @samp{@@}:
@end example
@end defun
+@defun char-before &optional position buffer
+This function returns the character in the current buffer immediately
+before position @var{position}. If @var{position} is out of range for
+this purpose, either at or before the beginning of the buffer, or beyond
+the end, then the value is @code{nil}. The default for
+@var{position} is point. If optional argument @var{buffer} is
+@code{nil}, the current buffer is assumed.
+@end defun
+
@defun following-char &optional buffer
This function returns the character following point in the buffer.
This is similar to @code{(char-after (point))}. However, if point is at
and so on. If a mismatch is found, it means that the sort keys are
unequal; the sort key whose character is less at the point of first
mismatch is the lesser sort key. The individual characters are compared
-according to their numerical values. Since Emacs uses the @sc{ASCII}
+according to their numerical values. Since Emacs uses the @sc{ascii}
character set, the ordering in that set determines alphabetical order.
@c version 19 change
@defun translate-region start end table
This function applies a translation table to the characters in the
-buffer between positions @var{start} and @var{end}.
+buffer between positions @var{start} and @var{end}. The translation
+table @var{table} can be either a string, a vector, or a char-table.
+
+If @var{table} is a string, its @var{n}th element is the mapping for the
+character with code @var{n}.
+
+If @var{table} is a vector, its @var{n}th element is the mapping for
+character with code @var{n}. Legal mappings are characters, strings, or
+@code{nil} (meaning don't replace.)
-The translation table @var{table} is a string; @code{(aref @var{table}
-@var{ochar})} gives the translated character corresponding to
-@var{ochar}. If the length of @var{table} is less than 256, any
-characters with codes larger than the length of @var{table} are not
-altered by the translation.
+If @var{table} is a char-table, its elements describe the mapping
+between characters and their replacements. The char-table should be of
+type @code{char} or @code{generic}.
+
+When the @var{table} is a string or vector and its length is less than
+the total number of characters (256 without Mule), any characters with
+codes larger than the length of @var{table} are not altered by the
+translation.
The return value of @code{translate-region} is the number of
characters that were actually changed by the translation. This does
not count characters that were mapped into themselves in the
translation table.
+
+@strong{NOTE}: Prior to XEmacs 21.2, the @var{table} argument was
+allowed only to be a string. This is still the case in FSF Emacs.
+
+The following example creates a char-table that is passed to
+@code{translate-region}, which translates character @samp{a} to
+@samp{the letter a}, removes character @samp{b}, and translates
+character @samp{c} to newline.
+
+@example
+@group
+---------- Buffer: foo ----------
+Here is a sentence in the buffer.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(let ((table (make-char-table 'generic)))
+ (put-char-table ?a "the letter a" table)
+ (put-char-table ?b "" table)
+ (put-char-table ?c ?\n table)
+ (translate-region (point-min) (point-max) table))
+ @result{} 3
+
+---------- Buffer: foo ----------
+Here is the letter a senten
+e in the uffer.
+---------- Buffer: foo ----------
+@end group
+@end example
@end defun
@node Registers