docs
API
Generated with
docs/scalus/scalus.builtin/BitwiseLogicalOperations

BitwiseLogicalOperations

scalus.builtin.BitwiseLogicalOperations
object BitwiseLogicalOperations

CIP-122 + shifts & rotations from CIP-123

Attributes

Graph
Supertypes
class Object
trait Matchable
class Any
Self type

Members list

Value members

Concrete methods

def andByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise AND between two byte strings.

Bitwise AND between two byte strings.

Value parameters

lhs

Left operand.

rhs

Right operand.

shouldPad

true - padding semantics (pad the shorter input at high-index bytes). false - truncation semantics (truncate to the shorter input).

Attributes

Returns

A new byte string representing the bitwise AND of the two inputs, using the chosen padding/truncation.

See also
Note

Bit 0 is the least-significant bit of the last byte.

Example 
 andByteString(false, hex"0f0f", hex"0fff") == hex"0f0f"
 andByteString(true,  hex"0f0f", hex"0fff") == hex"0f0f"
def complementByteString(byteString: ByteString): ByteString

Bitwise NOT of a byte string (flip all bits).

Bitwise NOT of a byte string (flip all bits).

Value parameters

byteString

Input byte string.

Attributes

Returns

A new byte string where each byte is replaced by 0xff - byte.

See also
Example 
 complementByteString(hex"00ff") == hex"ff00"
def countSetBits(byteString: ByteString): Int

Count the number of 1-bits in the byte string (Hamming weight).

Count the number of 1-bits in the byte string (Hamming weight).

Value parameters

byteString

Input byte string.

Attributes

Returns

Number of set bits.

Example 
 countSetBits(hex"0f0f") == 8
 countSetBits(hex"0000") == 0
def findFirstSetBit(byteString: ByteString): Int

Find the index of the least significant 1-bit.

Find the index of the least significant 1-bit.

Scans from bit 0 (LSB of last byte) upwards.

Value parameters

byteString

Input byte string.

Attributes

Returns

Index of the first set bit >= 0, or -1 if all bits are zero.

See also
Example 
 findFirstSetBit(hex"10") == 4 // 00010000
 findFirstSetBit(hex"00") == -1
def orByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise OR between two byte strings.

Bitwise OR between two byte strings.

Value parameters

lhs

Left operand.

rhs

Right operand.

shouldPad

true - padding semantics (pad the shorter input at high-index bytes). false - truncation semantics (truncate to the shorter input).

Attributes

Returns

A new byte string representing the bitwise OR of the two inputs, using the chosen padding/truncation.

See also
Example 
 orByteString(false, hex"0f0f", hex"f000") == hex"0000"
 orByteString(true,  hex"0f0f", hex"f000") == hex"ff0f"
def readBit(byteString: ByteString, index: BigInt): Boolean

Read a single bit from a byte string. Bit index 0 refers to the least significant bit of the last byte.

Read a single bit from a byte string. Bit index 0 refers to the least significant bit of the last byte.

Value parameters

byteString

Input byte string.

index

Bit index in the range [0, byteString.length * 8).

Attributes

Returns

true if the bit is 1, false if the bit is 0.

Throws
scalus.uplc.eval.BuiltinException

If the byte string is empty, or if the index is out of bounds.

See also
Note

Bit indexed 0 is the least-significant bit of the last byte.

Example 
 // Last byte: 10010000
 readBit(hex"1098", 4) == true
 readBit(hex"1098", 0) == false
def replicateByte(length: BigInt, byte: BigInt): ByteString

Construct a byte string by repeating a single byte.

Construct a byte string by repeating a single byte.

Value parameters

byte

Byte value in the range [0, 255].

length

Number of bytes to generate. Must be within [0, maximumOutputLength].

Attributes

Returns

A new byte string consisting of length copies of byte.

Throws
scalus.uplc.eval.BuiltinException

If the requested length or byte value is outside the permitted range.

See also
Example 
 replicateByte(4, 0xFF) == hex"ffffffff"
 replicateByte(0, 1) == hex""
def rotateByteString(byteString: ByteString, rotation: BigInt): ByteString

Rotate all bits of a byte string left or right, modulo its bit length.

Rotate all bits of a byte string left or right, modulo its bit length.

Value parameters

byteString

Input byte string.

rotation

Number of bits to rotate. Positive - rotate left, negative - rotate right.

Attributes

Returns

A byte string of identical length with bits rotated.

Throws
scalus.uplc.eval.BuiltinException

If the rotation remainder does not fit in a 32-bit signed integer.

See also
Note

Rotation wraps around the bitstring width (n * 8 bits).

Example 
 rotateByteString(hex"80", 1) == hex"01"
 rotateByteString(hex"01", -1) == hex"80"
def shiftByteString(byteString: ByteString, shift: BigInt): ByteString

Logical bit shift of a byte string.

Logical bit shift of a byte string.

Positive shift performs a left shift. Negative shift performs a right shift. Bits shifted out are discarded; zeros are shifted in.

Value parameters

byteString

Input byte string.

shift

Number of bits to shift. Must fit in a 32-bit signed integer.

Attributes

Returns

The shifted byte string.

Throws
scalus.uplc.eval.BuiltinException

If the shift value does not fit into a 32-bit signed integer.

See also
Note

Shifts never sign-extend; they are logical, not arithmetic.

Example 
 shiftByteString  hex"11ff"  4 == hex"1ff0"
 shiftByteString  hex"11ff" -4 == hex"011f"
def writeBits(byteString: ByteString, indexes: Seq[BigInt], bit: Boolean): ByteString

Write multiple bits in a byte string.

Write multiple bits in a byte string.

Value parameters

bit

The new bit value (true - set to 1, false - set to 0).

byteString

Input byte string to modify.

indexes

Sequence of bit indexes to change. Must be within bounds.

Attributes

Returns

A new byte string with all specified bits updated.

Throws
scalus.uplc.eval.BuiltinException

If the byte string is empty or any index lies outside the valid bit range.

See also
Note

Bulk updates are intentionally more efficient than repeated setBit calls (see CIP-122 design rationale).

Bit indexed 0 is the least-significant bit of the last byte.

Example 
 writeBits(hex"00", List(0, 3), true) == hex"09" // Set bits 0 and 3 in a single byte
def xorByteString(shouldPad: Boolean, lhs: ByteString, rhs: ByteString): ByteString

Bitwise XOR between two byte strings.

Bitwise XOR between two byte strings.

Value parameters

lhs

Left operand.

rhs

Right operand.

shouldPad

true - padding semantics (pad the shorter input at high-index bytes). false - truncation semantics (truncate to the shorter input).

Attributes

Returns

A new byte string representing the bitwise XOR of the two inputs, using the chosen padding/truncation.

See also
Example 
 xorByteString(false, hex"0f0f", hex"ffff") == hex"f0f0"
 xorByteString(true,  hex"0f0f", hex"ffff") == hex"f0f0"
Generated with