From 7f12c57ce623090bf47eb4b7ee2991a216574962 Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Mon, 30 Apr 2018 23:26:24 -0700 Subject: [PATCH] Tweak char and string chapters to be closer to R7RS. --- doc/ref-manual/characters.texi | 40 +++++----- doc/ref-manual/strings.texi | 131 ++++++++++++++++----------------- 2 files changed, 85 insertions(+), 86 deletions(-) diff --git a/doc/ref-manual/characters.texi b/doc/ref-manual/characters.texi index 17938c6ff..afa461e4a 100644 --- a/doc/ref-manual/characters.texi +++ b/doc/ref-manual/characters.texi @@ -146,11 +146,11 @@ Returns @code{#t} if @var{object} is a character, otherwise returns @code{#f}. @end deffn -@deffn {standard procedure} char=? char1 char2 -@deffnx {standard procedure} char? char1 char2 -@deffnx {standard procedure} char<=? char1 char2 -@deffnx {standard procedure} char>=? char1 char2 +@deffn {standard procedure} char=? char1 char2 char3 @dots{} +@deffnx {standard procedure} char? char1 char2 char3 @dots{} +@deffnx {standard procedure} char<=? char1 char2 char3 @dots{} +@deffnx {standard procedure} char>=? char1 char2 char3 @dots{} @cindex equivalence predicate, for characters @cindex ordering, of characters @cindex comparison, of characters @@ -162,11 +162,11 @@ non-decreasing, or monotonically non-increasing. These predicates are transitive. @end deffn -@deffn {standard procedure} char-ci=? char1 char2 -@deffnx {standard procedure} char-ci? char1 char2 -@deffnx {standard procedure} char-ci<=? char1 char2 -@deffnx {standard procedure} char-ci>=? char1 char2 +@deffn {char library procedure} char-ci=? char1 char2 char3 @dots{} +@deffnx {char library procedure} char-ci? char1 char2 char3 @dots{} +@deffnx {char library procedure} char-ci<=? char1 char2 char3 @dots{} +@deffnx {char library procedure} char-ci>=? char1 char2 char3 @dots{} These procedures are similar to @code{char=?} et cetera, but they treat upper case and lower case letters as the same. For example, @code{(char-ci=? #\A #\a)} returns @code{#t}. @@ -175,11 +175,11 @@ Specifically, these procedures behave as if @code{char-foldcase} were applied to their arguments before they were compared. @end deffn -@deffn {standard procedure} char-alphabetic? char -@deffnx {standard procedure} char-numeric? char -@deffnx {standard procedure} char-whitespace? char -@deffnx {standard procedure} char-upper-case? char -@deffnx {standard procedure} char-lower-case? char +@deffn {char library procedure} char-alphabetic? char +@deffnx {char library procedure} char-numeric? char +@deffnx {char library procedure} char-whitespace? char +@deffnx {char library procedure} char-upper-case? char +@deffnx {char library procedure} char-lower-case? char These procedures return @code{#t} if their arguments are alphabetic, numeric, whitespace, upper case, or lower case characters respectively, otherwise they return @code{#f}. @@ -196,7 +196,7 @@ Returns @code{#t} if @var{char} is either alphabetic or numeric, otherwise it returns @code{#f}. @end deffn -@deffn {standard procedure} digit-value char +@deffn {char library procedure} digit-value char This procedure returns the numeric value (0 to 9) of its argument if it is a numeric digit (that is, if @code{char-numeric?} returns @code{#t}), or @code{#f} on any other character. @@ -233,9 +233,9 @@ This is a very useful way to denote unusual character constants or @acronym{ASCII} codes. @end deffn -@deffn {standard procedure} char-upcase char -@deffnx {standard procedure} char-downcase char -@deffnx {standard procedure} char-foldcase char +@deffn {char library procedure} char-upcase char +@deffnx {char library procedure} char-downcase char +@deffnx {char library procedure} char-foldcase char @cindex uppercase, character conversion @cindex lowercase, character conversion @cindex case conversion, of character @@ -315,7 +315,7 @@ There are 4 bucky bits, named @dfn{control}, @dfn{meta}, @dfn{super}, and @dfn{hyper}. On GNU/Linux systems running a graphical desktop, the control bit corresponds to the @key{CTRL} key; the meta bit corresponds to the @key{ALT} key; and the super bit corresponds to the -``windows'' key. On Macos, these are the @key{CONTROL}, @key{OPTION}, +``windows'' key. On macOS, these are the @key{CONTROL}, @key{OPTION}, and @key{COMMAND} keys respectively. Characters with bucky bits are not used much outside of graphical user diff --git a/doc/ref-manual/strings.texi b/doc/ref-manual/strings.texi index 89a6dd1af..5adf447d5 100644 --- a/doc/ref-manual/strings.texi +++ b/doc/ref-manual/strings.texi @@ -128,9 +128,18 @@ characters of the string are initialized to @var{char}, otherwise the contents of the string are unspecified. @end deffn -@deffn {standard procedure} string char @dots{} -Returns an immutable string composed of the arguments. It is -analogous to @code{list}. +@deffn {extended standard procedure} string object @dots{} +@deffnx procedure string* objects +Returns an immutable string whose characters are the concatenation of +the characters from the given objects. Each object is converted to +characters as if passed to the @code{display} procedure. + +This is an MIT/GNU Scheme extension to the standard @code{string} that +accepts only characters as arguments. + +The procedure @code{string*} is identical to @code{string} but takes a +single argument that's a list of objects, rather than multiple object +arguments. @end deffn @deffn {standard procedure} string-length string @@ -169,7 +178,7 @@ exactly the same characters in the same positions, otherwise returns @code{#f}. @end deffn -@deffn {standard procedure} string-ci=? string1 string2 string @dots{} +@deffn {char library procedure} string-ci=? string1 string2 string @dots{} Returns @code{#t} if, after case-folding, all the strings are the same length and contain the same characters in the same positions, otherwise returns @code{#f}. Specifically, these procedures behave as @@ -178,13 +187,13 @@ comparing them. @end deffn @deffn {standard procedure} string? string1 string2 string @dots{} -@deffnx {standard procedure} string-ci>? string1 string2 string @dots{} +@deffnx {char library procedure} string-ci>? string1 string2 string @dots{} @deffnx {standard procedure} string<=? string1 string2 string @dots{} -@deffnx {standard procedure} string-ci<=? string1 string2 string @dots{} +@deffnx {char library procedure} string-ci<=? string1 string2 string @dots{} @deffnx {standard procedure} string>=? string1 string2 string @dots{} -@deffnx {standard procedure} string-ci>=? string1 string2 string @dots{} +@deffnx {char library procedure} string-ci>=? string1 string2 string @dots{} These procedures return @code{#t} if their arguments are (respectively): monotonically increasing, monotonically decreasing, monotonically non-decreasing, or monotonically non-increasing. @@ -236,10 +245,10 @@ thunk that is applied. @end example @end deffn -@deffn {standard procedure} string-upcase string -@deffnx {standard procedure} string-downcase string +@deffn {char library procedure} string-upcase string +@deffnx {char library procedure} string-downcase string @deffnx procedure string-titlecase string -@deffnx {standard procedure} string-foldcase string +@deffnx {char library procedure} string-foldcase string These procedures apply the Unicode full string uppercasing, lowercasing, titlecasing, and case-folding algorithms to their arguments and return the result. In certain cases, the result differs @@ -270,6 +279,42 @@ must contain at least one letter or the procedures return @code{#f}. @end example @end deffn +@deffn {standard procedure} substring string [start [end]] +Returns an immutable copy of the part of the given @var{string} +between @var{start} and @var{end}. +@end deffn + +@deffn procedure string-slice string [start [end]] +@cindex slice, of string +@cindex string slice +Returns a @dfn{slice} of @var{string}, restricted to the range of +characters specified by @var{start} and @var{end}. The returned slice +will be mutable if @code{string} is mutable, or immutable if +@code{string} is immutable. + +A slice is a kind of string that provides a view into another string. +The slice behaves like any other string, but changes to a mutable +slice are reflected in the original string and vice versa. + +@example +@group +(define foo (string-copy "abcde")) +foo @result{} "abcde" + +(define bar (string-slice foo 1 4)) +bar @result{} "bcd" + +(string-set! foo 2 #\z) +foo @result{} "abzde" +bar @result{} "bzd" + +(string-set! bar 1 #\y) +bar @result{} "byd" +foo @result{} "abyde" +@end group +@end example +@end deffn + @deffn {standard procedure} string-append string @dots{} @deffnx procedure string-append* strings Returns an immutable string whose characters are the concatenation of @@ -280,17 +325,6 @@ The non-standard procedure @code{string-append*} is identical to strings, rather than multiple string arguments. @end deffn -@deffn procedure string object @dots{} -@deffnx procedure string* objects -Returns an immutable string whose characters are the concatenation of -the characters from the given objects. Each object is converted to -characters as if passed to the @code{display} procedure. - -The procedure @code{string*} is identical to @code{string} but takes a -single argument that's a list of objects, rather than multiple object -arguments. -@end deffn - @deffn {standard procedure} string->list string [start [end]] @deffnx {standard procedure} list->string list It is an error if any element of @var{list} is not a character. @@ -303,10 +337,16 @@ preserved. @code{string->list} and @code{list->string} are inverses so far as @code{equal?} is concerned. @end deffn +@deffn {standard procedure} string-copy string [start [end]] +Returns a newly allocated mutable copy of the part of the given +@var{string} between @var{start} and @var{end}. +@end deffn + @deffn {standard procedure} string-copy! to at from [start [end]] -It is an error if @var{at} is less than zero or greater than the -length of @var{to}. It is also an error if @code{(- (string-length -@var{to}) @var{at})} is less than @code{(- @var{end} @var{start})}. +It is an error if @var{to} is not a mutable string or if @var{at} is +less than zero or greater than the length of @var{to}. It is also an +error if @code{(- (string-length @var{to}) @var{at})} is less than +@code{(- @var{end} @var{start})}. Copies the characters of string @var{from} between @var{start} and @var{end} to string @var{to}, starting at @var{at}. The order in @@ -329,47 +369,6 @@ Implementation note: in MIT/GNU Scheme @code{string-copy!} returns the value @code{(+ @var{at} (- @var{end} @var{start}))}. @end deffn -@deffn {standard procedure} string-copy string [start [end]] -Returns a newly allocated mutable copy of the part of the given -@var{string} between @var{start} and @var{end}. -@end deffn - -@deffn {standard procedure} substring string [start [end]] -Returns an immutable copy of the part of the given @var{string} -between @var{start} and @var{end}. -@end deffn - -@deffn procedure string-slice string [start [end]] -@cindex slice, of string -@cindex string slice -Returns a @dfn{slice} of @var{string}, restricted to the range of -characters specified by @var{start} and @var{end}. The returned slice -will be mutable if @code{string} is mutable, or immutable if -@code{string} is immutable. - -A slice is a kind of string that provides a view into another string. -The slice behaves like any other string, but changes to a mutable -slice are reflected in the original string and vice versa. - -@example -@group -(define foo (string-copy "abcde")) -foo @result{} "abcde" - -(define bar (string-slice foo 1 4)) -bar @result{} "bcd" - -(string-set! foo 2 #\z) -foo @result{} "abzde" -bar @result{} "bzd" - -(string-set! bar 1 #\y) -bar @result{} "byd" -foo @result{} "abyde" -@end group -@end example -@end deffn - @deffn {standard procedure} string-fill! string fill [start [end]] It is an error if @var{string} is not a mutable string or if @var{fill} is not a character. -- 2.25.1