protocol BinaryInteger
An integer type with a binary representation.
Inheritance  CustomStringConvertible, Hashable, Numeric, Strideable 

Conforming Types  FixedWidthInteger, SignedInteger, UnsignedInteger 
Associated Types 
associatedtype Words

The BinaryInteger
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 BinaryInteger
.
Converting Between Numeric Types
You can create new instances of a type that conforms to the BinaryInteger
protocol from a floatingpoint number or another binary integer of any
type. The BinaryInteger
protocol provides initializers for four
different kinds of conversion.
RangeChecked 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 floatingpoint value using the
default initializer, the value is rounded toward zero before the range is
checked. In the following example, the value 127.75
is rounded to 127
,
which is representable by the Int8
type. 128.25
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
outofrange 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 floatingpoint 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 outofrange values are clamped to the representable
range of the type. For a type T
, the resulting value is in the range
T.min...T.max
.
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(truncatingIfNeeded:)
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 signextending 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 valuenote that negative values are signextended 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 lessthan and equalto
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."
Initializers
Creates an integer from the given floatingpoint value, rounding toward zero.
Any fractional part of the value passed as source
is removed, rounding
the value toward zero.
let x = Int(21.5)
// x == 21
let y = Int(21.5)
// y == 21
If source
is outside the bounds of this type after rounding toward
zero, a runtime error may occur.
let z = UInt(21.5)
// Error: ...the result would be less than UInt.min
 Parameter source: A floatingpoint value to convert to an integer.
source
must be representable in this type after rounding toward zero.
Declaration
init<T>(_ source: T) where T: BinaryFloatingPoint
Creates a new instance from the given integer.
If the value passed as source
is not representable in this type, a
runtime error may occur.
let x = 500 as Int
let y = Int32(x)
// y == 500
// 500 is not representable as a 'UInt32' instance
let z = UInt32(x)
// Error
 Parameter source: An integer to convert.
source
must be representable in this type.
Declaration
init<T>(_ source: T) where T: BinaryInteger
Creates a new instance with the representable value that's closest to the given integer.
If the value passed as source
is greater than the maximum representable
value in this type, the result is the type's max
value. If source
is
less than the smallest representable value in this type, the result is
the type's min
value.
In this example, x
is initialized as an Int8
instance by clamping
500
to the range 128...127
, and y
is initialized as a UInt
instance by clamping 500
to the range 0...UInt.max
.
let x = Int8(clamping: 500)
// x == 127
// x == Int8.max
let y = UInt(clamping: 500)
// y == 0
 Parameter source: An integer to convert to this type.
Declaration
init<T>(clamping source: T) where T: BinaryInteger
Creates a new instance from the bit pattern of the given instance by signextending or truncating to fit this type.
When the bit width of T
(the type of source
) is equal to or greater
than this type's bit width, the result is the truncated
leastsignificant bits of source
. For example, when converting a
16bit value to an 8bit type, only the lower 8 bits of source
are
used.
let p: Int16 = 500
// 'p' has a binary representation of 11111110_00001100
let q = Int8(truncatingIfNeeded: p)
// q == 12
// 'q' has a binary representation of 00001100
When the bit width of T
is less than this type's bit width, the result
is signextended to fill the remaining bits. That is, if source
is
negative, the result is padded with ones; otherwise, the result is
padded with zeros.
let u: Int8 = 21
// 'u' has a binary representation of 00010101
let v = Int16(truncatingIfNeeded: u)
// v == 21
// 'v' has a binary representation of 00000000_00010101
let w: Int8 = 21
// 'w' has a binary representation of 11101011
let x = Int16(truncatingIfNeeded: w)
// x == 21
// 'x' has a binary representation of 11111111_11101011
let y = UInt16(truncatingIfNeeded: w)
// y == 65515
// 'y' has a binary representation of 11111111_11101011
 Parameter source: An integer to convert to this type.
Declaration
init<T>(truncatingIfNeeded source: T) where T: BinaryInteger
Creates an integer from the given floatingpoint value, if it can be represented exactly.
If the value passed as source
is not representable exactly, the result
is nil
. In the following example, the constant x
is successfully
created from a value of 21.0
, while the attempt to initialize the
constant y
from 21.5
fails:
let x = Int(exactly: 21.0)
// x == Optional(21)
let y = Int(exactly: 21.5)
// y == nil
 Parameter source: A floatingpoint value to convert to an integer.
