An integer type with a binary representation.
SDK
- Xcode 9.0+
Framework
- Swift Standard Library
Declaration
protocol BinaryInteger where Self.Magnitude : BinaryOverview
The Binary protocol is the basis for all the integer types provided by the standard library. All of the standard library’s integer types, such as Int and UInt32, conform to Binary.
Converting Between Numeric Types
You can create new instances of a type that conforms to the Binary protocol from a floating-point number or another binary integer of any type. The Binary protocol provides initializers for four different kinds of conversion.
Range-Checked Conversion
You use the default init(_:) initializer to create a new instance when you’re sure that the value passed is representable in the new type. For example, an instance of Int16 can represent the value 500, so the first conversion in the code sample below succeeds. That same value is too large to represent as an Int8 instance, so the second conversion fails, triggering a runtime error.
let x: Int = 500
let y = Int16(x)
// y == 500
let z = Int8(x)
// Error: Not enough bits to represent...
When you create a binary integer from a floating-point value using the default initializer, the value is rounded toward zero before the range is checked. In the following example, the value 127 is rounded to 127, which is representable by the Int8 type. 128 is rounded to 128, which is not representable as an Int8 instance, triggering a runtime error.
let e = Int8(127.75)
// e == 127
let f = Int8(128.25)
// Error: Double value cannot be converted...
Exact Conversion
Use the init?(exactly:) initializer to create a new instance after checking whether the passed value is representable. Instead of trapping on out-of-range values, using the failable init?(exactly:) initializer results in nil.
let x = Int16(exactly: 500)
// x == Optional(500)
let y = Int8(exactly: 500)
// y == nil
When converting floating-point values, the init?(exactly:) initializer checks both that the passed value has no fractional part and that the value is representable in the resulting type.
let e = Int8(exactly: 23.0) // integral value, representable
// e == Optional(23)
let f = Int8(exactly: 23.75) // fractional value, representable
// f == nil
let g = Int8(exactly: 500.0) // integral value, nonrepresentable
// g == nil
Clamping Conversion
Use the init(clamping:) initializer to create a new instance of a binary integer type where out-of-range values are clamped to the representable range of the type. For a type T, the resulting value is in the range T.
let x = Int16(clamping: 500)
// x == 500
let y = Int8(clamping: 500)
// y == 127
let z = UInt8(clamping: -500)
// z == 0
Bit Pattern Conversion
Use the init(truncating initializer to create a new instance with the same bit pattern as the passed value, extending or truncating the value’s representation as necessary. Note that the value may not be preserved, particularly when converting between signed to unsigned integer types or when the destination type has a smaller bit width than the source type. The following example shows how extending and truncating work for nonnegative integers:
let q: Int16 = 850
// q == 0b00000011_01010010
let r = Int8(truncatingIfNeeded: q) // truncate 'q' to fit in 8 bits
// r == 82
// == 0b01010010
let s = Int16(truncatingIfNeeded: r) // extend 'r' to fill 16 bits
// s == 82
// == 0b00000000_01010010
Any padding is performed by sign-extending the passed value. When nonnegative integers are extended, the result is padded with zeroes. When negative integers are extended, the result is padded with ones. This example shows several extending conversions of a negative value—note that negative values are sign-extended even when converting to an unsigned type.
let t: Int8 = -100
// t == -100
// t's binary representation == 0b10011100
let u = UInt8(truncatingIfNeeded: t)
// u == 156
// u's binary representation == 0b10011100
let v = Int16(truncatingIfNeeded: t)
// v == -100
// v's binary representation == 0b11111111_10011100
let w = UInt16(truncatingIfNeeded: t)
// w == 65436
// w's binary representation == 0b11111111_10011100
Comparing Across Integer Types
You can use relational operators, such as the less-than and equal-to operators (< and ==), to compare instances of different binary integer types. The following example compares instances of the Int, UInt, and UInt8 types:
let x: Int = -23
let y: UInt = 1_000
let z: UInt8 = 23
if x < y {
print("\(x) is less than \(y).")
}
// Prints "-23 is less than 1000."
if z > x {
print("\(z) is greater than \(x).")
}
// Prints "23 is greater than -23."