Manual page for make-bytevector(3scm)

make-bytevector - create a new bytevector

LIBRARY

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

SYNOPSIS

(make-bytevector k)
(make-bytevector k fill)

DESCRIPTION

Return a newly allocated bytevector of k bytes.

If the fill argument is missing, the initial contents of the returned bytevector are unspecified.

If the fill argument is present, it must be an exact integer object. Every byte in the returned bytevector will be set to this value.

R6RS: The fill argument must be in the range [−128, 255]. If fill is positive, it is interpreted as if passed to bytevector-u8-set!(3scm). If it is negative, it is instead used as if passed to bytevector-s8-set!(3scm).
R7RS: The fill argument must be in the range [0, 255].

IMPLEMENTATION NOTES

Chez Scheme, Loko Scheme, (others?): If k is zero then the empty bytevector object is returned.
GNU Guile, Loko Scheme, (others?): If fill is missing then the bytevector is initialized to zeros.
Chibi Scheme: Even though Chibi is an R7RS implementation, the fill argument is interpreted as in R6RS. This is a valid extension of R7RS.

RETURN VALUES

Returns a single object which is a bytevector object of the given length. If k is non-zero then the bytevector is fresh. If k is zero then the unique empty bytevector object may be returned.

EXAMPLES

(make-bytevector 2 12)
    => #u8(12 12)          ;R7RS notation

APPLICATION USAGE

This procedure is used in code that works with mutable bytevectors. For some code an alternative is to use open-bytevector-output-port(3scm) and to build the data sequentially.

COMPATIBILITY

Portable code should provide the second argument, and should keep it in the range [0, 255].

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.
&implementation-restriction (R6RS): There is not enough free memory to hold the new bytevector.
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.

STANDARDS

R6RS, R7RS

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 often a mistake to call this procedure without the fill argument. Unusual values of k can stress the Scheme implementation's memory allocator and cause a crash.

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