UInt32

public struct UInt32 { /* private fields */ }

A 32-bit unsigned integer.

UInt32 is the 32-bit member of the integer family. The same surface area is provided across all widths; switch widths to trade range for memory or to match an FFI ABI. Arithmetic wraps on overflow by default — use the *Checked variants for overflow detection or *Saturating to clamp to minValue/maxValue. The type is FFISafe and lays out as a single lang.i32 so it can cross C boundaries unchanged.

Examples

let a: Int64 = 100;
let b = a + 50;        // 150
let c = a * 2;         // 200
let d = a.addChecked(Int64.maxValue);  // None (overflow detected)

// Bit twiddling
(0b1010).countOnes      // 2
(1).shiftLeft(by: 4)    // 16
(-1).leadingZeros       // 0  (all bits set)

Representation

A single lang.i32 field. No padding, no headers — bit-identical to the corresponding C type.

Properties

public static var bitWidth: Int64 { get }

The width in bits (32). Useful for shift bounds and bit-walks.

public var byteSwapped: UInt32 { get }

Value with its byte order reversed. Use to convert between big- and little-endian; lowered to a bswap intrinsic.

public var countOnes: Int64 { get }

Population count — the number of 1 bits in the binary representation.

Lowered to a popcount intrinsic where the target supports it.

Examples

(0b1010).countOnes;  // 2
(0b1111).countOnes;  // 4
(0).countOnes;       // 0

public var countZeros: Int64 { get }

Complement of countOnes: equal to bitWidth - countOnes.

public var isNegative: Bool { get }

Always false — unsigned types cannot be negative.

public var isPositive: Bool { get }

True when self > 0.

public var isPowerOfTwo: Bool { get }

True when the value is a positive power of two (2^k for k >= 0).

Zero and negatives are excluded. Cheap branchless test built on x & (x - 1) == 0.

Examples

(1).isPowerOfTwo;   // true  (2^0)
(4).isPowerOfTwo;   // true  (2^2)
(3).isPowerOfTwo;   // false
(0).isPowerOfTwo;   // false

public var isZero: Bool { get }

True when self == 0.

public var leadingZeros: Int64 { get }

Number of leading zero bits, counting from the most-significant end.

For zero, returns bitWidth.

Examples

(1).leadingZeros;   // bitWidth - 1
(0).leadingZeros;   // bitWidth

public static var maxValue: UInt32 { get }

The largest representable value. This is 2^32 - 1 (4_294_967_295).

public static var minValue: UInt32 { get }

The smallest representable value. This is always 0 for unsigned types. Note that for signed types minValue.negate() overflows back to itself; use negateChecked() if you need to detect that.

public var raw: lang.i32

The underlying primitive lang.i32 value. Exposed for FFI and intrinsic use; prefer the typed surface for everything else.

public var sign: UInt32 { get }

Sign as a UInt32: 0 for zero, 1 otherwise (unsigned types have no negative values).

public var trailingZeros: Int64 { get }

Number of trailing zero bits. Equal to log2(self & -self) for non-zero values; returns bitWidth for zero. Useful for finding the largest power of two dividing the value.

Initializers

public init()

Creates the zero value, satisfying Defaultable.

Examples

let n = Int64();   // 0

public init[S](fromBytes: S) where S: Slice[UInt8]

Reassembles a UInt32 from 4 bytes in native byte order. Returns null if the input is not exactly 4 bytes long.

public init[S](fromBytesBigEndian: S) where S: Slice[UInt8]

Reassembles a UInt32 from 4 bytes in big-endian order. Returns null if the input is not exactly 4 bytes long.

public init[S](fromBytesLittleEndian: S) where S: Slice[UInt8]

Reassembles a UInt32 from 4 bytes in little-endian order. Returns null if the input is not exactly 4 bytes long.

public init(from: Int8)

Converts from Int8. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: Int16)

Converts from Int16. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: Int32)

Converts from Int32. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: Int64)

Converts from Int64. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: UInt8)

Converts from UInt8. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: UInt16)

Converts from UInt16. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

public init(from: UInt64)

Converts from UInt64. Narrowing conversions truncate the high bits; signed→unsigned reinterprets the bit pattern.

init(raw: lang.i32)

Wraps an existing lang.i32 without conversion. Internal constructor used by intrinsics; not part of the public API.

public init(intLiteral: lang.i64)

Compiler-emitted bridge that turns an integer literal into a UInt32.

