11.28 srfi.130 - Cursor-based string library

Module: srfi.130 ¶

This is an reduced version of srfi.13 that supports cursors in addition to indexes. The consistency with R7RS and recent srfis are also considered.

Gauche supports string cursors natively (see String cursors), so all built-in and SRFI-13 string procedures that takes string indexes can als otake string cursors as well. You want to use this module explicitly, though, if you’re writing a portable code.

The following are built-in. See String cursors, for the details.

string-cursor?        string-cursor-start    string-cursor-end
string-cursor-next    strig-cursor-prev      string-cursor-forward
string-cursor-back    string-cursor=?        string-cursor<?
string-cursor<=?      string-cursor>?        string-cursor>=?
string-cursor-diff    string-cursor->index   string-index->cursor

The following procedures are simply aliases of the builtin version without the /cursor or /cursors suffix.

string->list/cursors  string->vector/cursors string-copy/cursors
string-ref/cursor     substring/cursors

The following procedures are defined in SRFI-13. See srfi.13 - String library, for the details. Note: Some of those procedures in SRFI-13 accept only indexes. In SRFI-130, both indexes and cursors are accepted. Our SRFI-13 implementation shares the same procedure with SRFI-130, so they accept both indexes and cursors but such code won’t be portable as SRFI-13.

string-null?       string-any         string-every       string-tabulate
string-unfold      string-unfold-right                   reverse-list->string
string-take        string-drop        string-take-right  string-drop-right
string-pad         string-pad-right   string-trim        string-trim-right
string-trim-both   string-replace     string-prefix-length
string-suffix-length                  string-prefix?     string-suffix
string-concatenate string-concatenate-reverse            string-count
string-filter      string-reverse

The following procedures are the same as SRFI-152, except that the arguments that takes integer indexes can also accept string cursors (see srfi.152 - String library (reduced)):

string-replicate   string-remove      string-split

The following procedures are also defined in SRFI-13, but SRFI-130 redefines them to return a string cursor instead of an integer index. They are described below.

string-index        string-index-right
string-skip         string-skip-right
string-contains     string-contains-right

Function: string-index string pred :optional start end ¶

Function: string-index-right string pred :optional start end ¶

Function: string-skip string pred :optional start end ¶

Function: string-skip-right string pred :optional start end ¶

[SRFI-130]{srfi.130} Find the position of a character that satisfies pred (string-index/string-index-right), or does not satisfy pred (string-skip/string-skip-right), in a string. The chacter is searched from left to right in string-index/string-skip, and right to left in string-index-right/string-skip-right.

While SRFI-13’s procedures of the same names returns integer index, these returns a string cursor instead.

The returned cursor from string-index/string-skip points the leftmost character that satisfies/does not satsify pred, while the returned cursor from string-index-right points the next (right) character of the rightmost one that satisfies/does not satisfy pred. If there’re no characters that satisfy pred, string-index returns a cursor at the end of the string, while string-index-right returns a cursor at the beginning of the string. (The *-skip variation reverses the condition).

(This is easier to understand if you think the cursor is between characters; if we scan a string from left to right, the cursor looks at the character on its right; if we scan from right to left, the cursor looks at the character on its left.)

Be aware that they still return a cursor even no characters satisfy the condition, while SRFI-13 versions return #f in such cases.

The optional start/end can be string cursors or integer indexes to limit the region of string to search.

(define *s* "abc def ghi")

(string-cursor->index *s* (string-index *s* char-whitespace?))
  ⇒ 3

(string-cursor->index *s* (string-index *s* char-whitespace? 4))
  ⇒ 7

(string-cursor->index *s* (string-index-right *s* char-whitespace?))
  ⇒ 8

(string-cursor->index *s* (string-index-right *s* char-whitespace? 0 7))
  ⇒ 4

Function: string-contains haystack needle :optional start1 end1 start2 end2 ¶

Function: string-contains-right haystack needle :optional start1 end1 start2 end2 ¶

[SRFI-130]{srfi.130} Search for a substring needle in a string haystack. The substring is searched from left to right (string-contains) or right to left (string-contains-right).

While SRFI-13’s procedures of the same names returns an integer index of the beginning of the substring if found, these procedures returns a string cursor of the beginning of haystack.

If haystack doesn’t countain needle, they return #f.

Function: string-for-each-cursor proc string :optional start end ¶

[SRFI-130]{srfi.130} Calls proc with each cursor of string, from left to right, excluding the post-end cursor. This is the cursor version of string-for-each-index in SRFI-13 (see String mapping).

(define s "abc")
(string-for-each-cursor (^c (display (string-ref/cursor s c))) s)
 ⇒ displays abc