Scheme Programmer's Manual
NAME
bitwisearithmeticshift, bitwisearithmeticshiftleft, bitwisearithmeticshiftright, fxarithmeticshift, fxarithmeticshiftleft, fxarithmeticshiftright  arithmetic shift
LIBRARY
(import (rnrs)) ;R6RS
(import (rnrs arithmetic bitwise)) ;R6RS
(import (rnrs arithmetic fixnums)) ;R6RS
SYNOPSIS
(bitwisearithmeticshift n amount)
(bitwisearithmeticshiftleft n amount)
(bitwisearithmeticshiftright n amount)
(fxarithmeticshift n amount)
(fxarithmeticshiftleft n amount)
(fxarithmeticshiftright 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 nonnegative
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
(fxarithmeticshiftleft #b110011 1)
=> #b1100110
(bitwisearithmeticshift 6 1)
=> 3
(bitwisearithmeticshift 5 1)
=> 3
(bitwisearithmeticshift 4 1)
=> 2
(bitwisearithmeticshift 3 1)
=> 2
(bitwisearithmeticshift 2 1)
=> 1
(bitwisearithmeticshift 1 1)
=> 1
APPLICATION USAGE
Bitwise arithmetic shift is common in cryptography, (de)serialization,
pseudorandom functions, compression, errordetecting 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 24bit precision, so code dealing
with e.g. 32bit integers should be prepared to use the generic
variants.
These procedures are not available in R7RSsmall. See SRFI60 and SRFI151.
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.
 &implementationrestriction

The fixnum variants of the procedures raise this if the result is not
representable as a fixnum.
SEE ALSO
fixnumwidth(3),
expt(3)
STANDARDS
R6RS
AUTHORS
This page is part of the
schememanpages
project.
It includes materials from the RnRS documents.
More information can be found at
BUGS
Some implementations take a shortcut 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

(bitwisearithmeticshiftright 2 (+ (greatestfixnum) 1))
=> 2 ;WRONG
 Chez Scheme 8.4

(fxarithmeticshiftleft #xB00000000000000 2)
=> #xC00000000000000 ;WRONG
(fxarithmeticshiftleft #x500000000000000 3)
=> #x800000000000000 ;WRONG
 Racket 5.3.5

(bitwisearithmeticshiftright 42 (+ 1 (greatestfixnum)))
=> 42 ;WRONG
 Vicare Scheme 0.3d1

(bitwisearithmeticshiftright 1 (+ (greatestfixnum) 1))
=> an exception is raised ;WRONG
 IronScheme TFS:101169

(fxarithmeticshiftright 42 (fixnumwidth))
=> 42 ;WRONG
 Sagittarius 0.4.9

(bitwisearithmeticshift 0 65)
=> 0 ;WRONG: a bignum zero
Index
 NAME

 LIBRARY

 SYNOPSIS

 DESCRIPTION

 RETURN VALUES

 EXAMPLES

 APPLICATION USAGE

 COMPATIBILITY

 ERRORS

 SEE ALSO

 STANDARDS

 AUTHORS

 BUGS

Return to Main Contents