You will rarely call this directly — write the literal and let the ExpressibleByIntLiteral protocol pick it up. For widths smaller than 64 bits the literal is truncated with lang.cast_i64_i32.

Examples

let n: Int64 = 42;            // implicit

public init(parsing: String)

Parses a base-10 unsigned integer literal, optionally prefixed with +. A leading - is rejected. Returns null for an empty string, a non-digit character, or a value that does not fit in UInt32.

Examples

let n = UInt32(parsing: "42");   // Some(42)
let bad = UInt32(parsing: "-1"); // null (no sign for unsigned)

public init(parsing: String, radix: Int64)

Parses an unsigned integer in radix (base 2-36 inclusive). Letters a-z are case-insensitive and represent digit values 10-35. A leading + is allowed but a leading - is rejected. Returns null for an out-of-range radix, an empty string, an unrecognised digit, or a value that overflows UInt32.

Examples

let n = UInt32(parsing: "ff", radix: 16);      // Some(255 if it fits, else None)
let m = UInt32(parsing: "101010", radix: 2);   // Some(42)

Methods

public func addChecked(UInt32) -> UInt32?

Wrapping addition that returns None on overflow.

public func addSaturating(UInt32) -> UInt32

Addition that clamps to maxValue on overflow.

public func clamp(UInt32, UInt32) -> UInt32

Clamps self into [min, max]. Caller is responsible for ensuring min <= max; otherwise the result is undefined.

Examples

(5).clamp(0, 10);    // 5
(-5).clamp(0, 10);   // 0
(15).clamp(0, 10);   // 10

public func divideChecked(UInt32) -> UInt32?

Division that returns None for divide-by-zero.

public consuming func divideUnchecked(consuming UInt32) -> UInt32

self / other without the divide-by-zero and minValue / -1 guards — the bare hardware divide. Faster in hot loops, but undefined behaviour if other == 0 or (for signed types) self == minValue and other == -1. The caller must guarantee a valid divisor. Prefer divide everywhere correctness matters; this is the arr(unchecked:) of arithmetic.

Safety

UB when other == 0, or signed minValue / -1.

public func gcd(UInt32) -> UInt32

Greatest common divisor via Euclidean algorithm. For signed types the inputs are taken absolute first; the result is always non-negative.

Examples

(12).gcd(8);   // 4
(17).gcd(5);   // 1   (coprime)
(-12).gcd(8);  // 4

public func lcm(UInt32) -> UInt32

Least common multiple, computed as |self| / gcd(self, other) * |other| to avoid intermediate overflow. Returns zero if either input is zero.

Examples

(4).lcm(6);   // 12
(3).lcm(5);   // 15
(0).lcm(7);   // 0

public consuming func moduloUnchecked(consuming UInt32) -> UInt32

self % other without the divide-by-zero and minValue % -1 guards. Same safety contract as divideUnchecked.

Safety

UB when other == 0, or signed minValue % -1.

public func multiplyChecked(UInt32) -> UInt32?

Wrapping multiplication that returns None on overflow.

public func multiplySaturating(UInt32) -> UInt32

Multiplication that clamps to maxValue on overflow.

public func pow(Int64) -> UInt32

Raises self to exponent via binary exponentiation. Wraps on overflow. Negative exponents return zero (integer truncation of the would-be fraction).

Examples

(2).pow(10);  // 1024
(3).pow(4);   // 81
(5).pow(-1);  // 0

public func rotateLeft(by: Int64) -> UInt32

Rotates bits left by count, modulo bitWidth. Bits shifted past the MSB re-enter at the LSB.

public func rotateRight(by: Int64) -> UInt32

Rotates bits right by count, modulo bitWidth. Mirror of rotateLeft.

public func subtractChecked(UInt32) -> UInt32?

Subtraction that returns None on underflow (other > self).

public func subtractSaturating(UInt32) -> UInt32

Subtraction that clamps to 0 on underflow (unsigned types cannot represent negative results).

public func toBytes() -> std.collections.Array[UInt8]

Splits this integer into 4 bytes in native (host) byte order. Use toBytesBigEndian / toBytesLittleEndian when serialising for a fixed wire format.

Examples

let bytes = UInt32.maxValue.toBytes();   // 4 bytes, host order

public func toBytesBigEndian() -> std.collections.Array[UInt8]

Splits this integer into 4 bytes in big-endian order (most significant byte first — i.e. network byte order).

public func toBytesLittleEndian() -> std.collections.Array[UInt8]

Splits this integer into 4 bytes in little-endian order (least significant byte first).

ImplementsSteppable

