@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Base 64:: Conversion to or from base 64 encoding.
+* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@code{substring}, @code{insert}, and @code{buffer-substring}.
@menu
-* Examining Properties:: Looking at the properties of one character.
-* Changing Properties:: Setting the properties of a range of text.
-* Property Search:: Searching for where a property changes value.
-* Special Properties:: Particular properties with special meanings.
-* Format Properties:: Properties for representing formatting of text.
-* Sticky Properties:: How inserted text gets properties from
- neighboring text.
-* Saving Properties:: Saving text properties in files, and reading
- them back.
-* Lazy Properties:: Computing text properties in a lazy fashion
- only when text is examined.
-* Clickable Text:: Using text properties to make regions of text
- do something when you click on them.
-* Fields:: The @code{field} property defines
- fields within the buffer.
-* Not Intervals:: Why text properties do not use
- Lisp-visible text intervals.
+* Examining Properties:: Looking at the properties of one character.
+* Changing Properties:: Setting the properties of a range of text.
+* Property Search:: Searching for where a property changes value.
+* Special Properties:: Particular properties with special meanings.
+* Format Properties:: Properties for representing formatting of text.
+* Sticky Properties:: How inserted text gets properties from
+ neighboring text.
+* Saving Properties:: Saving text properties in files, and reading
+ them back.
+* Lazy Properties:: Computing text properties in a lazy fashion
+ only when text is examined.
+* Clickable Text:: Using text properties to make regions of text
+ do something when you click on them.
+* Fields:: The @code{field} property defines
+ fields within the buffer.
+* Not Intervals:: Why text properties do not use
+ Lisp-visible text intervals.
@end menu
@node Examining Properties
@var{limit} equals @var{pos}.
@end defun
-@defun next-char-property-change position &optional limit
+@defun next-char-property-change pos &optional limit
This is like @code{next-property-change} except that it considers
-overlay properties as well as text properties. There is no @var{object}
-operand because this function operates only on the current buffer. It
-returns the next address at which either kind of property changes.
+overlay properties as well as text properties, and if no change is
+found before the end of the buffer, it returns the maximum buffer
+position rather than @code{nil} (in this sense, it resembles the
+corresponding overlay function @code{next-overlay-change}, rather than
+@code{next-property-change}). There is no @var{object} operand
+because this function operates only on the current buffer. It returns
+the next address at which either kind of property changes.
@end defun
-@defun previous-char-property-change position &optional limit
+@defun previous-char-property-change pos &optional limit
This is like @code{next-char-property-change}, but scans back from
-@var{position} instead of forward.
+@var{pos} instead of forward, and returns the minimum buffer
+position if no change is found.
+@end defun
+
+@defun next-single-char-property-change pos prop &optional object limit
+@tindex next-single-char-property-change
+This is like @code{next-single-property-change} except that it
+considers overlay properties as well as text properties, and if no
+change is found before the end of the @var{object}, it returns the
+maximum valid position in @var{object} rather than @code{nil}. Unlike
+@code{next-char-property-change}, this function @emph{does} have an
+@var{object} operand; if @var{object} is not a buffer, only
+text-properties are considered.
+@end defun
+
+@defun previous-single-char-property-change pos prop &optional object limit
+@tindex previous-single-char-property-change
+This is like @code{next-single-char-property-change}, but scans back
+from @var{pos} instead of forward, and returns the minimum valid
+position in @var{object} if no change is found.
@end defun
@defun text-property-any start end prop value &optional object
In all of these functions, if @var{pos} is omitted or @code{nil}, the
value of point is used by default.
-@defun field-beginning &optional pos escape-from-edge
+@defun field-beginning &optional pos escape-from-edge limit
@tindex field-beginning
This function returns the beginning of the field specified by @var{pos}.
always the beginning of the preceding field that @emph{ends} at @var{pos},
regardless of the stickiness of the @code{field} properties around
@var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the
+beginning of the field is before @var{limit}, then @var{limit} will be
+returned instead.
@end defun
-@defun field-end &optional pos escape-from-edge
+@defun field-end &optional pos escape-from-edge limit
@tindex field-end
This function returns the end of the field specified by @var{pos}.
non-@code{nil}, then the return value is always the end of the following
field that @emph{begins} at @var{pos}, regardless of the stickiness of
the @code{field} properties around @var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the end
+of the field is after @var{limit}, then @var{limit} will be returned
+instead.
@end defun
@defun field-string &optional pos
@section Base 64 Encoding
@cindex base 64 encoding
- Base 64 code is used in email to encode a sequence of 8-bit bytes as a
-longer sequence of @sc{ascii} graphic characters. It is defined in RFC
-2045. This section describes the functions for converting to and from
-this code.
+ Base 64 code is used in email to encode a sequence of 8-bit bytes as
+a longer sequence of @sc{ascii} graphic characters. It is defined in
+Internet RFC@footnote{
+An RFC, an acronym for @dfn{Request for Comments}, is a numbered
+Internet informational document describing a standard. RFCs are
+usually written by technical experts acting on their own initiative,
+and are traditionally written in a pragmatic, experience-driven
+manner.
+}2045. This section describes the functions for
+converting to and from this code.
@defun base64-encode-region beg end &optional no-line-break
@tindex base64-encode-region
The decoding functions ignore newline characters in the encoded text.
@end defun
+@node MD5 Checksum
+@section MD5 Checksum
+@cindex MD5 checksum
+@cindex message digest computation
+
+ MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit
+``fingerprints'' of a document or program. They are used to verify
+that you have an exact and unaltered copy of the data. The algorithm
+to calculate the MD5 message digest is defined in Internet
+RFC@footnote{
+For an explanation of what is an RFC, see the footnote in @ref{Base
+64}.
+}1321. This section describes the Emacs facilities for computing
+message digests.
+
+@defun md5 object &optional start end coding-system noerror
+This function returns the MD5 message digest of @var{object}, which
+should be a buffer or a string.
+
+The two optional arguments @var{start} and @var{end} are character
+positions specifying the portion of @var{object} to compute the
+message digest for. If they are @code{nil} or omitted, the digest is
+computed for the whole of @var{object}.
+
+The function @code{md5} does not compute the message digest directly
+from the internal Emacs representation of the text (@pxref{Text
+Representations}). Instead, it encodes the text using a coding
+system, and computes the message digest from the encoded text. The
+optional fourth argument @var{coding-system} specifies which coding
+system to use for encoding the text. It should be the same coding
+system that you used to read the text, or that you used or will use
+when saving or sending the text. @xref{Coding Systems}, for more
+information about coding systems.
+
+If @var{coding-system} is @code{nil} or omitted, the default depends
+on @var{object}. If @var{object} is a buffer, the default for
+@var{coding-system} is whatever coding system would be chosen by
+default for writing this text into a file. If @var{object} is a
+string, the user's most preferred coding system (@pxref{Recognize
+Coding, prefer-coding-system, the description of
+@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used.
+
+Normally, @code{md5} signals an error if the text can't be encoded
+using the specified or chosen coding system. However, if
+@var{noerror} is non-@code{nil}, it silently uses @code{raw-text}
+coding instead.
+@end defun
+
@node Change Hooks
@section Change Hooks
@cindex change hooks