commit f640a247e5c147e264d672a802f25a70f2c0c45e
parent 9727a03590d31fd2e6e2a426ece3f44d9eb28dbf
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Sun, 4 Feb 2024 15:57:28 -0500
Strings: Reflow paragraphs & tidy examples.
Diffstat:
1 file changed, 96 insertions(+), 96 deletions(-)
diff --git a/doc/r7rs-small/procedures/strings.texinfo b/doc/r7rs-small/procedures/strings.texinfo
@@ -1,10 +1,11 @@
@node Strings
@section Strings
-Strings are sequences of characters. Strings are written as sequences of characters
-enclosed within quotation marks (@code{"}). Within a string literal, various escape
-sequences represent characters other than themselves. Escape sequences always start
-with a backslash (@code{\}):
+Strings are sequences of characters. Strings are written as sequences
+of characters enclosed within quotation marks (@code{"}). Within a
+string literal, various escape sequences represent characters other
+than themselves. Escape sequences always start with a backslash
+(@code{\}):
@c We can't use a two-column table here because user-defined macros
@c are apparently "unreliable" in tables.
@@ -44,13 +45,15 @@ with a backslash (@code{\}):
@end itemize
-The result is unspecified if any other character in a string occurs after a backslash.
+The result is unspecified if any other character in a string occurs
+after a backslash.
-Except for a line ending, any character outside of an escape sequence stands for itself in
-the string literal. A line ending which is preceded by @code{\}@svar{intraline whitespace} expands to
-nothing (along with any trailing intraline whitespace), and can be used to indent strings
-for improved legibility. Any other line ending has the same effect as inserting a @code{\n}
-character into the string.
+Except for a line ending, any character outside of an escape sequence
+stands for itself in the string literal. A line ending which is
+preceded by @code{\}@svar{intraline whitespace} expands to nothing
+(along with any trailing intraline whitespace), and can be used to
+indent strings for improved legibility. Any other line ending has the
+same effect as inserting a @code{\n} character into the string.
Examples:
@@ -62,34 +65,32 @@ Examples:
"\x03B1; is named GREEK SMALL LETTER ALPHA."
@end example
-The @dfn{length} of a string is the number of
-characters that it contains. This number is an exact, non-negative integer that is fixed
-when the string is created. The @dfn{valid indexes} of a string are the exact non-negative
-integers less than the length of the string. The first character of a string has index 0, the
-second has index 1, and so on.
+The @dfn{length} of a string is the number of characters that it
+contains. This number is an exact, non-negative integer that is fixed
+when the string is created. The @dfn{valid indexes} of a string are the
+exact non-negative integers less than the length of the string. The
+first character of a string has index 0, the second has index 1, and so
+on.
-Some of the procedures that operate on strings ignore the difference between upper
-and lower case. The names of the versions that ignore case end with @samp{-ci} (for ``case
-insensitive'').
+Some of the procedures that operate on strings ignore the difference
+between upper and lower case. The names of the versions that ignore
+case end with @samp{-ci} (for ``case insensitive'').
-Implementations may forbid certain characters from appearing in strings.
-However, with the exception of @code{#\null}, ASCII characters must
-not be forbidden.
-For example, an implementation might support the entire Unicode repertoire,
-but only allow characters U+0001 to U+00FF (the Latin-1 repertoire
-without @code{#\null}) in strings.
+Implementations may forbid certain characters from appearing in
+strings. However, with the exception of @code{#\null}, ASCII characters
+must not be forbidden. For example, an implementation might support the
+entire Unicode repertoire, but only allow characters U+0001 to U+00FF
+(the Latin-1 repertoire without @code{#\null}) in strings.
It is an error to pass such a forbidden character to
-@code{make-string}, @code{string}, @code{string-set!}, or @code{string-fill!},
-as part of the list passed to @code{list->string},
-or as part of the vector passed to @code{vector->string}
-(see @ref{Vectors}),
-or in UTF-8 encoded form within a bytevector passed to
-@code{utf8->string} (see @ref{Bytevectors}).
-It is also an error for a procedure passed to @code{string-map}
-(see @ref{Control features}) to return a forbidden character,
-or for @code{read-string} (see @ref{Input})
-to attempt to read one.
+@code{make-string}, @code{string}, @code{string-set!}, or
+@code{string-fill!}, as part of the list passed to @code{list->string},
+or as part of the vector passed to @code{vector->string} (see
+@ref{Vectors}), or in UTF-8 encoded form within a bytevector passed to
+@code{utf8->string} (see @ref{Bytevectors}). It is also an error for a
+procedure passed to @code{string-map} (see @ref{Control features}) to
+return a forbidden character, or for @code{read-string} (see
+@ref{Input}) to attempt to read one.
@deffn procedure string? obj
@@ -101,15 +102,16 @@ Returns @code{#t} if @var{obj} is a string, otherwise returns @code{#f}.
@deffnx procedure make-string k char
The @code{make-string} procedure returns a newly allocated string of
-length @var{k}. If @var{char} is given, then all the characters of the string
-are initialized to @var{char}, otherwise the contents of the
+length @var{k}. If @var{char} is given, then all the characters of the
+string are initialized to @var{char}, otherwise the contents of the
string are unspecified.
@end deffn
@deffn procedure string char@dots{}
-Returns a newly allocated string composed of the arguments. It is analogous to @code{list}.
+Returns a newly allocated string composed of the arguments. It is
+analogous to @code{list}.
@end deffn
@@ -123,8 +125,8 @@ Returns the number of characters in the given @var{string}.
It is an error if @var{k} is not a valid index of @var{string}.
-The @code{string-ref} procedure returns character @var{k} of @var{string}
-using zero-origin indexing.
+The @code{string-ref} procedure returns character @var{k} of
+@var{string} using zero-origin indexing.
There is no requirement for this procedure to execute in constant time.
@@ -134,34 +136,37 @@ There is no requirement for this procedure to execute in constant time.
It is an error if @var{k} is not a valid index of @var{string}.
-The @code{string-set!} procedure stores @var{char} in element @var{k} of @var{string}.
-There is no requirement for this procedure to execute in constant time.
+The @code{string-set!} procedure stores @var{char} in element @var{k}
+of @var{string}. There is no requirement for this procedure to execute
+in constant time.
@lisp
(define (f) (make-string 3 #\*))
(define (g) "***")
-(string-set! (f) 0 #\?) @result{} unspecified
-(string-set! (g) 0 #\?) @result{} error
+(string-set! (f) 0 #\?) @result{} unspecified
+(string-set! (g) 0 #\?) @result{} error
(string-set! (symbol->string 'immutable)
0
- #\?) @result{} error
+ #\?) @result{} error
@end lisp
+
@end deffn
@deffn procedure string=? @vari{string} @varii{string} @variii{string}@dots{}
-Returns @code{#t} if all the @var{string}s are the same length and contain
-exactly the same characters in the same positions, otherwise returns
-@code{#f}.
+Returns @code{#t} if all the @var{string}s are the same length and
+contain exactly the same characters in the same positions, otherwise
+returns @code{#f}.
@end deffn
@deffn {char library procedure} string-ci=? @vari{string} @varii{string} @variii{string}@dots{}
-Returns @code{#t} if, after case-folding, all the @var{string}s are the same
-length and contain the same characters in the same positions, otherwise
-returns @code{#f}. Specifically, these procedures behave as if
-@code{string-foldcase} were applied to their arguments before comparing them.
+Returns @code{#t} if, after case-folding, all the @var{string}s are the
+same length and contain the same characters in the same positions,
+otherwise returns @code{#f}. Specifically, these procedures behave as
+if @code{string-foldcase} were applied to their arguments before
+comparing them.
@end deffn
@@ -174,9 +179,9 @@ returns @code{#f}. Specifically, these procedures behave as if
@deffnx procedure string>=? @vari{string} @varii{string} @variii{string}@dots{}
@deffnx {char library procedure} string-ci>=? @vari{string} @varii{string} @variii{string}@dots{}
-These procedures return @code{#t} if their arguments are (respectively): monotonically
-increasing, monotonically decreasing, monotonically non-decreasing, or monotonically
-non-increasing.
+These procedures return @code{#t} if their arguments are (respectively):
+monotonically increasing, monotonically decreasing, monotonically
+non-decreasing, or monotonically non-increasing.
These predicates are required to be transitive.
@@ -188,17 +193,17 @@ would be the lexicographic ordering on strings induced by the ordering
are the same up to the length of the shorter string, the shorter string
would be considered to be lexicographically less than the longer string.
However, it is also permitted to use the natural ordering imposed by the
-implementation's internal representation of strings, or a more complex locale-specific
-ordering.
+implementation's internal representation of strings, or a more complex
+locale-specific ordering.
In all cases, a pair of strings must satisfy exactly one of
@code{string<?}, @code{string=?}, and @code{string>?}, and must satisfy
-@code{string<=?} if and only if they do not satisfy @code{string>?} and
-@code{string>=?} if and only if they do not satisfy @code{string<?}.
+@code{string<=?} if and only if they do not satisfy @code{string>?}
+and @code{string>=?} if and only if they do not satisfy @code{string<?}.
-The @samp{-ci} procedures behave as if they applied
-@code{string-foldcase} to their arguments before invoking the corresponding
-procedures without @samp{-ci}.
+The @samp{-ci} procedures behave as if they applied @code{string-foldcase}
+to their arguments before invoking the corresponding procedures without
+@samp{-ci}.
@end deffn
@@ -210,13 +215,13 @@ These procedures apply the Unicode full string uppercasing, lowercasing,
and case-folding algorithms to their arguments and return the result.
In certain cases, the result differs in length from the argument.
If the result is equal to the argument in the sense of @code{string=?},
-the argument may be returned.
-Note that language-sensitive mappings and foldings are not used.
+the argument may be returned. Note that language-sensitive mappings
+and foldings are not used.
The Unicode Standard prescribes special treatment of the Greek letter
-@greekcapitalsigma{}, whose normal lower-case form is @greeksmallsigma{} but which becomes
-@greekfinalsigma at the end of a word. See UAX #29 (part of
-the Unicode Standard) for details. However, implementations of
+@greekcapitalsigma{}, whose normal lower-case form is @greeksmallsigma{}
+but which becomes @greekfinalsigma at the end of a word. See UAX #29
+(part of the Unicode Standard) for details. However, implementations of
@code{string-downcase} are not required to provide this behavior, and may
choose to change @greekcapitalsigma{} to @greeksmallsigma{} in all cases.
@c cite{uax29}
@@ -225,19 +230,18 @@ choose to change @greekcapitalsigma{} to @greeksmallsigma{} in all cases.
@deffn procedure substring string start end
-The @code{substring} procedure returns a newly allocated string formed from the characters of
-@var{string} beginning with index @var{start} and ending with index
-@var{end}.
-This is equivalent to calling @code{string-copy} with the same arguments,
-but is provided for backward compatibility and
-stylistic flexibility.
+The @code{substring} procedure returns a newly allocated string formed
+from the characters of @var{string} beginning with index @var{start}
+and ending with index @var{end}. This is equivalent to calling
+@code{string-copy} with the same arguments, but is provided for
+backward compatibility and stylistic flexibility.
@end deffn
@deffn procedure string-append string@dots{}
-Returns a newly allocated string whose characters are the concatenation of the
-characters in the given @var{string}s.
+Returns a newly allocated string whose characters are the concatenation
+of the characters in the given @var{string}s.
@end deffn
@@ -248,15 +252,12 @@ characters in the given @var{string}s.
It is an error if any element of @var{list} is not a character.
-The @code{string->list} procedure returns a newly allocated list of the
-characters of @var{string} between @var{start} and @var{end}.
-@code{list->string}
-returns a newly allocated string formed from the elements in the list
-@var{list}.
-In both procedures, order is preserved.
-@code{string->list}
-and @code{list->string} are
-inverses so far as @code{equal?} is concerned.
+The @code{string->list} procedure returns a newly allocated list of
+the characters of @var{string} between @var{start} and @var{end}.
+@code{list->string} returns a newly allocated string formed from the
+elements in the list @var{list}. In both procedures, order is preserved.
+@code{string->list} and @code{list->string} are inverses so far as
+@code{equal?} is concerned.
@end deffn
@@ -273,17 +274,17 @@ between @var{start} and @var{end}.
@deffnx procedure string-copy! to at from start
@deffnx 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}@code{) }@var{at}@code{)}
-is less than @code{(- }@var{end} @var{start}@code{)}.
+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}@code{)
+}@var{at}@code{)} is less than @code{(- }@var{end} @var{start}@code{)}.
-Copies the characters of string @var{from} between @var{start} and @var{end}
-to string @var{to}, starting at @var{at}. The order in which characters are
-copied is unspecified, except that if the source and destination overlap,
-copying takes place as if the source is first copied into a temporary
-string and then into the destination. This can be achieved without
-allocating storage by making sure to copy in the correct direction in
-such circumstances.
+Copies the characters of string @var{from} between @var{start} and
+@var{end} to string @var{to}, starting at @var{at}. The order in
+which characters are copied is unspecified, except that if the source
+and destination overlap, copying takes place as if the source is first
+copied into a temporary string and then into the destination. This can
+be achieved without allocating storage by making sure to copy in the
+correct direction in such circumstances.
@lisp
(define a "12345")
@@ -300,8 +301,7 @@ b @result{} "a12de"
It is an error if @var{fill} is not a character.
-The @code{string-fill!} procedure stores @var{fill}
-in the elements of @var{string}
-between @var{start} and @var{end}.
+The @code{string-fill!} procedure stores @var{fill} in the elements of
+@var{string} between @var{start} and @var{end}.
@end deffn