Declaration
init?<T>(exactly source: T) where T: BinaryFloatingPoint
Instance Variables
The number of bits in the current binary representation of this value.
This property is a constant for instances of fixedwidth integer types.
Declaration
var bitWidth: Int
The number of trailing zeros in this value's binary representation.
For example, in a fixedwidth integer type with a bitWidth
value of 8,
the number 8 has three trailing zeros.
let x = Int8(bitPattern: 0b1111_1000)
// x == 8
// x.trailingZeroBitCount == 3
If the value is zero, then trailingZeroBitCount
is equal to bitWidth
.
Declaration
var trailingZeroBitCount: Int
A collection containing the words of this value's binary representation, in order from the least significant to most significant.
Negative values are returned in two's complement representation, regardless of the type's underlying implementation.
Declaration
var words: Self.Words
Instance Methods
Returns true
if this value is a multiple of the given value, and false
otherwise.
For two integers a and b, a is a multiple of b if there exists a third integer q such that a = q*b. For example, 6 is a multiple of 3 because 6 = 2*3. Zero is a multiple of everything because 0 = 0*x for any integer x.
Two edge cases are worth particular attention:
 Parameter other: The value to test.
Declaration
func isMultiple(of other: Self) > Bool
Returns the quotient and remainder of this value divided by the given value.
Use this method to calculate the quotient and remainder of a division at the same time.
let x = 1_000_000
let (q, r) = x.quotientAndRemainder(dividingBy: 933)
// q == 1071
// r == 757
 Parameter rhs: The value to divide this value by.
