silk.num.isize.

When to use#

Use isize for offsets paired with target-sized counts or addresses. Use a fixed-width integer for files, protocols, persistent data, or any value that must mean the same thing on 32-bit and 64-bit targets.

Details#

Each arithmetic operation has four forms with different overflow rules:

• The plain form, such as add, traps on overflow. Use it when overflow is a program error.

• The checked form, such as checkedAdd, returns None on overflow. Use it when input data controls the operands.

• The wrapping form, such as wrappingAdd, computes the result modulo two to the power of BITS.

• The saturating form, such as saturatingAdd, returns MIN or MAX on overflow.

Division and remainder by zero trap, and so does MIN divided by -1. checkedDivide and checkedRemainder return None for these inputs. The shift count must be in the range 0 to BITS - 1. Otherwise, the program traps. A rotate reduces its count modulo BITS, so each count is valid. A signed right shift copies the sign bit into the new high bits.

A to conversion, such as toU8, traps if the value is out of the range of the destination type. A checkedTo conversion returns None instead. Conversion to f32 or f64 rounds to the nearest value if the integer has more significant bits than the float.

A wrappingTo conversion, such as wrappingToI16, never traps. It keeps the low bits of the two's complement form of the value, like a cast in C or Rust, so it truncates, sign-extends, or reinterprets bits.

countOnes, leadingZeros, and trailingZeros count the bits of the value in its two's complement form. For zero, both zero counts return BITS.

BITS, MIN, and MAX depend on the target: 32 bits on wasm32 and 64 bits on the other targets.

parse reads decimal text. A leading - is valid, and a leading + is not valid. To write a value as text, use silk.text.format.Format.display or Format.displayWith with a Writer. Neither needs an Allocator.

Gotchas#

Code that succeeds at a 64-bit boundary can fail or trap when compiled for a 32-bit target. MIN also has no positive counterpart. Use checkedDivide when division by -1 can receive that value.

Examples#

Clamp an offset at the target boundary#

import silk.num.isize

pub fn main() -> i32 {
  if isize.saturatingAdd(isize.MAX, 1) != isize.MAX {
    return 1
  }
  return 0
}

Parse decimal text and reject invalid text#

import silk.text.format { ParseError }
import silk.core.result { Result }
import silk.num.isize

pub fn main() -> i32 {
  let parsed = isize.parse("42") |> Result<isize, ParseError>.unwrapOr(0)
  let invalid = isize.parse("4x2") |> Result<isize, ParseError>.unwrapOr(0)
  if parsed != 42 || invalid != 0 {
    return 1
  }
  return 0
}

Import as isize with import silk.num.isize.

Public declarations: 73.

MAX#

pub const MAX: isize

The largest isize value for the compilation target.

Details#

This is 2147483647 on a 32-bit target and 9223372036854775807 on a 64-bit target. Checked arithmetic rejects results above it.

MIN#

pub const MIN: isize

The smallest isize value for the compilation target.

Details#

This is -2147483648 on a 32-bit target and -9223372036854775808 on a 64-bit target.

BITS#

pub const BITS: u32

The width of isize in bits, which is the compilation target's pointer width.

negate#

pub fn negate(value: isize) -> isize

Returns the arithmetic negation of value and traps when value is MIN. Use this function when that boundary is a program error.

wrappingNegate#

pub fn wrappingNegate(value: isize) -> isize

Returns the arithmetic negation of value, wrapped to the isize range. MIN stays MIN. Use this function for deliberate modulo arithmetic.

saturatingNegate#

pub fn saturatingNegate(value: isize) -> isize

Returns the arithmetic negation of value, clamped to the isize range. MIN becomes MAX. Use this function when the positive boundary is required.

toU8#

pub fn toU8(value: isize) -> u8

Converts value to u8. Traps if value is outside the u8 range. Use this function when an out-of-range value is a program error.

checkedToU8#

pub fn checkedToU8(value: isize) -> Option<u8>

