This is a library for manipulating textual content based on character spans, also known as just spans. These are conceptually references to a part of a string delimited using two string cursors, which are references to the characters of a string. It is not defined whether the character span type is disjoint from strings. Character spans are immutable, and except as noted below, it is an error to mutate the string(s) that underly a span.
With the exception of the constructors, all the procedures in this proposal exist in pairs: one that accepts and produces character spans and one that accepts and produces strings. Only the character span version is documented in full; the string version should be understood as accepting the same non-span arguments, performing the same operations, and providing the same non-span results.
All predicates passed to procedures defined in this proposal may be called in any order and any number of times, except as otherwise noted.
String cursors are pointers into strings or spans, and are not necessarily disjoint from other Scheme types. For example, they may be exact integers that are character-based indexes into strings. Alternatively, in an implementation whose internal representation of strings is UTF-8, string cursors may be indexes of individual bytes in the string. It is also possible to implement string cursors as objects of a disjoint type. The string-cursor procedures of this proposal are mostly taken from Chibi Scheme.
Given a span of length n, there are n+2 possible cursors that refer to it: one for each character in the span, one for the position just before the first character, and one for the position just after the last character. These additional positions are provided for backward and forward iteration respectively, and also because when creating a span from cursors the second cursor argument is exclusive.
Most of the character span procedures in this proposal also have string equivalents. In order to make the specification more concise, the string procedures are listed but don't have detailed explanations, except for the constructors. Procedures with the same names and basic functions as SRFI 13 procedures are marked [SRFI 13]. However, this proposal contains only a subset of SRFI 13. In particular, the string procedures of this proposal do not accept start and end arguments, as their function is subsumed by spans, nor is SRFI 13's separation between sharable and non-sharable results supported. In addition, the SRFI 13 low-level procedures and macros are not provided, nor are there any mutators.
The operations provided here (with the exception of those in the Compatibility section) are entirely independent of the character repertoire supported by the implementation. In particular, this means that the case-insensitive procedures of SRFI 13 are excluded.
All the R7RS-small string procedures are included here, with the exception of the string mutators string-set!, string-copy!, and string-fill!. They are marked [R7RS-small], and are not exported by implementations of this proposal. They are included only for clarity and completeness.
(make-span string [start end ] ])
Returns a character span which contains the characters of string in order from indexes start (inclusive) to end (exclusive). The default values of start and end are 0 and the length of string respectively.
(span char ...)
Returns a character span which contains the characters char in order.
(string->span string)
Returns a character span which contains the characters of string in order. Later mutation of string will not affect the value of span.
(span-transform proc span obj ...)
Proc is a procedure which accepts a string as its first argument and returns a string. It is invoked on a string which contains the characters of span in order plus the obj arguments, if any. The resulting string is returned as a character span by span-transform. This procedure allows string-based procedures to be easily used in an environment that provides and expects spans.
(make-string k [ char ]) [R7RS-small]
Returns a string containing k characters, all of which are char. If char is omitted, the contents of the string are implementation-dependent.
(string char ...) [R7RS-small]
Returns a string consisting of the char arguments.
(string-unfold stop? mapper successor [ seed ])
(string-unfold-right stop? mapper successor [ seed ])
Returns a newly allocated string, whose characters are generated in forward/reverse order using the following algorithm: If the result of applying the predicate stop? to seed is true, the string is complete and is returned. Otherwise, apply the procedure mapper to seed. The value that mapper returns becomes the next character of the string. Then a new seed is obtained by applying the procedure successor to seed, and this algorithm is repeated.
(span->string span)
Returns a newly allocated string which contains the characters of span in order.
(string-tabulate len proc)
Invokes proc for all exact integers between 0 (inclusive) and len (exclusive), and returns a newly allocated string containing the characters returned by the invocations.
Compatibility note: The argument order here agrees with the list-tabulate procedure of SRFI 1 rather than SRFI 13's string-tabulate procedure. The discrepancy was unintentional, but was discovered too late to fix.
(span? obj)
(string? obj) [R7RS-small]
Returns #t if obj is a character span, and #f otherwise.
(span-null? span)
(string-null? string) [SRFI 13]
Returns #t if span contains zero characters, and #f otherwise.
(span-every pred span)
(string-every pred string) [SRFI 13]
Returns #t if pred returns true for every character in span, and #f otherwise.
(span-any pred span)
(string-any pred string) [SRFI 13]
Returns #f if pred returns false for each character in span, and #t otherwise.
(is-char? char)
Returns a predicate which accepts one argument. This predicate returns #t if the argument is the same as char (in the sense of char=?) and #f otherwise.
(in-char-set? char-set)
Returns a predicate which accepts one argument. This predicate returns #t if the argument is an element of char-set, a SRFI 14 character set, and #f otherwise.
(span-ref span k)
(string-ref string k) [R7RS-small]
Returns the kth character of span, starting with 0. It is an error if k is not a non-negative exact integer less than the length of span.
(span-take span n)
(string-take string n) [SRFI 13]
Returns a character span which contains the first n characters of span.
(span-take-right span n)
(string-take-right string n) [SRFI 13]
Returns a character span which contains the last n characters of span.
(span-drop span n)
(string-drop string n) [SRFI 13]
Returns a character span which contains all but the first n characters of span.
(span-drop-right span n)
(string-drop-right string n) [SRFI 13]
Returns a character span which contains all but the last n characters of span.
(span-split-at span n)
(string-split-at string n) [SRFI 13]
Returns two values, a character span containing the first n characters of span, and another character span containing the remaining characters of span.
(span-replicate span from to)
(string-replicate string from to)
Span is conceptually replicated an infinite number of times to both left and right, and this doubly infinite sequence is then truncated to form a span starting at index from (inclusive) and ending at index to (exclusive). Negative indexes are allowed in order to access the infinite left extension.
(string-replicate "abcdef" 2 7) => "cdefab" ; rotate left (string-replicate "abcdef" -2 4) => "efabcd" ; rotate right (string-replicate "abc" 0 7) => "abcabca" ; replicateThis procedure is the same as the SRFI 13 procedure xsubstring, except that the to argument is required.
(subspan span start end)
(substring string start end) [R7RS-small]
(subspan/cursors span start end)
(substring/cursors string start end)
Returns a character span which contains the characters in span between the indexes/cursors start (inclusive) and end (exclusive).
(span-pad span len [ char ])
(string-pad string len [ char ]) [SRFI 13]
(span-pad-right span len [ char ])
(string-pad-right string len [ char ]) [SRFI 13]
Returns a span of length len consisting of span padded on the left (right) by as many occurrences of the character char as needed. If span has more than len characters, it is truncated on the left (right) to length len. If char is omitted, #\space is used.
(span-trim span [ pred'' ])
(string-trim string [ pred'' ]) [SRFI 13]
(span-trim-right span [ pred ][ char'' ])
(string-trim-right string [ pred'' ]) [SRFI 13]
(span-trim-both span [ pred'' ])
(string-trim-both string [ pred'' ]) [SRFI 13]
Trim span by skipping over all characters on the left / on the right / on both sides that satisfy pred and returning the resulting span.
(span-compress span [ char ])
(string-compress string [ char ])
Return a span which differs from span in that every sequence of consecutive occurrences of char has been replaced by a single char. If char is omitted, #\space is used.
(span-prefix span1 span2)
(string-prefix string1 string2)
(span-suffix span1 span2)
(string-suffix string1 string2)
Returns a span containing the characters in the common prefix/suffix of span1 and span2. If there is no common prefix/suffix, returns an empty span.
(span-prefix-length span1 span2)
(string-prefix-length string1 string2) [SRFI 13]
(span-suffix-length span1 span2)
(string-suffix-length string1 string2) [SRFI 13]
Returns the length (in characters) of the span that would be returned by span-prefix and friends.
(span-mismatch span1 span2)
(string-mismatch string1 string2)
Returns a cursor referring to the first character in span2 that is not equal to the corresponding character in span1. If the spans are equal, the cursor referring to the position after the last character in span2 is returned.
(span-mismatch-right span1 span2)
(string-mismatch-right string1 string2)
Returns a cursor referring to the first character in span2, scanning in reverse order, that is not equal to the corresponding character in span1, also processed in reverse order. If the spans are equal, the cursor referring to the position before the first character in span2 is returned.
(span-prefix? span1 span2)
(string-prefix? string1 string2) [SRFI 13]
(span-suffix? span1 span2)
(string-suffix? string1 string2) [SRFI 13]
Returns #t if span1 is a prefix/suffix of span2, and #f otherwise.
(span-count pred span)
(string-count pred string) [SRFI 13]
Returns an exact integer, the number of characters in span which satisfy pred.
(span-find pred span)
(string-find pred string)
(span-find-right pred span)
(string-find-right pred string)
Returns a cursor pointing to the first/last character in span that satisfies pred, or the end/start cursor if there is none.
Compatibility note: These procedures are analogous to SRFI 13's string-index procedures, but return cursors rather than indexes or #f on failure.
(span-bypass pred span)
(string-bypass pred string)
(span-bypass-right pred span)
(string-bypass-right pred string)
Returns a cursor pointing to the first/last character in span that does not satisfy pred, or the end/start cursor if there is none.
Compatibility note: These procedures are analogous to SRFI 13's string-skip procedures, but return cursors rather than indexes or #f on failure.
(span-take-while pred span)
(string-take-while pred string)
Returns the longest initial prefix of span whose characters all satisfy pred.
(span-drop-while pred span)
(string-drop-while pred string)
Drops the longest initial prefix of span whose characters all satisfy pred, and returns the rest of span.
(span-span pred span)
(string-span pred string) [SRFI 13]
(span-break pred span)
(string-break pred string) [SRFI 13]
The span-span procedure splits span, returning two values: the longest initial prefix whose characters all satisfy pred, and the remainder of span. The span-break procedure inverts the sense of the predicate: the remainder commences with the first character of span that satisfies pred. In other words: span-span finds the intial span of characters satisfying pred, and span-break breaks span at the first character satisfying pred. The name "span-span" is unfortunate but unavoidable.
(span-contains haystack needle)
(string-contains string1 string2) [SRFI 13]
It is an error if needle and haystack are not both spans. Returns a cursor referring to haystack indicating the first position in which the characters of needle appear. If there is no such position, #f is returned.
For compatibility with SRFI 13, string-contains returns an index rather than a cursor.
(span-length span)
(string-length string) [R7RS-small]
Returns the number of characters in span.
(span-reverse span)
(string-reverse span) [SRFI 13]
Returns a span containing the characters of span in reverse order.
(span-append span ...)
(string-append string ...) [R7RS-small]
Returns a span containing the characters of the spans in order.
(span-concatenate list)
(string-concatenate list) [SRFI 13]
Returns a span containing the characters of the spans and/or strings enumerated in list in order. This procedure will succeed even if (apply string-append list-of-strings) fails due to an implementation limit on the number of arguments a procedure may receive. For convenience, the elements of list may be spans or strings or both.
(span-concatenate-reverse list)
(string-concatenate-reverse list [ end ]) [SRFI 13]
The same as span-concatenate, except that list is processed in reverse order. Note that the individual spans and strings are not processed in reverse order.
This procedure is useful in the construction of procedures that accumulate character data into lists of string buffers, and wish to convert the accumulated data into a single string when done.
(span-map proc span ...)
(string-map proc string ...) [R7RS-small]
It is an error if proc does not accept as many arguments as there are spans and return a single character.
Applies proc element-wise to the elements of the spans and returns a span of the results, in order. If more than one span is given and not all spans have the same length, span-map terminates when the shortest span runs out. The dynamic order in which proc is applied to the elements of the spans is unspecified. If multiple returns occur from span-map, the values returned by earlier returns are not mutated.
(span-for-each proc span ...)
(string-for-each proc string ...) [R7RS-small]
It is an error if proc does not accept as many arguments as there are strings.
The arguments to span-for-each are like the arguments to span-map, but it calls proc for its side effects rather than for its values. Unlike span-map, span-for-each is guaranteed to call proc on the elements of the lists in order from the first character(s) to the last, and the value returned by string-for-each is unspecified. If more than one span is given and not all spans have the same length, span-for-each terminates when the shortest string runs out.
(span-fold proc nil span)
(string-fold proc nil string) [SRFI 13]
(span-fold-right proc nil span)
(string-fold-right proc nil string) [SRFI 13]
Invokes proc on each member of span in forward/reverse order, passing the result of the previous invocation as a second argument. For the first invocation, nil is used as the second argument. Returns the result of the last invocation, or nil if there was no invocation.
(span-split span [sep [ limit'' ] ])
(span-split span [sep [ limit'' ] ])
Returns a list of the words contained in span. If sep (which is also a character span) is omitted, then the words are separated by one or more whitespace characters (those on which char-whitespace? returns #t). If sep is supplied, it specifies a string to be used as the word separator. The returned list will then have one more item than the number of non-overlapping occurrences of the separator in the string. If sep is an empty span, then the returned list contains a list of the characters in span.
If limit is provided, at most that many splits occur, and the remainder of span is returned as the final element of the list (thus, the result will have at most limit + 1 elements). If limit is not specified, then as many splits as possible are made. It is an error if limit is not a positive exact integer.
(span-join list [ delim [ grammar ] ])
(string-join list [ delim [ grammar ] ])
This procedure pastes the elements of list together using delimiter, which is a span. For convenience, list elements are allowed to be strings or spans or both. If delimiter is omitted, it is a single space. The grammar argument is a symbol that determines how the delimiter is used, and defaults to infix. The following values are understood:
(span-filter pred span) [SRFI 13]
(string-filter pred string)
Returns a span containing the characters of span which satisfy proc.
(span-remove pred span)
(string-remove pred string)
Returns a span containing the characters of span which do not satisfy proc.
Compatibility note: The SRFI 13 variant of this procedure is called string-delete, which is inconsistent with the conventions of SRFI 1 and other SRFIs.
(span-partition pred span)
(string-partition pred string)
Returns two values, a span containing the characters of span which satisfy proc and another span containing those which do not.
(span-copy span)
(string-copy string [ start [ end ] ]) [R7RS-small]
Makes a copy of span such that any future mutation of any string underlying span does not affect the characters of span.
(span->list span)
(string->list string [ start [ end ] ]) [R7RS-small]
(span->vector span)
(string->vector string[ start [ end ] ]) [R7RS-small]
Returns a newly allocated list/vector containing the characters of span in order. The start and end arguments are for compatibility with R7RS-small.
(list->string list) [R7RS-small]
(vector->string vector[ start [ end ] ]) [R7RS-small]
Returns a newly allocated string whose characters are the elements of list/vector in order. It is an error if the elements are not characters. The start and end arguments are for compatibility with R7RS-small.
(reverse-list->string list) [SRFI 13]
Returns a newly allocated string whose characters are the elements of list in reverse order. It is an error if the elements are not characters.
(span-cursor-start span)
(string-cursor-start string)
Returns a cursor referring to the first character in span.
(span-cursor-end span)
(string-cursor-end string)
Returns a cursor referring to the position following the last character in span.
(span-cursor-ref span cursor)
(string-cursor-ref string cursor)
Returns the character referred to by cursor. It is an error if cursor does not refer to a character in span.
(span-cursor-next span cursor)
(string-cursor-next string cursor)
Returns the cursor following cursor. It is an error if cursor does not refer to a character in span.
(span-cursor-prev span cursor)
(string-cursor-prev string cursor)
Returns the cursor following cursor. It is an error if cursor does not refer either to a character in span or the position following the last character in span.
(span-cursor-forward span cursor n)
(string-cursor-forward string cursor n)
(span-cursor-backward span cursor n)
(string-cursor-backward string cursor n)
Iterates span-cursor-next or span-cursor-prev n times.
(span-cursor-forward-until span cursor n)
(string-cursor-forward-until string cursor n)
Iterates span-cursor-next until it refers to a character that satisfies pred or the position following the last character of span is reached, and returns that cursor.
(span-cursor-backward-until span cursor n)
(string-cursor-backward-until string cursor n)
Iterates span-cursor-prev until it refers to a character that satisfies pred or the position preceding the first character of span is reached, and returns that cursor.
(span-cursor=? span cursor1 cursor2)
(string-cursor=? string cursor1 cursor2)
(span-cursor<? span cursor1 cursor2)
(string-cursor<? string cursor1 cursor2)
(span-cursor>? span cursor1 cursor2)
(string-cursor>? string cursor1 cursor2)
(span-cursor<=? span cursor1 cursor2)
(string-cursor<=? string cursor1 cursor2)
(span-cursor>=? span cursor1 cursor2)
(string-cursor>=? string cursor1 cursor2)
Compare cursor1 and cursor2. It is an error if the cursors do not refer to positions in span.
(span-cursor->index span cursor)
(string-cursor->index string cursor)
Return the character index into span corresponding to cursor. It is an error if cursor does not refer to a position in span.
(span-index->cursor span index)
(string-index->cursor string index)
Return the cursor referring to span that corresponds to cursor. It is an error if index is less than zero or greater than the length of span.
(span-cursor-difference span cursor1 cursor2)
(string-cursor-difference string cursor1 cursor2)
Return the difference in characters between cursor2 and cursor1. It is an error if the cursors do not refer to positions in span.
(write-string-tree obj [ port ])
It is an error if port is not a textual output port. If port is omitted, the value of (current-output-port) is used.
If obj is a string or character span, its characters are output to port. If obj is a character, it is output to port. If obj is a number, it is converted to a string as if by number->string and the characters of the string are output to port. If obj is a pair or vector, its components are processed recursively by write-string-tree. Otherwise, write-string-tree does nothing.
(tree->span obj)
(tree->string obj)
Behaves as if write-string-tree were applied to obj and a newly allocated string output port. When obj has been completely output, the port's string is returned as a span or a string.
(span-upcase span)
(string-upcase span) [R7RS-small]
(span-downcase span)
(string-downcase span) [R7RS-small]
(span-foldcase span)
(string-foldcase span) [R7RS-small]
For the behavior of the string procedures, see R7RS-small. In any implementation of this proposal based on R7RS, the span procedures must behave analogously to the string procedures. That is, if a call to string procedure x on a string containing characters y0 ... yn produces a string containing characters z0 ... zn, then a call to the analogous span procedure x′ on a span containing characters y0 ... yn must produce a span containing characters ''z0 ... z,,n,,'.
(span=? span1 span2 span ...)
(string=? span1 span2 span ...) [R7RS-small]
(span<? span1 span2 span ...)
(string<? span1 span2 span ...) [R7RS-small]
(span>? span1 span2 span ...)
(string>? span1 span2 span ...) [R7RS-small]
(span<=? span1 span2 span ...)
(string<=? span1 span2 span ...) [R7RS-small]
(span>=? span1 span2 span ...)
(string>=? span1 span2 span ...) [R7RS-small]
(span-ci=? span1 span2 span ...)
(string-ci=? span1 span2 span ...) [R7RS-small]
(span-ci<? span1 span2 span ...)
(string-ci<? span1 span2 span ...) [R7RS-small]
(span-ci>? span1 span2 span ...)
(string-ci>? span1 span2 span ...) [R7RS-small]
(span-ci<=? span1 span2 span ...)
(string-ci<=? span1 span2 span ...) [R7RS-small]
(span-ci>=? span1 span2 span ...)
(string-ci>=? span1 span2 span ...) [R7RS-small]
For the behavior of the string procedures, see R7RS-small. In any implementation of this proposal based on R7RS, the span procedures must behave analogously to the string procedures.
(span-titlecase ''span'')`
(string-titlecase span)[SRFI 13]
For every character c in span: if c is preceded by a character with case, it is downcased; otherwise it is replaced by its titlecase equivalent, if any. Other characters are unchanged. Note that most lowercase characters have the same character as both uppercase and titlecase equivalents.
(string-titlecase "--capitalize tHIS sentence.") => "--Capitalize This Sentence." (string-titlecase "see Spot run. see Nix run.") => "See Spot Run. See Nix Run." (string-titlecase "3com makes routers.") => "3Com Makes Routers."span-comparator
This is a SRFI 114 comparator for comparing strings. Its procedures behave as if their arguments are converted to strings and then passed to the procedures of string-comparator.