Integer & Bitwise Arithmetic Functions

Bitwise Operations

and(x1; x2; ...)

Performs a bitwise logical AND on the submitted parameters (at least two). All parameters have to be real integers from the range -2255 to +2255-1 (signed or unsigned 256 bit integers), non integer arguments are rounded toward zero. The result ranges from -2255 to +2255-1 (signed integer).

or(x1; x2; ...)

Performs a bitwise logical OR on the submitted parameters (at least two). All parameters have to be integers from the range -2255 to +2255-1 (signed integer), non integer arguments are rounded toward zero.

xor(x1; x2; ...)

Performs a bitwise logical XOR on the submitted parameters (at least two). All parameters have to be integers from the range -2255 to +2255-1 (signed integer), non integer arguments are rounded toward zero.

popcount(n)

New in version 1.0.

Returns the number of set bits (1 bits) in the 256-bit two’s complement representation of n.

The argument must be real and dimensionless, in the logic range used by the bitwise functions. Non-integer arguments are rounded toward zero.

not(n)

The not() function is defined by not(x) = -x-1, giving the same result as the one’s complement operator ~ in C/C++.

Warning

This function does not simply flip the bits!

The unary prefix operator ~ is equivalent to not():

~5
= -6
not(5)
= -6

-~(-1)
= 0
-not(-1)
= 0

New in version 1.0.

shl(x; n)

Performs an arithmetic left shift.

Parameters:

  • x – The number (bit pattern) to shift, -2255 <= x <= +2256-1.

  • n – Number of bits to shift, -255 <= n <= 255. Must be integer.

Note that n < 0 results in a right shift. The result ranges from -2255 to +2255-1 (signed integer). x is rounded toward zero before shifting. If n = 0, x is returned without rounding.

Shifted out bits are always dropped. During a right shift, the most significant bit (bit 255) is copied. During a left shift, zero bits are shifted in.

shr(x; n)

Performs an arithmetic right shift.

Parameters:

  • x – The number (bit pattern) to shift, -2255 <= x <= +2256-1.

  • n – Number of bits to shift, -255 <= n <= 255. Must be integer.

Note that n < 0 results in a left shift. The result ranges from -2255 to +2255-1 (signed integer). x is rounded toward zero before shifting. If n = 0, x is returned without rounding.

Shifted out bits are always dropped. During a right shift, the most significant bit (bit 255) is copied. During a left shift, zero bits are shifted in.

mask(x; n)

Returns the lowest n bits from x. For this, x must be in the range -2255 <= x <= +2256-1, and n must be an integer, 1 <= n <= 255. x is rounded toward zero.

The result is always unsigned.

Example: Getting the two’s complement of -1 in a 16-bit system:

hex(mask(-1; 16))
= 0xFFFF
unmask(x; n)

Takes the lower n bits from x and sign-extends them to full 256 bits. This means that bit at position n-1 is copied to all upper bits.

The value of x must be in the range -2 255 <= x <= +2 256 -1, and n must be an integer, 1 <= n <= 255. x is rounded toward zero.

Example: Converting a number in two’s complement representation to a signed number:

unmask(0xFFFF; 16)
= -1
unmask(0x1FFF; 16)
= 0x1FFF

Numeral Bases

The following functions only change the format for the current result. To change the base that is used for displaying results, select one of the corresponding settings in Settings ‣ Results ‣ Format.

bin(n)

Format n as binary (base-2).

oct(n)

Format n as octal (base-8).

dec(n)

Format n as decimal (base-10).

sci(n)

Format n in scientific notation.

dms(n)

Format n in sexagesimal notation, using the same convention as the Sexagesimal notation setting. Time quantities display as h:mm:ss; angles and dimensionless values display as degrees, minutes, and seconds.

eng(n[; exponent])

Format n in engineering notation.

If exponent is provided, force the e exponent suffix to that value. exponent can be:

  • an integer exponent that is a multiple of 3 (for example, -3 or 6), or

  • a power of ten with exponent a multiple of 3 (for example, milli, micro, kilo, mega, pico).

eng(0.000123456; milli) is equivalent to eng(0.000123456; -3).

rat(n)
ratio(n)
rational(n)

Format n in rational form when possible. If a suitable rational form is not found, the result falls back to decimal automatic formatting.

hex(n)

Format n as hexadecimal (base-16).

binpad(n[; bits])

New in version 1.0.

Format integer n as binary (base-2) and left-pad the integer part with zeros.

If bits is omitted, the width is padded to the next multiple of 8 bits (byte boundary). If bits is provided, the width is padded to at least bits (it never truncates).

Only real, dimensionless integer arguments are allowed.

octpad(n[; bits])

New in version 1.0.

Format integer n as octal (base-8) and left-pad the integer part with zeros.

If bits is omitted, the width is padded to the next multiple of 8 bits (byte boundary). If bits is provided, the width is padded to at least bits (it never truncates).

Only real, dimensionless integer arguments are allowed.

hexpad(n[; bits])

New in version 1.0.

Format integer n as hexadecimal (base-16) and left-pad the integer part with zeros.