Converts value to u8, or returns None if value is outside the u8 range. Use this function when an out-of-range value is input data.

toU16#

pub fn toU16(value: isize) -> u16

Converts value to u16. Traps if value is outside the u16 range. Use this function when an out-of-range value is a program error.

checkedToU16#

pub fn checkedToU16(value: isize) -> Option<u16>

Converts value to u16, or returns None if value is outside the u16 range. Use this function when an out-of-range value is input data.

toU32#

pub fn toU32(value: isize) -> u32

Converts value to u32. Traps if value is outside the u32 range. Use this function when an out-of-range value is a program error.

checkedToU32#

pub fn checkedToU32(value: isize) -> Option<u32>

Converts value to u32, or returns None if value is outside the u32 range. Use this function when an out-of-range value is input data.

toU64#

pub fn toU64(value: isize) -> u64

Converts value to u64. Traps if value is outside the u64 range. Use this function when an out-of-range value is a program error.

checkedToU64#

pub fn checkedToU64(value: isize) -> Option<u64>

Converts value to u64, or returns None if value is outside the u64 range. Use this function when an out-of-range value is input data.

toUsize#

pub fn toUsize(value: isize) -> usize

Converts value to usize. Traps if value is outside the usize range. Use this function when an out-of-range value is a program error.

checkedToUsize#

pub fn checkedToUsize(value: isize) -> Option<usize>

Converts value to usize, or returns None if value is outside the usize range. Use this function when an out-of-range value is input data.

toI8#

pub fn toI8(value: isize) -> i8

Converts value to i8. Traps if value is outside the i8 range. Use this function when an out-of-range value is a program error.

checkedToI8#

pub fn checkedToI8(value: isize) -> Option<i8>

Converts value to i8, or returns None if value is outside the i8 range. Use this function when an out-of-range value is input data.

toI16#

pub fn toI16(value: isize) -> i16

Converts value to i16. Traps if value is outside the i16 range. Use this function when an out-of-range value is a program error.

checkedToI16#

pub fn checkedToI16(value: isize) -> Option<i16>

Converts value to i16, or returns None if value is outside the i16 range. Use this function when an out-of-range value is input data.

toI32#

pub fn toI32(value: isize) -> i32

Converts value to i32. Traps if value is outside the i32 range. Use this function when an out-of-range value is a program error.

checkedToI32#

pub fn checkedToI32(value: isize) -> Option<i32>

Converts value to i32, or returns None if value is outside the i32 range. Use this function when an out-of-range value is input data.

toI64#

pub fn toI64(value: isize) -> i64

Converts value exactly to i64. Every isize value is representable.

checkedToI64#

pub fn checkedToI64(value: isize) -> Option<i64>

Converts value exactly to i64 and returns Some. Every isize value is representable.

toIsize#

pub fn toIsize(value: isize) -> isize

Returns value unchanged as isize. Use this function when generic conversion code can select isize as both source and destination.

checkedToIsize#

pub fn checkedToIsize(value: isize) -> Option<isize>

Returns Some with value unchanged as isize. Use this function when generic checked-conversion code can select the same source and destination type.

toF32#

pub fn toF32(value: isize) -> f32

Converts value to the nearest f32 value, with ties to even. Only magnitudes below 2^24 are exactly representable, so a larger isize rounds.

toF64#

pub fn toF64(value: isize) -> f64

Converts value to the nearest f64 value, with ties to even. Only magnitudes below 2^53 are exactly representable, so a larger isize rounds. Every isize is exact on a 32-bit target.

wrappingToU8#

pub fn wrappingToU8(value: isize) -> u8

Converts value to u8 modulo 2^8. Keeps the low 8 bits of the two's complement form of value and reads them as u8, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToU16#

pub fn wrappingToU16(value: isize) -> u16

Converts value to u16 modulo 2^16. Keeps the low 16 bits of the two's complement form of value and reads them as u16, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToU32#

pub fn wrappingToU32(value: isize) -> u32

