[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/strings.texi [lexbind]
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/strings.texi [lexbind] |
Date: |
Thu, 20 Nov 2003 19:36:50 -0500 |
Index: emacs/lispref/strings.texi
diff -c emacs/lispref/strings.texi:1.22.8.2 emacs/lispref/strings.texi:1.22.8.3
*** emacs/lispref/strings.texi:1.22.8.2 Tue Oct 14 19:10:12 2003
--- emacs/lispref/strings.texi Thu Nov 20 19:35:47 2003
***************
*** 44,50 ****
The length of a string (like any array) is fixed, and cannot be
altered once the string exists. 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.)
Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence functions.
--- 44,50 ----
The length of a string (like any array) is fixed, and cannot be
altered once the string exists. Strings in Lisp are @emph{not}
terminated by a distinguished character code. (By contrast, strings in
! C are terminated by a character with @acronym{ASCII} code 0.)
Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence functions.
***************
*** 52,61 ****
change individual characters in a string using the functions @code{aref}
and @code{aset} (@pxref{Array Functions}).
! There are two text representations for address@hidden characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
! Representations}). An @sc{ascii} character always occupies one byte in a
! string; in fact, when a string is all @sc{ascii}, there is no real
difference between the unibyte and multibyte representations.
For most Lisp programming, you don't need to be concerned with these two
representations.
--- 52,61 ----
change individual characters in a string using the functions @code{aref}
and @code{aset} (@pxref{Array Functions}).
! There are two text representations for address@hidden characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
! Representations}). An @acronym{ASCII} character always occupies one byte in a
! string; in fact, when a string is all @acronym{ASCII}, there is no real
difference between the unibyte and multibyte representations.
For most Lisp programming, you don't need to be concerned with these two
representations.
***************
*** 66,73 ****
codes 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. If you want to store such characters in a sequence, such as
a key sequence, you must use a vector instead of a string.
@xref{Character Type}, for more information about the representation of meta
--- 66,73 ----
codes in the range 128 to 255.
Strings cannot hold characters that have the hyper, super or alt
! modifiers; they can hold @acronym{ASCII} control characters, but no other
! control characters. They do not distinguish case in @acronym{ASCII} control
characters. If you want to store such characters in a sequence, such as
a key sequence, you must use a vector instead of a string.
@xref{Character Type}, for more information about the representation of meta
***************
*** 172,178 ****
@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
--- 172,178 ----
@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 for @var{end}, it stands for the length of the
string. Thus,
@example
***************
*** 208,217 ****
@result{} [b (c)]
@end example
! 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
--- 208,218 ----
@result{} [b (c)]
@end example
! A @code{wrong-type-argument} error is signaled if @var{start} is not
! an integer or if @var{end} is neither an integer nor @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
***************
*** 219,227 ****
beginning of a buffer is at index 1.
@end defun
! @defun substring-no-properties string start &optional end
! This works like @code{substring} but discards all text properties
! from the value.
@end defun
@defun concat &rest sequences
--- 220,231 ----
beginning of a buffer is at index 1.
@end defun
! @defun substring-no-properties string &optional start end
! This works like @code{substring} but discards all text properties from
! the value. Also, @var{start} may be omitted or @code{nil}, which is
! equivalent to 0. Thus, @address@hidden(substring-no-properties
! @var{string})}} returns a copy of @var{string}, with all text
! properties removed.
@end defun
@defun concat &rest sequences
***************
*** 264,270 ****
Lists}.
@end defun
! @defun split-string string separators omit-nulls
This function splits @var{string} into substrings at matches for the
regular expression @var{separators}. Each match for @var{separators}
defines a splitting point; the substrings between the splitting points
--- 268,274 ----
Lists}.
@end defun
! @defun split-string string &optional separators omit-nulls
This function splits @var{string} into substrings at matches for the
regular expression @var{separators}. Each match for @var{separators}
defines a splitting point; the substrings between the splitting points
***************
*** 285,291 ****
@example
(split-string " two words ")
! @result{} ("two" "words")
@end example
The result is not @samp{("" "two" "words" "")}, which would rarely be
--- 289,295 ----
@example
(split-string " two words ")
! @result{} ("two" "words")
@end example
The result is not @samp{("" "two" "words" "")}, which would rarely be
***************
*** 294,326 ****
@example
(split-string " two words " split-string-default-separators)
! @result{} ("" "two" "words" "")
@end example
More examples:
@example
(split-string "Soup is good food" "o")
! @result{} ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o" t)
! @result{} ("S" "up is g" "d f" "d")
(split-string "Soup is good food" "o+")
! @result{} ("S" "up is g" "d f" "d")
@end example
! Empty matches do count, when not adjacent to another match:
@example
! (split-string "Soup is good food" "o*")
! @result{}("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
! (split-string "Nice doggy!" "")
! @result{}("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
@end example
@end defun
@defvar split-string-default-separators
The default value of @var{separators} for @code{split-string}, initially
! @samp{"[ \f\t\n\r\v]+"}.
@end defvar
@node Modifying Strings
--- 298,359 ----
@example
(split-string " two words " split-string-default-separators)
! @result{} ("" "two" "words" "")
@end example
More examples:
@example
(split-string "Soup is good food" "o")
! @result{} ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o" t)
! @result{} ("S" "up is g" "d f" "d")
(split-string "Soup is good food" "o+")
! @result{} ("S" "up is g" "d f" "d")
@end example
! Empty matches do count, except that @code{split-string} will not look
! for a final empty match when it already reached the end of the string
! using a non-empty match or when @var{string} is empty:
@example
! (split-string "aooob" "o*")
! @result{} ("" "a" "" "b" "")
! (split-string "ooaboo" "o*")
! @result{} ("" "" "a" "b" "")
! (split-string "" "")
! @result{} ("")
! @end example
!
! However, when @var{separators} can match the empty string,
! @var{omit-nulls} is usually @code{t}, so that the subtleties in the
! three previous examples are rarely relevant:
!
! @example
! (split-string "Soup is good food" "o*" t)
! @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
! (split-string "Nice doggy!" "" t)
! @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
! (split-string "" "" t)
! @result{} nil
! @end example
!
! Somewhat odd, but predictable, behavior can occur for certain
! ``non-greedy'' values of @var{separators} that can prefer empty
! matches over non-empty matches. Again, such values rarely occur in
! practice:
!
! @example
! (split-string "ooo" "o*" t)
! @result{} nil
! (split-string "ooo" "\\|o+" t)
! @result{} ("o" "o" "o")
@end example
@end defun
@defvar split-string-default-separators
The default value of @var{separators} for @code{split-string}, initially
! @address@hidden"[ \f\t\n\r\v]+"}}.
@end defvar
@node Modifying Strings
***************
*** 367,373 ****
@defun string= string1 string2
This function returns @code{t} if the characters of the two strings
! match exactly.
Case is always significant, regardless of @code{case-fold-search}.
@example
--- 400,407 ----
@defun string= string1 string2
This function returns @code{t} if the characters of the two strings
! match exactly. Symbols are also allowed as arguments, in which case
! their print names are used.
Case is always significant, regardless of @code{case-fold-search}.
@example
***************
*** 383,389 ****
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
! If the strings contain address@hidden characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
Representations}.
@end defun
--- 417,423 ----
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
! If the strings contain address@hidden characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
Representations}.
@end defun
***************
*** 405,415 ****
Pairs of characters are compared according to their character codes.
Keep in mind that lower case letters have higher numeric values in the
! @sc{ascii} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
! letters. An @sc{ascii} character is less than any address@hidden
! character; a unibyte address@hidden character is always less than any
! multibyte address@hidden character (@pxref{Text Representations}).
@example
@group
--- 439,449 ----
Pairs of characters are compared according to their character codes.
Keep in mind that lower case letters have higher numeric values in the
! @acronym{ASCII} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
! letters. An @acronym{ASCII} character is less than any address@hidden
! character; a unibyte address@hidden character is always less than any
! multibyte address@hidden character (@pxref{Text Representations}).
@example
@group
***************
*** 441,446 ****
--- 475,483 ----
@result{} nil
@end group
@end example
+
+ Symbols are also allowed as arguments, in which case their print names
+ are used.
@end defun
@defun string-lessp string1 string2
***************
*** 514,520 ****
@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
--- 551,557 ----
@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, @acronym{ASCII} code
0.
@example
***************
*** 545,552 ****
--- 582,591 ----
@example
(number-to-string 256)
@result{} "256"
+ @group
(number-to-string -23)
@result{} "-23"
+ @end group
(number-to-string -23.5)
@result{} "-23.5"
@end example
***************
*** 560,579 ****
@defun string-to-number string &optional base
@cindex string to number
This function returns the numeric value of the characters in
! @var{string}. If @var{base} is address@hidden, integers are converted
! in that base. If @var{base} is @code{nil}, then base ten is used.
! Floating point conversion always uses base ten; we have not implemented
! other radices for floating point numbers, because that would be much
! more work and does not seem useful. If @var{string} looks like an
! integer but its value is too large to fit into a Lisp integer,
@code{string-to-number} returns a floating point result.
! The parsing 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
! neither a digit, nor a plus or minus sign, nor the leading dot of a
! floating point number, this function returns 0.
@example
(string-to-number "256")
--- 599,620 ----
@defun string-to-number string &optional base
@cindex string to number
This function returns the numeric value of the characters in
! @var{string}. If @var{base} is address@hidden, it must be an integer
! between 2 and 16 (inclusive), and integers are converted in that base.
! If @var{base} is @code{nil}, then base ten is used. Floating point
! conversion only works in base ten; we have not implemented other
! radices for floating point numbers, because that would be much more
! work and does not seem useful. If @var{string} looks like an integer
! but its value is too large to fit into a Lisp integer,
@code{string-to-number} returns a floating point result.
! The parsing skips spaces and tabs at the beginning of @var{string},
! then reads as much of @var{string} as it can interpret as a number in
! the given base. (On some systems it ignores other whitespace at the
! beginning, not just spaces and tabs.) If the first character after
! the ignored whitespace is neither a digit in the given base, nor a
! plus or minus sign, nor the leading dot of a floating point number,
! this function returns 0.
@example
(string-to-number "256")
***************
*** 675,690 ****
copied into the output. The text properties of the @samp{%s} itself
are also copied, but those of the object take priority.
- 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 (that is, using @address@hidden
Functions}). 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
--- 716,727 ----
***************
*** 747,758 ****
@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. Here are some examples of padding:
@example
(format "%06d is padded on the left with zeros" 123)
--- 784,800 ----
@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. Some of these
! conventions are ignored for specification characters for which they do
! not make sense. That is, %s, %S and %c accept a numeric prefix
! starting with 0, but still pad with @emph{spaces} on the left. Also,
! %% accepts a numeric prefix, but ignores it. Here are some examples
! of padding:
@example
(format "%06d is padded on the left with zeros" 123)
***************
*** 804,810 ****
The character case functions change the case of single characters or
of the contents of strings. The functions normally convert only
alphabetic characters (the letters @samp{A} through @samp{Z} and
! @samp{a} through @samp{z}, as well as address@hidden letters); other
characters are not altered. You can specify a different case
conversion mapping by specifying a case table (@pxref{Case Tables}).
--- 846,852 ----
The character case functions change the case of single characters or
of the contents of strings. The functions normally convert only
alphabetic characters (the letters @samp{A} through @samp{Z} and
! @samp{a} through @samp{z}, as well as address@hidden letters); other
characters are not altered. You can specify a different case
conversion mapping by specifying a case table (@pxref{Case Tables}).
***************
*** 812,818 ****
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.
--- 854,860 ----
arguments.
The examples below use the characters @samp{X} and @samp{x} which have
! @acronym{ASCII} codes 88 and 120 respectively.
@defun downcase string-or-char
This function converts a character or a string to lower case.
***************
*** 872,882 ****
--- 914,928 ----
has the same result as @code{upcase}.
@example
+ @group
(capitalize "The cat in the hat")
@result{} "The Cat In The Hat"
+ @end group
+ @group
(capitalize "THE 77TH-HATTED CAT")
@result{} "The 77th-Hatted Cat"
+ @end group
@group
(capitalize ?x)
***************
*** 885,900 ****
@end example
@end defun
! @defun upcase-initials string
! This function capitalizes the initials of the words in @var{string},
! without altering any letters other than the initials. It returns a new
! string whose contents are a copy of @var{string}, in which each word has
had its initial letter converted to upper 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 (@pxref{Syntax Class Table}).
@example
@group
(upcase-initials "The CAT in the hAt")
--- 931,950 ----
@end example
@end defun
! @defun upcase-initials string-or-char
! If @var{string-or-char} is a string, this function capitalizes the
! initials of the words in @var{string-or-char}, without altering any
! letters other than the initials. It returns a new string whose
! contents are a copy of @var{string-or-char}, in which each word has
had its initial letter converted to upper 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 (@pxref{Syntax Class Table}).
+ When the argument to @code{upcase-initials} is a character,
+ @code{upcase-initials} has the same result as @code{upcase}.
+
@example
@group
(upcase-initials "The CAT in the hAt")
***************
*** 951,957 ****
The extra table @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.)
--- 1001,1007 ----
The extra table @var{equivalences} is a map that cyclicly permutes
each equivalence class (of characters with the same canonical
! equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into
@samp{A} and @samp{A} into @samp{a}, and likewise for each set of
equivalent characters.)
***************
*** 988,994 ****
@end defun
The following three functions are convenient subroutines for packages
! that define address@hidden character sets. They modify the specified
case table @var{case-table}; they also modify the standard syntax table.
@xref{Syntax Tables}. Normally you would use these functions to change
the standard case table.
--- 1038,1044 ----
@end defun
The following three functions are convenient subroutines for packages
! that define address@hidden character sets. They modify the specified
case table @var{case-table}; they also modify the standard syntax table.
@xref{Syntax Tables}. Normally you would use these functions to change
the standard case table.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/strings.texi [lexbind],
Miles Bader <=