changeset 6550:e3f5cba23198

Initial revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/strings.texi	Mon Mar 28 01:39:26 1994 +0000
@@ -0,0 +1,810 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/strings
+@node Strings and Characters, Lists, Numbers, Top
+@comment  node-name,  next,  previous,  up
+@chapter Strings and Characters
+@cindex strings
+@cindex character arrays
+@cindex characters
+@cindex bytes
+
+  A string in Emacs Lisp is an array that contains an ordered sequence
+of characters.  Strings are used as names of symbols, buffers, and
+files, to send messages to users, to hold text being copied between
+buffers, and for many other purposes.  Because strings are so important,
+Emacs Lisp has many functions expressly for manipulating them.  Emacs
+Lisp programs use strings more often than individual characters.
+
+  @xref{Strings of Events}, for special considerations for strings of
+keyboard character events.
+
+@menu
+* Basics: String Basics.      Basic properties of strings and characters.
+* Predicates for Strings::    Testing whether an object is a string or char.
+* Creating Strings::          Functions to allocate new strings.
+* Text Comparison::           Comparing characters or strings.
+* String Conversion::         Converting characters or strings and vice versa.
+* Formatting Strings::        @code{format}: Emacs's analog of @code{printf}.
+* Character Case::            Case conversion functions.
+* Case Table::		      Customizing case conversion.
+@end menu
+
+@node String Basics
+@section String and Character Basics
+
+  Strings in Emacs Lisp are arrays that contain an ordered sequence of
+characters.  Characters are represented in Emacs Lisp as integers;
+whether an integer was intended as a character or not is determined only
+by how it is used.  Thus, strings really contain integers.
+
+  The length of a string (like any array) is fixed and independent of
+the string contents, and cannot be altered.  Strings in Lisp are
+@emph{not} terminated by a distinguished character code.  (By contrast,
+strings in C are terminated by a character with @sc{ASCII} code 0.)
+This means that any character, including the null character (@sc{ASCII}
+code 0), is a valid element of a string.@refill
+
+  Since strings are considered arrays, you can operate on them with the
+general array functions.  (@xref{Sequences Arrays Vectors}.)  For
+example, you can access or change individual characters in a string
+using the functions @code{aref} and @code{aset} (@pxref{Array
+Functions}).
+
+  Each character in a string is stored in a single byte.  Therefore,
+numbers not in the range 0 to 255 are truncated when stored into a
+string.  This means that a string takes up much less memory than a
+vector of the same length.
+
+  Sometimes key sequences are represented as strings.  When a string is
+a key sequence, string elements in the range 128 to 255 represent meta
+characters (which are extremely large integers) rather than keyboard
+events in the range 128 to 255.
+
+  Strings cannot hold characters that have the hyper, super or alt
+modifiers; they can hold @sc{ASCII} control characters, but no other
+control characters.  They do not distinguish case in @sc{ASCII} control
+characters.  @xref{Character Type}, for more information about
+representation of meta and other modifiers for keyboard input
+characters.
+
+  Like a buffer, a string can contain text properties for the characters
+in it, as well as the characters themselves.  @xref{Text Properties}.
+
+  @xref{Text}, for information about functions that display strings or
+copy them into buffers.  @xref{Character Type}, and @ref{String Type},
+for information about the syntax of characters and strings.
+
+@node Predicates for Strings
+@section The Predicates for Strings
+
+For more information about general sequence and array predicates,
+see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
+
+@defun stringp object
+  This function returns @code{t} if @var{object} is a string, @code{nil}
+otherwise.
+@end defun
+
+@defun char-or-string-p object
+  This function returns @code{t} if @var{object} is a string or a
+character (i.e., an integer), @code{nil} otherwise.
+@end defun
+
+@node Creating Strings
+@section Creating Strings
+
+  The following functions create strings, either from scratch, or by
+putting strings together, or by taking them apart.
+
+@defun make-string count character
+  This function returns a string made up of @var{count} repetitions of
+@var{character}.  If @var{count} is negative, an error is signaled.
+
+@example
+(make-string 5 ?x)
+     @result{} "xxxxx"
+(make-string 0 ?x)
+     @result{} ""
+@end example
+
+  Other functions to compare with this one include @code{char-to-string}
+(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and
+@code{make-list} (@pxref{Building Lists}).
+@end defun
+
+@defun substring string start &optional end
+  This function returns a new string which consists of those characters
+from @var{string} in the range from (and including) the character at the
+index @var{start} up to (but excluding) the character at the index
+@var{end}.  The first character is at index zero.
+
+@example
+@group
+(substring "abcdefg" 0 3)
+     @result{} "abc"
+@end group
+@end example
+
+@noindent
+Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the
+index for @samp{c} is 2.  Thus, three letters, @samp{abc}, are copied
+from the string @code{"abcdefg"}.  The index 3 marks the character
+position up to which the substring is copied.  The character whose index
+is 3 is actually the fourth character in the string.
+
+A negative number counts from the end of the string, so that @minus{}1
+signifies the index of the last character of the string.  For example: 
+
+@example
+@group
+(substring "abcdefg" -3 -1)
+     @result{} "ef"
+@end group
+@end example
+
+@noindent
+In this example, the index for @samp{e} is @minus{}3, the index for
+@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
+Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
+
+When @code{nil} is used as an index, it stands for the length of the
+string.  Thus,
+
+@example
+@group
+(substring "abcdefg" -3 nil)
+     @result{} "efg"
+@end group
+@end example
+
+Omitting the argument @var{end} is equivalent to specifying @code{nil}.
+It follows that @code{(substring @var{string} 0)} returns a copy of all
+of @var{string}.
+
+@example
+@group
+(substring "abcdefg" 0)
+     @result{} "abcdefg"
+@end group
+@end example
+
+@noindent
+But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
+Functions}).
+
+A @code{wrong-type-argument} error is signaled if either @var{start} or
+@var{end} is not an integer or @code{nil}.  An @code{args-out-of-range}
+error is signaled if @var{start} indicates a character following
+@var{end}, or if either integer is out of range for @var{string}.
+
+Contrast this function with @code{buffer-substring} (@pxref{Buffer
+Contents}), which returns a string containing a portion of the text in
+the current buffer.  The beginning of a string is at index 0, but the
+beginning of a buffer is at index 1.
+@end defun
+
+@defun concat &rest sequences
+@cindex copying strings
+@cindex concatenating strings
+This function returns a new string consisting of the characters in the
+arguments passed to it.  The arguments may be strings, lists of numbers,
+or vectors of numbers; they are not themselves changed.  If
+@code{concat} receives no arguments, it returns an empty string.
+
+@example
+(concat "abc" "-def")
+     @result{} "abc-def"
+(concat "abc" (list 120 (+ 256 121)) [122])
+     @result{} "abcxyz"
+;; @r{@code{nil} is an empty sequence.}
+(concat "abc" nil "-def")
+     @result{} "abc-def"
+(concat "The " "quick brown " "fox.")
+     @result{} "The quick brown fox."
+(concat)
+     @result{} ""
+@end example
+
+@noindent
+The second example above shows how characters stored in strings are
+taken modulo 256.  In other words, each character in the string is
+stored in one byte.
+
+The @code{concat} function always constructs a new string that is
+not @code{eq} to any existing string.
+
+When an argument is an integer (not a sequence of integers), it is
+converted to a string of digits making up the decimal printed
+representation of the integer.  This special case exists for
+compatibility with Mocklisp, and we don't recommend you take advantage
+of it.  If you want to convert an integer to digits in this way, use
+@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
+(@pxref{String Conversion}).
+
+@example
+@group
+(concat 137)
+     @result{} "137"
+(concat 54 321)
+     @result{} "54321"
+@end group
+@end example
+
+For information about other concatenation functions, see the
+description of @code{mapconcat} in @ref{Mapping Functions},
+@code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building
+Lists}.
+@end defun
+
+@node Text Comparison
+@section Comparison of Characters and Strings
+@cindex string equality
+
+@defun char-equal character1 character2
+This function returns @code{t} if the arguments represent the same
+character, @code{nil} otherwise.  This function ignores differences
+in case if @code{case-fold-search} is non-@code{nil}.
+
+@example
+(char-equal ?x ?x)
+     @result{} t
+(char-to-string (+ 256 ?x))
+     @result{} "x"
+(char-equal ?x  (+ 256 ?x))
+     @result{} t
+@end example
+@end defun
+
+@defun string= string1 string2
+This function returns @code{t} if the characters of the two strings
+match exactly; case is significant.
+
+@example
+(string= "abc" "abc")
+     @result{} t
+(string= "abc" "ABC")
+     @result{} nil
+(string= "ab" "ABC")
+     @result{} nil
+@end example
+@end defun
+
+@defun string-equal string1 string2
+@code{string-equal} is another name for @code{string=}.
+@end defun
+
+@cindex lexical comparison
+@defun string< string1 string2
+@c (findex string< causes problems for permuted index!!)
+This function compares two strings a character at a time.  First it
+scans both the strings at once to find the first pair of corresponding
+characters that do not match.  If the lesser character of those two is
+the character from @var{string1}, then @var{string1} is less, and this
+function returns @code{t}.  If the lesser character is the one from
+@var{string2}, then @var{string1} is greater, and this function returns
+@code{nil}.  If the two strings match entirely, the value is @code{nil}.
+
+Pairs of characters are compared by their @sc{ASCII} codes.  Keep in
+mind that lower case letters have higher numeric values in the
+@sc{ASCII} character set than their upper case counterparts; numbers and
+many punctuation characters have a lower numeric value than upper case
+letters.
+
+@example
+@group
+(string< "abc" "abd")
+     @result{} t
+(string< "abd" "abc")
+     @result{} nil
+(string< "123" "abc")
+     @result{} t
+@end group
+@end example
+
+When the strings have different lengths, and they match up to the
+length of @var{string1}, then the result is @code{t}.  If they match up
+to the length of @var{string2}, the result is @code{nil}.  A string of
+no characters is less than any other string.
+
+@example
+@group
+(string< "" "abc")
+     @result{} t
+(string< "ab" "abc")
+     @result{} t
+(string< "abc" "")
+     @result{} nil
+(string< "abc" "ab")
+     @result{} nil
+(string< "" "")
+     @result{} nil                   
+@end group
+@end example
+@end defun
+
+@defun string-lessp string1 string2
+@code{string-lessp} is another name for @code{string<}.
+@end defun
+
+  See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
+a way to compare text in buffers.  The function @code{string-match},
+which matches a regular expression against a string, can be used
+for a kind of string comparison; see @ref{Regexp Search}.
+
+@node String Conversion
+@comment  node-name,  next,  previous,  up
+@section Conversion of Characters and Strings
+@cindex conversion of strings
+
+  This section describes functions for conversions between characters,
+strings and integers.  @code{format} and @code{prin1-to-string}
+(@pxref{Output Functions}) can also convert Lisp objects into strings.
+@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
+string representation of a Lisp object into an object.
+
+  @xref{Documentation}, for functions that produce textual descriptions
+of text characters and general input events
+(@code{single-key-description} and @code{text-char-description}).  These
+functions are used primarily for making help messages.
+
+@defun char-to-string character
+@cindex character to string
+  This function returns a new string with a length of one character.
+The value of @var{character}, modulo 256, is used to initialize the
+element of the string.
+
+This function is similar to @code{make-string} with an integer argument
+of 1.  (@xref{Creating Strings}.)  This conversion can also be done with
+@code{format} using the @samp{%c} format specification.
+(@xref{Formatting Strings}.)
+
+@example
+(char-to-string ?x)
+     @result{} "x"
+(char-to-string (+ 256 ?x))
+     @result{} "x"
+(make-string 1 ?x)
+     @result{} "x"
+@end example
+@end defun
+
+@defun string-to-char string
+@cindex string to character
+  This function returns the first character in @var{string}.  If the
+string is empty, the function returns 0.  The value is also 0 when the
+first character of @var{string} is the null character, @sc{ASCII} code
+0.
+
+@example
+(string-to-char "ABC")
+     @result{} 65
+(string-to-char "xyz")
+     @result{} 120
+(string-to-char "")
+     @result{} 0
+(string-to-char "\000")
+     @result{} 0
+@end example
+
+This function may be eliminated in the future if it does not seem useful
+enough to retain.
+@end defun
+
+@defun number-to-string number
+@cindex integer to string
+@cindex integer to decimal
+This function returns a string consisting of the printed
+representation of @var{number}, which may be an integer or a floating
+point number.  The value starts with a sign if the argument is
+negative.
+
+@example
+(number-to-string 256)
+     @result{} "256"
+(number-to-string -23)
+     @result{} "-23"
+(number-to-string -23.5)
+     @result{} "-23.5"
+@end example
+
+@cindex int-to-string
+@code{int-to-string} is a semi-obsolete alias for this function.
+
+See also the function @code{format} in @ref{Formatting Strings}.
+@end defun
+
+@defun string-to-number string
+@cindex string to number
+This function returns the numeric value of the characters in
+@var{string}, read in base ten.  It skips spaces and tabs at the
+beginning of @var{string}, then reads as much of @var{string} as it can
+interpret as a number.  (On some systems it ignores other whitespace at
+the beginning, not just spaces and tabs.)  If the first character after
+the ignored whitespace is not a digit or a minus sign, this function
+returns 0.
+
+@example
+(string-to-number "256")
+     @result{} 256
+(string-to-number "25 is a perfect square.")
+     @result{} 25
+(string-to-number "X256")
+     @result{} 0
+(string-to-number "-4.5")
+     @result{} -4.5
+@end example
+
+@findex string-to-int
+@code{string-to-int} is an obsolete alias for this function.
+@end defun
+
+@node Formatting Strings
+@comment  node-name,  next,  previous,  up
+@section Formatting Strings
+@cindex formatting strings
+@cindex strings, formatting them
+
+  @dfn{Formatting} means constructing a string by substitution of
+computed values at various places in a constant string.  This string
+controls how the other values are printed as well as where they appear;
+it is called a @dfn{format string}.
+
+  Formatting is often useful for computing messages to be displayed.  In
+fact, the functions @code{message} and @code{error} provide the same
+formatting feature described here; they differ from @code{format} only
+in how they use the result of formatting.
+
+@defun format string &rest objects
+  This function returns a new string that is made by copying
+@var{string} and then replacing any format specification 
+in the copy with encodings of the corresponding @var{objects}.  The
+arguments @var{objects} are the computed values to be formatted.
+@end defun
+
+@cindex @samp{%} in format
+@cindex format specification
+  A format specification is a sequence of characters beginning with a
+@samp{%}.  Thus, if there is a @samp{%d} in @var{string}, the
+@code{format} function replaces it with the printed representation of
+one of the values to be formatted (one of the arguments @var{objects}).
+For example:
+
+@example
+@group
+(format "The value of fill-column is %d." fill-column)
+     @result{} "The value of fill-column is 72."
+@end group
+@end example
+
+  If @var{string} contains more than one format specification, the
+format specifications correspond with successive values from
+@var{objects}.  Thus, the first format specification in @var{string}
+uses the first such value, the second format specification uses the
+second such value, and so on.  Any extra format specifications (those
+for which there are no corresponding values) cause unpredictable
+behavior.  Any extra values to be formatted are ignored.
+
+  Certain format specifications require values of particular types.
+However, no error is signaled if the value actually supplied fails to
+have the expected type.  Instead, the output is likely to be
+meaningless.
+
+  Here is a table of valid format specifications:
+
+@table @samp
+@item %s
+Replace the specification with the printed representation of the object,
+made without quoting.  Thus, strings are represented by their contents
+alone, with no @samp{"} characters, and symbols appear without @samp{\}
+characters.
+
+If there is no corresponding object, the empty string is used.
+
+@item %S
+Replace the specification with the printed representation of the object,
+made with quoting.  Thus, strings are enclosed in @samp{"} characters,
+and @samp{\} characters appear where necessary before special characters.
+
+If there is no corresponding object, the empty string is used.
+
+@item %o
+@cindex integer to octal
+Replace the specification with the base-eight representation of an
+integer.
+
+@item %d
+Replace the specification with the base-ten representation of an
+integer.
+
+@item %x
+@cindex integer to hexadecimal
+Replace the specification with the base-sixteen representation of an
+integer.
+
+@item %c
+Replace the specification with the character which is the value given.
+
+@item %e
+Replace the specification with the exponential notation for a floating
+point number.
+
+@item %f
+Replace the specification with the decimal-point notation for a floating
+point number.
+
+@item %g
+Replace the specification with notation for a floating point number,
+using either exponential notation or decimal-point notation whichever
+is shorter.
+
+@item %%
+A single @samp{%} is placed in the string.  This format specification is
+unusual in that it does not use a value.  For example, @code{(format "%%
+%d" 30)} returns @code{"% 30"}.
+@end table
+
+  Any other format character results in an @samp{Invalid format
+operation} error.
+
+  Here are several examples:
+
+@example
+@group
+(format "The name of this buffer is %s." (buffer-name))
+     @result{} "The name of this buffer is strings.texi."
+
+(format "The buffer object prints as %s." (current-buffer))
+     @result{} "The buffer object prints as #<buffer strings.texi>."
+
+(format "The octal value of %d is %o, 
+         and the hex value is %x." 18 18 18)
+     @result{} "The octal value of 18 is 22, 
+         and the hex value is 12."
+@end group
+@end example
+
+@cindex numeric prefix
+@cindex field width
+@cindex padding
+  All the specification characters allow an optional numeric prefix
+between the @samp{%} and the character.  The optional numeric prefix
+defines the minimum width for the object.  If the printed representation
+of the object contains fewer characters than this, then it is padded.
+The padding is on the left if the prefix is positive (or starts with
+zero) and on the right if the prefix is negative.  The padding character
+is normally a space, but if the numeric prefix starts with a zero, zeros
+are used for padding.
+
+@example
+(format "%06d is padded on the left with zeros" 123)
+     @result{} "000123 is padded on the left with zeros"
+
+(format "%-6d is padded on the right" 123)
+     @result{} "123    is padded on the right"
+@end example
+
+  @code{format} never truncates an object's printed representation, no
+matter what width you specify.  Thus, you can use a numeric prefix to
+specify a minimum spacing between columns with no risk of losing
+information.
+
+  In the following three examples, @samp{%7s} specifies a minimum width
+of 7.  In the first case, the string inserted in place of @samp{%7s} has
+only 3 letters, so 4 blank spaces are inserted for padding.  In the
+second case, the string @code{"specification"} is 13 letters wide but is
+not truncated.  In the third case, the padding is on the right.
+
+@smallexample 
+@group
+(format "The word `%7s' actually has %d letters in it."
+        "foo" (length "foo"))
+     @result{} "The word `    foo' actually has 3 letters in it."  
+@end group
+
+@group
+(format "The word `%7s' actually has %d letters in it."
+        "specification" (length "specification")) 
+     @result{} "The word `specification' actually has 13 letters in it."  
+@end group
+
+@group
+(format "The word `%-7s' actually has %d letters in it."
+        "foo" (length "foo"))
+     @result{} "The word `foo    ' actually has 3 letters in it."  
+@end group
+@end smallexample
+
+@node Character Case
+@comment node-name, next, previous, up 
+@section Character Case
+@cindex upper case 
+@cindex lower case 
+@cindex character case 
+
+  The character case functions change the case of single characters or
+of the contents of strings.  The functions convert only alphabetic
+characters (the letters @samp{A} through @samp{Z} and @samp{a} through
+@samp{z}); other characters are not altered.  The functions do not
+modify the strings that are passed to them as arguments.
+
+  The examples below use the characters @samp{X} and @samp{x} which have
+@sc{ASCII} codes 88 and 120 respectively.
+
+@defun downcase string-or-char
+This function converts a character or a string to lower case.
+
+When the argument to @code{downcase} is a string, the function creates
+and returns a new string in which each letter in the argument that is
+upper case is converted to lower case.  When the argument to
+@code{downcase} is a character, @code{downcase} returns the
+corresponding lower case character.  This value is an integer.  If the
+original character is lower case, or is not a letter, then the value
+equals the original character.
+
+@example
+(downcase "The cat in the hat")
+     @result{} "the cat in the hat"
+
+(downcase ?X)
+     @result{} 120
+@end example
+@end defun
+
+@defun upcase string-or-char
+This function converts a character or a string to upper case.
+
+When the argument to @code{upcase} is a string, the function creates
+and returns a new string in which each letter in the argument that is
+lower case is converted to upper case.
+
+When the argument to @code{upcase} is a character, @code{upcase}
+returns the corresponding upper case character.  This value is an integer.
+If the original character is upper case, or is not a letter, then the
+value equals the original character.
+
+@example
+(upcase "The cat in the hat")
+     @result{} "THE CAT IN THE HAT"
+
+(upcase ?x)
+     @result{} 88
+@end example
+@end defun
+
+@defun capitalize string-or-char
+@cindex capitalization
+This function capitalizes strings or characters.  If
+@var{string-or-char} is a string, the function creates and returns a new
+string, whose contents are a copy of @var{string-or-char} in which each
+word has been capitalized.  This means that the first character of each
+word is converted to upper case, and the rest are converted to lower
+case.
+
+The definition of a word is any sequence of consecutive characters that
+are assigned to the word constituent syntax class in the current syntax
+table (@xref{Syntax Class Table}).
+
+When the argument to @code{capitalize} is a character, @code{capitalize}
+has the same result as @code{upcase}.
+
+@example
+(capitalize "The cat in the hat")
+     @result{} "The Cat In The Hat"
+
+(capitalize "THE 77TH-HATTED CAT")
+     @result{} "The 77th-Hatted Cat"
+
+@group
+(capitalize ?x)
+     @result{} 88
+@end group
+@end example
+@end defun
+
+@node Case Table
+@section The Case Table
+
+  You can customize case conversion by installing a special @dfn{case
+table}.  A case table specifies the mapping between upper case and lower
+case letters.  It affects both the string and character case conversion
+functions (see the previous section) and those that apply to text in the
+buffer (@pxref{Case Changes}).  You need a case table if you are using a
+language which has letters other than the standard @sc{ASCII} letters.
+
+  A case table is a list of this form:
+
+@example
+(@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences})
+@end example
+
+@noindent
+where each element is either @code{nil} or a string of length 256.  The
+element @var{downcase} says how to map each character to its lower-case
+equivalent.  The element @var{upcase} maps each character to its
+upper-case equivalent.  If lower and upper case characters are in
+one-to-one correspondence, use @code{nil} for @var{upcase}; then Emacs
+deduces the upcase table from @var{downcase}.
+
+  For some languages, upper and lower case letters are not in one-to-one
+correspondence.  There may be two different lower case letters with the
+same upper case equivalent.  In these cases, you need to specify the
+maps for both directions.
+
+  The element @var{canonicalize} maps each character to a canonical
+equivalent; any two characters that are related by case-conversion have
+the same canonical equivalent character.
+
+  The element @var{equivalences} is a map that cyclicly permutes each
+equivalence class (of characters with the same canonical equivalent).
+(For ordinary @sc{ASCII}, this would map @samp{a} into @samp{A} and
+@samp{A} into @samp{a}, and likewise for each set of equivalent
+characters.)
+
+  When you construct a case table, you can provide @code{nil} for both
+@var{canonicalize} and @var{equivalences}.  When you specify the case
+table for use, Emacs fills in these strings, computing them from
+@var{upcase} and @var{downcase}.  In a case table that is actually in
+use, those components are non-@code{nil}.  Do not try to make just one
+of these components @code{nil}; that is not meaningful.
+
+  Each buffer has a case table.  Emacs also has a @dfn{standard case
+table} which is copied into each buffer when you create the buffer.
+Changing the standard case table doesn't affect any existing buffers.
+
+  Here are the functions for working with case tables:
+
+@defun case-table-p object
+This predicate returns non-@code{nil} if @var{object} is a valid case
+table.
+@end defun
+
+@defun set-standard-case-table table
+This function makes @var{table} the standard case table, so that it will
+apply to any buffers created subsequently.
+@end defun
+
+@defun standard-case-table
+This returns the standard case table.
+@end defun
+
+@defun current-case-table
+This function returns the current buffer's case table.
+@end defun
+
+@defun set-case-table table
+This sets the current buffer's case table to @var{table}.
+@end defun
+
+  The following three functions are convenient subroutines for packages
+that define non-@sc{ASCII} character sets.  They modify a string
+@var{downcase-table} provided as an argument; this should be a string to
+be used as the @var{downcase} part of a case table.  They also modify
+the standard syntax table.  @xref{Syntax Tables}.
+
+@defun set-case-syntax-pair uc lc downcase-table
+This function specifies a pair of corresponding letters, one upper case
+and one lower case.
+@end defun
+
+@defun set-case-syntax-delims l r downcase-table
+This function makes characters @var{l} and @var{r} a matching pair of
+case-invariant delimiters.
+@end defun
+
+@defun set-case-syntax char syntax downcase-table
+This function makes @var{char} case-invariant, with syntax
+@var{syntax}.
+@end defun
+
+@deffn Command describe-buffer-case-table
+This command displays a description of the contents of the current
+buffer's case table.
+@end deffn
+
+@cindex ISO Latin 1
+@pindex iso-syntax
+You can load the library @file{iso-syntax} to set up the standard syntax
+table and define a case table for the 256-bit ISO Latin 1 character set.