Converts value to u32 modulo 2^32. Keeps the low 32 bits of the two's complement form of value and reads them as u32, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToU64#

pub fn wrappingToU64(value: isize) -> u64

Converts value to u64 modulo 2^64. Keeps the low 64 bits of the two's complement form of value and reads them as u64, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToUsize#

pub fn wrappingToUsize(value: isize) -> usize

Converts value to usize modulo 2^usize.BITS. Keeps the low usize.BITS bits of the two's complement form of value and reads them as usize, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToI8#

pub fn wrappingToI8(value: isize) -> i8

Converts value to i8 modulo 2^8. Keeps the low 8 bits of the two's complement form of value and reads them as i8, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToI16#

pub fn wrappingToI16(value: isize) -> i16

Converts value to i16 modulo 2^16. Keeps the low 16 bits of the two's complement form of value and reads them as i16, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToI32#

pub fn wrappingToI32(value: isize) -> i32

Converts value to i32 modulo 2^32. Keeps the low 32 bits of the two's complement form of value and reads them as i32, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToI64#

pub fn wrappingToI64(value: isize) -> i64

Converts value to i64 modulo 2^64. Keeps the low 64 bits of the two's complement form of value and reads them as i64, so it never traps. Use this function for deliberate truncation, sign extension, or bit reinterpretation, such as reading a signed field.

wrappingToIsize#

pub fn wrappingToIsize(value: isize) -> isize

Returns value unchanged. Use this function when generic wrapping-conversion code can select isize as both source and destination.

add#

pub fn add(left: isize, right: isize) -> isize

Returns left + right and traps if the result is outside the isize range. Use this function when overflow is a program error.

subtract#

pub fn subtract(left: isize, right: isize) -> isize

Returns left - right and traps if the result is outside the isize range. Use this function when overflow is a program error.

multiply#

pub fn multiply(left: isize, right: isize) -> isize

Returns left * right and traps if the result is outside the isize range. Use this function when overflow is a program error.

divide#

pub fn divide(left: isize, right: isize) -> isize

Returns left / right, rounded toward zero. Traps if right is zero or MIN is divided by -1. Use this function when an invalid quotient is a program error.

remainder#

pub fn remainder(left: isize, right: isize) -> isize

Returns the remainder with the sign of left. Traps if right is zero or MIN is divided by -1. Use this function when invalid division is a program error.

bitAnd#

pub fn bitAnd(left: isize, right: isize) -> isize

Returns the bitwise AND of left and right.

bitOr#

pub fn bitOr(left: isize, right: isize) -> isize

Returns the bitwise OR of left and right.

bitXor#

pub fn bitXor(left: isize, right: isize) -> isize

Returns the bitwise exclusive OR of left and right.

bitNot#

pub fn bitNot(value: isize) -> isize

Returns value with each bit inverted.

shiftLeft#

pub fn shiftLeft(left: isize, right: isize) -> isize

Shifts left bits left by right positions. Traps if right is negative or not less than BITS.

shiftRight#

pub fn shiftRight(left: isize, right: isize) -> isize

Shifts left bits right by right positions and preserves its sign. Traps if right is negative or not less than BITS.

rotateLeft#

pub fn rotateLeft(left: isize, right: isize) -> isize

Rotates the bits of left left by right positions. The count is reduced modulo BITS, so each count is valid.

rotateRight#

pub fn rotateRight(left: isize, right: isize) -> isize

Rotates the bits of left right by right positions. The count is reduced modulo BITS, so each count is valid.

countOnes#

pub fn countOnes(value: isize) -> u32

Returns the number of one bits in the two's complement form of value.

leadingZeros#

pub fn leadingZeros(value: isize) -> u32

Returns the number of zero bits above the highest one bit of the two's complement form of value. Returns BITS for zero and 0 for a negative value.

trailingZeros#

pub fn trailingZeros(value: isize) -> u32

Returns the number of zero bits below the lowest one bit of value. Returns BITS for zero.

wrappingAdd#

