diff options
Diffstat (limited to 'doc/scheme-data.texi')
-rwxr-xr-x | doc/scheme-data.texi | 118 |
1 files changed, 0 insertions, 118 deletions
diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi index d317ba5a7..cd982ab34 100755 --- a/doc/scheme-data.texi +++ b/doc/scheme-data.texi @@ -1346,8 +1346,6 @@ called with string containing unusal characters. * 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. -* Read Only Strings:: Treating certain non-strings as strings. @end menu @node String Syntax @@ -1772,122 +1770,6 @@ is currently reading symbols case--insensitively. @end deffn -@node 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 -interpreter allocates a new string and copies data from the old string. -This is expensive, but @code{substring} is so convenient for -manipulating text that programmers use it often. - -Guile Scheme provides the concept of the @dfn{shared substring} to -improve performance of many substring-related operations. A shared -substring is an object that mostly behaves just like an ordinary -substring, except that it actually shares storage space with its parent -string. - -@deffn primitive make-shared-substring str [start [end]] -Return a shared substring of @var{str}. The semantics are the -same as for the @code{substring} function: the shared substring -returned includes all of the text from @var{str} between -indexes @var{start} (inclusive) and @var{end} (exclusive). If -@var{end} is omitted, it defaults to the end of @var{str}. The -shared substring returned by @code{make-shared-substring} -occupies the same storage space as @var{str}. -@end deffn - -Example: - -@example -(define foo "the quick brown fox") -(define bar (make-shared-substring some-string 4 9)) - -foo => "t h e q u i c k b r o w n f o x" -bar =========> |---------| -@end example - -The shared substring @var{bar} is not given its own storage space. -Instead, the Guile interpreter notes internally that @var{bar} points to -a portion of the memory allocated to @var{foo}. However, @var{bar} -behaves like an ordinary string in most respects: it may be used with -string primitives like @code{string-length}, @code{string-ref}, -@code{string=?}. Guile makes the necessary translation between indices -of @var{bar} and indices of @var{foo} automatically. - -@example -(string-length? bar) @result{} 5 ; bar only extends from indices 4 to 9 -(string-ref bar 3) @result{} #\c ; same as (string-ref foo 7) -(make-shared-substring bar 2) - @result{} "ick" ; can even make a shared substring! -@end example - -Because creating a shared substring does not require allocating new -storage from the heap, it is a very fast operation. However, because it -shares memory with its parent string, a change to the contents of the -parent string will implicitly change the contents of its shared -substrings. - -@example -(string-set! foo 7 #\r) -bar @result{} "quirk" -@end example - -Guile considers shared substrings to be immutable. This is because -programmers might not always be aware that a given string is really a -shared substring, and might innocently try to mutate it without -realizing that the change would affect its parent string. (We are -currently considering a "copy-on-write" strategy that would permit -modifying shared substrings without affecting the parent string.) - -In general, shared substrings are useful in circumstances where it is -important to divide a string into smaller portions, but you do not -expect to change the contents of any of the strings involved. - -@node 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 -and read only strings. Mutable strings answer @code{#t} to -@code{string?} while read only strings may or may not. All kinds of -strings, whether or not they are mutable return #t to this: - -@deffn primitive read-only-string? obj -Return true if @var{obj} can be read as a string, - -This illustrates the difference between @code{string?} and -@code{read-only-string?}: - -@lisp -(string? "a string") @result{} #t -(string? 'a-symbol) @result{} #f - -(read-only-string? "a string") @result{} #t -(read-only-string? 'a-symbol) @result{} #t -@end lisp -@end deffn - -"Read-only" refers to how the string will be used, not how the string is -permitted to be used. In particular, all strings are "read-only -strings" even if they are mutable, because a function that only reads -from a string can certainly operate on even a mutable string. - -Symbols are an example of read-only strings. Many string functions, -such as @code{string-append} are happy to operate on symbols. Many -functions that expect a string argument, such as @code{open-file}, will -accept a symbol as well. - -Shared substrings, discussed in the previous chapter, also happen to be -read-only strings. - - @node Regular Expressions @section Regular Expressions |