Protocol

# BinaryInteger

An integer type with a binary representation.

## Overview

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 floating-point number or another binary integer of any type. The `BinaryInteger` 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.

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.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.

#### 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`.

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.

#### 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.min...T.max`.

#### 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:

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.

### 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:

## Topics

### Associated Types

`associatedtype Words`

A type that represents the words of a binary integer.

Required.

### Initializers

`init()`

Creates a new value equal to zero.

`init<T>(T)`

Creates an integer from the given floating-point value, rounding toward zero.

Required. Default implementations provided.

`init<T>(T)`

Creates a new instance from the given integer.

Required.

`init<T>(clamping: T)`

Creates a new instance with the representable value that’s closest to the given integer.

Required. Default implementation provided.

`init?<T>(exactly: T)`

Creates an integer from the given floating-point value, if it can be represented exactly.

Required. Default implementations provided.

`init<T>(truncatingIfNeeded: T)`

Creates a new instance from the bit pattern of the given instance by sign-extending or truncating to fit this type.

Required. Default implementation provided.

### Instance Properties

`var bitWidth: Int`

The number of bits in the current binary representation of this value.

Required.

`var trailingZeroBitCount: Int`

The number of trailing zeros in this value’s binary representation.

Required.

`var words: Self.Words`

A collection containing the words of this value’s binary representation, in order from the least significant to most significant.

Required.

### Type Properties

`static var isSigned: Bool`

A Boolean value indicating whether this type is a signed integer type.

Required. Default implementations provided.

### Instance Methods

`func isMultiple(of: Self) -> Bool`

Returns `true` if this value is a multiple of the given value, and `false` otherwise.

Required. Default implementations provided.

`func quotientAndRemainder(dividingBy: Self) -> (quotient: Self, remainder: Self)`

Returns the quotient and remainder of this value divided by the given value.

Required. Default implementation provided.

`func signum() -> Self`

Returns `-1` if this value is negative and `1` if it’s positive; otherwise, `0`.

Required. Default implementation provided.

### Operator Functions

`static func != <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the two given values are not equal.

`static func % (Self, Self) -> Self`

Returns the remainder of dividing the first value by the second.

Required.

`static func %= (inout Self, Self)`

Divides the first value by the second and stores the remainder in the left-hand-side variable.

Required.

`static func & (Self, Self) -> Self`

Returns the result of performing a bitwise AND operation on the two given values.

Required. Default implementation provided.

`static func &= (inout Self, Self)`

Stores the result of performing a bitwise AND operation on the two given values in the left-hand-side variable.

Required.

`static func * (Self, Self) -> Self`

Multiplies two values and produces their product.

Required.

`static func *= (inout Self, Self)`

Multiplies two values and stores the result in the left-hand-side variable.

Required.

`static func + (Self, Self) -> Self`

Adds two values and produces their sum.

Required.

`static func += (inout Self, Self)`

Adds two values and stores the result in the left-hand-side variable.

Required.

`static func - (Self, Self) -> Self`

Subtracts one value from another and produces their difference.

Required.

`static func -= (inout Self, Self)`

Subtracts the second value from the first and stores the difference in the left-hand-side variable.

Required.

`static func / (Self, Self) -> Self`

Returns the quotient of dividing the first value by the second.

Required.

`static func /= (inout Self, Self)`

Divides the first value by the second and stores the quotient in the left-hand-side variable.

Required.

`static func < <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

`static func << <RHS>(Self, RHS) -> Self`

Returns the result of shifting a value’s binary representation the specified number of digits to the left.

Required. Default implementations provided.

`static func <<= <RHS>(inout Self, RHS)`

Stores the result of shifting a value’s binary representation the specified number of digits to the left in the left-hand-side variable.

Required. Default implementation provided.

`static func <= (Self, Self) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is less than or equal to that of the second argument.

`static func <= <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is less than or equal to that of the second argument.

`static func == <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the two given values are equal.

`static func > <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is greater than that of the second argument.

`static func > (Self, Self) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is greater than that of the second argument.

`static func >= (Self, Self) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.

`static func >= <Other>(Self, Other) -> Bool`

Returns a Boolean value indicating whether the value of the first argument is greater than or equal to that of the second argument.

`static func >> <RHS>(Self, RHS) -> Self`

Returns the result of shifting a value’s binary representation the specified number of digits to the right.

Required. Default implementations provided.

`static func >>= <RHS>(inout Self, RHS)`

Stores the result of shifting a value’s binary representation the specified number of digits to the right in the left-hand-side variable.

Required. Default implementation provided.

`static func ^ (Self, Self) -> Self`

Returns the result of performing a bitwise XOR operation on the two given values.

Required. Default implementation provided.

`static func ^= (inout Self, Self)`

Stores the result of performing a bitwise XOR operation on the two given values in the left-hand-side variable.

Required.

`static func | (Self, Self) -> Self`

Returns the result of performing a bitwise OR operation on the two given values.

Required. Default implementation provided.

`static func |= (inout Self, Self)`

Stores the result of performing a bitwise OR operation on the two given values in the left-hand-side variable.

Required.

`static func ~ (Self) -> Self`

Returns the inverse of the bits set in the argument.

Required. Default implementation provided.

## Relationships

### Integer

`protocol FixedWidthInteger`

An integer type that uses a fixed size for every instance.

`protocol SignedInteger`

An integer type that can represent both positive and negative values.

`protocol UnsignedInteger`

An integer type that can represent only nonnegative values.