Scheme Programmer's Manual

NAME

bytevector-sint-ref, bytevector-sint-set!, bytevector-uint-ref, bytevector-uint-set! - variable length bytevector operations

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs bytevectors))         ;R6RS

SYNOPSIS

(bytevector-sint-ref bytevector k endianness size)
(bytevector-uint-ref bytevector k endianness size)
(bytevector-sint-set! bytevector k n endianness size)
(bytevector-uint-set! bytevector k n endianness size)

DESCRIPTION

These procedures are for working with variable-length integers encoded in bytevectors.

The bytevector-sint-ref and bytevector-uint-ref procedures decode a signed or unsigned integer (respectively) from bytevector, starting from index k, according to endianness, reading size bytes.

The integers are encoded according to signedness, endianness and size. Signed or unsigned is chosen by using the appropriate procedure. The size argument is a positive exact integer that determines how many bytes the encoded integer uses (a 128-bit integer would have a size of 16). The endianness is normally one of these symbols:

big
Big endian. The more significant bytes come before the less significant bytes.
little
Little endian. The less significant bytes come before the more significant bytes.

The signed variants use the two's complement representation. The range that can be encoded by the unsigned variants is [0,(256^size)−1]. The range of the signed variants is [−(256^size)/2,((256^size)/2)-1].

RETURN VALUES

The bytevector-sint-ref and bytevector-uint-ref procedures return a single exact integer object.

The bytevector-sint-set! and bytevector-uint-set! procedures return unspecified values.

EXAMPLES

(define b (make-bytevector 16 -127))

;; Using (endianness little) is the same as writing ;; (quote little), but it gives a free typo check. (bytevector-uint-set! b 0 (- (expt 2 128) 3)
                     (endianness little) 16)

(bytevector-uint-ref b 0 (endianness little) 16)
          =>
    #xfffffffffffffffffffffffffffffffd

(bytevector-sint-ref b 0 (endianness little) 16)
          => -3

(bytevector->u8-list b)
          => (253 255 255 255 255 255 255 255
              255 255 255 255 255 255 255 255)

(bytevector-uint-set! b 0 (- (expt 2 128) 3)
                 (endianness big) 16) (bytevector-uint-ref b 0 (endianness big) 16)
          =>
    #xfffffffffffffffffffffffffffffffd

(bytevector-sint-ref b 0 (endianness big) 16)
          => -3

(bytevector->u8-list b)
          => (255 255 255 255 255 255 255 255
              255 255 255 255 255 255 255 253))

APPLICATION USAGE

These procedures are used in some data formats that encode variable-length integers by using an explicit length encoding. (Base-128 compression, where the highest bit in every byte is a continuation flag, is more common).

They are sometimes used in code that is easier to express as operations on integers rather than bytevectors.

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, if size is zero or k+size-1 is not a valid index of bytevector.

SEE ALSO

bytevector-u8-ref(3), bytevector-u8-set!(3), bytevector-u16-ref(3), bytevector-u16-set!(3)

STANDARDS

R6RS

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at

BUGS

In some type of code it is easy to make the mistake of passing a zero size argument, which will raise an exception.

Index

NAME
LIBRARY
SYNOPSIS
DESCRIPTION
RETURN VALUES
EXAMPLES
APPLICATION USAGE
ERRORS
SEE ALSO
STANDARDS
AUTHORS
BUGS
Return to Main Contents