position stored in a register.
* Transposition:: Swapping two portions of a buffer.
* Change Hooks:: Supplying functions to be run when text is changed.
+* Transformations:: MD5 and base64 support.
@end menu
@node Near Point
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
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
@end defvar
+
+@node Transformations
+@section Textual transformations---MD5 and base64 support
+@cindex MD5 digests
+@cindex base64
+
+Some textual operations inherently require examining each character in
+turn, and performing arithmetic operations on them. Such operations
+can, of course, be implemented in Emacs Lisp, but tend to be very slow
+for large portions of text or data. This is why some of them are
+implemented in C, with an appropriate interface for Lisp programmers.
+Examples of algorithms thus provided are MD5 and base64 support.
+
+MD5 is an algorithm for calculating message digests, as described in
+rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit
+``fingerprint'' (``message digest'') corresponding to that message. It
+is considered computationally infeasible to produce two messages having
+the same MD5 digest, or to produce a message having a prespecified
+target digest. MD5 is used heavily by various authentication schemes.
+
+Emacs Lisp interface to MD5 consists of a single function @code{md5}:
+
+@defun md5 object &optional start end
+This function returns the MD5 message digest of @var{object}, a buffer
+or string.
+
+Optional arguments @var{start} and @var{end} denote positions for
+computing the digest of a portion of @var{object}.
+
+Some examples of usage:
+
+@example
+@group
+;; @r{Calculate the digest of the entire buffer}
+(md5 (current-buffer))
+ @result{} "8842b04362899b1cda8d2d126dc11712"
+@end group
+
+@group
+;; @r{Calculate the digest of the current line}
+(md5 (current-buffer) (point-at-bol) (point-at-eol))
+ @result{} "60614d21e9dee27dfdb01fa4e30d6d00"
+@end group
+
+@group
+;; @r{Calculate the digest of your name and email address}
+(md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
+ @result{} "0a2188c40fd38922d941fe6032fce516"
+@end group
+@end example
+@end defun
+
+Base64 is a portable encoding for arbitrary sequences of octets, in a
+form that need not be readable by humans. It uses a 65-character subset
+of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode
+binary bodies, and to encode binary characters in message headers.
+
+The Lisp interface to base64 consists of four functions:
+
+@defun base64-encode-region beg end &optional no-line-break
+This function encodes the region between @var{beg} and @var{end} of the
+current buffer to base64 format. This means that the original region is
+deleted, and replaced with its base64 equivalent.
+
+Normally, encoded base64 output is multi-line, with 76-character lines.
+If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
+resulting in single-line output.
+
+Mule note: you should make sure that you convert the multibyte
+characters (those that do not fit into 0--255 range) to something else,
+because they cannot be meaningfully converted to base64. If the
+@code{base64-encode-region} encounters such characters, it will signal
+an error.
+
+@code{base64-encode-region} returns the length of the encoded text.
+
+@example
+@group
+;; @r{Encode the whole buffer in base64}
+(base64-encode-region (point-min) (point-max))
+@end group
+@end example
+
+The function can also be used interactively, in which case it works on
+the currently active region.
+@end defun
+
+@defun base64-encode-string string
+This function encodes @var{string} to base64, and returns the encoded
+string.
+
+For Mule, the same considerations apply as for
+@code{base64-encode-region}.
+
+@example
+@group
+(base64-encode-string "fubar")
+ @result{} "ZnViYXI="
+@end group
+@end example
+@end defun
+
+@defun base64-decode-region beg end
+This function decodes the region between @var{beg} and @var{end} of the
+current buffer. The region should be in base64 encoding.
+
+If the region was decoded correctly, @code{base64-decode-region} returns
+the length of the decoded region. If the decoding failed, @code{nil} is
+returned.
+
+@example
+@group
+;; @r{Decode a base64 buffer, and replace it with the decoded version}
+(base64-decode-region (point-min) (point-max))
+@end group
+@end example
+@end defun
+
+@defun base64-decode-string string
+This function decodes @var{string} to base64, and returns the decoded
+string. @var{string} should be valid base64-encoded text.
+
+If encoding was not possible, @code{nil} is returned.
+
+@example
+@group
+(base64-decode-string "ZnViYXI=")
+ @result{} "fubar"
+@end group
+
+@group
+(base64-decode-string "totally bogus")
+ @result{} nil
+@end group
+@end example
+@end defun
projects / chise / xemacs-chise.git.1 / blobdiff