silk/usize

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

Pointer-width unsigned integers for lengths, indices, capacities, and allocation sizes.

When to use

Use usize for values that index target memory or describe its layout. Use a fixed-width integer for serialized data, protocols, and persistent identifiers whose range must not change between 32-bit and 64-bit targets.

Details

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

ZERO and ONE provide typed values where an uncontextualized literal would be i32. Decimal parse uses the target's range. Use Format with Format.display for defaults or Format.displayWith for explicit options. Both operations stream through a mutable Writer without Allocator.

Gotchas

A value valid as usize on a 64-bit target can be out of range on a 32-bit target.

Examples

Keep a count within the target range

import silk.option { Option }

import silk.usize

pub fn main() -> i32 {
  let next = usize.checkedAdd(usize.MAX, usize.ONE)
  let recovered = move next
    |> Option.unwrapOr<usize>(42)
  return usize.toI32(recovered)
}

Import as usize with import silk.usize.

Public declarations: 58.

MAX

pub const MAX: usize

The largest usize value for the compilation target.

Details

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

MIN

pub const MIN: usize

The smallest usize value, which is zero at each pointer width.

BITS

pub const BITS: u32

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

ZERO

pub const ZERO: usize

The usize zero value for a count without a typed context.

ONE

pub const ONE: usize

The usize value one for a step or count that has no other type context.

toU8

pub fn toU8(value: usize) -> 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: usize) -> silk/option.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: usize) -> 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: usize) -> silk/option.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: usize) -> 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: usize) -> silk/option.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: usize) -> u64

Converts value exactly to u64. Every usize value is representable.

checkedToU64

pub fn checkedToU64(value: usize) -> silk/option.Option<u64>

Converts value exactly to u64 and returns Some. Every usize value is representable.

toUsize

pub fn toUsize(value: usize) -> usize

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

checkedToUsize

pub fn checkedToUsize(value: usize) -> silk/option.Option<usize>

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

toI8

pub fn toI8(value: usize) -> 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: usize) -> silk/option.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: usize) -> 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: usize) -> silk/option.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: usize) -> 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: usize) -> silk/option.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: usize) -> i64

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

checkedToI64

pub fn checkedToI64(value: usize) -> silk/option.Option<i64>

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

toIsize

pub fn toIsize(value: usize) -> isize

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

checkedToIsize

pub fn checkedToIsize(value: usize) -> silk/option.Option<isize>

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

toF32

pub fn toF32(value: usize) -> f32

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

toF64

pub fn toF64(value: usize) -> f64

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

add

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

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

subtract

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

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

multiply

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

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

divide

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

Returns left / right. Traps if right is zero. Use this function when a zero divisor is a program error.

remainder

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

Returns the remainder of left / right. Traps if right is zero. Use this function when a zero divisor is a program error.

bitAnd

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

Returns the bitwise AND of left and right.

bitOr

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

Returns the bitwise OR of left and right.

bitXor

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

Returns the bitwise exclusive OR of left and right.

bitNot

pub fn bitNot(value: usize) -> usize

Returns value with each bit inverted.

shiftLeft

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

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

shiftRight

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

Shifts left bits right by right positions and inserts zero bits. Traps if right is not less than BITS.

rotateLeft

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

Rotates the bits of left left by right positions.

rotateRight

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

Rotates the bits of left right by right positions.

wrappingAdd

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

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

wrappingSubtract

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

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

wrappingMultiply

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

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

saturatingAdd

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

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: usize, right: usize) -> usize

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: usize, right: usize) -> usize

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: usize, right: usize) -> silk/option.Option<usize>

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

checkedSubtract

pub fn checkedSubtract(left: usize, right: usize) -> silk/option.Option<usize>

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

checkedMultiply

pub fn checkedMultiply(left: usize, right: usize) -> silk/option.Option<usize>

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

checkedDivide

pub fn checkedDivide(left: usize, right: usize) -> silk/option.Option<usize>

Returns Some with left / right, or None if right is zero. Use this function when a zero divisor is input data.

checkedRemainder

pub fn checkedRemainder(left: usize, right: usize) -> silk/option.Option<usize>

Returns Some with the remainder, or None if right is zero. Use this function when a zero divisor is input data.

equals

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

Returns true when left and right are equal.

notEquals

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

Returns true when left and right are not equal.

lessThan

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

Returns true when left is less than right.

lessOrEqual

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

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

greaterThan

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

Returns true when left is greater than right.

greaterOrEqual

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

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

parse

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

Reads the complete text as an unsigned decimal usize.

Details

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