string-ref - get a character from a string

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs base))                ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

SYNOPSIS

(string-ref string k)

DESCRIPTION

Returns character k of string using zero-origin indexing.
R6RS
Implementors should make string-ref run in constant time.
R7RS
There is no requirement for this procedure to execute in constant time.

IMPLEMENTATION NOTES

Chibi Scheme
Chibi supports O(1) string access if the SEXP_USE_STRING_INDEX_TABLE feature is enabled.

RETURN VALUES

Returns a single value which is a character object. It is eqv?(3scm) to the one that was last placed in the string at index k.

EXAMPLES

(string-ref "abc" 1)  =>  #\b

APPLICATION USAGE

This procedure is used to implement algorithms that read strings in non-linear access patterns. Programs that read strings at increasing indices can use open-string-input-port(3scm) instead.

RATIONALE

The choice of R7RS to not require execution in constant time opens the possibility for implementations to use UTF-8 or UTF-16 as the internal string representation.

COMPATIBILITY

This procedure is functionally the same in all RnRS revisions after R2RS. The differences are in which characters an implementation can represent, how errors are signalled, and the time complexity of doing the lookup.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain. Raised if k is not a valid index of string.
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

SEE ALSO

string-set!(3scm), vector-ref(3scm), open-string-input-port(3scm)

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

First introduced in R2RS. Scheme before R2RS running on MacLISP had a similar getchar function, but it used one-origin indexing and worked on atomic symbols instead of character strings.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

BUGS

It is easy to get the index validity check wrong. GNU Guile 3.0.8 segfaults on evaluating (string-ref "" -1).

Markup created by unroff 1.0sc,    March 04, 2023.