silk/isize

Pointer-width signed integers for offsets whose range follows the selected compilation target.

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

BITS, MIN, and MAX are selected from the target. Ordinary arithmetic, narrowing conversions, division by zero, and invalid shift counts trap. checked* returns Option, wrapping* uses arithmetic modulo the target width, and saturating* clamps at the target bound.

Decimal parse and toText use the selected target range; formatting allocates owned text.

Gotchas

Code that succeeds at a 64-bit boundary may 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.isize as isize

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

Import as isize with import silk.isize.

Public declarations: 60.

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.

toF64

pub fn toF64(value: isize) -> f64

Converts value to the nearest f64 value, with ties to even.

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.

rotateRight

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

Rotates the bits of left right by right positions.

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.

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 when left and right are equal.

notEquals

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

Returns true when left and right are not equal.

lessThan

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

Returns true when left is less than right.

lessOrEqual

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

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

greaterThan

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

Returns true when left is greater than right.

greaterOrEqual

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

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

toText

pub effect fn toText(value: isize) -> String ! OutOfMemoryError ? &mut Allocator

Renders the value as base-10 text in new owned storage. Allocation uses the required Allocator and can fail with OutOfMemoryError.

parse

pub fn parse(text: string) -> silk/result.Result<isize, silk/format.ParseError>

Reads the complete text as a signed decimal isize.

Details

A failure contains silk.format.NotANumber for empty text, a leading +, a non-digit, or trailing bytes. It contains silk.format.OutOfRange outside the target's isize range.