Methods

public func distance(to: UInt32) -> Int64

Number of successor() steps from self to other — other - self widened to Int64 (negative when other < self). O(1); lets closed ranges iterate with a counter instead of a "finished" flag.

public func predecessor() -> UInt32

Predecessor — self - 1. Wraps at minValue.

public func successor() -> UInt32

Successor — self + 1. Wraps at maxValue. Used by for-in over integer ranges.

ImplementsComparable

Associated Types

type Output = Bool

Methods

public func compare(UInt32) -> Ordering

Three-way comparison returning an Ordering. Signed types compare using two's-complement ordering; unsigned types use natural ordering.

Examples

(1).compare(2);   // .Less
(2).compare(2);   // .Equal
(3).compare(2);   // .Greater

public func greaterThan(Self) -> Bool

> derived from compare.

public func greaterThanOrEqual(Self) -> Bool

>= derived from compare.

public func isAtLeast(Self) -> Bool

start.. lower-bound check, derived from compare.

public func isAtMost(Self) -> Bool

..=end upper-bound check, derived from compare.

public func isBelow(Self) -> Bool

..<end upper-bound check, derived from compare.

public func lessThan(Self) -> Bool

< derived from compare.

public func lessThanOrEqual(Self) -> Bool

<= derived from compare.

ImplementsEquatable

Associated Types

type Output = Bool

Methods

public func equal(to: Self) -> Bool

Bridges Equal.equal(to:) to Equatable.isEqual(to:).

public func isEqual(to: UInt32) -> Bool

Bit-for-bit equality. Backs the == operator.

Examples

(42).isEqual(to: 42);  // true
42 == 42;               // true

public func notEqual(to: Self) -> Bool

Default !=: delegates to == so there's a single source of truth.

ImplementsMatchable

Methods

public func matches(UInt32) -> Bool

Pattern-matching hook for Matchable. Identical to isEqual.

ImplementsFormattable

Methods

public func format(into: mutating StringBuilder, FormatOptions)

Formats the integer directly into writer, honouring the supplied FormatOptions. Implements the Formattable protocol.

Examples

(42).format();                                           // "42"
(255).format(.{radix: 16});                     // "ff"
(255).format(.{radix: 16, uppercase: true});    // "FF"
(255).format(.{radix: 16, alternate: true});    // "0xff"
(42).format(.{radix: 2, alternate: true});      // "0b101010"
(42).format(.{width: .Some(5), fill: '0'});     // "00042"
(-42).format(.{sign: .Always});                 // "-42"

public func formatted(FormatOptions) -> String

Returns this value rendered as a String.

Convenience wrapper: creates a StringBuilder, calls format(into:), and returns the built string. Uses a distinct name to avoid overload-resolution ambiguity with format(into:).

ImplementsHashable

Methods

public func hash[H](into: mutating H) where H: Hasher

Feeds the raw bytes of this value into hasher. Endianness-agnostic only within a single process — do not persist hashes across builds.

ImplementsAddable

Properties

public static var zero: UInt32 { get }

The additive identity, 0.

Associated Types

type Output = UInt32

type Output = Range[UInt32]

type Output = ClosedRange[UInt32]

type Output = RangeFrom[UInt32]

type Output = RangeUpTo[UInt32]

type Output = RangeThrough[UInt32]

Methods

public consuming func add(consuming UInt32) -> UInt32

self + other, wrapping on overflow. Use addChecked to detect or addSaturating to clamp.

ImplementsSubtractable

Associated Types

type Output

Methods

public consuming func subtract(consuming UInt32) -> UInt32

self - other, wrapping on overflow.

ImplementsMultipliable

Properties

public static var one: UInt32 { get }

The multiplicative identity, 1.

Associated Types

type Output

Methods

public consuming func multiply(consuming UInt32) -> UInt32

self * other, wrapping on overflow.

ImplementsDivisible

Associated Types

type Output

Methods

public consuming func divide(consuming UInt32) -> UInt32

Truncating integer division (self / other). For signed types, minValue / -1 wraps; use divideChecked to detect.

Errors

Traps on division by zero (LLVM udiv/sdiv are UB on zero — the process aborts before producing a result).

ImplementsModulo

Associated Types

type Output

Methods

public consuming func modulo(consuming UInt32) -> UInt32

self % other — truncated remainder; the result has the sign of self for signed types.

init(from: From)

Creates an instance from value.

ImplementsExitable

Methods

consuming func report() -> ExitCode

Defined in lang/std/numeric/uint32.ks