bitwise-arithmetic-shift, bitwise-arithmetic-shift-left, bitwise-arithmetic-shift-right, fxarithmetic-shift, fxarithmetic-shift-left, fxarithmetic-shift-right - arithmetic shift

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs arithmetic bitwise))  ;R6RS
(import (rnrs arithmetic fixnums))  ;R6RS

SYNOPSIS

(bitwise-arithmetic-shift n amount)
(bitwise-arithmetic-shift-left n amount)
(bitwise-arithmetic-shift-right n amount)
(fxarithmetic-shift n amount)
(fxarithmetic-shift-left n amount)
(fxarithmetic-shift-right n amount)

DESCRIPTION

Performs a bitwise arithmetic shift on n by amount bit positions.

More precisely, these procedures compute the result of the following expression. The -right variants first negate amount. 

    (floor (* n (expt 2 amount)))

The variants with -left or -right require a non-negative amount. The fixnum variants raise an exception if the result would not be a fixnum. They also restrict amount, see below.

RETURN VALUES

Returns a single exact integer object. The fixnum variants are further restricted to return a fixnum object.

EXAMPLES

(fxarithmetic-shift-left #b110011 1)
   => #b1100110

(bitwise-arithmetic-shift -6 -1)
   => -3
(bitwise-arithmetic-shift -5 -1)
   => -3
(bitwise-arithmetic-shift -4 -1)
   => -2
(bitwise-arithmetic-shift -3 -1)
   => -2
(bitwise-arithmetic-shift -2 -1)
   => -1
(bitwise-arithmetic-shift -1 -1)
   => -1

APPLICATION USAGE

Bitwise arithmetic shift is common in cryptography, (de)serialization, pseudo-random functions, compression, error-detecting and correcting codes and more.

Truncating left shift can be achieved by masking the input so that only the remaining bits are kept, before calling the left shift procedure.

COMPATIBILITY

This is the same as the logical shift operations on signed (two's complement) integers available in most languages and machines, commonly called such things as >>, <<, ASL, and SAL. The fixnum variant can be seen as a subset of the machine instruction whereas the generic one switches to bignums when necessary. (Other implementation strategies are possible).

Fixnums are only guaranteed to have 24-bit precision, so code dealing with e.g. 32-bit integers should be prepared to use the generic variants.

These procedures are not available in R7RS-small. See SRFI-60 and SRFI-151.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion
The wrong number of arguments was passed or an argument was outside its domain. For the fixnum variants, this is raised if the absolute shift amount is not less than the fixnum width.
&implementation-restriction
The fixnum variants of the procedures raise this if the result is not representable as a fixnum.

SEE ALSO

fixnum-width(3scm), expt(3scm)

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 https://github.com/schemedoc/manpages/.

BUGS

Some implementations take a short-cut to handle right shifting with huge shift amounts. Given a shift amount that is larger then the number of bits in the number, the result can only ever be 0 or -1. This is not guaranteed to be fast, so don't rely on it in your code.

These procedures have been known to give bad results for unusual combinations of inputs. Here is a list of some of them so that you may compare with your own implementation.

Guile 2.0.9 
(bitwise-arithmetic-shift-right -2 (+ (greatest-fixnum) 1))
   => -2                      ;WRONG
Chez Scheme 8.4 
(fxarithmetic-shift-left #xB00000000000000 2)
   => #xC00000000000000       ;WRONG

(fxarithmetic-shift-left #x-500000000000000 3)
   => #x-800000000000000      ;WRONG
Racket 5.3.5 
(bitwise-arithmetic-shift-right 42 (+ 1 (greatest-fixnum)))
   => 42                      ;WRONG
Vicare Scheme 0.3d1 
(bitwise-arithmetic-shift-right -1 (+ (greatest-fixnum) 1))
   => an exception is raised  ;WRONG
IronScheme TFS:101169 
(fxarithmetic-shift-right 42 (fixnum-width))
   => 42                      ;WRONG
Sagittarius 0.4.9 
(bitwise-arithmetic-shift 0 65)
   => 0                       ;WRONG: a bignum zero

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