mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-12 23:00:22 +02:00
Code Activity

* scheme-data.texi (Strings): Reorganized the whole `Strings'

Browse source 
section and wrote introductory material for each new subsection.
This commit is contained in:
Martin Grabmüller 2001-03-27 15:42:12 +00:00
parent 91344cebe0
commit b576faf1c0
2 changed files with 304 additions and 202 deletions
Download patch file Download diff file Expand all files Collapse all files

5
doc/ChangeLog
View file

@ -1,3 +1,8 @@
2001-03-27 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-data.texi (Strings): Reorganized the whole `Strings'
section and wrote introductory material for each new subsection.
2001-03-25 Marius Vollmer <mvo@zagadka.ping.de> 2001-03-25 Marius Vollmer <mvo@zagadka.ping.de>
* intro.texi (Modules and Extensions): Some short text about * intro.texi (Modules and Extensions): Some short text about

501
doc/scheme-data.texi
View file

@ -51,11 +51,11 @@ sections of this manual that cover them.
* Keywords:: Self-quoting, customizable display keywords. * Keywords:: Self-quoting, customizable display keywords.
* Pairs:: Scheme's basic building block. * Pairs:: Scheme's basic building block.
* Lists:: Special list functions supported by Guile. * Lists:: Special list functions supported by Guile.
* Records:: * Records::
* Structures:: * Structures::
* Arrays:: * Arrays::
* Association Lists and Hash Tables:: * Association Lists and Hash Tables::
* Vectors:: * Vectors::
* Hooks:: User-customizable event lists. * Hooks:: User-customizable event lists.
* Other Data Types:: Data types that are documented elsewhere. * Other Data Types:: Data types that are documented elsewhere.
@end menu @end menu
@ -154,7 +154,7 @@ in Scheme, which is particularly clear and accessible: see
* Reals and Rationals:: Real and rational numbers. * Reals and Rationals:: Real and rational numbers.
* Complex Numbers:: Complex numbers. * Complex Numbers:: Complex numbers.
* Exactness:: Exactness and inexactness. * Exactness:: Exactness and inexactness.
* Number Syntax:: Read syntax for numerical data. * Number Syntax:: Read syntax for numerical data.
* Integer Operations:: Operations on integer values. * Integer Operations:: Operations on integer values.
* Comparison:: Comparison predicates. * Comparison:: Comparison predicates.
* Conversion:: Converting numbers to and from strings. * Conversion:: Converting numbers to and from strings.
@ -1397,23 +1397,76 @@ Return the lowercase character version of @var{chr}.
@node Strings @node Strings
@section Strings @section Strings
[FIXME: this is pasted in from Tom Lord's original guile.texi and should Strings are fixed--length sequences of characters. They can be created
be reviewed] by calling constructor procedures, but they can also literally get
entered at the REPL or in Scheme source files.
For the sake of efficiency, two special kinds of strings are available The read syntax for strings is an arbitrarily long sequence of characters
in Guile: shared substrings and the misleadingly named ``read-only'' enclosed in double quotes (@code{"}). @footnote{Actually, the current
strings. It is not necessary to know about these to program in Guile, implementation restricts strings to a length of 2&24 characters.} If
but you are likely to run into one or both of these special string types you want to insert a double quote character into a string literal, it
eventually, and it will be helpful to know how they work. must be prefixed with a backslash @code{\} character (called an
@emph{escape character}).
The following are examples of string literals:
@lisp
"foo"
"bar plonk"
"Hello World"
"\"Hi\", he said."
@end lisp
Guile provides a rich set of string processing procedures, because text
handling is very important when Guile is used as a scripting language.
@menu @menu
* String Fun:: New functions for manipulating strings. * String Predicates:: Testing strings for certain properties.
* String Constructors:: Creating new string objects.
* List/String Conversion:: Converting from/to lists of characters.
* String Selection:: Select portions from strings.
* String Modification:: Modify parts or whole strings.
* String Comparison:: Lexicographic ordering predicates.
* String Searching:: Searching in strings.
* Alphabetic Case Mapping:: Convert the alphabetic case of strings.
* Appending Strings:: Appending strings to form a new string.
* String Miscellanea:: Miscellaneous string procedures.
* Shared Substrings:: Strings which share memory with each other. * Shared Substrings:: Strings which share memory with each other.
* Read Only Strings:: Treating certain non-strings as strings. * Read Only Strings:: Treating certain non-strings as strings.
@end menu @end menu
@node String Fun @node String Predicates
@subsection String Fun @subsection String Predicates
The following procedures can be used to check whether a given string
fulfills some specified property.
@r5index string?
@c docstring begin (texi-doc-string "guile" "string?")
@deffn primitive string? obj
Returns @code{#t} iff @var{obj} is a string, else returns
@code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "string-null?")
@deffn primitive string-null? str
Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}
otherwise.
@example
(string-null? "") @result{} #t
y @result{} "foo"
(string-null? y) @result{} #f
@end example
@end deffn
@node String Constructors
@subsection String Constructors
The string constructor procedures create new string objects, possibly
initializing them with some specified character data.
@c FIXME::martin: list->string belongs into `List/String Conversion'
@r5index string @r5index string
@r5index list->string @r5index list->string
@ -1434,13 +1487,32 @@ the string are initialized to @var{chr}, otherwise the contents
of the @var{string} are unspecified. of the @var{string} are unspecified.
@end deffn @end deffn
@r5index string-append @node List/String Conversion
@c docstring begin (texi-doc-string "guile" "string-append") @subsection List/String conversion
@deffn primitive string-append . args
Return a newly allocated string whose characters form the When processing strings, it is often convenient to first convert them
concatenation of the given strings, @var{args}. into a list representation by using the procedure @code{string->list},
work with the resulting list, and then convert it back into a string.
These procedures are useful for similar tasks.
@r5index string->list
@c docstring begin (texi-doc-string "guile" "string->list")
@deffn primitive string->list str
@samp{String->list} returns a newly allocated list of the
characters that make up the given string. @samp{List->string}
returns a newly allocated string formed from the characters in the list
@var{list}, which must be a list of characters. @samp{String->list}
and @samp{list->string} are
inverses so far as @samp{equal?} is concerned. (r5rs)
@end deffn @end deffn
@node String Selection
@subsection String Selection
Portions of strings can be extracted by these procedures.
@code{string-ref} delivers individual characters whereas
@code{substring} can be used to extract substrings from longer strings.
@r5index string-length @r5index string-length
@c docstring begin (texi-doc-string "guile" "string-length") @c docstring begin (texi-doc-string "guile" "string-length")
@deffn primitive string-length string @deffn primitive string-length string
@ -1454,19 +1526,10 @@ Return character @var{k} of @var{str} using zero-origin
indexing. @var{k} must be a valid index of @var{str}. indexing. @var{k} must be a valid index of @var{str}.
@end deffn @end deffn
@r5index string-set! @r5index string-copy
@c docstring begin (texi-doc-string "guile" "string-set!") @c docstring begin (texi-doc-string "guile" "string-copy")
@deffn primitive string-set! str k chr @deffn primitive string-copy str
Store @var{chr} in element @var{k} of @var{str} and return Returns a newly allocated copy of the given @var{string}. (r5rs)
an unspecified value. @var{k} must be a valid index of
@var{str}.
@end deffn
@r5index string?
@c docstring begin (texi-doc-string "guile" "string?")
@deffn primitive string? obj
Returns @code{#t} iff @var{obj} is a string, else returns
@code{#f}.
@end deffn @end deffn
@r5index substring @r5index substring
@ -1481,49 +1544,41 @@ exact integers satisfying:
0 <= @var{start} <= @var{end} <= (string-length @var{str}). 0 <= @var{start} <= @var{end} <= (string-length @var{str}).
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "string-index") @node String Modification
@deffn primitive string-index str chr [frm [to]] @subsection String Modification
Return the index of the first occurrence of @var{chr} in @var{str}. The
optional integer arguments @var{frm} and @var{to} limit the search to
a portion of the string. This procedure essentially implements the
@code{index} or @code{strchr} functions from the C library.
(qdocs:) Returns the index of @var{char} in @var{str}, or @code{#f} if the These procedures are for modifying strings in--place. That means, that
@var{char} isn't in @var{str}. If @var{frm} is given and not @code{#f}, not a new string is the result of a string operation, but that the
it is used as the starting index; if @var{to} is given and not @code{#f}, actual memory representation of a string is modified.
it is used as the ending index (exclusive).
@example @r5index string-set!
(string-index "weiner" #\e) @c docstring begin (texi-doc-string "guile" "string-set!")
@result{} 1 @deffn primitive string-set! str k chr
Store @var{chr} in element @var{k} of @var{str} and return
(string-index "weiner" #\e 2) an unspecified value. @var{k} must be a valid index of
@result{} 4 @var{str}.
(string-index "weiner" #\e 2 4)
@result{} #f
@end example
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "string-rindex") @r5index string-fill!
@deffn primitive string-rindex str chr [frm [to]] @c docstring begin (texi-doc-string "guile" "string-fill!")
Like @code{string-index}, but search from the right of the string rather @deffn primitive string-fill! str chr
than from the left. This procedure essentially implements the Stores @var{char} in every element of the given @var{string} and returns an
@code{rindex} or @code{strrchr} functions from the C library. unspecified value. (r5rs)
@end deffn
(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance @c ARGFIXME fill/fill-char
of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to @c docstring begin (texi-doc-string "guile" "substring-fill!")
the entire string. @deffn primitive substring-fill! str start end fill
Change every character in @var{str} between @var{start} and @var{end} to
@var{fill-char}.
(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.
@example @example
(string-rindex "weiner" #\e) (define y "abcdefg")
@result{} 4 (substring-fill! y 1 3 #\r)
y
(string-rindex "weiner" #\e 2 4) @result{} "arrdefg"
@result{} #f
(string-rindex "weiner" #\e 2 5)
@result{} 4
@end example @end example
@end deffn @end deffn
@ -1603,102 +1658,14 @@ y
@end example @end example
@end deftypefn @end deftypefn
@c docstring begin (texi-doc-string "guile" "vector-move-left!")
@deffn primitive vector-move-left! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-left!}.
@end deffn
@c docstring begin (texi-doc-string "guile" "vector-move-right!") @node String Comparison
@deffn primitive vector-move-right! vec1 start1 end1 vec2 start2 @subsection String Comparison
Vector version of @code{substring-move-right!}.
@end deffn
@c ARGFIXME fill/fill-char The procedures in this section are similar to the character ordering
@c docstring begin (texi-doc-string "guile" "substring-fill!") predicates (REFFIXME), but are defined on character sequences. They all
@deffn primitive substring-fill! str start end fill return @code{#t} on success and @code{#f} on failure. The predicates
Change every character in @var{str} between @var{start} and @var{end} to ending in @code{-ci} ignore the character case when comparing strings.
@var{fill-char}.
(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.
@example
(define y "abcdefg")
(substring-fill! y 1 3 #\r)
y
@result{} "arrdefg"
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-null?")
@deffn primitive string-null? str
Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}
otherwise.
(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}.
@example
(string-null? "")
@result{} #t
(string-null? y)
@result{} #f
@end example
@end deffn
@c ARGFIXME v/str
@c docstring begin (texi-doc-string "guile" "string-upcase!")
@deffn primitive string-upcase! str
Destructively upcase every character in @code{str}.
(qdocs:) Converts each element in @var{str} to upper case.
@example
(string-upcase! y)
@result{} "ARRDEFG"
y
@result{} "ARRDEFG"
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-upcase")
@deffn primitive string-upcase str
Upcase every character in @code{str}.
@end deffn
@c ARGFIXME v/str
@c docstring begin (texi-doc-string "guile" "string-downcase!")
@deffn primitive string-downcase! str
Destructively downcase every character in @code{str}.
(qdocs:) Converts each element in @var{str} to lower case.
@example
y
@result{} "ARRDEFG"
(string-downcase! y)
@result{} "arrdefg"
y
@result{} "arrdefg"
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-downcase")
@deffn primitive string-downcase str
Downcase every character in @code{str}.
@end deffn
@c docstring begin (texi-doc-string "guile" "string-capitalize!")
@deffn primitive string-capitalize! str
Destructively capitalize every character in @code{str}.
@end deffn
@c docstring begin (texi-doc-string "guile" "string-capitalize")
@deffn primitive string-capitalize str
Capitalize every character in @code{str}.
@end deffn
@r5index string<=? @r5index string<=?
@c docstring begin (texi-doc-string "guile" "string-ci<=?") @c docstring begin (texi-doc-string "guile" "string-ci<=?")
@ -1785,15 +1752,150 @@ Lexicographic ordering predicate; returns @code{#t} if
@var{s1} is lexicographically greater than @var{s2}. (r5rs) @var{s1} is lexicographically greater than @var{s2}. (r5rs)
@end deffn @end deffn
@r5index string->list @node String Searching
@c docstring begin (texi-doc-string "guile" "string->list") @subsection String Searching
@deffn primitive string->list str
@samp{String->list} returns a newly allocated list of the When searching the index of a character in a string, these procedures
characters that make up the given string. @samp{List->string} can be used.
returns a newly allocated string formed from the characters in the list
@var{list}, which must be a list of characters. @samp{String->list} @c docstring begin (texi-doc-string "guile" "string-index")
and @samp{list->string} are @deffn primitive string-index str chr [frm [to]]
inverses so far as @samp{equal?} is concerned. (r5rs) Return the index of the first occurrence of @var{chr} in @var{str}. The
optional integer arguments @var{frm} and @var{to} limit the search to
a portion of the string. This procedure essentially implements the
@code{index} or @code{strchr} functions from the C library.
(qdocs:) Returns the index of @var{char} in @var{str}, or @code{#f} if the
@var{char} isn't in @var{str}. If @var{frm} is given and not @code{#f},
it is used as the starting index; if @var{to} is given and not @code{#f},
it is used as the ending index (exclusive).
@example
(string-index "weiner" #\e)
@result{} 1
(string-index "weiner" #\e 2)
@result{} 4
(string-index "weiner" #\e 2 4)
@result{} #f
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-rindex")
@deffn primitive string-rindex str chr [frm [to]]
Like @code{string-index}, but search from the right of the string rather
than from the left. This procedure essentially implements the
@code{rindex} or @code{strrchr} functions from the C library.
(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance
of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to
the entire string.
@example
(string-rindex "weiner" #\e)
@result{} 4
(string-rindex "weiner" #\e 2 4)
@result{} #f
(string-rindex "weiner" #\e 2 5)
@result{} 4
@end example
@end deffn
@node Alphabetic Case Mapping
@subsection Alphabetic Case Mapping
These are procedures for mapping strings to their upper-- or lower--case
equivalents, respectively, or for capitalizing strings.
@c ARGFIXME v/str
@c docstring begin (texi-doc-string "guile" "string-upcase!")
@deffn primitive string-upcase! str
Destructively upcase every character in @code{str}.
(qdocs:) Converts each element in @var{str} to upper case.
@example
(string-upcase! y)
@result{} "ARRDEFG"
y
@result{} "ARRDEFG"
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-upcase")
@deffn primitive string-upcase str
Upcase every character in @code{str}.
@end deffn
@c ARGFIXME v/str
@c docstring begin (texi-doc-string "guile" "string-downcase!")
@deffn primitive string-downcase! str
Destructively downcase every character in @code{str}.
(qdocs:) Converts each element in @var{str} to lower case.
@example
y
@result{} "ARRDEFG"
(string-downcase! y)
@result{} "arrdefg"
y
@result{} "arrdefg"
@end example
@end deffn
@c docstring begin (texi-doc-string "guile" "string-downcase")
@deffn primitive string-downcase str
Downcase every character in @code{str}.
@end deffn
@c docstring begin (texi-doc-string "guile" "string-capitalize!")
@deffn primitive string-capitalize! str
Destructively capitalize every character in @code{str}.
@end deffn
@c docstring begin (texi-doc-string "guile" "string-capitalize")
@deffn primitive string-capitalize str
Capitalize every character in @code{str}.
@end deffn
@node Appending Strings
@subsection Appending Strings
The procedure @code{string-append} appends several strings together to
form a longer result string.
@r5index string-append
@c docstring begin (texi-doc-string "guile" "string-append")
@deffn primitive string-append . args
Return a newly allocated string whose characters form the
concatenation of the given strings, @var{args}.
@end deffn
@node String Miscellanea
@subsection String Miscellanea
This section contains several remaining string procedures.
@c FIXME::martin: Should go into vector section.
@c docstring begin (texi-doc-string "guile" "vector-move-left!")
@deffn primitive vector-move-left! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-left!}.
@end deffn
@c FIXME::martin: Should go into vector section.
@c docstring begin (texi-doc-string "guile" "vector-move-right!")
@deffn primitive vector-move-right! vec1 start1 end1 vec2 start2
Vector version of @code{substring-move-right!}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "string-ci->symbol") @c docstring begin (texi-doc-string "guile" "string-ci->symbol")
@ -1801,23 +1903,15 @@ inverses so far as @samp{equal?} is concerned. (r5rs)
Return the symbol whose name is @var{str}, downcased in necessary(???). Return the symbol whose name is @var{str}, downcased in necessary(???).
@end deffn @end deffn
@r5index string-copy
@c docstring begin (texi-doc-string "guile" "string-copy")
@deffn primitive string-copy str
Returns a newly allocated copy of the given @var{string}. (r5rs)
@end deffn
@r5index string-fill!
@c docstring begin (texi-doc-string "guile" "string-fill!")
@deffn primitive string-fill! str chr
Stores @var{char} in every element of the given @var{string} and returns an
unspecified value. (r5rs)
@end deffn
@node Shared Substrings @node Shared Substrings
@subsection Shared Substrings @subsection Shared Substrings
[FIXME: this is pasted in from Tom Lord's original guile.texi and should
be reviewed]
@c FIXME::martin: Shared substrings are gone, so this section should die.
Whenever you extract a substring using @code{substring}, the Scheme Whenever you extract a substring using @code{substring}, the Scheme
interpreter allocates a new string and copies data from the old string. interpreter allocates a new string and copies data from the old string.
This is expensive, but @code{substring} is so convenient for This is expensive, but @code{substring} is so convenient for
@ -1891,6 +1985,9 @@ expect to change the contents of any of the strings involved.
@node Read Only Strings @node Read Only Strings
@subsection Read Only Strings @subsection Read Only Strings
@c FIXME::martin: Read-only strings are gone, too, so this section should
@c also die.
Type-checking in Guile primitives distinguishes between mutable strings Type-checking in Guile primitives distinguishes between mutable strings
and read only strings. Mutable strings answer @code{#t} to and read only strings. Mutable strings answer @code{#t} to
@code{string?} while read only strings may or may not. All kinds of @code{string?} while read only strings may or may not. All kinds of
@ -2642,10 +2739,10 @@ syntax extension to permit keywords to begin with @code{:} as well as
@code{#:}. @code{#:}.
@menu @menu
* Why Use Keywords?:: * Why Use Keywords?::
* Coding With Keywords:: * Coding With Keywords::
* Keyword Read Syntax:: * Keyword Read Syntax::
* Keyword Primitives:: * Keyword Primitives::
@end menu @end menu
@node Why Use Keywords? @node Why Use Keywords?
@ -3590,10 +3687,10 @@ Return the vtable tag of the structure @var{handle}.
@section Arrays @section Arrays
@menu @menu
* Conventional Arrays:: Arrays with arbitrary data. * Conventional Arrays:: Arrays with arbitrary data.
* Array Mapping:: Applying a procedure to the contents of an array. * Array Mapping:: Applying a procedure to the contents of an array.
* Uniform Arrays:: Arrays with data of a single type. * Uniform Arrays:: Arrays with data of a single type.
* Bit Vectors:: Vectors of bits. * Bit Vectors:: Vectors of bits.
@end menu @end menu
@node Conventional Arrays @node Conventional Arrays
@ -4076,8 +4173,8 @@ useful for organizing and indexing large bodies of information.
@menu @menu
* Dictionary Types:: About dictionary types; what they're good for. * Dictionary Types:: About dictionary types; what they're good for.
* Association Lists:: * Association Lists::
* Hash Tables:: * Hash Tables::
@end menu @end menu
@node Dictionary Types @node Dictionary Types
@ -4148,12 +4245,12 @@ because association lists are so useful, Guile also provides specific
procedures for manipulating them. procedures for manipulating them.
@menu @menu
* Alist Key Equality:: * Alist Key Equality::
* Adding or Setting Alist Entries:: * Adding or Setting Alist Entries::
* Retrieving Alist Entries:: * Retrieving Alist Entries::
* Removing Alist Entries:: * Removing Alist Entries::
* Sloppy Alist Functions:: * Sloppy Alist Functions::
* Alist Example:: * Alist Example::
@end menu @end menu
@node Alist Key Equality @node Alist Key Equality