index.nct

//! Integer and IEEE floating-point operations, conversion, and numeric text.

use /mem.TryAllocator
use /order.Ordering
use /string.String
see ./decimal.nct
see ./conversion.nct
see ./floating.nct
see ./float_big.nct
see ./float_parse.nct
see ./integer_bits.nct
see ./checked_arithmetic.nct
see ./scalar.nct
see ./tests.nct
see ./text.nct

/// Boolean truth value.
pub primitive type bool

/// IEEE 754 binary32 floating-point value.
pub primitive type f32

/// IEEE 754 binary64 floating-point value.
pub primitive type f64

/// Signed 8-bit integer.
pub primitive type i8

/// Signed 16-bit integer.
pub primitive type i16

/// Signed 32-bit integer.
pub primitive type i32

/// Signed 64-bit integer.
pub primitive type i64

/// Unsigned 8-bit integer.
pub primitive type u8

/// Unsigned 16-bit integer.
pub primitive type u16

/// Unsigned 32-bit integer.
pub primitive type u32

/// Unsigned 64-bit integer.
pub primitive type u64

/// Pointer-sized unsigned integer.
pub primitive type usize

/// Pointer-sized signed integer.
pub primitive type isize

/// Positive binary32 infinity.
pub const F32_INFINITY: f32 = 1.0f32 / 0.0f32

/// Negative binary32 infinity.
pub const F32_NEG_INFINITY: f32 = -1.0f32 / 0.0f32

/// One quiet binary32 NaN. Arithmetic does not promise to preserve this payload.
pub const F32_NAN: f32 = 0.0f32 / 0.0f32

/// Positive binary64 infinity.
pub const F64_INFINITY: f64 = 1.0 / 0.0

/// Negative binary64 infinity.
pub const F64_NEG_INFINITY: f64 = -1.0 / 0.0

/// One quiet binary64 NaN. Arithmetic does not promise to preserve this payload.
pub const F64_NAN: f64 = 0.0 / 0.0

construct f32 {
    /// Creates a binary32 value with exactly the supplied IEEE representation.
    pub noalloc func from_bits(bits: u32): Self

    /// Rounds a binary64 value to binary32, or returns none if a finite value leaves binary32's
    /// finite nonzero range.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete locale-independent decimal or canonical non-finite spelling.
    pub func parse(text: &str): Self?

    /// Parses the same spelling with recoverable temporary allocation.
    pub func try_parse(allocator: &+TryAllocator, text: &str): Self?!
}

construct f64 {
    /// Creates a binary64 value with exactly the supplied IEEE representation.
    pub noalloc func from_bits(bits: u64): Self

    /// Parses one complete locale-independent decimal or canonical non-finite spelling.
    pub func parse(text: &str): Self?

    /// Parses the same spelling with recoverable temporary allocation.
    pub func try_parse(allocator: &+TryAllocator, text: &str): Self?!
}