If bits is omitted, the width is padded to the next multiple of 8 bits (byte boundary). If bits is provided, the width is padded to at least bits (it never truncates).

Only real, dimensionless integer arguments are allowed.

Rounding

ceil(x)

Round x upward to the least integer value greater than or equal to x. For quantities with dimensions, the numeric value is rounded and the original dimensions are preserved.

This is the expression-level counterpart to the Toward +∞ (ceil) rounding mode. Only real arguments are allowed.

floor(x)

Round x downward to the greatest integer value less than or equal to x. For quantities with dimensions, the numeric value is rounded and the original dimensions are preserved.

This is the expression-level counterpart to the Toward −∞ (floor) rounding mode. Only real arguments are allowed.

round(x[; n])

Round x to the nearest value with n fractional digits using half-away-from-zero rounding; n may be omitted, in which case x is rounded to the closest integer. When a value is exactly halfway between two candidates, the result with the larger absolute value is chosen.

For quantities with dimensions, the numeric value is rounded and the original dimensions are preserved.

This is the expression-level counterpart to the Nearest, Half Away (round) rounding mode. It does not depend on the global rounding mode.

Example:

round(0.5)
= 1

round(-0.5)
= -1

round(1.5)
= 2

round(12.345; 2)
= 12.34

round(12345; -2)
= 12300

x must be real. n must be a real, dimensionless integer.

roundeven(x[; n])

Round x to the nearest value with n fractional digits using half-even, also known as banker’s rounding; n may be omitted, in which case x is rounded to the closest integer.

For quantities with dimensions, the numeric value is rounded and the original dimensions are preserved.

Ties are rounded to the value whose last kept digit is even. This is the expression-level counterpart to the Nearest, Half Even (roundeven) rounding mode. This strategy is commonly known as Banker’s rounding. It does not depend on the global rounding mode.

Example:

roundeven(0.5)
= 0

roundeven(1.5)
= 2

roundeven(2.5)
= 2

roundeven(12.345; 2)
= 12.34

x must be real. n must be a real, dimensionless integer.

trunc(x[; n])

Truncate x toward zero to the next value with n fractional digits; n may be omitted, in which case x is rounded to an integer. This discards extra digits without increasing the absolute value.

For quantities with dimensions, the numeric value is rounded and the original dimensions are preserved.

This is the expression-level counterpart to the Toward Zero (trunc) rounding mode. x must be real. n must be a real, dimensionless integer.

See also

int()
frac()
ceil()
floor()
round()
roundeven()

Integer Division

idiv(a; b)

Compute the integer part of the division a/b. The result is guaranteed to be exact. While int(a/b) covers a larger range of arguments, the result is computed via floating point arithmetics and may be subject to rounding errors. This function will instead yield an error if the parameters exceed the safe bounds.

It is possible to apply idiv() to non-integers as well, but be aware that rounding errors might be lead to off-by-one errors. If the result depends on the validity of the guard digits, NaN is returned.

Only real, dimensionless arguments are allowed.

mod(a; b)

Compute the remainder of the integer division a/b. The divisor b must be non-zero. The result takes the sign of a.

This function is paired with idiv() (truncating integer quotient), so a = idiv(a; b) * b + mod(a; b).

Example: mod(-1; 360) = -1. If you want wrap-around behavior in [0, 360), use emod(): emod(-1; 360) = 359.

For large powers, avoid computing the full power first (for example, mod(3^233; 353)), since the intermediate value may lose precision. Use powmod() instead.

This function always returns an exact result, provided that the parameters are exact.

You can use this function with non-integers as well, but rounding errors might lead to off-by-one errors. Evaluating mod() can be computationally expensive, so the function is internally restricted to 250 division loops.

Only real, dimensionless arguments are allowed.

emod(a; b)

New in version 1.0.

Compute the Euclidean remainder of a/b. The divisor b must be non-zero. The result has the sign of b (or is zero), and its absolute value is smaller than the absolute value of b.

For positive b, this maps values to [0, b); for example, emod(-1; 360) = 359.

This function always returns an exact result, provided that the parameters are exact.

You can use this function with non-integers as well, but rounding errors might lead to off-by-one errors.

Only real, dimensionless arguments are allowed.

powmod(base; exponent; modulo)

New in version 1.0.

Compute base^exponent reduced by modulo using modular exponentiation. This avoids building huge intermediate powers and is therefore the recommended approach for large exponents (for example in cryptography).

Arguments must be real, integer, and dimensionless. modulo must be non-zero, and exponent must be non-negative.

The result follows emod() semantics (same sign as modulo or zero). Example: powmod(3; 233; 353) = 248.

gcd(n1; n2; ...)

Returns the greatest common divisor of the arguments (at least two must be given). You can use this function to reduce a rational number. If a rational number is given as p/q, its reduced form is (p / gcd(p; q)) / (q / gcd(p; q)).

Only real, integer arguments are allowed.

lcm(n1; n2; ...)

New in version 1.0.

Returns the least common multiple of the arguments (at least two must be given). The result is always non-negative.

gcd() and lcm() are related by:

\[lcm(n1; n2) = n1 * n2 / gcd(n1; n2)\]

Only real, integer arguments are allowed.