comparison lispref/objects.texi @ 52978:1a5c50faf357

Replace @sc{foo} with @acronym{FOO}.

52977:8af8c70252c1

  @xref{Numbers}, for more information.

@node Character Type
@subsection Character Type
@cindex @sc{ascii} character codes

  A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
other words, characters are represented by their character codes.  For
example, the character @kbd{A} is represented as the @w{integer 65}.

common to work with @emph{strings}, which are sequences composed of
characters.  @xref{String Type}.

  Characters in strings, buffers, and files are currently limited to the
range of 0 to 524287---nineteen bits.  But not all values in that range
are valid character codes.  Codes 0 through 127 are @sc{ascii} codes; the
rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}).  Characters that represent
keyboard input have a much wider range, to encode modifier keys such as
Control, Meta and Shift.

@cindex read syntax for characters
@cindex printed representation for characters

@example
?\^I @result{} 9     ?\C-I @result{} 9
@end example

  In strings and buffers, the only control characters allowed are those
that exist in @sc{ascii}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}.  The character
codes for these non-@sc{ascii} control characters include the
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
bit as well as the code for the corresponding non-control
character.  Ordinary terminals have no way of generating non-@sc{ascii}
control characters, but you can generate them straightforwardly using X
and other window systems.

  For historical reasons, Emacs treats the @key{DEL} character as
the control equivalent of @kbd{?}:

@math{2^{7}}
@end tex
@ifnottex
2**7
@end ifnottex
bit attached to an @sc{ascii} character indicates a meta character; thus, the
meta characters that can fit in a string have codes in the range from
128 to 255, and are the meta versions of the ordinary @sc{ascii}
characters.  (In Emacs versions 18 and older, this convention was used
for characters outside of strings as well.)

  The read syntax for meta characters uses @samp{\M-}.  For example,
@samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with

syntax for a character.  Thus, you can write @kbd{M-A} as @samp{?\M-A},
or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.

  The case of a graphic character is indicated by its character code;
for example, @sc{ascii} distinguishes between the characters @samp{a}
and @samp{A}.  But @sc{ascii} has no way to represent whether a control
character is upper case or lower case.  Emacs uses the
@tex
@math{2^{25}}
@end tex
@ifnottex

  Finally, the most general read syntax for a character represents the
character code in either octal or hex.  To use octal, write a question
mark followed by a backslash and the octal character code (up to three
octal digits); thus, @samp{?\101} for the character @kbd{A},
@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
character @kbd{C-b}.  Although this syntax can represent any @sc{ascii}
character, it is preferred only when the precise octal value is more
important than the @sc{ascii} representation.

@example
@group
?\012 @result{} 10         ?\n @result{} 10         ?\C-j @result{} 10
?\101 @result{} 65         ?A @result{} 65

in documentation strings,
but the newline is ignored if escaped."
@end example

@node Non-ASCII in Strings
@subsubsection Non-@sc{ascii} Characters in Strings

  You can include a non-@sc{ascii} international character in a string
constant by writing it literally.  There are two text representations
for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
and multibyte.  If the string constant is read from a multibyte source,
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
makes the string multibyte.  If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.

  You can also represent a multibyte non-@sc{ascii} character with its
character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary.  (Multibyte non-@sc{ascii} character codes are all
greater than 256.)  Any character which is not a valid hex digit
terminates this construct.  If the next character in the string could be
interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
one character, @samp{a} with grave accent.  @w{@samp{\ }} in a string
constant is just like backslash-newline; it does not contribute any
character to the string, but it does terminate the preceding hex escape.

  Using a multibyte hex escape forces the string to multibyte.  You can
represent a unibyte non-@sc{ascii} character with its character code,
which must be in the range from 128 (0200 octal) to 255 (0377 octal).
This forces a unibyte string.

  @xref{Text Representations}, for more information about the two
text representations.

them, like this: @code{"\t, \C-a"}.  @xref{Character Type}, for a
description of the read syntax for characters.

  However, not all of the characters you can write with backslash
escape-sequences are valid in strings.  The only control characters that
a string can hold are the @sc{ascii} control characters.  Strings do not
distinguish case in @sc{ascii} control characters.

  Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
that provides a way to represent meta versions of @sc{ascii} characters in a
string.  If you use the @samp{\M-} syntax to indicate a meta character
in a string constant, this sets the
@tex
@math{2^{7}}
@end tex

@end example

Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings.
A unibyte string never equals a multibyte string unless the
contents are entirely @sc{ascii} (@pxref{Text Representations}).

@example
@group
(equal "asdf" "ASDF")
     @result{} nil

52978:1a5c50faf357

  @xref{Numbers}, for more information.