Declaration
func quotientAndRemainder(dividingBy rhs: Self) > (quotient: Self, remainder: Self)
Returns 1
if this value is negative and 1
if it's positive;
otherwise, 0
.
Declaration
func signum() > Self
Type Variables
A Boolean value indicating whether this type is a signed integer type.
Signed integer types can represent both positive and negative values. Unsigned integer types can represent only nonnegative values.
Declaration
var isSigned: Bool
Type Methods
Returns the remainder of dividing the first value by the second.
The result of the remainder operator (%
) has the same sign as lhs
and
has a magnitude less than rhs.magnitude
.
let x = 22 % 5
// x == 2
let y = 22 % 5
// y == 2
let z = 22 % 5
// z == 2
For any two integers a
and b
, their quotient q
, and their remainder
r
, a == b * q + r
.
Declaration
static func %(lhs: Self, rhs: Self) > Self
Divides the first value by the second and stores the remainder in the lefthandside variable.
The result has the same sign as lhs
and has a magnitude less than
rhs.magnitude
.
var x = 22
x %= 5
// x == 2
var y = 22
y %= 5
// y == 2
var z = 22
z %= 5
// z == 2
Declaration
static func %=(lhs: inout Self, rhs: Self)
Returns the result of performing a bitwise AND operation on the two given values.
A bitwise AND operation results in a value that has each bit set to 1
where both of its arguments have that bit set to 1
. For example:
let x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
let z = x & y // 0b00000100
// z == 4
Declaration
static func &(lhs: Self, rhs: Self) > Self
Stores the result of performing a bitwise AND operation on the two given values in the lefthandside variable.
A bitwise AND operation results in a value that has each bit set to 1
where both of its arguments have that bit set to 1
. For example:
var x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
x &= y // 0b00000100
Declaration
static func &=(lhs: inout Self, rhs: Self)
Multiplies two values and produces their product.
The multiplication operator (*
) calculates the product of its two
arguments. For example:
2 * 3 // 6
100 * 21 // 2100
10 * 15 // 150
3.5 * 2.25 // 7.875
You cannot use *
with arguments of different types. To multiply values
of different types, convert one of the values to the other value's type.
let x: Int8 = 21
let y: Int = 1000000
Int(x) * y // 21000000
Declaration
override static func *(lhs: Self, rhs: Self) > Self
Multiplies two values and stores the result in the lefthandside variable.
Declaration
override static func *=(lhs: inout Self, rhs: Self)
Adds two values and produces their sum.
The addition operator (+
) calculates the sum of its two arguments. For
example:
1 + 2 // 3
10 + 15 // 5
15 + 5 // 20
21.5 + 3.25 // 24.75
You cannot use +
with arguments of different types. To add values of
different types, convert one of the values to the other value's type.
let x: Int8 = 21
let y: Int = 1000000
Int(x) + y // 1000021
Declaration
override static func +(lhs: Self, rhs: Self) > Self
Adds two values and stores the result in the lefthandside variable.
Declaration
override static func +=(lhs: inout Self, rhs: Self)
Subtracts one value from another and produces their difference.
The subtraction operator (
) calculates the difference of its two
arguments. For example:
8  3 // 5
10  5 // 15
100  5 // 105
10.5  100.0 // 89.5
You cannot use 
with arguments of different types. To subtract values
of different types, convert one of the values to the other value's type.
let x: UInt8 = 21
let y: UInt = 1000000
y  UInt(x) // 999979
Declaration
override static func (lhs: Self, rhs: Self) > Self
Subtracts the second value from the first and stores the difference in the lefthandside variable.
Declaration
override static func =(lhs: inout Self, rhs: Self)
Returns the quotient of dividing the first value by the second.
For integer types, any remainder of the division is discarded.
let x = 21 / 5
// x == 4
Declaration
static func /(lhs: Self, rhs: Self) > Self
Divides the first value by the second and stores the quotient in the lefthandside variable.
For integer types, any remainder of the division is discarded.
var x = 21
x /= 5
// x == 4
Declaration
static func /=(lhs: inout Self, rhs: Self)
Returns the result of shifting a value's binary representation the specified number of digits to the left.
The <<
operator performs a smart shift, which defines a result for a
shift of any value.
The following example defines x
as an instance of UInt8
, an 8bit,
unsigned integer type. If you use 2
as the righthandside value in an
operation on x
, the value is shifted left by two bits.
let x: UInt8 = 30 // 0b00011110
let y = x << 2
// y == 120 // 0b01111000
If you use 11
as rhs
, x
is overshifted such that all of its bits
are set to zero.
let z = x << 11
// z == 0 // 0b00000000
Using a negative value as rhs
is the same as performing a right shift
with abs(rhs)
.
let a = x << 3
// a == 3 // 0b00000011
let b = x >> 3
// b == 3 // 0b00000011
Declaration
static func <<<RHS>(lhs: Self, rhs: RHS) > Self where RHS: BinaryInteger
Stores the result of shifting a value's binary representation the specified number of digits to the left in the lefthandside variable.
The <<
operator performs a smart shift, which defines a result for a
shift of any value.
The following example defines x
as an instance of UInt8
, an 8bit,
unsigned integer type. If you use 2
as the righthandside value in an
operation on x
, the value is shifted left by two bits.
var x: UInt8 = 30 // 0b00011110
x <<= 2
// x == 120 // 0b01111000
If you use 11
as rhs
, x
is overshifted such that all of its bits
are set to zero.
var y: UInt8 = 30 // 0b00011110
y <<= 11
// y == 0 // 0b00000000
Using a negative value as rhs
is the same as performing a right shift
with abs(rhs)
.
var a: UInt8 = 30 // 0b00011110
a <<= 3
// a == 3 // 0b00000011
var b: UInt8 = 30 // 0b00011110
b >>= 3
// b == 3 // 0b00000011
Declaration
static func <<=<RHS>(lhs: inout Self, rhs: RHS) where RHS: BinaryInteger
Returns the result of shifting a value's binary representation the specified number of digits to the right.
The >>
operator performs a smart shift, which defines a result for a
shift of any value.
The following example defines x
as an instance of UInt8
, an 8bit,
unsigned integer type. If you use 2
as the righthandside value in an
operation on x
, the value is shifted right by two bits.
let x: UInt8 = 30 // 0b00011110
let y = x >> 2
// y == 7 // 0b00000111
If you use 11
as rhs
, x
is overshifted such that all of its bits
are set to zero.
let z = x >> 11
// z == 0 // 0b00000000
Using a negative value as rhs
is the same as performing a left shift
using abs(rhs)
.
let a = x >> 3
// a == 240 // 0b11110000
let b = x << 3
// b == 240 // 0b11110000
Right shift operations on negative values "fill in" the high bits with ones instead of zeros.
let q: Int8 = 30 // 0b11100010
let r = q >> 2
// r == 8 // 0b11111000
let s = q >> 11
// s == 1 // 0b11111111
Declaration
static func >><RHS>(lhs: Self, rhs: RHS) > Self where RHS: BinaryInteger
Stores the result of shifting a value's binary representation the specified number of digits to the right in the lefthandside variable.
The >>=
operator performs a smart shift, which defines a result for a
shift of any value.
The following example defines x
as an instance of UInt8
, an 8bit,
unsigned integer type. If you use 2
as the righthandside value in an
operation on x
, the value is shifted right by two bits.
var x: UInt8 = 30 // 0b00011110
x >>= 2
// x == 7 // 0b00000111
If you use 11
as rhs
, x
is overshifted such that all of its bits
are set to zero.
var y: UInt8 = 30 // 0b00011110
y >>= 11
// y == 0 // 0b00000000
Using a negative value as rhs
is the same as performing a left shift
using abs(rhs)
.
var a: UInt8 = 30 // 0b00011110
a >>= 3
// a == 240 // 0b11110000
var b: UInt8 = 30 // 0b00011110
b <<= 3
// b == 240 // 0b11110000
Right shift operations on negative values "fill in" the high bits with ones instead of zeros.
var q: Int8 = 30 // 0b11100010
q >>= 2
// q == 8 // 0b11111000
var r: Int8 = 30 // 0b11100010
r >>= 11
// r == 1 // 0b11111111
Declaration
static func >>=<RHS>(lhs: inout Self, rhs: RHS) where RHS: BinaryInteger
Returns the result of performing a bitwise XOR operation on the two given values.
A bitwise XOR operation, also known as an exclusive OR operation, results
in a value that has each bit set to 1
where one or the other but not
both of its arguments had that bit set to 1
. For example:
let x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
let z = x ^ y // 0b00001011
// z == 11
Declaration
static func ^(lhs: Self, rhs: Self) > Self
Stores the result of performing a bitwise XOR operation on the two given values in the lefthandside variable.
A bitwise XOR operation, also known as an exclusive OR operation, results
in a value that has each bit set to 1
where one or the other but not
both of its arguments had that bit set to 1
. For example:
var x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
x ^= y // 0b00001011
Declaration
static func ^=(lhs: inout Self, rhs: Self)
Returns the result of performing a bitwise OR operation on the two given values.
A bitwise OR operation results in a value that has each bit set to 1
where one or both of its arguments have that bit set to 1
. For
example:
let x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
let z = x  y // 0b00001111
// z == 15
Declaration
static func (lhs: Self, rhs: Self) > Self
Stores the result of performing a bitwise OR operation on the two given values in the lefthandside variable.
A bitwise OR operation results in a value that has each bit set to 1
where one or both of its arguments have that bit set to 1
. For
example:
var x: UInt8 = 5 // 0b00000101
let y: UInt8 = 14 // 0b00001110
x = y // 0b00001111
Declaration
static func =(lhs: inout Self, rhs: Self)
Returns the inverse of the bits set in the argument.
The bitwise NOT operator (~
) is a prefix operator that returns a value
in which all the bits of its argument are flipped: Bits that are 1
in
the argument are 0
in the result, and bits that are 0
in the argument
are 1
in the result. This is equivalent to the inverse of a set. For
example:
let x: UInt8 = 5 // 0b00000101
let notX = ~x // 0b11111010
Performing a bitwise NOT operation on 0 returns a value with every bit
set to 1
.
let allOnes = ~UInt8.min // 0b11111111
Complexity: O(1).
Declaration
prefix static func ~(x: Self) > Self
Default Implementations
Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.
This function is the only requirement of the Comparable
protocol. The
remainder of the relational operator functions are implemented by the
standard library for any type that conforms to Comparable
.
Declaration
@inlinable public static func <(x: Self, y: Self) > Bool
Returns a Boolean value indicating whether two values are equal.
Equality is the inverse of inequality. For any values a
and b
,
a == b
implies that a != b
is false
.
Declaration
@inlinable public static func ==(x: Self, y: Self) > Bool
The
Words
type must conform to theRandomAccessCollection
protocol with anElement
type ofUInt
andIndex
type of `Int.