rshift · Builtins · MPL Reference

`rshift (object shiftCount -- shiftedValue)`

Inputs

object: Whole-number object to shift.
shiftCount: Whole-number shift amount.

Outputs

shiftedValue: Right-shift result in the same schema.

rshift consumes two Whole objects. object provides the bits to shift and the schema of the result. shiftCount provides the shift amount and may use a different Whole schema.

The bits of object move to the right. The result always keeps the same schema as object.

Behavior

For Nat, zero bits are inserted at the high end. This is the logical right shift.
If shiftCount uses an Int schema, its bit pattern is first reinterpreted as the matching Nat width. Non-negative Int shift counts therefore behave the same as equal-valued Nat shift counts.
If shiftCount, after that reinterpretation, is at least the bit width of object, the behavior of the shift is not defined; this includes every negative Int count. Neither compile time nor run time checks the count.
For Int, copies of the sign bit are inserted at the high end. This is the arithmetic right shift.
In Int32, -1 31 rshift therefore still produces -1.
If both inputs are known at compile time, the result is computed at compile time.
If object is known zero, the result is known zero even when shiftCount is unknown; an excessive count remains not defined.
Otherwise, an unknown input produces an unknown result of the same schema as object.

Example

{} () {} [
  "-- nat32 --" printCompilerMessage
  12n32 2 rshift printStack _:;
  12n32 1i8 rshift printStack _:;

  "-- nat8 high bits --" printCompilerMessage
  0x80n8 1 rshift printStack _:;

  "-- zero and unknown shift --" printCompilerMessage
  unknownShift: 0n32 dynamic;
  0n32 unknownShift rshift printStack _:;

  "-- unknown value and zero shiftCount --" printCompilerMessage
  unknownNat: 0n32 dynamic;
  unknownNat 0 rshift printStack _:;

  "-- int32 --" printCompilerMessage
  -4 1 rshift printStack _:;
  -1 31 rshift printStack _:;
  1 31 rshift printStack _:;
] "main" exportFunction

Expected Output During Compilation

-- nat32 --
3n32
6n32
-- nat8 high bits --
64n8
-- zero and unknown shift --
0n32
-- unknown value and zero shiftCount --
Nat32
-- int32 --
-2
-1
0