instance f32 {
    /// Returns the exact stored IEEE representation.
    pub noalloc method self.to_bits(): u32

    /// Reports whether this value is a NaN.
    pub noalloc method self.is_nan(): bool

    /// Reports whether this value is positive or negative infinity.
    pub noalloc method self.is_infinite(): bool

    /// Reports whether this value is finite.
    pub noalloc method self.is_finite(): bool

    /// Reports whether this value is either sign of zero.
    pub noalloc method self.is_zero(): bool

    /// Reports whether this finite nonzero value uses the normal representation.
    pub noalloc method self.is_normal(): bool

    /// Reports whether this value uses the subnormal representation.
    pub noalloc method self.is_subnormal(): bool

    /// Reports whether the IEEE sign bit is set, including for zero and NaN.
    pub noalloc method self.is_sign_negative(): bool

    /// Reports whether the IEEE sign bit is clear, including for zero and NaN.
    pub noalloc method self.is_sign_positive(): bool

    /// Clears the IEEE sign bit without changing the payload.
    pub noalloc method self.abs(): Self

    /// Rounds toward negative infinity.
    pub noalloc method self.floor(): Self

    /// Rounds toward positive infinity.
    pub noalloc method self.ceil(): Self

    /// Rounds toward zero.
    pub noalloc method self.trunc(): Self

    /// Rounds to the nearest integer, choosing the even value at a tie.
    pub noalloc method self.round_ties_even(): Self

    /// Compares every IEEE representation in a deterministic total order.
    pub noalloc method self.total_compare(other: Self): Ordering

    /// Returns the shortest decimal spelling that parses to the same IEEE value.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance f64 {
    /// Returns the exact stored IEEE representation.
    pub noalloc method self.to_bits(): u64

    /// Reports whether this value is a NaN.
    pub noalloc method self.is_nan(): bool

    /// Reports whether this value is positive or negative infinity.
    pub noalloc method self.is_infinite(): bool

    /// Reports whether this value is finite.
    pub noalloc method self.is_finite(): bool

    /// Reports whether this value is either sign of zero.
    pub noalloc method self.is_zero(): bool

    /// Reports whether this finite nonzero value uses the normal representation.
    pub noalloc method self.is_normal(): bool

    /// Reports whether this value uses the subnormal representation.
    pub noalloc method self.is_subnormal(): bool

    /// Reports whether the IEEE sign bit is set, including for zero and NaN.
    pub noalloc method self.is_sign_negative(): bool

    /// Reports whether the IEEE sign bit is clear, including for zero and NaN.
    pub noalloc method self.is_sign_positive(): bool

    /// Clears the IEEE sign bit without changing the payload.
    pub noalloc method self.abs(): Self

    /// Rounds toward negative infinity.
    pub noalloc method self.floor(): Self

    /// Rounds toward positive infinity.
    pub noalloc method self.ceil(): Self

    /// Rounds toward zero.
    pub noalloc method self.trunc(): Self

    /// Rounds to the nearest integer, choosing the even value at a tie.
    pub noalloc method self.round_ties_even(): Self

    /// Compares every IEEE representation in a deterministic total order.
    pub noalloc method self.total_compare(other: Self): Ordering

    /// Returns the shortest decimal spelling that parses to the same IEEE value.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

construct i8 {
    /// Creates a signed integer with exactly the supplied two's-complement representation.
    pub noalloc notrap func from_bits(bits: u8): Self

    /// Converts an integral binary64 value when it is representable as `i8`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete signed decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct i16 {
    /// Creates a signed integer with exactly the supplied two's-complement representation.
    pub noalloc notrap func from_bits(bits: u16): Self

    /// Converts an integral binary64 value when it is representable as `i16`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete signed decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct i32 {
    /// Creates a signed integer with exactly the supplied two's-complement representation.
    pub noalloc notrap func from_bits(bits: u32): Self

    /// Converts an integral binary64 value when it is representable as `i32`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete signed decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct i64 {
    /// Creates a signed integer with exactly the supplied two's-complement representation.
    pub noalloc notrap func from_bits(bits: u64): Self

    /// Converts an integral binary64 value when it is representable as `i64`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete signed decimal integer.
    pub noalloc func parse(text: &str): Self?
}

instance i8 {
    /// Adds two values, or returns none when the mathematical result is outside `i8`.
    pub noalloc notrap method self.checked_add(other: i8): i8?

    /// Subtracts two values, or returns none when the mathematical result is outside `i8`.
    pub noalloc notrap method self.checked_sub(other: i8): i8?

    /// Multiplies two values, or returns none when the mathematical result is outside `i8`.
    pub noalloc notrap method self.checked_mul(other: i8): i8?

    /// Returns the exact stored two's-complement representation.
    pub noalloc notrap method self.to_bits(): u8
}

instance i16 {
    /// Adds two values, or returns none when the mathematical result is outside `i16`.
    pub noalloc notrap method self.checked_add(other: i16): i16?

    /// Subtracts two values, or returns none when the mathematical result is outside `i16`.
    pub noalloc notrap method self.checked_sub(other: i16): i16?

    /// Multiplies two values, or returns none when the mathematical result is outside `i16`.
    pub noalloc notrap method self.checked_mul(other: i16): i16?

    /// Returns the exact stored two's-complement representation.
    pub noalloc notrap method self.to_bits(): u16
}

instance i32 {
    /// Adds two values, or returns none when the mathematical result is outside `i32`.
    pub noalloc notrap method self.checked_add(other: i32): i32?

    /// Subtracts two values, or returns none when the mathematical result is outside `i32`.
    pub noalloc notrap method self.checked_sub(other: i32): i32?

    /// Multiplies two values, or returns none when the mathematical result is outside `i32`.
    pub noalloc notrap method self.checked_mul(other: i32): i32?

    /// Returns the exact stored two's-complement representation.
    pub noalloc notrap method self.to_bits(): u32
}

instance i64 {
    /// Adds two values, or returns none when the mathematical result is outside `i64`.
    pub noalloc notrap method self.checked_add(other: i64): i64?

    /// Subtracts two values, or returns none when the mathematical result is outside `i64`.
    pub noalloc notrap method self.checked_sub(other: i64): i64?

    /// Multiplies two values, or returns none when the mathematical result is outside `i64`.
    pub noalloc notrap method self.checked_mul(other: i64): i64?

    /// Returns the exact stored two's-complement representation.
    pub noalloc notrap method self.to_bits(): u64
}

construct isize {
    /// Converts an integral binary64 value when it is representable as `isize`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete signed decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct u8 {
    /// Converts an unsigned value when it is representable as `u8`.
    pub noalloc func from_u64(value: u64): Self?

    /// Converts an integral binary64 value when it is representable as `u8`.
    pub noalloc func from_f64(value: f64): Self?

    /// Keeps the low eight bits of a value.
    pub noalloc func truncate(value: u64): Self

    /// Parses one complete unsigned decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct u16 {
    /// Converts an integral binary64 value when it is representable as `u16`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete unsigned decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct u32 {
    /// Converts an unsigned value when it is representable as `u32`.
    pub noalloc func from_u64(value: u64): Self?

    /// Converts an integral binary64 value when it is representable as `u32`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete unsigned decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct u64 {
    /// Converts an integral binary64 value when it is representable as `u64`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete unsigned decimal integer.
    pub noalloc func parse(text: &str): Self?
}

construct usize {
    /// Converts an integral binary64 value when it is representable as `usize`.
    pub noalloc func from_f64(value: f64): Self?

    /// Parses one complete unsigned decimal integer.
    pub noalloc func parse(text: &str): Self?
}

instance i8 {
    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance i16 {
    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance i32 {
    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance i64 {
    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance isize {
    /// Adds two values, or returns none when the mathematical result is outside `isize`.
    pub noalloc notrap method self.checked_add(other: isize): isize?

    /// Subtracts two values, or returns none when the mathematical result is outside `isize`.
    pub noalloc notrap method self.checked_sub(other: isize): isize?

    /// Multiplies two values, or returns none when the mathematical result is outside `isize`.
    pub noalloc notrap method self.checked_mul(other: isize): isize?

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance u64 {
    /// Adds two values, or returns none when the mathematical result exceeds `u64`.
    pub noalloc notrap method self.checked_add(other: u64): u64?

    /// Subtracts two values, or returns none when the mathematical result is negative.
    pub noalloc notrap method self.checked_sub(other: u64): u64?

    /// Multiplies two values, or returns none when the mathematical result exceeds `u64`.
    pub noalloc notrap method self.checked_mul(other: u64): u64?

    /// Adds two values modulo 2^64.
    pub noalloc notrap method self.wrapping_add(other: u64): u64

    /// Subtracts two values modulo 2^64.
    pub noalloc notrap method self.wrapping_sub(other: u64): u64

    /// Multiplies two values modulo 2^64.
    pub noalloc notrap method self.wrapping_mul(other: u64): u64

    /// Returns the high half of the full 128-bit unsigned product.
    pub noalloc notrap method self.multiply_high(other: u64): u64

    /// Returns the bitwise conjunction of two values.
    pub noalloc notrap method self.bit_and(other: u64): u64

    /// Returns the bitwise disjunction of two values.
    pub noalloc notrap method self.bit_or(other: u64): u64

    /// Returns the bitwise exclusive OR of two values.
    pub noalloc notrap method self.bit_xor(other: u64): u64

    /// Rotates the bits right; only the low six bits of amount are significant.
    pub noalloc notrap method self.rotate_right(amount: u64): u64

    /// Returns the number of zero bits before the most-significant set bit, or 64 for zero.
    pub noalloc notrap method self.leading_zeros(): u64

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance u8 {
    /// Adds two values, or returns none when the mathematical result exceeds `u8`.
    pub noalloc notrap method self.checked_add(other: u8): u8?

    /// Subtracts two values, or returns none when the mathematical result is negative.
    pub noalloc notrap method self.checked_sub(other: u8): u8?

    /// Multiplies two values, or returns none when the mathematical result exceeds `u8`.
    pub noalloc notrap method self.checked_mul(other: u8): u8?

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance u16 {
    /// Adds two values, or returns none when the mathematical result exceeds `u16`.
    pub noalloc notrap method self.checked_add(other: u16): u16?

    /// Subtracts two values, or returns none when the mathematical result is negative.
    pub noalloc notrap method self.checked_sub(other: u16): u16?

    /// Multiplies two values, or returns none when the mathematical result exceeds `u16`.
    pub noalloc notrap method self.checked_mul(other: u16): u16?

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance u32 {
    /// Adds two values, or returns none when the mathematical result exceeds `u32`.
    pub noalloc notrap method self.checked_add(other: u32): u32?

    /// Subtracts two values, or returns none when the mathematical result is negative.
    pub noalloc notrap method self.checked_sub(other: u32): u32?

    /// Multiplies two values, or returns none when the mathematical result exceeds `u32`.
    pub noalloc notrap method self.checked_mul(other: u32): u32?

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}

instance usize {
    /// Adds two counts, or returns none when the mathematical result exceeds `usize`.
    pub noalloc notrap method self.checked_add(other: usize): usize?

    /// Subtracts two counts, or returns none when the mathematical result is negative.
    pub noalloc notrap method self.checked_sub(other: usize): usize?

    /// Multiplies two counts, or returns none when the mathematical result exceeds `usize`.
    pub noalloc notrap method self.checked_mul(other: usize): usize?

    /// Returns the shortest ordinary decimal spelling.
    pub method self.to_string(): String

    /// Returns the same spelling using a recoverable allocator.
    pub method self.try_to_string(allocator: &+TryAllocator): String! from allocator
}