ProtocolSwift

FixedWidthInteger

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

protocol FixedWidthInteger : BinaryInteger, LosslessStringConvertible where Self.Magnitude : FixedWidthInteger, Self.Magnitude : UnsignedInteger, Self.Stride : FixedWidthInteger, Self.Stride : SignedInteger

Overview

The FixedWidthInteger protocol adds binary bitwise operations, bit shifts, and overflow handling to the operations supported by the BinaryInteger protocol.

Use the FixedWidthInteger protocol as a constraint or extension point when writing operations that depend on bit shifting, performing bitwise operations, catching overflows, or having access to the maximum or minimum representable value of a type. For example, the following code provides a binaryString property on every fixed-width integer that represents the number’s binary representation, split into 8-bit chunks.

extension FixedWidthInteger {
    var binaryString: String {
        var result: [String] = []
        for i in 0..<(Self.bitWidth / 8) {
            let byte = UInt8(truncatingIfNeeded: self >> (i * 8))
            let byteString = String(byte, radix: 2)
            let padding = String(repeating: "0",
                                 count: 8 - byteString.count)
            result.append(padding + byteString)
        }
        return "0b" + result.reversed().joined(separator: "_")
    }
}

print(Int16.max.binaryString)
// Prints "0b01111111_11111111"
print((101 as UInt8).binaryString)
// Prints "0b11001001"

The binaryString implementation uses the static bitWidth property and the right shift operator (>>), both of which are available to any type that conforms to the FixedWidthInteger protocol.

The next example declares a generic squared function, which accepts an instance x of any fixed-width integer type. The function uses the multipliedReportingOverflow(by:) method to multiply x by itself and check whether the result is too large to represent in the same type.

func squared<T: FixedWidthInteger>(_ x: T) -> T? {
    let (result, overflow) = x.multipliedReportingOverflow(by: x)
    if overflow {
        return nil
    }
    return result
}

let (x, y): (Int8, Int8) = (9, 123)
print(squared(x))
// Prints "Optional(81)"
print(squared(y))
// Prints "nil"

Conforming to the FixedWidthInteger Protocol

To make your own custom type conform to the FixedWidthInteger protocol, declare the required initializers, properties, and methods. The required methods that are suffixed with ReportingOverflow serve as the customization points for arithmetic operations. When you provide just those methods, the standard library provides default implementations for all other arithmetic methods and operators.

Requirements

Initializers

  • init(bigEndian: Self)

    Creates an integer from its big-endian representation, changing the byte order if necessary.

  • init(littleEndian: Self)

    Creates an integer from its little-endian representation, changing the byte order if necessary.

Type Properties

Instance Properties

Instance Methods

Operators

  • static func &<< (Self, Self) -> Self

    Returns the result of shifting a value’s binary representation the specified number of digits to the left, masking the shift amount to the type’s bit width.

  • static func &<<= (inout Self, Self)

    Returns the result of shifting a value’s binary representation the specified number of digits to the left, masking the shift amount to the type’s bit width, and stores the result in the left-hand-side variable.

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

    Returns the result of shifting a value’s binary representation the specified number of digits to the right, masking the shift amount to the type’s bit width.

  • static func &>>= (inout Self, Self)

    Calculates the result of shifting a value’s binary representation the specified number of digits to the right, masking the shift amount to the type’s bit width, and stores the result in the left-hand-side variable.

Members

Initializers

Type Methods

Operators

Implies

Conforming Types