@node Character Type
@subsection Character Type
@cindex @acronym{ASCII} character codes

  A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
other words, characters are represented by their character codes.  For
example, the character @kbd{A} is represented as the @w{integer 65}.

common to work with @emph{strings}, which are sequences composed of
characters.  @xref{String Type}.

  Characters in strings, buffers, and files are currently limited to the
range of 0 to 524287---nineteen bits.  But not all values in that range
are valid character codes.  Codes 0 through 127 are @acronym{ASCII} codes; the
rest are non-@acronym{ASCII} (@pxref{Non-ASCII Characters}).  Characters that represent
keyboard input have a much wider range, to encode modifier keys such as
Control, Meta and Shift.

@cindex read syntax for characters
@cindex printed representation for characters

@example
?\^I @result{} 9     ?\C-I @result{} 9
@end example

  In strings and buffers, the only control characters allowed are those
that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}.  The character
codes for these non-@acronym{ASCII} control characters include the
@tex
@math{2^{26}}
@end tex
@ifnottex
2**26
@end ifnottex
bit as well as the code for the corresponding non-control
character.  Ordinary terminals have no way of generating non-@acronym{ASCII}
control characters, but you can generate them straightforwardly using X
and other window systems.

  For historical reasons, Emacs treats the @key{DEL} character as
the control equivalent of @kbd{?}:

@math{2^{7}}
@end tex
@ifnottex
2**7
@end ifnottex
bit attached to an @acronym{ASCII} character indicates a meta character; thus, the
meta characters that can fit in a string have codes in the range from
128 to 255, and are the meta versions of the ordinary @acronym{ASCII}
characters.  (In Emacs versions 18 and older, this convention was used
for characters outside of strings as well.)

  The read syntax for meta characters uses @samp{\M-}.  For example,
@samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with

syntax for a character.  Thus, you can write @kbd{M-A} as @samp{?\M-A},
or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.

  The case of a graphic character is indicated by its character code;
for example, @acronym{ASCII} distinguishes between the characters @samp{a}
and @samp{A}.  But @acronym{ASCII} has no way to represent whether a control
character is upper case or lower case.  Emacs uses the
@tex
@math{2^{25}}
@end tex
@ifnottex

  Finally, the most general read syntax for a character represents the
character code in either octal or hex.  To use octal, write a question
mark followed by a backslash and the octal character code (up to three
octal digits); thus, @samp{?\101} for the character @kbd{A},
@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
character @kbd{C-b}.  Although this syntax can represent any @acronym{ASCII}
character, it is preferred only when the precise octal value is more
important than the @acronym{ASCII} representation.

@example
@group
?\012 @result{} 10         ?\n @result{} 10         ?\C-j @result{} 10
?\101 @result{} 65         ?A @result{} 65

in documentation strings,
but the newline is ignored if escaped."
@end example

@node Non-ASCII in Strings
@subsubsection Non-@acronym{ASCII} Characters in Strings

  You can include a non-@acronym{ASCII} international character in a string
constant by writing it literally.  There are two text representations
for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte.  If the string constant is read from a multibyte source,
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
makes the string multibyte.  If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.

  You can also represent a multibyte non-@acronym{ASCII} character with its
character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary.  (Multibyte non-@acronym{ASCII} character codes are all
greater than 256.)  Any character which is not a valid hex digit
terminates this construct.  If the next character in the string could be
interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
one character, @samp{a} with grave accent.  @w{@samp{\ }} in a string
constant is just like backslash-newline; it does not contribute any
character to the string, but it does terminate the preceding hex escape.

  Using a multibyte hex escape forces the string to multibyte.  You can
represent a unibyte non-@acronym{ASCII} character with its character code,
which must be in the range from 128 (0200 octal) to 255 (0377 octal).
This forces a unibyte string.

  @xref{Text Representations}, for more information about the two
text representations.

them, like this: @code{"\t, \C-a"}.  @xref{Character Type}, for a
description of the read syntax for characters.

  However, not all of the characters you can write with backslash
escape-sequences are valid in strings.  The only control characters that
a string can hold are the @acronym{ASCII} control characters.  Strings do not
distinguish case in @acronym{ASCII} control characters.

  Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
that provides a way to represent meta versions of @acronym{ASCII} characters in a
string.  If you use the @samp{\M-} syntax to indicate a meta character
in a string constant, this sets the
@tex
@math{2^{7}}
@end tex

@end example

Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings.
A unibyte string never equals a multibyte string unless the
contents are entirely @acronym{ASCII} (@pxref{Text Representations}).

@example
@group
(equal "asdf" "ASDF")
     @result{} nil