pub fn wrappingAdd(left: isize, right: isize) -> isize

Returns left + right, wrapped to the isize range. Use this function for deliberate modulo arithmetic.

wrappingSubtract#

pub fn wrappingSubtract(left: isize, right: isize) -> isize

Returns left - right, wrapped to the isize range. Use this function for deliberate modulo arithmetic.

wrappingMultiply#

pub fn wrappingMultiply(left: isize, right: isize) -> isize

Returns left * right, wrapped to the isize range. Use this function for deliberate modulo arithmetic.

saturatingAdd#

pub fn saturatingAdd(left: isize, right: isize) -> isize

Returns left + right, clamped to MIN or MAX. Use this function when a boundary value is the required overflow result.

saturatingSubtract#

pub fn saturatingSubtract(left: isize, right: isize) -> isize

Returns left - right, clamped to MIN or MAX. Use this function when a boundary value is the required overflow result.

saturatingMultiply#

pub fn saturatingMultiply(left: isize, right: isize) -> isize

Returns left * right, clamped to MIN or MAX. Use this function when a boundary value is the required overflow result.

multiplyHigh#

pub fn multiplyHigh(left: isize, right: isize) -> isize

Returns the high half of the exact double-width product left * right. It never overflows.

When to use#

Use this function with wrappingMultiply, which returns the low half, when an algorithm needs the full product, such as multi-word arithmetic, multiply-shift hashing, or division by a precomputed reciprocal.

Details#

The width is the target word: the high 64 bits of a 128-bit product on a 64-bit target, and the high 32 bits of a 64-bit product on a 32-bit target.

The product is signed, so the high half carries its sign: multiplyHigh(-1, 1) is -1. The full product is the high half times 2 to the power of the word width, plus the low half read as unsigned bits.

checkedAdd#

pub fn checkedAdd(left: isize, right: isize) -> Option<isize>

Returns Some with left + right, or None if the result is outside the isize range. Use this function when overflow is input data.

checkedSubtract#

pub fn checkedSubtract(left: isize, right: isize) -> Option<isize>

Returns Some with left - right, or None if the result is outside the isize range. Use this function when overflow is input data.

checkedMultiply#

pub fn checkedMultiply(left: isize, right: isize) -> Option<isize>

Returns Some with left * right, or None if the result is outside the isize range. Use this function when overflow is input data.

checkedDivide#

pub fn checkedDivide(left: isize, right: isize) -> Option<isize>

Returns Some with left / right, or None if right is zero or MIN is divided by -1. Use this function when an invalid quotient is input data.

checkedRemainder#

pub fn checkedRemainder(left: isize, right: isize) -> Option<isize>

Returns Some with the remainder, or None if right is zero or MIN is divided by -1. Use this function when invalid division is input data.

equals#

pub fn equals(left: isize, right: isize) -> bool

Returns true if left and right are equal.

notEquals#

pub fn notEquals(left: isize, right: isize) -> bool

Returns true if left and right are not equal.

lessThan#

pub fn lessThan(left: isize, right: isize) -> bool

Returns true if left is less than right.

lessOrEqual#

pub fn lessOrEqual(left: isize, right: isize) -> bool

Returns true if left is less than or equal to right.

greaterThan#

pub fn greaterThan(left: isize, right: isize) -> bool

Returns true if left is greater than right.

greaterOrEqual#

pub fn greaterOrEqual(left: isize, right: isize) -> bool

Returns true if left is greater than or equal to right.

parse#

pub fn parse(text: string) -> Result<isize, ParseError>

Returns the isize value of the decimal text text, or a ParseError.

Details#

The complete text must be one decimal number, with an optional leading -. This function does not skip spaces and does not accept digit separators.

Errors#

• ParseError with reason silk.text.format.NotANumber if text is empty, starts with +, contains a byte that is not a digit, or has bytes after the number. offset gives the byte position where the read stopped.

• ParseError with reason silk.text.format.OutOfRange if the number is outside the range of isize on the target.

Category: Numbers.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.