From 3e99b8257bc97f34595128b200e25b76a2fe560f Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 21 Nov 2010 13:07:47 -0500 Subject: [PATCH] Document byte-to-string in Lisp manual. * objects.texi (Symbol Type): * text.texi (Near Point): * help.texi (Help Functions): * functions.texi (Mapping Functions): Use string instead of char-to-string in examples. * nonascii.texi (Converting Representations): Document byte-to-string. * strings.texi (Creating Strings): Don't mention semi-obsolete function char-to-string. (String Conversion): Shorten discussion of semi-obsolete function string-to-char. Link to Converting Representations. --- doc/lispref/ChangeLog | 16 ++++++++++ doc/lispref/functions.texi | 2 +- doc/lispref/help.texi | 2 +- doc/lispref/nonascii.texi | 7 +++++ doc/lispref/objects.texi | 1 - doc/lispref/strings.texi | 63 +++++++++++++++----------------------- doc/lispref/text.texi | 6 ++-- etc/NEWS | 1 + 8 files changed, 54 insertions(+), 44 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 2ea15fe3ca..959f4844c1 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,19 @@ +2010-11-21 Chong Yidong + + * nonascii.texi (Converting Representations): Document + byte-to-string. + + * strings.texi (Creating Strings): Don't mention semi-obsolete + function char-to-string. + (String Conversion): Shorten discussion of semi-obsolete function + string-to-char. Link to Converting Representations. + + * objects.texi (Symbol Type): + * text.texi (Near Point): + * help.texi (Help Functions): + * functions.texi (Mapping Functions): Use string instead of + char-to-string in examples. + 2010-11-20 Chong Yidong * text.texi (Kill Functions, Kill Functions) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 6f3fd63013..635245426f 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -818,7 +818,7 @@ length of @var{sequence}. For example: @result{} (a c e) (mapcar '1+ [1 2 3]) @result{} (2 3 4) -(mapcar 'char-to-string "abc") +(mapcar 'string "abc") @result{} ("a" "b" "c") @end group diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 026258f247..31a4db31dc 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -551,7 +551,7 @@ follows: @smallexample @group -(define-key global-map (char-to-string help-char) 'help-command) +(define-key global-map (string help-char) 'help-command) (fset 'help-command help-map) @end group @end smallexample diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index dfcb3e4730..f8d98cb1ad 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -202,6 +202,13 @@ unibyte string, it is returned unchanged. Use this function for characters. @end defun +@defun byte-to-string byte +@cindex byte to string +This function returns a unibyte string containing a single byte of +character data, @var{character}. It signals a error if +@var{character} is not an integer between 0 and 255. +@end defun + @defun multibyte-char-to-unibyte char This converts the multibyte character @var{char} to a unibyte character, and returns that character. If @var{char} is neither diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index c8ccb15a2d..8f72cc0168 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -582,7 +582,6 @@ makes it invalid as a number. @group foo ; @r{A symbol named @samp{foo}.} FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -char-to-string ; @r{A symbol named @samp{char-to-string}.} @end group @group 1+ ; @r{A symbol named @samp{1+}} diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 1128ca87d8..94d2765a83 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -126,9 +126,8 @@ This function returns a string made up of @var{count} repetitions of @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}). + Other functions to compare with this one include @code{make-vector} +(@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). @end defun @defun string &rest characters @@ -565,38 +564,6 @@ of text characters and general input events (@code{single-key-description} and @code{text-char-description}). These are used primarily for making help messages. -@defun char-to-string character -@cindex character to string -This function returns a new string containing one character, -@var{character}. This function is semi-obsolete because the function -@code{string} is more general. @xref{Creating Strings}. -@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, @acronym{ASCII} code -0. - -@example -(string-to-char "ABC") - @result{} 65 - -(string-to-char "xyz") - @result{} 120 -(string-to-char "") - @result{} 0 -@group -(string-to-char "\000") - @result{} 0 -@end group -@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 @@ -657,21 +624,41 @@ this function returns 0. @findex string-to-int @code{string-to-int} is an obsolete alias for this function. +@end defun + +@defun char-to-string character +@cindex character to string +This function returns a new string containing one character, +@var{character}. This function is semi-obsolete because the function +@code{string} is more general. @xref{Creating Strings}. +@end defun + +@defun string-to-char string + This function returns the first character in @var{string}. This +mostly identical to @code{(aref string 0)}, except that it returns 0 +if the string is empty. (The value is also 0 when the first character +of @var{string} is the null character, @acronym{ASCII} code 0.) This +function may be eliminated in the future if it does not seem useful +enough to retain. @end defun Here are some other functions that can convert to or from a string: @table @code @item concat -@code{concat} can convert a vector or a list into a string. +This function converts a vector or a list into a string. @xref{Creating Strings}. @item vconcat -@code{vconcat} can convert a string into a vector. @xref{Vector +This function converts a string into a vector. @xref{Vector Functions}. @item append -@code{append} can convert a string into a list. @xref{Building Lists}. +This function converts a string into a list. @xref{Building Lists}. + +@item byte-to-string +This function converts a byte of character data into a unibyte string. +@xref{Converting Representations}. @end table @node Formatting Strings diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 025bf1b6f8..57bf482588 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -86,7 +86,7 @@ buffer is @samp{@@}: @example @group -(char-to-string (char-after 1)) +(string (char-after 1)) @result{} "@@" @end group @end example @@ -121,9 +121,9 @@ but there is no peace. @end group @group -(char-to-string (preceding-char)) +(string (preceding-char)) @result{} "a" -(char-to-string (following-char)) +(string (following-char)) @result{} "c" @end group @end example diff --git a/etc/NEWS b/etc/NEWS index 4a7b9a5259..6e152777ae 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -108,6 +108,7 @@ starting from the first line of text below the header line. +++ ** The yank-handler argument to kill-region and friends is now obsolete. ++++ ** New function byte-to-string, like char-to-string but for bytes. -- 2.20.1