put-bytevector, write-bytevector - write a bytevector to a port
LIBRARY
(import (rnrs)) ;R6RS
(import (rnrs io ports)) ;R6RS
(import (scheme base)) ;R7RS
SYNOPSIS
(put-bytevector binary-port bytevector) ;R6RS
(put-bytevector binary-port bytevector start) ;R6RS
(put-bytevector binary-port bytevector start count) ;R6RS
(write-bytevector bytevector) ;R7RS
(write-bytevector bytevector port) ;R7RS
(write-bytevector bytevector port start) ;R7RS
(write-bytevector bytevector port start end) ;R7RS
DESCRIPTION
Writes the selected bytes from
bytevector
to
binary-port
(or
port).
- R6RS
-
The default value for
start
is
0.
The default value for
count
is
(bytevector-length
bytevector)
−
start.
- R7RS
-
R7RS does not specify any default values, so an implementation can
presumably treat any such calls as errors, but some reasonable
assumptions can be made. The default value for
port
is
(current-output-port).
Normally the current output port is textual and using it here would be an error.
The default value for
start
is
0.
The default value for
end
is
(bytevector-length
bytevector).
IMPLEMENTATION NOTES
- Chibi Scheme, GNU Guile
-
Ports can be both binary and textual. It is possible to write bytes
to the default value of
current-output-port(3scm).
This is not portable.
standard-output-port(3scm)
should be used to get a fresh binary port.
RETURN VALUES
These procedures return unspecified values.
EXAMPLES
(import (rnrs))
;; Write a TARGA header followed by pixels
(define (put-tga p width height bits/pixel pixel-data)
(let ((hdr (make-bytevector 18 0)))
(bytevector-u8-set! hdr 2 2)
(bytevector-u16-set! hdr 12 width (endianness little))
(bytevector-u16-set! hdr 14 height (endianness little))
(bytevector-u8-set! hdr 16 bits/pixel)
(put-bytevector p hdr)
(put-bytevector p pixel-data)))
(let ((pixel-data (make-bytevector (* 320 240 4))))
;; Generate some image data
(do ((y 0 (+ y 1)))
((= y 240))
(do ((x 0 (+ x 1)))
((= x 320))
(bytevector-u32-set! pixel-data (* 4 (+ x (* y 320)))
(+ #xff
(* (round (* y 255/240)) 256)
(* (round (* x 255/320)) 256 256))
(endianness big))))
;; Create an image file
(call-with-port (open-file-output-port "image.tga")
(lambda (p)
(put-tga p 320 240 32 pixel-data))))
APPLICATION USAGE
The
put-bytevector
procedure is used in applications that write bulk data to binary
output ports. This can, for example, be code that works with binary
files or network streams.
It is sometimes used in conjunction with a port created by
open-bytevector-output-port(3scm),
as a different method of constructing a bytevector. The benefit is that
the port will keep track of the current byte position, and the size of
the data does not need to be known in advance.
RATIONALE
If one were forced to remove either
put-bytevector(3scm)
or
put-u8(3scm)
from the language, then the latter should be removed. The first one
is more general, more efficient and supports the writing of bulk data
to non-buffered ports.
COMPATIBILITY
There are trivial differences in the signatures from R6RS and R7RS.
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.
This is also raised if
start
or
count
are negative, or if the length of
bytevector
is not at least
start+count.
This is also raised if the port is not an open binary port.
- &i/o-write (R6RS)
-
There was a write error during an I/O operation.
- 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
put-u8(3scm)
STANDARDS
R6RS,
R7RS
HISTORY
This procedure was not present in R5RS and earlier reports. It can
be seen as analogous to to the
fwrite(3)
function from the C language, or similar to the
write(2)
function from POSIX in the case of non-buffered ports.
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
Markup created by unroff 1.0sc, March 04, 2023.