string-set! - modify a string element

LIBRARY

(import (rnrs mutable-strings))     ;R6RS
(import (scheme r5rs))              ;R7RS
(import (scheme base))              ;R7RS

SYNOPSIS

(string-set! string k char)

DESCRIPTION

Stores char in element k of string.
R6RS
Implementors should make string-ref(3scm) run in constant time, which may mean that this procedure will also run in constant time.
R7RS
There is no requirement for this procedure to execute in constant time.

RETURN VALUES

R6RS
Returns unspecified values.
R7RS
Returns an unspecified value.

EXAMPLES

(define (f) (make-string 3 #\*))
(define (g) "***")
(string-set! (f) 0 #\?)       => unspecified
(string-set! (g) 0 #\?)       => unspecified
             ; should raise &assertion exception

APPLICATION USAGE

This procedure is rarely used to modify existing strings. It is sometimes used to build up new strings, but a better option is often to use an output string created by open-string-output-port(3scm), which have the benefit that the output length does not need to be known in advance.

COMPATIBILITY

This procedure works the same everywhere. Whether a string literal is truly immutable depends on the implementation (but they should not be mutated either way).

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. In particular, k must be a valid index of string, which in turn must be a mutable 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

open-string-output-port(3scm)

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

HISTORY

The first Scheme report to include this procedure was R2RS. In R6RS this procedure was moved to its own library which is normally not imported.

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/.

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