protocol-oriented integers (take 2)


(Max Moiseev) #1

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 <https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

Proposal: SE-NNNN <https://gist.github.com/moiseev/0000-even-more-improved-integers.md>
Authors: Dave Abrahams <https://github.com/dabrahams>, Maxim Moiseev <https://github.com/moiseev>
Review Manager: TBD
Status: Awaiting review
Bug: SR-3196 <https://bugs.swift.org/browse/SR-3196>
Previous Proposal: SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#introduction>Introduction

This proposal is an evolution of SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>) are listed in a dedicated section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#motivation>Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post <http://blog.krzyzanowskim.com/2015/03/01/swift_madness_of_generic_integer/> for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x <<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#proposed-solution>Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

                +--------------+ +-------------+
        +------>+ Arithmetic | | Comparable |
        > > (+,-,*,/) | | (==,<,>,...)|
        > +-------------++ +---+---------+
        > ^ ^
+-------+------------+ | |

SignedArithmetic | +-+-------+-----------+
    (unary -) | | BinaryInteger |

+------+-------------+ |(words,%,bitwise,...)|
       ^ ++---+-----+----------+
       > +-----------^ ^ ^---------------+
       > > > >
+------+---------++ +---------+---------------+ +--+----------------+

SignedInteger | | FixedWidthInteger | | UnsignedInteger |
                > >(endianness,overflow,...)| | |

+---------------+-+ +-+--------------------+--+ +-+-----------------+
                ^ ^ ^ ^
                > > > >
                > > > >
               ++--------+-+ +-+-------+-+
               >Int family |-+ |UInt family|-+
               +-----------+ | +-----------+ |
                 +-----------+ +-----------+
There are several benefits provided by this model over the old one:

It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 <https://gist.github.com/moiseev/0067-floating-point-protocols.md> should now refine SignedArithmetic.

It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch <https://github.com/apple/swift/tree/new-integer-protocols>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#a-note-on-bit-shifts>A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined <http://llvm.org/docs/LangRef.html#bitwise-binary-operations> in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

x << -2 is equivalent to x >> 2

(1 as UInt8) >> 42) will evaluate to 0

(-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#detailed-design>Detailed design

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>What's new since SE-0104

SE-0091 <https://gist.github.com/moiseev/0091-improving-operators-in-protocols.md> removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model <https://gist.github.com/moiseev/0065-collections-move-indices.md> in Swift 3.

Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

minimumSignedRepresentationBitWidth property was removed.

trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

Standard library introduces the new type DoubleWidth<T>.

See this section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth> for more details.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>Protocols

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#arithmetic>Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral {
  /// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
  /// constant `y` from `1_000` fails because the `Int8` type can represent
  /// `127` at maximum:
  ///
  /// let x = Int8(exactly: 100)
  /// // x == Optional(100)
  /// let y = Int8(exactly: 1_000)
  /// // y == nil
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  init?<T : BinaryInteger>(exactly source: T)

  /// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

  /// The magnitude of this value.
  ///
  /// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
  /// You can use the `magnitude` property in operations that are simpler to
  /// implement in terms of unsigned values, such as printing the value of an
  /// integer, which is just printing a '-' character in front of an absolute
  /// value.
  ///
  /// let x = -200
  /// // x.magnitude == 200
  ///
  /// The global `abs(_:)` function provides more familiar syntax when you need
  /// to find an absolute value. In addition, because `abs(_:)` always returns
  /// a value of the same type, even in a generic context, using the function
  /// instead of the `magnitude` property is encouraged.
  ///
  /// - SeeAlso: `abs(_:)`
  var magnitude: Magnitude { get }

  /// Returns the sum of the two given values.
  ///
  /// The sum of `lhs` and `rhs` must be representable in the same type. In the
  /// following example, the result of `100 + 200` is greater than the maximum
  /// representable `Int8` value:
  ///
  /// let x: Int8 = 10 + 21
  /// // x == 31
  /// let y: Int8 = 100 + 121
  /// // Overflow error
  static func +(_ lhs: Self, _ rhs: Self) -> Self

  /// Adds the given value to this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y += 7
  /// // y == 22
  static func +=(_ lhs: inout Self, rhs: Self)

  /// Returns the difference of the two given values.
  ///
  /// The difference of `lhs` and `rhs` must be representable in the same type.
  /// In the following example, the result of `10 - 21` is less than zero, the
  /// minimum representable `UInt` value:
  ///
  /// let x: UInt = 21 - 10
  /// // x == 11
  /// let y: UInt = 10 - 21
  /// // Overflow error
  static func -(_ lhs: Self, _ rhs: Self) -> Self

  /// Subtracts the given value from this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y -= 7
  /// // y == 8
  static func -=(_ lhs: inout Self, rhs: Self)

  /// Returns the product of the two given values.
  ///
  /// The product of `lhs` and `rhs` must be representable in the same type. In
  /// the following example, the result of `10 * 50` is greater than the
  /// maximum representable `Int8` value.
  ///
  /// let x: Int8 = 10 * 5
  /// // x == 50
  /// let y: Int8 = 10 * 50
  /// // Overflow error
  static func *(_ lhs: Self, _ rhs: Self) -> Self

  /// Multiples this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y *= 7
  /// // y == 105
  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
  static func /(_ lhs: Self, _ rhs: Self) -> Self

  /// Divides this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y /= 7
  /// // y == 2
  static func /=(_ lhs: inout Self, rhs: Self)
}

extension Arithmetic {
  public init() { self = 0 }

  public static prefix func + (x: Self) -> Self {
    return x
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#signedarithmetic>SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic {
  /// Returns the additive inverse of this value.
  ///
  /// let x = 21
  /// let y = -x
  /// // y == -21
  ///
  /// - Returns: The additive inverse of this value.
  ///
  /// - SeeAlso: `negate()`
  static prefix func - (_ operand: Self) -> Self

  /// Replaces this value with its additive inverse.
  ///
  /// The following example uses the `negate()` method to negate the value of
  /// an integer `x`:
  ///
  /// var x = 21
  /// x.negate()
  /// // x == -21
  ///
  /// - SeeAlso: The unary minus operator (`-`).
  mutating func negate()
}

extension SignedArithmetic {
  public static prefix func - (_ operand: Self) -> Self {
    var result = operand
    result.negate()
    return result
  }

  public mutating func negate() {
    self = Self() - self
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#binaryinteger>BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

Extend or truncate the value to fit into Self

Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
  Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable {

  /// 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.
  static var isSigned: Bool { get }

  /// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
  init?<T : FloatingPoint>(exactly source: T)

  /// Creates an integer from the given floating-point value, truncating any
  /// fractional part.
  ///
  /// Truncating the fractional part of `source` is equivalent to rounding
  /// 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 truncation, a
  /// runtime error may occur.
  ///
  /// let z = UInt(-21.5)
  /// // Error: ...the result would be less than UInt.min
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  /// `source` must be representable in this type after truncation.
  init<T : FloatingPoint>(_ source: T)

  /// Creates an 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.
  init<T : BinaryInteger>(_ source: T)

  /// Creates a new instance from the bit pattern of the given instance by
  /// sign-extending 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
  /// least-significant bits of `source`. For example, when converting a
  /// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
  /// // x == -21
  /// // 'x' has a binary representation of 11111111_11101011
  /// let y = UInt16(extendingOrTruncating: w)
  /// // y == 65515
  /// // 'y' has a binary representation of 11111111_11101011
  ///
  /// - Parameter source: An integer to convert to this type.
  init<T : BinaryInteger>(extendingOrTruncating source: T)

  /// 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.
  init<T : BinaryInteger>(clamping source: T)

  /// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

  /// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get }

  /// The number of trailing zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number -8 has three trailing zeros.
  ///
  /// let x = Int8(bitPattern: 0b1111_1000)
  /// // x == -8
  /// // x.trailingZeros == 3
  var trailingZeros: Int { get }

  /// Returns the remainder of dividing the first value by the second.
  ///
  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
  ///
  /// let x = 22 % 5
  /// // x == 2
  /// let y = 22 % -5
  /// // y == 2
  /// let z = -22 % -5
  /// // z == -2
  ///
  /// - Parameters:
  /// - lhs: The value to divide.
  /// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
  static func %(_ lhs: Self, _ rhs: Self) -> Self

  /// Replaces this value with the remainder of itself divided by the given
  /// value. For example:
  ///
  /// var x = 15
  /// x %= 7
  /// // x == 1
  ///
  /// - Parameter rhs: The value to divide this value by. `rhs` must not be
  /// zero.
  ///
  /// - SeeAlso: `remainder(dividingBy:)`
  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).
  static prefix func ~ (_ x: Self) -> Self

  /// Returns the result of performing a bitwise AND operation on this value
  /// and the given value.
  ///
  /// 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
  static func &(_ lhs: Self, _ rhs: Self) -> Self
  static func &=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise OR operation on this value and
  /// the given value.
  ///
  /// 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
  static func |(_ lhs: Self, _ rhs: Self) -> Self
  static func |=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise XOR operation on this value
  /// and the given value.
  ///
  /// 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
  static func ^(_ lhs: Self, _ rhs: Self) -> Self
  static func ^=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the right.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 7 // 0b00000111
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &>> 11
  /// // z == 3 // 0b00000011
  ///
  /// Relationship to the Right Shift Operator
  /// ----------------------------------------
  ///
  /// The masking right shift operator handles attempted overshifts and
  /// undershifts differently from the right shift operator (`>>`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the right shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &>> 2
  /// // y1 == 7 // 0b00000111
  /// let y2 = x >> 2
  /// // y2 == 7 // 0b00000111
  ///
  /// The right shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &>> 11
  /// // z1 == 240 // 0b00000011
  /// let z2 = x >> 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the right. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// right.
  ///
  /// - SeeAlso: `&<<`, `>>`
  static func &>>(_ lhs: Self, _ rhs: Self) -> Self
  static func &>>=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the left.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 120 // 0b01111000
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &<< 11
  /// // z == 240 // 0b11110000
  ///
  /// Relationship to the Left Shift Operator
  /// ---------------------------------------
  ///
  /// The masking left shift operator handles attempted overshifts and
  /// undershifts differently from the left shift operator (`<<`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the left shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &<< 2
  /// // y1 == 120 // 0b01111000
  /// let y2 = x << 2
  /// // y2 == 120 // 0b01111000
  ///
  /// The left shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &<< 11
  /// // z1 == 240 // 0b11110000
  /// let z2 = x << 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the left. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// left.
  ///
  /// - SeeAlso: `&>>`, `<<`
  static func &<<(_ lhs: Self, _ rhs: Self) -> Self
  static func &<<=(_ lhs: inout Self, _ rhs: Self)

  /// 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.
  /// - Returns: A tuple containing the quotient and remainder of this value
  /// divided by `rhs`.
  func quotientAndRemainder(dividingBy rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// Returns `-1` if this value is negative and `1` if it's positive;
  /// otherwise, `0`.
  ///
  /// - Returns: The sign of this number, expressed as an integer of the same
  /// type.
  func signum() -> Self
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#fixedwidthinteger>FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger {
  /// The number of bits used for the underlying binary representation of
  /// values of this type.
  ///
  /// An unsigned, fixed-width integer type can represent values from 0 through
  /// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
  /// fixed-width integer type can represent values from
  /// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
  /// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
  /// the range `-128...127`.
  static var bitWidth : Int { get }

  /// The maximum representable integer in this type.
  ///
  /// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
  /// `**` is exponentiation. For signed integer types, this value is
  /// `(2 ** bitWidth - 1) - 1`.
  static var max: Self { get }

  /// The minimum representable value.
  ///
  /// For unsigned integer types, this value is always `0`. For signed integer
  /// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
  /// exponentiation.
  static var min: Self { get }

  /// Returns the sum of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to add to this value.
  /// - Returns: A tuple containing the result of the addition along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire sum. If
  /// the `overflow` component is `.overflow`, an overflow occurred and the
  /// `partialValue` component contains the truncated sum of this value and
  /// `other`.
  ///
  /// - SeeAlso: `+`
  func addingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the difference of this value and the given value along with a
  /// flag indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to subtract from this value.
  /// - Returns: A tuple containing the result of the subtraction along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire
  /// difference. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// result of `other` subtracted from this value.
  ///
  /// - SeeAlso: `-`
  func subtractingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the product of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to multiply by this value.
  /// - Returns: A tuple containing the result of the multiplication along with
  /// a flag indicating whether overflow occurred. If the `overflow`
  /// component is `.none`, the `partialValue` component contains the entire
  /// product. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// product of this value and `other`.
  ///
  /// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
  func multipliedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the quotient of dividing this value by the given value along with
  /// a flag indicating whether overflow occurred in the operation.
  ///
  /// For a value `x`, if zero is passed as `other`, the result is
  /// `(x, .overflow)`.
  ///
  /// - Parameter other: The value to divide this value by.
  /// - Returns: A tuple containing the result of the division along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire quotient.
  /// If the `overflow` component is `.overflow`, an overflow occurred and
  /// the `partialValue` component contains the truncated quotient.
  ///
  /// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
  func dividedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns a tuple containing the high and low parts of the result of
  /// multiplying its arguments.
  ///
  /// Use this method to calculate the full result of a product that would
  /// otherwise overflow. Unlike traditional truncating multiplication, the
  /// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
  /// parts of the product of `lhs` and `rhs`. The following example uses this
  /// method to multiply two `UInt8` values that normally overflow when
  /// multiplied:
  ///
  /// let x: UInt8 = 100
  /// let y: UInt8 = 20
  /// let result = UInt8.doubleWidthMultiply(100, 20)
  /// // result.high == 0b00000111
  /// // result.low == 0b11010000
  ///
  /// The product of `x` and `y` is 2000, which is too large to represent in a
  /// `UInt8` instance. The `high` and `low` components of the `result` tuple
  /// represent 2000 when concatenated to form a double-width integer; that
  /// is, using `result.high` as the high byte and `result.low` as the low byte
  /// of a `UInt16` instance.
  ///
  /// let z = UInt16(result.high) << 8 | UInt16(result.low)
  /// // z == 2000
  ///
  /// - Parameters:
  /// - lhs: A value to multiply.
  /// - rhs: Another value to multiply.
  /// - Returns: A tuple containing the high and low parts of the result of
  /// multiplying `lhs` and `rhs`.
  ///
  /// - SeeAlso: `multipliedWithOverflow(by:)`
  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self)
    -> (high: Self, low: Magnitude)

  /// Returns a tuple containing the quotient and remainder of dividing the
  /// first argument by the second.
  ///
  /// The resulting quotient must be representable within the bounds of the
  /// type. If the quotient of dividing `lhs` by `rhs` is too large to
  /// represent in the type, a runtime error may occur.
  ///
  /// - Parameters:
  /// - lhs: A tuple containing the high and low parts of a double-width
  /// integer. The `high` component of the tuple carries the sign, if the
  /// type is signed.
  /// - rhs: The integer to divide into `lhs`.
  /// - Returns: A tuple containing the quotient and remainder of `lhs` divided
  /// by `rhs`.
  static func doubleWidthDivide(
    _ lhs: (high: Self, low: Magnitude), _ rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get }

  /// The number of leading zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has three leading zeros.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.leadingZeros == 3
  /// - SeeAlso: `BinaryInteger.trailingZeros`
  var leadingZeros: Int { get }

  /// Creates an integer from its big-endian representation, changing the
  /// byte order if necessary.
  init(bigEndian value: Self)

  /// Creates an integer from its little-endian representation, changing the
  /// byte order if necessary.
  init(littleEndian value: Self)

  /// The big-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a big-endian platform, for any
  /// integer `x`, `x == x.bigEndian`.
  ///
  /// - SeeAlso: `littleEndian`
  var bigEndian: Self { get }

  /// The little-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a little-endian platform, for any
  /// integer `x`, `x == x.littleEndian`.
  ///
  /// - SeeAlso: `bigEndian`
  var littleEndian: Self { get }

  /// A representation of this integer with the byte order swapped.
  var byteSwapped: Self { get }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#auxiliary-protocols>Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger {
  associatedtype Magnitude : BinaryInteger
}
public protocol SignedInteger : BinaryInteger, SignedArithmetic {
  associatedtype Magnitude : BinaryInteger
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth>DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#extra-operators>Extra operators

In addition to the operators described in the protocols section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>, we also provide a few extensions that are not protocol requirements:

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-shifts>Heterogeneous shifts

extension BinaryInteger {
  // Masking shifts
  static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)

  // 'Smart' shifts
  static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-equality-and-comparison>Heterogeneous equality and comparison

extension BinaryInteger {
  // Equality
  static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

  // Comparison
  static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#masking-arithmetic>Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#non-goals>Non-goals

This proposal:

DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#source-compatibility>Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.


(Xiaodi Wu) #2

[Resending to list with original message removed for length.]

This is fantastic. Glad to see it take shape. Very neat and insightful to
have trailingZeros on BinaryInteger but leadingZeros on FixedWidthInteger.
A couple of questions on smart shifts: What is the performance penalty as
compared to the existing operators? Beyond performance, what are the
implications for migrating existing bit twiddling algorithms written in
Swift 3?


(Charles Srstka) #3

How could anyone ever argue against this?

+1.

Charles

···

On Jan 13, 2017, at 2:47 PM, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 <https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

Proposal: SE-NNNN <https://gist.github.com/moiseev/0000-even-more-improved-integers.md>
Authors: Dave Abrahams <https://github.com/dabrahams>, Maxim Moiseev <https://github.com/moiseev>
Review Manager: TBD
Status: Awaiting review
Bug: SR-3196 <https://bugs.swift.org/browse/SR-3196>
Previous Proposal: SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#introduction>Introduction

This proposal is an evolution of SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>) are listed in a dedicated section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#motivation>Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post <http://blog.krzyzanowskim.com/2015/03/01/swift_madness_of_generic_integer/> for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x <<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#proposed-solution>Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

                +--------------+ +-------------+
        +------>+ Arithmetic | | Comparable |
        > > (+,-,*,/) | | (==,<,>,...)|
        > +-------------++ +---+---------+
        > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
       ^ ++---+-----+----------+
       > +-----------^ ^ ^---------------+
       > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
                ^ ^ ^ ^
                > > > >
                > > > >
               ++--------+-+ +-+-------+-+
               >Int family |-+ |UInt family|-+
               +-----------+ | +-----------+ |
                 +-----------+ +-----------+
There are several benefits provided by this model over the old one:

It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 <https://gist.github.com/moiseev/0067-floating-point-protocols.md> should now refine SignedArithmetic.

It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch <https://github.com/apple/swift/tree/new-integer-protocols>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#a-note-on-bit-shifts>A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined <http://llvm.org/docs/LangRef.html#bitwise-binary-operations> in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

x << -2 is equivalent to x >> 2

(1 as UInt8) >> 42) will evaluate to 0

(-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#detailed-design>Detailed design

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>What's new since SE-0104

SE-0091 <https://gist.github.com/moiseev/0091-improving-operators-in-protocols.md> removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model <https://gist.github.com/moiseev/0065-collections-move-indices.md> in Swift 3.

Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

minimumSignedRepresentationBitWidth property was removed.

trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

Standard library introduces the new type DoubleWidth<T>.

See this section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth> for more details.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>Protocols

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#arithmetic>Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral {
  /// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
  /// constant `y` from `1_000` fails because the `Int8` type can represent
  /// `127` at maximum:
  ///
  /// let x = Int8(exactly: 100)
  /// // x == Optional(100)
  /// let y = Int8(exactly: 1_000)
  /// // y == nil
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  init?<T : BinaryInteger>(exactly source: T)

  /// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

  /// The magnitude of this value.
  ///
  /// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
  /// You can use the `magnitude` property in operations that are simpler to
  /// implement in terms of unsigned values, such as printing the value of an
  /// integer, which is just printing a '-' character in front of an absolute
  /// value.
  ///
  /// let x = -200
  /// // x.magnitude == 200
  ///
  /// The global `abs(_:)` function provides more familiar syntax when you need
  /// to find an absolute value. In addition, because `abs(_:)` always returns
  /// a value of the same type, even in a generic context, using the function
  /// instead of the `magnitude` property is encouraged.
  ///
  /// - SeeAlso: `abs(_:)`
  var magnitude: Magnitude { get }

  /// Returns the sum of the two given values.
  ///
  /// The sum of `lhs` and `rhs` must be representable in the same type. In the
  /// following example, the result of `100 + 200` is greater than the maximum
  /// representable `Int8` value:
  ///
  /// let x: Int8 = 10 + 21
  /// // x == 31
  /// let y: Int8 = 100 + 121
  /// // Overflow error
  static func +(_ lhs: Self, _ rhs: Self) -> Self

  /// Adds the given value to this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y += 7
  /// // y == 22
  static func +=(_ lhs: inout Self, rhs: Self)

  /// Returns the difference of the two given values.
  ///
  /// The difference of `lhs` and `rhs` must be representable in the same type.
  /// In the following example, the result of `10 - 21` is less than zero, the
  /// minimum representable `UInt` value:
  ///
  /// let x: UInt = 21 - 10
  /// // x == 11
  /// let y: UInt = 10 - 21
  /// // Overflow error
  static func -(_ lhs: Self, _ rhs: Self) -> Self

  /// Subtracts the given value from this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y -= 7
  /// // y == 8
  static func -=(_ lhs: inout Self, rhs: Self)

  /// Returns the product of the two given values.
  ///
  /// The product of `lhs` and `rhs` must be representable in the same type. In
  /// the following example, the result of `10 * 50` is greater than the
  /// maximum representable `Int8` value.
  ///
  /// let x: Int8 = 10 * 5
  /// // x == 50
  /// let y: Int8 = 10 * 50
  /// // Overflow error
  static func *(_ lhs: Self, _ rhs: Self) -> Self

  /// Multiples this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y *= 7
  /// // y == 105
  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
  static func /(_ lhs: Self, _ rhs: Self) -> Self

  /// Divides this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y /= 7
  /// // y == 2
  static func /=(_ lhs: inout Self, rhs: Self)
}

extension Arithmetic {
  public init() { self = 0 }

  public static prefix func + (x: Self) -> Self {
    return x
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#signedarithmetic>SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic {
  /// Returns the additive inverse of this value.
  ///
  /// let x = 21
  /// let y = -x
  /// // y == -21
  ///
  /// - Returns: The additive inverse of this value.
  ///
  /// - SeeAlso: `negate()`
  static prefix func - (_ operand: Self) -> Self

  /// Replaces this value with its additive inverse.
  ///
  /// The following example uses the `negate()` method to negate the value of
  /// an integer `x`:
  ///
  /// var x = 21
  /// x.negate()
  /// // x == -21
  ///
  /// - SeeAlso: The unary minus operator (`-`).
  mutating func negate()
}

extension SignedArithmetic {
  public static prefix func - (_ operand: Self) -> Self {
    var result = operand
    result.negate()
    return result
  }

  public mutating func negate() {
    self = Self() - self
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#binaryinteger>BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

Extend or truncate the value to fit into Self

Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
  Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable {

  /// 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.
  static var isSigned: Bool { get }

  /// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
  init?<T : FloatingPoint>(exactly source: T)

  /// Creates an integer from the given floating-point value, truncating any
  /// fractional part.
  ///
  /// Truncating the fractional part of `source` is equivalent to rounding
  /// 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 truncation, a
  /// runtime error may occur.
  ///
  /// let z = UInt(-21.5)
  /// // Error: ...the result would be less than UInt.min
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  /// `source` must be representable in this type after truncation.
  init<T : FloatingPoint>(_ source: T)

  /// Creates an 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.
  init<T : BinaryInteger>(_ source: T)

  /// Creates a new instance from the bit pattern of the given instance by
  /// sign-extending 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
  /// least-significant bits of `source`. For example, when converting a
  /// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
  /// // x == -21
  /// // 'x' has a binary representation of 11111111_11101011
  /// let y = UInt16(extendingOrTruncating: w)
  /// // y == 65515
  /// // 'y' has a binary representation of 11111111_11101011
  ///
  /// - Parameter source: An integer to convert to this type.
  init<T : BinaryInteger>(extendingOrTruncating source: T)

  /// 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.
  init<T : BinaryInteger>(clamping source: T)

  /// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

  /// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get }

  /// The number of trailing zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number -8 has three trailing zeros.
  ///
  /// let x = Int8(bitPattern: 0b1111_1000)
  /// // x == -8
  /// // x.trailingZeros == 3
  var trailingZeros: Int { get }

  /// Returns the remainder of dividing the first value by the second.
  ///
  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
  ///
  /// let x = 22 % 5
  /// // x == 2
  /// let y = 22 % -5
  /// // y == 2
  /// let z = -22 % -5
  /// // z == -2
  ///
  /// - Parameters:
  /// - lhs: The value to divide.
  /// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
  static func %(_ lhs: Self, _ rhs: Self) -> Self

  /// Replaces this value with the remainder of itself divided by the given
  /// value. For example:
  ///
  /// var x = 15
  /// x %= 7
  /// // x == 1
  ///
  /// - Parameter rhs: The value to divide this value by. `rhs` must not be
  /// zero.
  ///
  /// - SeeAlso: `remainder(dividingBy:)`
  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).
  static prefix func ~ (_ x: Self) -> Self

  /// Returns the result of performing a bitwise AND operation on this value
  /// and the given value.
  ///
  /// 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
  static func &(_ lhs: Self, _ rhs: Self) -> Self
  static func &=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise OR operation on this value and
  /// the given value.
  ///
  /// 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
  static func |(_ lhs: Self, _ rhs: Self) -> Self
  static func |=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise XOR operation on this value
  /// and the given value.
  ///
  /// 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
  static func ^(_ lhs: Self, _ rhs: Self) -> Self
  static func ^=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the right.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 7 // 0b00000111
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &>> 11
  /// // z == 3 // 0b00000011
  ///
  /// Relationship to the Right Shift Operator
  /// ----------------------------------------
  ///
  /// The masking right shift operator handles attempted overshifts and
  /// undershifts differently from the right shift operator (`>>`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the right shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &>> 2
  /// // y1 == 7 // 0b00000111
  /// let y2 = x >> 2
  /// // y2 == 7 // 0b00000111
  ///
  /// The right shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &>> 11
  /// // z1 == 240 // 0b00000011
  /// let z2 = x >> 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the right. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// right.
  ///
  /// - SeeAlso: `&<<`, `>>`
  static func &>>(_ lhs: Self, _ rhs: Self) -> Self
  static func &>>=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the left.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 120 // 0b01111000
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &<< 11
  /// // z == 240 // 0b11110000
  ///
  /// Relationship to the Left Shift Operator
  /// ---------------------------------------
  ///
  /// The masking left shift operator handles attempted overshifts and
  /// undershifts differently from the left shift operator (`<<`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the left shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &<< 2
  /// // y1 == 120 // 0b01111000
  /// let y2 = x << 2
  /// // y2 == 120 // 0b01111000
  ///
  /// The left shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &<< 11
  /// // z1 == 240 // 0b11110000
  /// let z2 = x << 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the left. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// left.
  ///
  /// - SeeAlso: `&>>`, `<<`
  static func &<<(_ lhs: Self, _ rhs: Self) -> Self
  static func &<<=(_ lhs: inout Self, _ rhs: Self)

  /// 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.
  /// - Returns: A tuple containing the quotient and remainder of this value
  /// divided by `rhs`.
  func quotientAndRemainder(dividingBy rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// Returns `-1` if this value is negative and `1` if it's positive;
  /// otherwise, `0`.
  ///
  /// - Returns: The sign of this number, expressed as an integer of the same
  /// type.
  func signum() -> Self
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#fixedwidthinteger>FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger {
  /// The number of bits used for the underlying binary representation of
  /// values of this type.
  ///
  /// An unsigned, fixed-width integer type can represent values from 0 through
  /// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
  /// fixed-width integer type can represent values from
  /// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
  /// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
  /// the range `-128...127`.
  static var bitWidth : Int { get }

  /// The maximum representable integer in this type.
  ///
  /// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
  /// `**` is exponentiation. For signed integer types, this value is
  /// `(2 ** bitWidth - 1) - 1`.
  static var max: Self { get }

  /// The minimum representable value.
  ///
  /// For unsigned integer types, this value is always `0`. For signed integer
  /// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
  /// exponentiation.
  static var min: Self { get }

  /// Returns the sum of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to add to this value.
  /// - Returns: A tuple containing the result of the addition along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire sum. If
  /// the `overflow` component is `.overflow`, an overflow occurred and the
  /// `partialValue` component contains the truncated sum of this value and
  /// `other`.
  ///
  /// - SeeAlso: `+`
  func addingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the difference of this value and the given value along with a
  /// flag indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to subtract from this value.
  /// - Returns: A tuple containing the result of the subtraction along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire
  /// difference. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// result of `other` subtracted from this value.
  ///
  /// - SeeAlso: `-`
  func subtractingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the product of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to multiply by this value.
  /// - Returns: A tuple containing the result of the multiplication along with
  /// a flag indicating whether overflow occurred. If the `overflow`
  /// component is `.none`, the `partialValue` component contains the entire
  /// product. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// product of this value and `other`.
  ///
  /// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
  func multipliedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the quotient of dividing this value by the given value along with
  /// a flag indicating whether overflow occurred in the operation.
  ///
  /// For a value `x`, if zero is passed as `other`, the result is
  /// `(x, .overflow)`.
  ///
  /// - Parameter other: The value to divide this value by.
  /// - Returns: A tuple containing the result of the division along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire quotient.
  /// If the `overflow` component is `.overflow`, an overflow occurred and
  /// the `partialValue` component contains the truncated quotient.
  ///
  /// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
  func dividedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns a tuple containing the high and low parts of the result of
  /// multiplying its arguments.
  ///
  /// Use this method to calculate the full result of a product that would
  /// otherwise overflow. Unlike traditional truncating multiplication, the
  /// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
  /// parts of the product of `lhs` and `rhs`. The following example uses this
  /// method to multiply two `UInt8` values that normally overflow when
  /// multiplied:
  ///
  /// let x: UInt8 = 100
  /// let y: UInt8 = 20
  /// let result = UInt8.doubleWidthMultiply(100, 20)
  /// // result.high == 0b00000111
  /// // result.low == 0b11010000
  ///
  /// The product of `x` and `y` is 2000, which is too large to represent in a
  /// `UInt8` instance. The `high` and `low` components of the `result` tuple
  /// represent 2000 when concatenated to form a double-width integer; that
  /// is, using `result.high` as the high byte and `result.low` as the low byte
  /// of a `UInt16` instance.
  ///
  /// let z = UInt16(result.high) << 8 | UInt16(result.low)
  /// // z == 2000
  ///
  /// - Parameters:
  /// - lhs: A value to multiply.
  /// - rhs: Another value to multiply.
  /// - Returns: A tuple containing the high and low parts of the result of
  /// multiplying `lhs` and `rhs`.
  ///
  /// - SeeAlso: `multipliedWithOverflow(by:)`
  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self)
    -> (high: Self, low: Magnitude)

  /// Returns a tuple containing the quotient and remainder of dividing the
  /// first argument by the second.
  ///
  /// The resulting quotient must be representable within the bounds of the
  /// type. If the quotient of dividing `lhs` by `rhs` is too large to
  /// represent in the type, a runtime error may occur.
  ///
  /// - Parameters:
  /// - lhs: A tuple containing the high and low parts of a double-width
  /// integer. The `high` component of the tuple carries the sign, if the
  /// type is signed.
  /// - rhs: The integer to divide into `lhs`.
  /// - Returns: A tuple containing the quotient and remainder of `lhs` divided
  /// by `rhs`.
  static func doubleWidthDivide(
    _ lhs: (high: Self, low: Magnitude), _ rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get }

  /// The number of leading zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has three leading zeros.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.leadingZeros == 3
  /// - SeeAlso: `BinaryInteger.trailingZeros`
  var leadingZeros: Int { get }

  /// Creates an integer from its big-endian representation, changing the
  /// byte order if necessary.
  init(bigEndian value: Self)

  /// Creates an integer from its little-endian representation, changing the
  /// byte order if necessary.
  init(littleEndian value: Self)

  /// The big-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a big-endian platform, for any
  /// integer `x`, `x == x.bigEndian`.
  ///
  /// - SeeAlso: `littleEndian`
  var bigEndian: Self { get }

  /// The little-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a little-endian platform, for any
  /// integer `x`, `x == x.littleEndian`.
  ///
  /// - SeeAlso: `bigEndian`
  var littleEndian: Self { get }

  /// A representation of this integer with the byte order swapped.
  var byteSwapped: Self { get }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#auxiliary-protocols>Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger {
  associatedtype Magnitude : BinaryInteger
}
public protocol SignedInteger : BinaryInteger, SignedArithmetic {
  associatedtype Magnitude : BinaryInteger
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth>DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#extra-operators>Extra operators

In addition to the operators described in the protocols section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>, we also provide a few extensions that are not protocol requirements:

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-shifts>Heterogeneous shifts

extension BinaryInteger {
  // Masking shifts
  static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)

  // 'Smart' shifts
  static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-equality-and-comparison>Heterogeneous equality and comparison

extension BinaryInteger {
  // Equality
  static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

  // Comparison
  static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#masking-arithmetic>Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#non-goals>Non-goals

This proposal:

DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#source-compatibility>Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Jacob Bandes-Storch) #4

Great work, all. I'm not sure I ever commented on SE-0104, so I've read
through this one more carefully. Here are some things that came to mind:

*## Arithmetic*

Why are ExpressibleByIntegerLiteral and init?<T:BinaryInteger>(exactly:)
required? I could understand needing access to 0, but this could be
provided by a static property or nullary initializer. It doesn't seem like
all types supporting arithmetic operations would necessarily be convertible
from an arbitrary binary integer.

I tried to evaluate the Arithmetic protocol by considering what it means
for higher-dimensional types such as CGPoint and CGVector. My use case was
a linear interpolation function:

    func lerp<T: Arithmetic>(from a: T, to b: T, by ratio: T) -> T {
        return a + (b - a) * ratio
    }

If I've read the proposal correctly, this definition works for integer and
floating-point values. But we can't make it work properly for CGVector (or,
perhaps less mathematically correct but more familiar, CGPoint). It's okay
to define +(CGVector, CGVector) and -(CGVector, CGVector), but *(CGVector,
CGVector) and /(CGVector, CGVector) don't make much sense. What we really
want is *(CGVector, *CGFloat*) and /(CGVector, *CGFloat*).

After consulting a mathematician, I believe what the lerp function really
wants is for its generic param to be an affine space
<https://en.wikipedia.org/wiki/Affine_space>. I explored this a bit here:
https://gist.github.com/jtbandes/93eeb7d5eee8e1a7245387c660d
53b03#file-affine-swift-L16-L18

This approach is less restrictive and more composable than the proposed
Arithmetic protocol, which can be viewed as a special case with the
following definitions:

    extension Arithmetic: AffineSpace, VectorSpace { // not actually
allowed in Swift
        typealias Displacement = Self
        typealias Scalar = Self
    }

It'd be great to be able to define a lerp() which works for all
floating-point and integer numbers, as well as points and vectors (assuming
a glorious future where CGPoint and CGVector have built-in arithmetic
operations). But maybe the complexity of these extra protocols isn't worth
it for the stdlib...

*## BinaryInteger*

I'm a little confused by the presence of init(extendingOrTruncating:) for
*all* binary integers. Why does it make sense to be able to write
UInt16(extendingOrTruncating: (-21 as Int8)) ? In my mind, sign-extension
only has meaning when the source and destination types are both signed.

Although I would not be against a clamp() function in the standard library,
"init(clamping:)" sounds strange to me. What about calling it
"init(nearestTo:)"? One could also define a FloatingPoint version of
init(nearestTo:), i.e. lround(). For maximum annoyance and explicitness,
you could even rename the existing init(_:slight_smile: to init(truncating:) to make it
clear that truncation, not regular rounding, occurs when converting from
floating-point.

*... masking shifts*

The example claims that "(30 as UInt8) &>> 11" produces 3, because it
right-shifts 30 by 3. But isn't the bitWidth of UInt8 always 8 since it's a
fixed-width type? Why should 11 get masked to 3 before the shift? (Also, it
might be a good idea to choose examples with numbers whose base-ten
representations don't look like valid binary. :wink:) What use cases are there
for masking shifts? I was under the impression that "smart shifts" were
pretty much how the usual shift instructions already behaved.

(Minor: were the smart shift operators supposed to be included as
BinaryInteger protocol requirements? I only see them in the "heterogeneous
shifts" extension.)

*... init<T: BinaryInteger>(_ source: T)*

Now a thought experiment: suppose you wanted to write an
arbitrary-precision BigInt, or any binary integer such as Int256. The
BinaryInteger protocol requires you to provide init<T:BinaryInteger>(_
source: T). Given the source of type T, how do you access its bits? Is
repeated use of word(at:) the recommended way? If so, it might be nice to
include a "wordCount" returning the number of available words; otherwise I
suppose the user has to use something like bitWidth/(8*MemoryLayout<Int>.size),
which is pretty ugly.

*## FixedWidthInteger*

Why is popcount restricted to FixedWidthInteger? It seems like it could
theoretically apply to any UnsignedInteger.

*## Heterogenous shifts, equality, and comparison*

These look great. How will the default implementations be provided?
(Equivalent question: how would a user define their own heterogeneous
operators?) I suppose this works:

    static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self {
        // delegate to the protocol requirement &>>(Self, Self)
        return self &>> Self(extendingOrTruncating: rhs)
    }

But for operations you can't delegate so easily... I'm imagining trying to
implement heterogeneous comparison (i.e. < ) and the best I can come up
with uses signum() and word(at:)...

Also, should these be protocol requirements so user-defined types can
specialize them?

*## Masking arithmetic*

Do &* and &+ and &- need their operands to have the same type, or could
these be heterogeneous too (at least &+ and &-)?

Jacob

···

On Fri, Jan 13, 2017 at 12:47 PM, Max Moiseev via swift-evolution < swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the
standard library. It even resulted in acceptance of SE-0104
<https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for
Swift 3. Unfortunately we were not able to implement it in time for the
release.

But it was not forgotten, although, as time went by, a few changes needed
to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make
integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/m
oiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max


(Rien) #5

+1

Any change of including “ranged integers”?
I.e. an integer with a value that must fit in a predefined range?

Regards,
Rien

Site: http://balancingrock.nl
Blog: http://swiftrien.blogspot.com
Github: http://github.com/Swiftrien
Project: http://swiftfire.nl

···

On 13 Jan 2017, at 21:47, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

  • Proposal: SE-NNNN
  • Authors: Dave Abrahams, Maxim Moiseev
  • Review Manager: TBD
  • Status: Awaiting review
  • Bug: SR-3196
  • Previous Proposal: SE-0104
Introduction

This proposal is an evolution of SE-0104. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104) are listed in a dedicated section.

Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x
<<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

                +--------------+ +-------------+
        +------>+ Arithmetic | | Comparable |
        > > (+,-,*,/) | | (==,<,>,...)|
        > +-------------++ +---+---------+
        > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
       ^ ++---+-----+----------+
       > +-----------^ ^ ^---------------+
       > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
                ^ ^ ^ ^
                > > > >
                > > > >
               ++--------+-+ +-+-------+-+
               >Int family |-+ |UInt family|-+
               +-----------+ | +-----------+ |
                 +-----------+ +-----------+

There are several benefits provided by this model over the old one:

  • It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

  • It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

  • It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 should now refine SignedArithmetic.

  • It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch.

A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

  • x << -2 is equivalent to x >> 2

  • (1 as UInt8) >> 42) will evaluate to 0

  • (-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

Detailed design

What's new since SE-0104

  • SE-0091 removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

  • Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model in Swift 3.

  • Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

  • BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

  • minimumSignedRepresentationBitWidth property was removed.

  • trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

  • Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

  • Standard library introduces the new type DoubleWidth<T>.

See this section for more details.

Protocols

Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral
{
  
/// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
  /// constant `y` from `1_000` fails because the `Int8` type can represent
  /// `127` at maximum:
  ///
  /// let x = Int8(exactly: 100)
  /// // x == Optional(100)
  /// let y = Int8(exactly: 1_000)
  /// // y == nil
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  init?<T : BinaryInteger>(exactly source
: T)

/// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

/// The magnitude of this value.
  ///
  /// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
  /// You can use the `magnitude` property in operations that are simpler to
  /// implement in terms of unsigned values, such as printing the value of an
  /// integer, which is just printing a '-' character in front of an absolute
  /// value.
  ///
  /// let x = -200
  /// // x.magnitude == 200
  ///
  /// The global `abs(_:)` function provides more familiar syntax when you need
  /// to find an absolute value. In addition, because `abs(_:)` always returns
  /// a value of the same type, even in a generic context, using the function
  /// instead of the `magnitude` property is encouraged.
  ///
  /// - SeeAlso: `abs(_:)`
  var magnitude: Magnitude { get
}

/// Returns the sum of the two given values.
  ///
  /// The sum of `lhs` and `rhs` must be representable in the same type. In the
  /// following example, the result of `100 + 200` is greater than the maximum
  /// representable `Int8` value:
  ///
  /// let x: Int8 = 10 + 21
  /// // x == 31
  /// let y: Int8 = 100 + 121
  /// // Overflow error
  static func +(_ lhs: Self, _ rhs: Self) -> Self

/// Adds the given value to this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y += 7
  /// // y == 22
  static func +=(_ lhs: inout Self, rhs: Self
)

/// Returns the difference of the two given values.
  ///
  /// The difference of `lhs` and `rhs` must be representable in the same type.
  /// In the following example, the result of `10 - 21` is less than zero, the
  /// minimum representable `UInt` value:
  ///
  /// let x: UInt = 21 - 10
  /// // x == 11
  /// let y: UInt = 10 - 21
  /// // Overflow error
  static func -(_ lhs: Self, _ rhs: Self) -> Self

/// Subtracts the given value from this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y -= 7
  /// // y == 8
  static func -=(_ lhs: inout Self, rhs: Self
)

/// Returns the product of the two given values.
  ///
  /// The product of `lhs` and `rhs` must be representable in the same type. In
  /// the following example, the result of `10 * 50` is greater than the
  /// maximum representable `Int8` value.
  ///
  /// let x: Int8 = 10 * 5
  /// // x == 50
  /// let y: Int8 = 10 * 50
  /// // Overflow error
  static func *(_ lhs: Self, _ rhs: Self) -> Self

/// Multiples this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y *= 7
  /// // y == 105
  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
  static func /(_ lhs: Self, _ rhs: Self) -> Self

/// Divides this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y /= 7
  /// // y == 2
  static func /=(_ lhs: inout Self, rhs: Self
)
}

extension Arithmetic
{
  
public init() { self = 0
}

public static prefix func + (x: Self) -> Self
{
    
return
x
  }
}

SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic
{
  
/// Returns the additive inverse of this value.
  ///
  /// let x = 21
  /// let y = -x
  /// // y == -21
  ///
  /// - Returns: The additive inverse of this value.
  ///
  /// - SeeAlso: `negate()`
  static prefix func - (_ operand: Self) -> Self

/// Replaces this value with its additive inverse.
  ///
  /// The following example uses the `negate()` method to negate the value of
  /// an integer `x`:
  ///
  /// var x = 21
  /// x.negate()
  /// // x == -21
  ///
  /// - SeeAlso: The unary minus operator (`-`).
  mutating func negate
()
}

extension SignedArithmetic
{
  
public static prefix func - (_ operand: Self) -> Self
{
    
var result =
operand
    result.
negate
()
    
return
result
  }

public mutating func negate
() {
    
self = Self() - self

  }
}

BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

  • Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

  • Extend or truncate the value to fit into Self

  • Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
  Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable
{

/// 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.
  static var isSigned: Bool { get
}

/// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
  init?<T : FloatingPoint>(exactly source
: T)

/// Creates an integer from the given floating-point value, truncating any
  /// fractional part.
  ///
  /// Truncating the fractional part of `source` is equivalent to rounding
  /// 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 truncation, a
  /// runtime error may occur.
  ///
  /// let z = UInt(-21.5)
  /// // Error: ...the result would be less than UInt.min
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  /// `source` must be representable in this type after truncation.
  init<T : FloatingPoint>(_ source
: T)

/// Creates an 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.
  init<T : BinaryInteger>(_ source
: T)

/// Creates a new instance from the bit pattern of the given instance by
  /// sign-extending 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
  /// least-significant bits of `source`. For example, when converting a
  /// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
  /// // x == -21
  /// // 'x' has a binary representation of 11111111_11101011
  /// let y = UInt16(extendingOrTruncating: w)
  /// // y == 65515
  /// // 'y' has a binary representation of 11111111_11101011
  ///
  /// - Parameter source: An integer to convert to this type.
  init<T : BinaryInteger>(extendingOrTruncating source
: T)

/// 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.
  init<T : BinaryInteger>(clamping source
: T)

/// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

/// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get
}

/// The number of trailing zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number -8 has three trailing zeros.
  ///
  /// let x = Int8(bitPattern: 0b1111_1000)
  /// // x == -8
  /// // x.trailingZeros == 3
  var trailingZeros: Int { get
}

/// Returns the remainder of dividing the first value by the second.
  ///
  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
  ///
  /// let x = 22 % 5
  /// // x == 2
  /// let y = 22 % -5
  /// // y == 2
  /// let z = -22 % -5
  /// // z == -2
  ///
  /// - Parameters:
  /// - lhs: The value to divide.
  /// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
  static func %(_ lhs: Self, _ rhs: Self) -> Self

/// Replaces this value with the remainder of itself divided by the given
  /// value. For example:
  ///
  /// var x = 15
  /// x %= 7
  /// // x == 1
  ///
  /// - Parameter rhs: The value to divide this value by. `rhs` must not be
  /// zero.
  ///
  /// - SeeAlso: `remainder(dividingBy:)`
  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).
  static prefix func ~ (_ x: Self) -> Self

/// Returns the result of performing a bitwise AND operation on this value
  /// and the given value.
  ///
  /// 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
  static func &(_ lhs: Self, _ rhs: Self) -> Self

static func &=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise OR operation on this value and
  /// the given value.
  ///
  /// 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
  static func |(_ lhs: Self, _ rhs: Self) -> Self

static func |=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise XOR operation on this value
  /// and the given value.
  ///
  /// 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
  static func ^(_ lhs: Self, _ rhs: Self) -> Self

static func ^=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the right.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 7 // 0b00000111
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &>> 11
  /// // z == 3 // 0b00000011
  ///
  /// Relationship to the Right Shift Operator
  /// ----------------------------------------
  ///
  /// The masking right shift operator handles attempted overshifts and
  /// undershifts differently from the right shift operator (`>>`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the right shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &>> 2
  /// // y1 == 7 // 0b00000111
  /// let y2 = x >> 2
  /// // y2 == 7 // 0b00000111
  ///
  /// The right shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &>> 11
  /// // z1 == 240 // 0b00000011
  /// let z2 = x >> 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the right. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// right.
  ///
  /// - SeeAlso: `&<<`, `>>`
  static func &>>(_ lhs: Self, _ rhs: Self) -> Self

static func &>>=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the left.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 120 // 0b01111000
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &<< 11
  /// // z == 240 // 0b11110000
  ///
  /// Relationship to the Left Shift Operator
  /// ---------------------------------------
  ///
  /// The masking left shift operator handles attempted overshifts and
  /// undershifts differently from the left shift operator (`<<`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the left shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &<< 2
  /// // y1 == 120 // 0b01111000
  /// let y2 = x << 2
  /// // y2 == 120 // 0b01111000
  ///
  /// The left shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &<< 11
  /// // z1 == 240 // 0b11110000
  /// let z2 = x << 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the left. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// left.
  ///
  /// - SeeAlso: `&>>`, `<<`
  static func &<<(_ lhs: Self, _ rhs: Self) -> Self

static func &<<=(_ lhs: inout Self, _ rhs: Self
)

/// 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.
  /// - Returns: A tuple containing the quotient and remainder of this value
  /// divided by `rhs`.
  func quotientAndRemainder(dividingBy rhs: Self
)
    
-> (quotient: Self, remainder: Self
)

/// Returns `-1` if this value is negative and `1` if it's positive;
  /// otherwise, `0`.
  ///
  /// - Returns: The sign of this number, expressed as an integer of the same
  /// type.
  func signum() -> Self

}

FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger
{
  
/// The number of bits used for the underlying binary representation of
  /// values of this type.
  ///
  /// An unsigned, fixed-width integer type can represent values from 0 through
  /// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
  /// fixed-width integer type can represent values from
  /// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
  /// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
  /// the range `-128...127`.
  static var bitWidth : Int { get
}

/// The maximum representable integer in this type.
  ///
  /// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
  /// `**` is exponentiation. For signed integer types, this value is
  /// `(2 ** bitWidth - 1) - 1`.
  static var max: Self { get
}

/// The minimum representable value.
  ///
  /// For unsigned integer types, this value is always `0`. For signed integer
  /// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
  /// exponentiation.
  static var min: Self { get
}

/// Returns the sum of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to add to this value.
  /// - Returns: A tuple containing the result of the addition along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire sum. If
  /// the `overflow` component is `.overflow`, an overflow occurred and the
  /// `partialValue` component contains the truncated sum of this value and
  /// `other`.
  ///
  /// - SeeAlso: `+`
  func addingWithOverflow(_ other: Self
)
    
-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the difference of this value and the given value along with a
  /// flag indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to subtract from this value.
  /// - Returns: A tuple containing the result of the subtraction along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire
  /// difference. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// result of `other` subtracted from this value.
  ///
  /// - SeeAlso: `-`
  func subtractingWithOverflow(_ other: Self
)
    
-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the product of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to multiply by this value.
  /// - Returns: A tuple containing the result of the multiplication along with
  /// a flag indicating whether overflow occurred. If the `overflow`
  /// component is `.none`, the `partialValue` component contains the entire
  /// product. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// product of this value and `other`.
  ///
  /// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
  func multipliedWithOverflow(by other: Self
)
    
-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the quotient of dividing this value by the given value along with
  /// a flag indicating whether overflow occurred in the operation.
  ///
  /// For a value `x`, if zero is passed as `other`, the result is
  /// `(x, .overflow)`.
  ///
  /// - Parameter other: The value to divide this value by.
  /// - Returns: A tuple containing the result of the division along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire quotient.
  /// If the `overflow` component is `.overflow`, an overflow occurred and
  /// the `partialValue` component contains the truncated quotient.
  ///
  /// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
  func dividedWithOverflow(by other: Self
)
    
-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns a tuple containing the high and low parts of the result of
  /// multiplying its arguments.
  ///
  /// Use this method to calculate the full result of a product that would
  /// otherwise overflow. Unlike traditional truncating multiplication, the
  /// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
  /// parts of the product of `lhs` and `rhs`. The following example uses this
  /// method to multiply two `UInt8` values that normally overflow when
  /// multiplied:
  ///
  /// let x: UInt8 = 100
  /// let y: UInt8 = 20
  /// let result = UInt8.doubleWidthMultiply(100, 20)
  /// // result.high == 0b00000111
  /// // result.low == 0b11010000
  ///
  /// The product of `x` and `y` is 2000, which is too large to represent in a
  /// `UInt8` instance. The `high` and `low` components of the `result` tuple
  /// represent 2000 when concatenated to form a double-width integer; that
  /// is, using `result.high` as the high byte and `result.low` as the low byte
  /// of a `UInt16` instance.
  ///
  /// let z = UInt16(result.high) << 8 | UInt16(result.low)
  /// // z == 2000
  ///
  /// - Parameters:
  /// - lhs: A value to multiply.
  /// - rhs: Another value to multiply.
  /// - Returns: A tuple containing the high and low parts of the result of
  /// multiplying `lhs` and `rhs`.
  ///
  /// - SeeAlso: `multipliedWithOverflow(by:)`
  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self
)
    
-> (high: Self, low
: Magnitude)

/// Returns a tuple containing the quotient and remainder of dividing the
  /// first argument by the second.
  ///
  /// The resulting quotient must be representable within the bounds of the
  /// type. If the quotient of dividing `lhs` by `rhs` is too large to
  /// represent in the type, a runtime error may occur.
  ///
  /// - Parameters:
  /// - lhs: A tuple containing the high and low parts of a double-width
  /// integer. The `high` component of the tuple carries the sign, if the
  /// type is signed.
  /// - rhs: The integer to divide into `lhs`.
  /// - Returns: A tuple containing the quotient and remainder of `lhs` divided
  /// by `rhs`.
  static func doubleWidthDivide
(
    
_ lhs: (high: Self, low: Magnitude), _ rhs: Self
)
    
-> (quotient: Self, remainder: Self
)

/// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get
}

/// The number of leading zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has three leading zeros.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.leadingZeros == 3
  /// - SeeAlso: `BinaryInteger.trailingZeros`
  var leadingZeros: Int { get
}

/// Creates an integer from its big-endian representation, changing the
  /// byte order if necessary.
  init(bigEndian value: Self
)

/// Creates an integer from its little-endian representation, changing the
  /// byte order if necessary.
  init(littleEndian value: Self
)

/// The big-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a big-endian platform, for any
  /// integer `x`, `x == x.bigEndian`.
  ///
  /// - SeeAlso: `littleEndian`
  var bigEndian: Self { get
}

/// The little-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a little-endian platform, for any
  /// integer `x`, `x == x.littleEndian`.
  ///
  /// - SeeAlso: `bigEndian`
  var littleEndian: Self { get
}

/// A representation of this integer with the byte order swapped.
  var byteSwapped: Self { get
}
}

Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger
{
  
associatedtype Magnitude : BinaryInteger

}

public protocol SignedInteger : BinaryInteger, SignedArithmetic
{
  
associatedtype Magnitude : BinaryInteger

}

DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

Extra operators

In addition to the operators described in the protocols section, we also provide a few extensions that are not protocol requirements:

Heterogeneous shifts

extension BinaryInteger
{
  
// Masking shifts
  static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)
  
static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

// 'Smart' shifts
  static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)
  
static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)
}

Heterogeneous equality and comparison

extension BinaryInteger
{
  
// Equality
  static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

// Comparison
  static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

}

Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
Non-goals

This proposal:

  • DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

  • DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

  • Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

  • Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

  • Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Karl) #6

Really glad to see this coming back :slight_smile:

I have a couple of questions:

1) How does Strideable relate to Arithmetic?

My understanding is that Strideable allows non-numeric types to express different-type addition and subtraction, and that Arithmetic is for numeric types only (derives from ExpressibleByIntegerLiteral) and allows then to express same-type operations. Is that correct? If so, it would be nice to add it to the proposal so people know when they should conform (or set their generic constraints) to one or the other.

2) Can SignedNumber get some operators now?

Strideable.Stride is bound to this weird protocol ‘SignedNumber’. You can create instances of it out of thin air via an integer literal, but you can’t accumulate Strides to find the overall distance between some adjacent Strideables.

Also, #1 is why I don’t like the Strideable operator deprecation being part of the proposal (and therefore part of the language specification). It doesn’t solve the underlying issue, which is that our integer literal protocols aren’t really good enough - they’re not useful enough outside the standard library (see: https://bugs.swift.org/browse/SR-920), and evidently the compiler isn’t able to use them to infer types correctly. Perhaps fixing it is a low priority, and that’s fine, but what about if somebody else defines this operator in their library? They start of break lots of valid code because the compiler can’t do the right thing. Improved literal protocols may be the better way to resolve that problem.

- Karl


(Ben Rimmington) #7

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c>

  public protocol Arithmetic {
    init?<T : BinaryInteger>(exactly source: T)
  }

  public protocol BinaryInteger : Arithmetic {
    init?<T : FloatingPoint>(exactly source: T)
  }

Should the `init?(exactly:)` initializers belong to the same protocol?
Would this allow generic conversions between integer and floating-point types?
For example, a failable `numericCast` function.

-- Ben


(Anton Mironov) #8

Hi everyone,

I want to suggest a tiny extension to an Arithmetic protocol. It would be nice to have an additive identity and a multiplicative identity constants. Basically zero and one.

protocol Arithmetic {
  /* ... */
  static var zero: Self { get }  // additive identity: (value + .zero) == value
  static var one: Self { get }   // multiplicative identity: (value * .one) == value
}

These constants will ease implementation of math structures: vectors, matrices and etc.
I’m sorry if I’m duplicating someone’s suggestion. It is really hard to search for something in a long thread.

Thanks,
Anton Mironov

···

On Jan 13, 2017, at 10:47 PM, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 <https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

Proposal: SE-NNNN <https://gist.github.com/moiseev/0000-even-more-improved-integers.md>
Authors: Dave Abrahams <https://github.com/dabrahams>, Maxim Moiseev <https://github.com/moiseev>
Review Manager: TBD
Status: Awaiting review
Bug: SR-3196 <https://bugs.swift.org/browse/SR-3196>
Previous Proposal: SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#introduction>Introduction

This proposal is an evolution of SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>) are listed in a dedicated section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#motivation>Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post <http://blog.krzyzanowskim.com/2015/03/01/swift_madness_of_generic_integer/> for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x <<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#proposed-solution>Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

                +--------------+ +-------------+
        +------>+ Arithmetic | | Comparable |
        > > (+,-,*,/) | | (==,<,>,...)|
        > +-------------++ +---+---------+
        > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
       ^ ++---+-----+----------+
       > +-----------^ ^ ^---------------+
       > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
                ^ ^ ^ ^
                > > > >
                > > > >
               ++--------+-+ +-+-------+-+
               >Int family |-+ |UInt family|-+
               +-----------+ | +-----------+ |
                 +-----------+ +-----------+
There are several benefits provided by this model over the old one:

It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 <https://gist.github.com/moiseev/0067-floating-point-protocols.md> should now refine SignedArithmetic.

It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch <https://github.com/apple/swift/tree/new-integer-protocols>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#a-note-on-bit-shifts>A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined <http://llvm.org/docs/LangRef.html#bitwise-binary-operations> in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

x << -2 is equivalent to x >> 2

(1 as UInt8) >> 42) will evaluate to 0

(-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#detailed-design>Detailed design

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>What's new since SE-0104

SE-0091 <https://gist.github.com/moiseev/0091-improving-operators-in-protocols.md> removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model <https://gist.github.com/moiseev/0065-collections-move-indices.md> in Swift 3.

Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

minimumSignedRepresentationBitWidth property was removed.

trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

Standard library introduces the new type DoubleWidth<T>.

See this section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth> for more details.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>Protocols

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#arithmetic>Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral {
  /// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
  /// constant `y` from `1_000` fails because the `Int8` type can represent
  /// `127` at maximum:
  ///
  /// let x = Int8(exactly: 100)
  /// // x == Optional(100)
  /// let y = Int8(exactly: 1_000)
  /// // y == nil
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  init?<T : BinaryInteger>(exactly source: T)

  /// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

  /// The magnitude of this value.
  ///
  /// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
  /// You can use the `magnitude` property in operations that are simpler to
  /// implement in terms of unsigned values, such as printing the value of an
  /// integer, which is just printing a '-' character in front of an absolute
  /// value.
  ///
  /// let x = -200
  /// // x.magnitude == 200
  ///
  /// The global `abs(_:)` function provides more familiar syntax when you need
  /// to find an absolute value. In addition, because `abs(_:)` always returns
  /// a value of the same type, even in a generic context, using the function
  /// instead of the `magnitude` property is encouraged.
  ///
  /// - SeeAlso: `abs(_:)`
  var magnitude: Magnitude { get }

  /// Returns the sum of the two given values.
  ///
  /// The sum of `lhs` and `rhs` must be representable in the same type. In the
  /// following example, the result of `100 + 200` is greater than the maximum
  /// representable `Int8` value:
  ///
  /// let x: Int8 = 10 + 21
  /// // x == 31
  /// let y: Int8 = 100 + 121
  /// // Overflow error
  static func +(_ lhs: Self, _ rhs: Self) -> Self

  /// Adds the given value to this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y += 7
  /// // y == 22
  static func +=(_ lhs: inout Self, rhs: Self)

  /// Returns the difference of the two given values.
  ///
  /// The difference of `lhs` and `rhs` must be representable in the same type.
  /// In the following example, the result of `10 - 21` is less than zero, the
  /// minimum representable `UInt` value:
  ///
  /// let x: UInt = 21 - 10
  /// // x == 11
  /// let y: UInt = 10 - 21
  /// // Overflow error
  static func -(_ lhs: Self, _ rhs: Self) -> Self

  /// Subtracts the given value from this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y -= 7
  /// // y == 8
  static func -=(_ lhs: inout Self, rhs: Self)

  /// Returns the product of the two given values.
  ///
  /// The product of `lhs` and `rhs` must be representable in the same type. In
  /// the following example, the result of `10 * 50` is greater than the
  /// maximum representable `Int8` value.
  ///
  /// let x: Int8 = 10 * 5
  /// // x == 50
  /// let y: Int8 = 10 * 50
  /// // Overflow error
  static func *(_ lhs: Self, _ rhs: Self) -> Self

  /// Multiples this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y *= 7
  /// // y == 105
  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
  static func /(_ lhs: Self, _ rhs: Self) -> Self

  /// Divides this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y /= 7
  /// // y == 2
  static func /=(_ lhs: inout Self, rhs: Self)
}

extension Arithmetic {
  public init() { self = 0 }

  public static prefix func + (x: Self) -> Self {
    return x
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#signedarithmetic>SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic {
  /// Returns the additive inverse of this value.
  ///
  /// let x = 21
  /// let y = -x
  /// // y == -21
  ///
  /// - Returns: The additive inverse of this value.
  ///
  /// - SeeAlso: `negate()`
  static prefix func - (_ operand: Self) -> Self

  /// Replaces this value with its additive inverse.
  ///
  /// The following example uses the `negate()` method to negate the value of
  /// an integer `x`:
  ///
  /// var x = 21
  /// x.negate()
  /// // x == -21
  ///
  /// - SeeAlso: The unary minus operator (`-`).
  mutating func negate()
}

extension SignedArithmetic {
  public static prefix func - (_ operand: Self) -> Self {
    var result = operand
    result.negate()
    return result
  }

  public mutating func negate() {
    self = Self() - self
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#binaryinteger>BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

Extend or truncate the value to fit into Self

Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
  Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable {

  /// 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.
  static var isSigned: Bool { get }

  /// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
  init?<T : FloatingPoint>(exactly source: T)

  /// Creates an integer from the given floating-point value, truncating any
  /// fractional part.
  ///
  /// Truncating the fractional part of `source` is equivalent to rounding
  /// 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 truncation, a
  /// runtime error may occur.
  ///
  /// let z = UInt(-21.5)
  /// // Error: ...the result would be less than UInt.min
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  /// `source` must be representable in this type after truncation.
  init<T : FloatingPoint>(_ source: T)

  /// Creates an 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.
  init<T : BinaryInteger>(_ source: T)

  /// Creates a new instance from the bit pattern of the given instance by
  /// sign-extending 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
  /// least-significant bits of `source`. For example, when converting a
  /// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
  /// // x == -21
  /// // 'x' has a binary representation of 11111111_11101011
  /// let y = UInt16(extendingOrTruncating: w)
  /// // y == 65515
  /// // 'y' has a binary representation of 11111111_11101011
  ///
  /// - Parameter source: An integer to convert to this type.
  init<T : BinaryInteger>(extendingOrTruncating source: T)

  /// 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.
  init<T : BinaryInteger>(clamping source: T)

  /// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

  /// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get }

  /// The number of trailing zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number -8 has three trailing zeros.
  ///
  /// let x = Int8(bitPattern: 0b1111_1000)
  /// // x == -8
  /// // x.trailingZeros == 3
  var trailingZeros: Int { get }

  /// Returns the remainder of dividing the first value by the second.
  ///
  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
  ///
  /// let x = 22 % 5
  /// // x == 2
  /// let y = 22 % -5
  /// // y == 2
  /// let z = -22 % -5
  /// // z == -2
  ///
  /// - Parameters:
  /// - lhs: The value to divide.
  /// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
  static func %(_ lhs: Self, _ rhs: Self) -> Self

  /// Replaces this value with the remainder of itself divided by the given
  /// value. For example:
  ///
  /// var x = 15
  /// x %= 7
  /// // x == 1
  ///
  /// - Parameter rhs: The value to divide this value by. `rhs` must not be
  /// zero.
  ///
  /// - SeeAlso: `remainder(dividingBy:)`
  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).
  static prefix func ~ (_ x: Self) -> Self

  /// Returns the result of performing a bitwise AND operation on this value
  /// and the given value.
  ///
  /// 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
  static func &(_ lhs: Self, _ rhs: Self) -> Self
  static func &=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise OR operation on this value and
  /// the given value.
  ///
  /// 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
  static func |(_ lhs: Self, _ rhs: Self) -> Self
  static func |=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise XOR operation on this value
  /// and the given value.
  ///
  /// 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
  static func ^(_ lhs: Self, _ rhs: Self) -> Self
  static func ^=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the right.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 7 // 0b00000111
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &>> 11
  /// // z == 3 // 0b00000011
  ///
  /// Relationship to the Right Shift Operator
  /// ----------------------------------------
  ///
  /// The masking right shift operator handles attempted overshifts and
  /// undershifts differently from the right shift operator (`>>`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the right shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &>> 2
  /// // y1 == 7 // 0b00000111
  /// let y2 = x >> 2
  /// // y2 == 7 // 0b00000111
  ///
  /// The right shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &>> 11
  /// // z1 == 240 // 0b00000011
  /// let z2 = x >> 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the right. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// right.
  ///
  /// - SeeAlso: `&<<`, `>>`
  static func &>>(_ lhs: Self, _ rhs: Self) -> Self
  static func &>>=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the left.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 120 // 0b01111000
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &<< 11
  /// // z == 240 // 0b11110000
  ///
  /// Relationship to the Left Shift Operator
  /// ---------------------------------------
  ///
  /// The masking left shift operator handles attempted overshifts and
  /// undershifts differently from the left shift operator (`<<`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the left shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &<< 2
  /// // y1 == 120 // 0b01111000
  /// let y2 = x << 2
  /// // y2 == 120 // 0b01111000
  ///
  /// The left shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &<< 11
  /// // z1 == 240 // 0b11110000
  /// let z2 = x << 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the left. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// left.
  ///
  /// - SeeAlso: `&>>`, `<<`
  static func &<<(_ lhs: Self, _ rhs: Self) -> Self
  static func &<<=(_ lhs: inout Self, _ rhs: Self)

  /// 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.
  /// - Returns: A tuple containing the quotient and remainder of this value
  /// divided by `rhs`.
  func quotientAndRemainder(dividingBy rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// Returns `-1` if this value is negative and `1` if it's positive;
  /// otherwise, `0`.
  ///
  /// - Returns: The sign of this number, expressed as an integer of the same
  /// type.
  func signum() -> Self
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#fixedwidthinteger>FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger {
  /// The number of bits used for the underlying binary representation of
  /// values of this type.
  ///
  /// An unsigned, fixed-width integer type can represent values from 0 through
  /// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
  /// fixed-width integer type can represent values from
  /// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
  /// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
  /// the range `-128...127`.
  static var bitWidth : Int { get }

  /// The maximum representable integer in this type.
  ///
  /// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
  /// `**` is exponentiation. For signed integer types, this value is
  /// `(2 ** bitWidth - 1) - 1`.
  static var max: Self { get }

  /// The minimum representable value.
  ///
  /// For unsigned integer types, this value is always `0`. For signed integer
  /// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
  /// exponentiation.
  static var min: Self { get }

  /// Returns the sum of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to add to this value.
  /// - Returns: A tuple containing the result of the addition along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire sum. If
  /// the `overflow` component is `.overflow`, an overflow occurred and the
  /// `partialValue` component contains the truncated sum of this value and
  /// `other`.
  ///
  /// - SeeAlso: `+`
  func addingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the difference of this value and the given value along with a
  /// flag indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to subtract from this value.
  /// - Returns: A tuple containing the result of the subtraction along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire
  /// difference. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// result of `other` subtracted from this value.
  ///
  /// - SeeAlso: `-`
  func subtractingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the product of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to multiply by this value.
  /// - Returns: A tuple containing the result of the multiplication along with
  /// a flag indicating whether overflow occurred. If the `overflow`
  /// component is `.none`, the `partialValue` component contains the entire
  /// product. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// product of this value and `other`.
  ///
  /// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
  func multipliedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the quotient of dividing this value by the given value along with
  /// a flag indicating whether overflow occurred in the operation.
  ///
  /// For a value `x`, if zero is passed as `other`, the result is
  /// `(x, .overflow)`.
  ///
  /// - Parameter other: The value to divide this value by.
  /// - Returns: A tuple containing the result of the division along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire quotient.
  /// If the `overflow` component is `.overflow`, an overflow occurred and
  /// the `partialValue` component contains the truncated quotient.
  ///
  /// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
  func dividedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns a tuple containing the high and low parts of the result of
  /// multiplying its arguments.
  ///
  /// Use this method to calculate the full result of a product that would
  /// otherwise overflow. Unlike traditional truncating multiplication, the
  /// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
  /// parts of the product of `lhs` and `rhs`. The following example uses this
  /// method to multiply two `UInt8` values that normally overflow when
  /// multiplied:
  ///
  /// let x: UInt8 = 100
  /// let y: UInt8 = 20
  /// let result = UInt8.doubleWidthMultiply(100, 20)
  /// // result.high == 0b00000111
  /// // result.low == 0b11010000
  ///
  /// The product of `x` and `y` is 2000, which is too large to represent in a
  /// `UInt8` instance. The `high` and `low` components of the `result` tuple
  /// represent 2000 when concatenated to form a double-width integer; that
  /// is, using `result.high` as the high byte and `result.low` as the low byte
  /// of a `UInt16` instance.
  ///
  /// let z = UInt16(result.high) << 8 | UInt16(result.low)
  /// // z == 2000
  ///
  /// - Parameters:
  /// - lhs: A value to multiply.
  /// - rhs: Another value to multiply.
  /// - Returns: A tuple containing the high and low parts of the result of
  /// multiplying `lhs` and `rhs`.
  ///
  /// - SeeAlso: `multipliedWithOverflow(by:)`
  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self)
    -> (high: Self, low: Magnitude)

  /// Returns a tuple containing the quotient and remainder of dividing the
  /// first argument by the second.
  ///
  /// The resulting quotient must be representable within the bounds of the
  /// type. If the quotient of dividing `lhs` by `rhs` is too large to
  /// represent in the type, a runtime error may occur.
  ///
  /// - Parameters:
  /// - lhs: A tuple containing the high and low parts of a double-width
  /// integer. The `high` component of the tuple carries the sign, if the
  /// type is signed.
  /// - rhs: The integer to divide into `lhs`.
  /// - Returns: A tuple containing the quotient and remainder of `lhs` divided
  /// by `rhs`.
  static func doubleWidthDivide(
    _ lhs: (high: Self, low: Magnitude), _ rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get }

  /// The number of leading zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has three leading zeros.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.leadingZeros == 3
  /// - SeeAlso: `BinaryInteger.trailingZeros`
  var leadingZeros: Int { get }

  /// Creates an integer from its big-endian representation, changing the
  /// byte order if necessary.
  init(bigEndian value: Self)

  /// Creates an integer from its little-endian representation, changing the
  /// byte order if necessary.
  init(littleEndian value: Self)

  /// The big-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a big-endian platform, for any
  /// integer `x`, `x == x.bigEndian`.
  ///
  /// - SeeAlso: `littleEndian`
  var bigEndian: Self { get }

  /// The little-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a little-endian platform, for any
  /// integer `x`, `x == x.littleEndian`.
  ///
  /// - SeeAlso: `bigEndian`
  var littleEndian: Self { get }

  /// A representation of this integer with the byte order swapped.
  var byteSwapped: Self { get }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#auxiliary-protocols>Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger {
  associatedtype Magnitude : BinaryInteger
}
public protocol SignedInteger : BinaryInteger, SignedArithmetic {
  associatedtype Magnitude : BinaryInteger
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth>DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#extra-operators>Extra operators

In addition to the operators described in the protocols section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>, we also provide a few extensions that are not protocol requirements:

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-shifts>Heterogeneous shifts

extension BinaryInteger {
  // Masking shifts
  static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)

  // 'Smart' shifts
  static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-equality-and-comparison>Heterogeneous equality and comparison

extension BinaryInteger {
  // Equality
  static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

  // Comparison
  static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#masking-arithmetic>Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#non-goals>Non-goals

This proposal:

DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#source-compatibility>Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Brent Royal-Gordon) #9

Protocol-oriented integers (take 2)

  • Proposal: SE-NNNN
  • Authors: Dave Abrahams, Maxim Moiseev
  • Review Manager: TBD
  • Status: Awaiting review
  • Bug: SR-3196
  • Previous Proposal: SE-0104

Definitely liking what I'm seeing here.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral
{

Is there a reason `Arithmetic` is not `Hashable`? (I think `Comparable` isn't here because complex numbers can't be compared, but correct me if I'm wrong about that.)

/// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

Is there a reason not to have this be `Arithmetic`? Maybe just the circularity problem?

/// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

How does the client know how many words there are? Are they supposed to calculate that from `bitWidth`?

Oh, I see:

good catch; countRepresentedWords is in the prototype
(https://github.com/apple/swift/blob/new-integer-protocols/stdlib/public/core/Integers.swift.gyb#L1521),
and it should be in the proposal.

That looks fine to me.

/// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get }

So, um, I'm a little confused about this one. Is this the physical number of bits in the value, or is it the number of bits you need to get from `word(at:)` in order to get all bits representing the value?

For instance, when you call `UInt32.bitWidth`, does it return `32`, the physical number of bits in the value, or `33`, the number of bits including the (always zero) sign bit?

  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self) -> (high: Self, low: Magnitude)
  static func doubleWidthDivide(_ lhs: (high: Self, low: Magnitude), _ rhs: Self) -> (quotient: Self, remainder: Self)

Could these take/return a single `DoubleWidth<Self>` value instead of two separate `Self` and `Magnitude` values? Or would that present circularity problems?

/// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get }

I'm not super-fond of this name; I assume it's a term of art, but it's a pretty obscure one. Maybe `numberOfOnes`? `onesWithin`?

DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

I'm glad you're planning to include `DoubleWidth` this time.

  • Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

While I'm sure any such type *could* be a binary integer type, I'm not convinced they necessary *should* be. For instance, suppose I have a "bit vector"; I know I never want to perform arithmetic on it, but I *do* want to manipulate bits separately, so I make it look like a `RandomAccessCollection` of `Bool`s. It might make a great deal of sense to support bitwise operations on this type, even though I don't want to clutter it up with arithmetic.

···

On Jan 13, 2017, at 12:47 PM, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

--
Brent Royal-Gordon
Architechies


(David Sweeris) #10

What about having a "CompoundBinaryInteger<T,U>" type, and then do "typealias DoubleWidth<T> = CompoundBinaryInteger<T,T>"? That would make it easier to have, say, 40-bit ints, "CompoundBinaryInteger<Int8,Int32>", while still having the convenience of "DoubleWidth<T>".

- Dave Sweeris

···

On Jan 13, 2017, at 12:47, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

DoubleWidth
The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.


(Max Moiseev) #11

Hi Xiaodi,

What is the performance penalty as compared to the existing operators?

First of all, I don’t have the concrete numbers unfortunately. But…
If we are talking about concrete types, there should be very little difference between the two smart and masking shifts.
For example, the following functions:

public func foo(x: UInt) -> UInt {
  return x >> 32
}

public func bar(x: UInt) -> UInt {
  return x &>> 32
}

Produce equivalent SIL and LLVM IR when compiled with optimizations. Moreover, if you change 32 to 100, then foo will become something like:

foo(x: UInt) { return 0 }

whereas bar will still call the llvm.shl.

Beyond performance, what are the implications for migrating existing bit twiddling algorithms written in Swift 3?

Let’s take for example the ‘&>>” operator. There are 2 overloads: &>>(Self, Self) and &>><Other : BinaryInteger>(Self, Other)
(In Swift 3 there is only one version of >>, that takes both arguments of the same type.)

So, in an expression `x &>> 32`, compiler assumes 32 to have type Int (which is the default type for the integer literals) and prefer the heterogeneous overload. It might not be too bad, as I showed in examples above, but in order to increase chances of success you might want to specify an explicit type context, as in `x &>> (32 as TypeOfX)`.

As always, only concrete benchmarks will tell. We spent many hours optimizing the implementation for our existing benchmark suite.

Max

···

On Jan 13, 2017, at 2:14 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

[Resending to list with original message removed for length.]

This is fantastic. Glad to see it take shape. Very neat and insightful to have trailingZeros on BinaryInteger but leadingZeros on FixedWidthInteger. A couple of questions on smart shifts: What is the performance penalty as compared to the existing operators? Beyond performance, what are the implications for migrating existing bit twiddling algorithms written in Swift 3?


(Stephen Canon) #12

Hi Xiaodi —

I don’t want to speak for Max and Dave, but I think I can provide some insight for your questions about shifts.

First, the overwhelming majority of shifts have a compile-time-constant RHS. For these cases, there’s no performance change (except that the smart shifts may be able to optimize away the entire expression if the shift is overlarge).

For smart shifts with non-constant right-hand sides, the compiler will frequently still be able to prove that the shift count is always positive or negative and less than word size (this handles a lot of the most common cases like normalizing an integer, reading from a bitstream, or shifting words of a bignum); again there’s no performance penalty.

In the remaining cases where the compiler cannot bound the right-hand side, there will be some branches present; there may be a few regressions from these cases, but I expect most to be small (and the code simplifications are well worth it). Users can always use the masking shifts, which lower to single instructions for 32b and 64b integers types on Intel and arm64, and which are at worst an and and a shift (two very cheap instructions) on other architectures.

Basically, I expect there to be no perf impact for almost all code, and that the perf impact is relatively easily mitigated when it does occur. This is an easy tradeoff for fully-defined and sensible operator behavior.

– Steve

···

On Jan 13, 2017, at 5:14 PM, Xiaodi Wu via swift-evolution <swift-evolution@swift.org> wrote:

[Resending to list with original message removed for length.]

This is fantastic. Glad to see it take shape. Very neat and insightful to have trailingZeros on BinaryInteger but leadingZeros on FixedWidthInteger. A couple of questions on smart shifts: What is the performance penalty as compared to the existing operators? Beyond performance, what are the implications for migrating existing bit twiddling algorithms written in Swift 3?


(Benjamin Spratling) #13

I notice the BinaryInteger's func word(at n: Int) -> UInt function expects a 2's complement representation. Do you expect that "BigInt" will be implemented with 2's complement? As a nonmutating function, I would think any implementation from a 1's complement big int would result in O(n^2) unless the BigInt were designed with scratch space where it could store the intermediate values of that representation. I only ask because just last week I was designing an arbitrary-width float type in 1's complement, well, really I kept the sign bit in a separate Bool. Of course, I recognize the value of being able to write integer init code from a 2's complement representation, I'm just curious if there's a way to allow this function to be more efficient for alternate representations.

I love that there's a DoubleWidth type, having coded some arbitrary precision arithmetic, that's always a downer going from generic code to having to pick a specific "big enough" result type.

I'm glad the % operator got moved. It really did stand out as not part of floating points.

Trailing zeros looks like a sensible optimization.

I agree with moving the shift operators, I like that you've called out the notion of an infinite shift. I can't say I fully understood the use of the separate mask vs. smart shift operators, but I'll take another read in the next few days and see if I understand why they exist.

I know this PR does not address the BitInt implementation, but do you have one?

I'm glad to see this moving forward.

-Ben Spratling

···

Sent from my iPad

On Jan 14, 2017, at 2:00 AM, Rien via swift-evolution <swift-evolution@swift.org> wrote:

+1

Any change of including “ranged integers”?
I.e. an integer with a value that must fit in a predefined range?

Regards,
Rien

Site: http://balancingrock.nl
Blog: http://swiftrien.blogspot.com
Github: http://github.com/Swiftrien
Project: http://swiftfire.nl

On 13 Jan 2017, at 21:47, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

   • Proposal: SE-NNNN
   • Authors: Dave Abrahams, Maxim Moiseev
   • Review Manager: TBD
   • Status: Awaiting review
   • Bug: SR-3196
   • Previous Proposal: SE-0104
Introduction

This proposal is an evolution of SE-0104. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104) are listed in a dedicated section.

Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x
<<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

               +--------------+ +-------------+
       +------>+ Arithmetic | | Comparable |
       > > (+,-,*,/) | | (==,<,>,...)|
       > +-------------++ +---+---------+
       > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
      ^ ++---+-----+----------+
      > +-----------^ ^ ^---------------+
      > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
               ^ ^ ^ ^
               > > > >
               > > > >
              ++--------+-+ +-+-------+-+
              >Int family |-+ |UInt family|-+
              +-----------+ | +-----------+ |
                +-----------+ +-----------+

There are several benefits provided by this model over the old one:

   • It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

   • It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

   • It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 should now refine SignedArithmetic.

   • It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch.

A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

   • x << -2 is equivalent to x >> 2

   • (1 as UInt8) >> 42) will evaluate to 0

   • (-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

Detailed design

What's new since SE-0104

   • SE-0091 removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

   • Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model in Swift 3.

   • Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

   • BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

   • minimumSignedRepresentationBitWidth property was removed.

   • trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

   • Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

   • Standard library introduces the new type DoubleWidth<T>.

See this section for more details.

Protocols

Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral
{

/// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
/// constant `y` from `1_000` fails because the `Int8` type can represent
/// `127` at maximum:
///
/// let x = Int8(exactly: 100)
/// // x == Optional(100)
/// let y = Int8(exactly: 1_000)
/// // y == nil
///
/// - Parameter source: A floating-point value to convert to an integer.
init?<T : BinaryInteger>(exactly source
: T)

/// A type that can represent the absolute value of any possible value of the
/// conforming type.
associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

/// The magnitude of this value.
///
/// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
/// You can use the `magnitude` property in operations that are simpler to
/// implement in terms of unsigned values, such as printing the value of an
/// integer, which is just printing a '-' character in front of an absolute
/// value.
///
/// let x = -200
/// // x.magnitude == 200
///
/// The global `abs(_:)` function provides more familiar syntax when you need
/// to find an absolute value. In addition, because `abs(_:)` always returns
/// a value of the same type, even in a generic context, using the function
/// instead of the `magnitude` property is encouraged.
///
/// - SeeAlso: `abs(_:)`
var magnitude: Magnitude { get
}

/// Returns the sum of the two given values.
///
/// The sum of `lhs` and `rhs` must be representable in the same type. In the
/// following example, the result of `100 + 200` is greater than the maximum
/// representable `Int8` value:
///
/// let x: Int8 = 10 + 21
/// // x == 31
/// let y: Int8 = 100 + 121
/// // Overflow error
static func +(_ lhs: Self, _ rhs: Self) -> Self

/// Adds the given value to this value in place.
///
/// For example:
///
/// var x = 15
/// y += 7
/// // y == 22
static func +=(_ lhs: inout Self, rhs: Self
)

/// Returns the difference of the two given values.
///
/// The difference of `lhs` and `rhs` must be representable in the same type.
/// In the following example, the result of `10 - 21` is less than zero, the
/// minimum representable `UInt` value:
///
/// let x: UInt = 21 - 10
/// // x == 11
/// let y: UInt = 10 - 21
/// // Overflow error
static func -(_ lhs: Self, _ rhs: Self) -> Self

/// Subtracts the given value from this value in place.
///
/// For example:
///
/// var x = 15
/// y -= 7
/// // y == 8
static func -=(_ lhs: inout Self, rhs: Self
)

/// Returns the product of the two given values.
///
/// The product of `lhs` and `rhs` must be representable in the same type. In
/// the following example, the result of `10 * 50` is greater than the
/// maximum representable `Int8` value.
///
/// let x: Int8 = 10 * 5
/// // x == 50
/// let y: Int8 = 10 * 50
/// // Overflow error
static func *(_ lhs: Self, _ rhs: Self) -> Self

/// Multiples this value by the given value in place.
///
/// For example:
///
/// var x = 15
/// y *= 7
/// // y == 105
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
static func /(_ lhs: Self, _ rhs: Self) -> Self

/// Divides this value by the given value in place.
///
/// For example:
///
/// var x = 15
/// y /= 7
/// // y == 2
static func /=(_ lhs: inout Self, rhs: Self
)
}

extension Arithmetic
{

public init() { self = 0
}

public static prefix func + (x: Self) -> Self
{

return
x
}
}

SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic
{

/// Returns the additive inverse of this value.
///
/// let x = 21
/// let y = -x
/// // y == -21
///
/// - Returns: The additive inverse of this value.
///
/// - SeeAlso: `negate()`
static prefix func - (_ operand: Self) -> Self

/// Replaces this value with its additive inverse.
///
/// The following example uses the `negate()` method to negate the value of
/// an integer `x`:
///
/// var x = 21
/// x.negate()
/// // x == -21
///
/// - SeeAlso: The unary minus operator (`-`).
mutating func negate
()
}

extension SignedArithmetic
{

public static prefix func - (_ operand: Self) -> Self
{

var result =
operand
   result.
negate
()

return
result
}

public mutating func negate
() {

self = Self() - self

}
}

BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

   • Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

   • Extend or truncate the value to fit into Self

   • Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable
{

/// 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.
static var isSigned: Bool { get
}

/// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
init?<T : FloatingPoint>(exactly source
: T)

/// Creates an integer from the given floating-point value, truncating any
/// fractional part.
///
/// Truncating the fractional part of `source` is equivalent to rounding
/// 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 truncation, a
/// runtime error may occur.
///
/// let z = UInt(-21.5)
/// // Error: ...the result would be less than UInt.min
///
/// - Parameter source: A floating-point value to convert to an integer.
/// `source` must be representable in this type after truncation.
init<T : FloatingPoint>(_ source
: T)

/// Creates an 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.
init<T : BinaryInteger>(_ source
: T)

/// Creates a new instance from the bit pattern of the given instance by
/// sign-extending 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
/// least-significant bits of `source`. For example, when converting a
/// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
/// // x == -21
/// // 'x' has a binary representation of 11111111_11101011
/// let y = UInt16(extendingOrTruncating: w)
/// // y == 65515
/// // 'y' has a binary representation of 11111111_11101011
///
/// - Parameter source: An integer to convert to this type.
init<T : BinaryInteger>(extendingOrTruncating source
: T)

/// 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.
init<T : BinaryInteger>(clamping source
: T)

/// Returns the n-th word, counting from the least significant to most
/// significant, of this value's binary representation.
///
/// The `word(at:)` method returns negative values in two's complement
/// representation, regardless of a type's underlying implementation. If `n`
/// is greater than the number of words in this value's current
/// representation, the result is `0` for positive numbers and `~0` for
/// negative numbers.
///
/// - Parameter n: The word to return, counting from the least significant to
/// most significant. `n` must be greater than or equal to zero.
/// - Returns: An word-sized, unsigned integer with the bit pattern of the
/// n-th word of this value.
func word(at n: Int) -> UInt

/// The number of bits in the current binary representation of this value.
///
/// This property is a constant for instances of fixed-width integer
/// types.
var bitWidth : Int { get
}

/// The number of trailing zeros in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number -8 has three trailing zeros.
///
/// let x = Int8(bitPattern: 0b1111_1000)
/// // x == -8
/// // x.trailingZeros == 3
var trailingZeros: Int { get
}

/// Returns the remainder of dividing the first value by the second.
///
/// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
///
/// let x = 22 % 5
/// // x == 2
/// let y = 22 % -5
/// // y == 2
/// let z = -22 % -5
/// // z == -2
///
/// - Parameters:
/// - lhs: The value to divide.
/// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
static func %(_ lhs: Self, _ rhs: Self) -> Self

/// Replaces this value with the remainder of itself divided by the given
/// value. For example:
///
/// var x = 15
/// x %= 7
/// // x == 1
///
/// - Parameter rhs: The value to divide this value by. `rhs` must not be
/// zero.
///
/// - SeeAlso: `remainder(dividingBy:)`
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).
static prefix func ~ (_ x: Self) -> Self

/// Returns the result of performing a bitwise AND operation on this value
/// and the given value.
///
/// 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
static func &(_ lhs: Self, _ rhs: Self) -> Self

static func &=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise OR operation on this value and
/// the given value.
///
/// 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
static func |(_ lhs: Self, _ rhs: Self) -> Self

static func |=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise XOR operation on this value
/// and the given value.
///
/// 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
static func ^(_ lhs: Self, _ rhs: Self) -> Self

static func ^=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
/// specified number of digits to the right.
///
/// In a *masking shift*, the bit pattern of the value passed as `rhs` is
/// masked to produce a value between zero and the bit width of `lhs`. The
/// shift is performed using this masked value. Masking shifts require more
/// care to use correctly than a traditional bit shift, but are likely to be
/// more efficient when used with shift amounts that are not compile-time
/// constants. On most architectures, a masking shift compiles down to a
/// single instruction.
///
/// For example, if you shift an 8-bit, unsigned integer by 2, the shift
/// amount requires no masking.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y = x &>> 2
/// // y == 7 // 0b00000111
///
/// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
/// uses that masked value as the number of bits to shift `x`.
///
/// let z = x &>> 11
/// // z == 3 // 0b00000011
///
/// Relationship to the Right Shift Operator
/// ----------------------------------------
///
/// The masking right shift operator handles attempted overshifts and
/// undershifts differently from the right shift operator (`>>`). When the
/// value passed as `rhs` in a masking shift is within the range
/// `0...<bitWidth`, the operation is equivalent to using the right shift
/// operator.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y1 = x &>> 2
/// // y1 == 7 // 0b00000111
/// let y2 = x >> 2
/// // y2 == 7 // 0b00000111
///
/// The right shift operator does not mask its right-hand-side argument, so
/// passing `11` as `rhs` shifts all the bits of `x` to zero.
///
/// let z1 = x &>> 11
/// // z1 == 240 // 0b00000011
/// let z2 = x >> 11
/// // z2 == 0 // 0b00000000
///
/// - Parameter rhs: The number of bits to shift this value to the right. If
/// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
/// value within that range.
/// - Returns: The result of shifting this value by the masked `rhs` to the
/// right.
///
/// - SeeAlso: `&<<`, `>>`
static func &>>(_ lhs: Self, _ rhs: Self) -> Self

static func &>>=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
/// specified number of digits to the left.
///
/// In a *masking shift*, the bit pattern of the value passed as `rhs` is
/// masked to produce a value between zero and the bit width of `lhs`. The
/// shift is performed using this masked value. Masking shifts require more
/// care to use correctly than a traditional bit shift, but are likely to be
/// more efficient when used with shift amounts that are not compile-time
/// constants. On most architectures, a masking shift compiles down to a
/// single instruction.
///
/// For example, if you shift an 8-bit, unsigned integer by 2, the shift
/// amount requires no masking.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y = x &>> 2
/// // y == 120 // 0b01111000
///
/// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
/// uses that masked value as the number of bits to shift `x`.
///
/// let z = x &<< 11
/// // z == 240 // 0b11110000
///
/// Relationship to the Left Shift Operator
/// ---------------------------------------
///
/// The masking left shift operator handles attempted overshifts and
/// undershifts differently from the left shift operator (`<<`). When the
/// value passed as `rhs` in a masking shift is within the range
/// `0...<bitWidth`, the operation is equivalent to using the left shift
/// operator.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y1 = x &<< 2
/// // y1 == 120 // 0b01111000
/// let y2 = x << 2
/// // y2 == 120 // 0b01111000
///
/// The left shift operator does not mask its right-hand-side argument, so
/// passing `11` as `rhs` shifts all the bits of `x` to zero.
///
/// let z1 = x &<< 11
/// // z1 == 240 // 0b11110000
/// let z2 = x << 11
/// // z2 == 0 // 0b00000000
///
/// - Parameter rhs: The number of bits to shift this value to the left. If
/// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
/// value within that range.
/// - Returns: The result of shifting this value by the masked `rhs` to the
/// left.
///
/// - SeeAlso: `&>>`, `<<`
static func &<<(_ lhs: Self, _ rhs: Self) -> Self

static func &<<=(_ lhs: inout Self, _ rhs: Self
)

/// 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.
/// - Returns: A tuple containing the quotient and remainder of this value
/// divided by `rhs`.
func quotientAndRemainder(dividingBy rhs: Self
)

-> (quotient: Self, remainder: Self
)

/// Returns `-1` if this value is negative and `1` if it's positive;
/// otherwise, `0`.
///
/// - Returns: The sign of this number, expressed as an integer of the same
/// type.
func signum() -> Self

}

FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger
{

/// The number of bits used for the underlying binary representation of
/// values of this type.
///
/// An unsigned, fixed-width integer type can represent values from 0 through
/// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
/// fixed-width integer type can represent values from
/// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
/// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
/// the range `-128...127`.
static var bitWidth : Int { get
}

/// The maximum representable integer in this type.
///
/// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
/// `**` is exponentiation. For signed integer types, this value is
/// `(2 ** bitWidth - 1) - 1`.
static var max: Self { get
}

/// The minimum representable value.
///
/// For unsigned integer types, this value is always `0`. For signed integer
/// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
/// exponentiation.
static var min: Self { get
}

/// Returns the sum of this value and the given value along with a flag
/// indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to add to this value.
/// - Returns: A tuple containing the result of the addition along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire sum. If
/// the `overflow` component is `.overflow`, an overflow occurred and the
/// `partialValue` component contains the truncated sum of this value and
/// `other`.
///
/// - SeeAlso: `+`
func addingWithOverflow(_ other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the difference of this value and the given value along with a
/// flag indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to subtract from this value.
/// - Returns: A tuple containing the result of the subtraction along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire
/// difference. If the `overflow` component is `.overflow`, an overflow
/// occurred and the `partialValue` component contains the truncated
/// result of `other` subtracted from this value.
///
/// - SeeAlso: `-`
func subtractingWithOverflow(_ other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the product of this value and the given value along with a flag
/// indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to multiply by this value.
/// - Returns: A tuple containing the result of the multiplication along with
/// a flag indicating whether overflow occurred. If the `overflow`
/// component is `.none`, the `partialValue` component contains the entire
/// product. If the `overflow` component is `.overflow`, an overflow
/// occurred and the `partialValue` component contains the truncated
/// product of this value and `other`.
///
/// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
func multipliedWithOverflow(by other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the quotient of dividing this value by the given value along with
/// a flag indicating whether overflow occurred in the operation.
///
/// For a value `x`, if zero is passed as `other`, the result is
/// `(x, .overflow)`.
///
/// - Parameter other: The value to divide this value by.
/// - Returns: A tuple containing the result of the division along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire quotient.
/// If the `overflow` component is `.overflow`, an overflow occurred and
/// the `partialValue` component contains the truncated quotient.
///
/// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
func dividedWithOverflow(by other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns a tuple containing the high and low parts of the result of
/// multiplying its arguments.
///
/// Use this method to calculate the full result of a product that would
/// otherwise overflow. Unlike traditional truncating multiplication, the
/// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
/// parts of the product of `lhs` and `rhs`. The following example uses this
/// method to multiply two `UInt8` values that normally overflow when
/// multiplied:
///
/// let x: UInt8 = 100
/// let y: UInt8 = 20
/// let result = UInt8.doubleWidthMultiply(100, 20)
/// // result.high == 0b00000111
/// // result.low == 0b11010000
///
/// The product of `x` and `y` is 2000, which is too large to represent in a
/// `UInt8` instance. The `high` and `low` components of the `result` tuple
/// represent 2000 when concatenated to form a double-width integer; that
/// is, using `result.high` as the high byte and `result.low` as the low byte
/// of a `UInt16` instance.
///
/// let z = UInt16(result.high) << 8 | UInt16(result.low)
/// // z == 2000
///
/// - Parameters:
/// - lhs: A value to multiply.
/// - rhs: Another value to multiply.
/// - Returns: A tuple containing the high and low parts of the result of
/// multiplying `lhs` and `rhs`.
///
/// - SeeAlso: `multipliedWithOverflow(by:)`
static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self
)

-> (high: Self, low
: Magnitude)

/// Returns a tuple containing the quotient and remainder of dividing the
/// first argument by the second.
///
/// The resulting quotient must be representable within the bounds of the
/// type. If the quotient of dividing `lhs` by `rhs` is too large to
/// represent in the type, a runtime error may occur.
///
/// - Parameters:
/// - lhs: A tuple containing the high and low parts of a double-width
/// integer. The `high` component of the tuple carries the sign, if the
/// type is signed.
/// - rhs: The integer to divide into `lhs`.
/// - Returns: A tuple containing the quotient and remainder of `lhs` divided
/// by `rhs`.
static func doubleWidthDivide
(

_ lhs: (high: Self, low: Magnitude), _ rhs: Self
)

-> (quotient: Self, remainder: Self
)

/// The number of bits equal to 1 in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number 31 has five bits equal to 1.
///
/// let x: Int8 = 0b0001_1111
/// // x == 31
/// // x.popcount == 5
var popcount: Int { get
}

/// The number of leading zeros in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number 31 has three leading zeros.
///
/// let x: Int8 = 0b0001_1111
/// // x == 31
/// // x.leadingZeros == 3
/// - SeeAlso: `BinaryInteger.trailingZeros`
var leadingZeros: Int { get
}

/// Creates an integer from its big-endian representation, changing the
/// byte order if necessary.
init(bigEndian value: Self
)

/// Creates an integer from its little-endian representation, changing the
/// byte order if necessary.
init(littleEndian value: Self
)

/// The big-endian representation of this integer.
///
/// If necessary, the byte order of this value is reversed from the typical
/// byte order of this integer type. On a big-endian platform, for any
/// integer `x`, `x == x.bigEndian`.
///
/// - SeeAlso: `littleEndian`
var bigEndian: Self { get
}

/// The little-endian representation of this integer.
///
/// If necessary, the byte order of this value is reversed from the typical
/// byte order of this integer type. On a little-endian platform, for any
/// integer `x`, `x == x.littleEndian`.
///
/// - SeeAlso: `bigEndian`
var littleEndian: Self { get
}

/// A representation of this integer with the byte order swapped.
var byteSwapped: Self { get
}
}

Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger
{

associatedtype Magnitude : BinaryInteger

}

public protocol SignedInteger : BinaryInteger, SignedArithmetic
{

associatedtype Magnitude : BinaryInteger

}

DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

Extra operators

In addition to the operators described in the protocols section, we also provide a few extensions that are not protocol requirements:

Heterogeneous shifts

extension BinaryInteger
{

// Masking shifts
static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

// 'Smart' shifts
static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)
}

Heterogeneous equality and comparison

extension BinaryInteger
{

// Equality
static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

// Comparison
static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

}

Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
Non-goals

This proposal:

   • DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

   • DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

   • Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

   • Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

   • Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Xiaodi Wu) #14

Great work, all. I'm not sure I ever commented on SE-0104, so I've read
through this one more carefully. Here are some things that came to mind:

*## Arithmetic*

Why are ExpressibleByIntegerLiteral and init?<T:BinaryInteger>(exactly:)
required? I could understand needing access to 0, but this could be
provided by a static property or nullary initializer. It doesn't seem like
all types supporting arithmetic operations would necessarily be convertible
from an arbitrary binary integer.

I tried to evaluate the Arithmetic protocol by considering what it means
for higher-dimensional types such as CGPoint and CGVector. My use case was
a linear interpolation function:

    func lerp<T: Arithmetic>(from a: T, to b: T, by ratio: T) -> T {
        return a + (b - a) * ratio
    }

If I've read the proposal correctly, this definition works for integer and
floating-point values. But we can't make it work properly for CGVector (or,
perhaps less mathematically correct but more familiar, CGPoint). It's okay
to define +(CGVector, CGVector) and -(CGVector, CGVector), but *(CGVector,
CGVector) and /(CGVector, CGVector) don't make much sense. What we really
want is *(CGVector, *CGFloat*) and /(CGVector, *CGFloat*).

After consulting a mathematician, I believe what the lerp function really
wants is for its generic param to be an affine space
<https://en.wikipedia.org/wiki/Affine_space>. I explored this a bit here:
https://gist.github.com/jtbandes/93eeb7d5eee8e1a7245387c660d53b
03#file-affine-swift-L16-L18

This approach is less restrictive and more composable than the proposed
Arithmetic protocol, which can be viewed as a special case with the
following definitions:

    extension Arithmetic: AffineSpace, VectorSpace { // not actually
allowed in Swift
        typealias Displacement = Self
        typealias Scalar = Self
    }

It'd be great to be able to define a lerp() which works for all
floating-point and integer numbers, as well as points and vectors (assuming
a glorious future where CGPoint and CGVector have built-in arithmetic
operations). But maybe the complexity of these extra protocols isn't worth
it for the stdlib...

I think, in the end, it's the _name_ that could use improvement here. As
the doc comments say, `Arithmetic` is supposed to provide a "suitable basis
for arithmetic on scalars"--perhaps `ScalarArithmetic` might be more
appropriate? It would make it clear that `CGVector` is not meant to be a
conforming type.

*## BinaryInteger*

I'm a little confused by the presence of init(extendingOrTruncating:) for
*all* binary integers. Why does it make sense to be able to write
UInt16(extendingOrTruncating: (-21 as Int8)) ? In my mind, sign-extension
only has meaning when the source and destination types are both signed.

Here (just IMHO), I disagree. Since any binary integer can be truncated and
any can be right-shifted, it makes sense for `init(extendingOrTruncating:)`
to be available for all of them. If I understand the proposal correctly,
`Int(extendingOrTruncating: (-1 as Int8))` would give you a different
result than `Int(extendingOrTruncating: (255 as UInt8)`.

Although I would not be against a clamp() function in the standard library,

"init(clamping:)" sounds strange to me. What about calling it
"init(nearestTo:)"? One could also define a FloatingPoint version of
init(nearestTo:), i.e. lround(). For maximum annoyance and explicitness,
you could even rename the existing init(_:slight_smile: to init(truncating:) to make it
clear that truncation, not regular rounding, occurs when converting from
floating-point.

I would disagree with that as well; the existing `init(_:)` truncates the
fractional part but errors if that value is outside the representable
range, while the word "truncating" makes it sound like something is done to
make any possible source value give you a destination value (a la
"extendingOrTruncating" for integers).

Meanwhile, "nearest to" is problematic for me because either 127 and 129 is
"nearest to" 128, and neither integer is "nearest to" 500, yet
`Int8(clamping: 128)` and `Int8(clamping: 500)` both give you 127. This
operation is very different from lround() for floating point, which in
Swift is `rounded(.toNearestOrAwayFromZero)` (or just `rounded()`).

In both these cases, I think it's important to use spellings that
distinguish doing things to the fractional part of floating point values
and doing things to the binary representation of integer values. I think
there's great value in using the term "clamp", which is very different from
"nearest"; and in using an unlabeled `init(_:)` for initializing from FP
values, which is most similar to the unlabeled `init(_:)` for initializing
from integer values, as opposed to your suggested `init(truncating:)` which
connotes some similarity to `init(extendingOrTruncating:)` for integer
values.

*... masking shifts*

The example claims that "(30 as UInt8) &>> 11" produces 3, because it
right-shifts 30 by 3. But isn't the bitWidth of UInt8 always 8 since it's a
fixed-width type? Why should 11 get masked to 3 before the shift? (Also, it
might be a good idea to choose examples with numbers whose base-ten
representations don't look like valid binary. :wink:) What use cases are there
for masking shifts? I was under the impression that "smart shifts" were
pretty much how the usual shift instructions already behaved.

(Minor: were the smart shift operators supposed to be included as
BinaryInteger protocol requirements? I only see them in the "heterogeneous
shifts" extension.)

*... init<T: BinaryInteger>(_ source: T)*

Now a thought experiment: suppose you wanted to write an
arbitrary-precision BigInt, or any binary integer such as Int256. The
BinaryInteger protocol requires you to provide init<T:BinaryInteger>(_
source: T). Given the source of type T, how do you access its bits? Is
repeated use of word(at:) the recommended way? If so, it might be nice to
include a "wordCount" returning the number of available words; otherwise I
suppose the user has to use something like bitWidth/(8*MemoryLayout<Int>.size),
which is pretty ugly.

*## FixedWidthInteger*

Why is popcount restricted to FixedWidthInteger? It seems like it could
theoretically apply to any UnsignedInteger.

You can perfectly legitimately get a popcount for a signed integer. It's
just looking at the binary representation and counting the ones. But then
with two's complement, it'd have to be restricted to FixedWidthInteger and
not BinaryInteger, because the same negative value would have a different
popcount depending on the type's bitwidth. I'd disagree strongly with
removing popcount from signed binary integers. However, I suppose the same
requirement could be applied to both FixedWidthInteger and UnsignedInteger.

*## Heterogenous shifts, equality, and comparison*

···

On Sat, Jan 14, 2017 at 1:32 AM, Jacob Bandes-Storch via swift-evolution < swift-evolution@swift.org> wrote:

These look great. How will the default implementations be provided?
(Equivalent question: how would a user define their own heterogeneous
operators?) I suppose this works:

    static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
{
        // delegate to the protocol requirement &>>(Self, Self)
        return self &>> Self(extendingOrTruncating: rhs)
    }

But for operations you can't delegate so easily... I'm imagining trying to
implement heterogeneous comparison (i.e. < ) and the best I can come up
with uses signum() and word(at:)...

Also, should these be protocol requirements so user-defined types can
specialize them?

*## Masking arithmetic*

Do &* and &+ and &- need their operands to have the same type, or could
these be heterogeneous too (at least &+ and &-)?

Jacob

On Fri, Jan 13, 2017 at 12:47 PM, Max Moiseev via swift-evolution < > swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for
the standard library. It even resulted in acceptance of SE-0104
<https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for
Swift 3. Unfortunately we were not able to implement it in time for the
release.

But it was not forgotten, although, as time went by, a few changes needed
to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make
integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/m
oiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #15

It's easy to prove that the heterogeneous overload can't have different
semantics from the homogeneous one, so there is absolutely nothing to
worry about—other than, arguably, that it could take slightly more
time to type-check.

···

on Fri Jan 13 2017, Max Moiseev <swift-evolution@swift.org> wrote:

So, in an expression `x &>> 32`, compiler assumes 32 to have type Int
(which is the default type for the integer literals) and prefer the
heterogeneous overload. It might not be too bad, as I showed in
examples above, but in order to increase chances of success you might
want to specify an explicit type context, as in `x &>> (32 as
TypeOfX)`.

--
-Dave


(Dave Abrahams) #16

I notice the BinaryInteger's func word(at n: Int) -> UInt function
expects a 2's complement representation. Do you expect that "BigInt"
will be implemented with 2's complement?

Ah, this is an excellent question, excellently phrased!

We designed it so BigInt could use 2's complement (see
DoubleWidth<Int64>, which works that way), which should be faster than
sign-magnitude...

BUT: I hadn't really considered that if existing bignum libraries use
sign-magnitude, we'll want to be able to efficiently use their
representations, so we need to make sure the protocols don't force those
representations to be inefficient.

As a nonmutating function, I would think any implementation from a 1's
complement big int would result in O(n^2) unless the BigInt were
designed with scratch space where it could store the intermediate
values of that representation.

Oh... you mean that word(at:) itself would be linear, and thus
algorithms that iterate the words linearly would be O(N^2)... yuck.

So far, the only algorithm we have using word(at:) is this one, and
https://github.com/apple/swift/blob/new-integer-protocols/stdlib/public/core/Integers.swift.gyb#L2191
presumably we could adapt it to sign-magnitude by expanding the
BinaryInteger protocol with a static var that indicates which
representation is used.

  enum Representation {
    twosComplement, signMagnitude, /*onesComplement?*/
  }
  static var representation: Representation { get }

Now, the other algorithms that I can anticipate would use word(at:) are
basically... the ones you'd have to implement to build BigInt, so I
guess this change would be OK.

Supporting sign-magnitude complicates generic programming with these
protocols, though, so I want to be really sure we need to do this before
we take the plunge.

I only ask because just last week I was designing an arbitrary-width
float type in 1's complement, well, really I kept the sign bit in a
separate Bool.

Sounds like sign-magnitude rather than 1's complement if I remember my
complements correctly.

Of course, I recognize the value of being able to write integer init
code from a 2's complement representation, I'm just curious if there's
a way to allow this function to be more efficient for alternate
representations.

I love that there's a DoubleWidth type, having coded some arbitrary
precision arithmetic, that's always a downer going from generic code
to having to pick a specific "big enough" result type.

I'm glad the % operator got moved. It really did stand out as not
part of floating points.

Trailing zeros looks like a sensible optimization.

I agree with moving the shift operators, I like that you've called out
the notion of an infinite shift.

I don't think we ever meant to say anything about infinite shifts!

I can't say I fully understood the use of the separate mask vs. smart
shift operators, but I'll take another read in the next few days and
see if I understand why they exist.

You're not alone it appears. We need to clarify that in the text,
obviously. The smart shift operators are there to give you sensible
semantics without undefined behavior or traps in the cases that have
logically computable answers. The masking shifts are there for
performance in the rare cases where smart shifting with a non-literal
shift amount introduces non-negligible overheads (testing and branching
to handle overshifts and negative shift amounts).

Obviously you have to know that the masking behavior is benign in your
use case when using masking shifts in an operation. I made the mistake
of using a masking shift to optimize some code the other day where the
shift amount could be equal to the full width of the value being
shifted. I ended up widening the LHS before doing the shift and then
truncating back to the width, but that's only because I was writing
performance-critical code. The smart shift would have “just worked.”

I know this PR does not address the BitInt implementation, but do you
have one?

I know someone that implemented one... using sign-magnitude, actually,
and his word(at:) implementation has the linear cost problem. I'll ask
him to post a link.

···

on Sat Jan 14 2017, Benjamin Spratling <swift-evolution@swift.org> wrote:

I'm glad to see this moving forward.

-Ben Spratling

On Jan 14, 2017, at 2:00 AM, Rien via swift-evolution <swift-evolution@swift.org> wrote:

+1

Any change of including “ranged integers”?
I.e. an integer with a value that must fit in a predefined range?

Regards,
Rien

Site: http://balancingrock.nl
Blog: http://swiftrien.blogspot.com
Github: http://github.com/Swiftrien
Project: http://swiftfire.nl

On 13 Jan 2017, at 21:47, Max Moiseev via swift-evolution <swift-evolution@swift.org> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

   • Proposal: SE-NNNN
   • Authors: Dave Abrahams, Maxim Moiseev
   • Review Manager: TBD
   • Status: Awaiting review
   • Bug: SR-3196
   • Previous Proposal: SE-0104
Introduction

This proposal is an evolution of SE-0104. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104) are listed in a dedicated section.

Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x
<<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

               +--------------+ +-------------+
       +------>+ Arithmetic | | Comparable |
       > > (+,-,*,/) | | (==,<,>,...)|
       > +-------------++ +---+---------+
       > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
      ^ ++---+-----+----------+
      > +-----------^ ^ ^---------------+
      > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
               ^ ^ ^ ^
               > > > >
               > > > >
              ++--------+-+ +-+-------+-+
              >Int family |-+ |UInt family|-+
              +-----------+ | +-----------+ |
                +-----------+ +-----------+

There are several benefits provided by this model over the old one:

   • It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

   • It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

   • It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 should now refine SignedArithmetic.

   • It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch.

A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

   • x << -2 is equivalent to x >> 2

   • (1 as UInt8) >> 42) will evaluate to 0

   • (-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

Detailed design

What's new since SE-0104

   • SE-0091 removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

   • Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model in Swift 3.

   • Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

   • BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

   • minimumSignedRepresentationBitWidth property was removed.

   • trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

   • Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

   • Standard library introduces the new type DoubleWidth<T>.

See this section for more details.

Protocols

Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral
{

/// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
/// constant `y` from `1_000` fails because the `Int8` type can represent
/// `127` at maximum:
///
/// let x = Int8(exactly: 100)
/// // x == Optional(100)
/// let y = Int8(exactly: 1_000)
/// // y == nil
///
/// - Parameter source: A floating-point value to convert to an integer.
init?<T : BinaryInteger>(exactly source
: T)

/// A type that can represent the absolute value of any possible value of the
/// conforming type.
associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

/// The magnitude of this value.
///
/// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
/// You can use the `magnitude` property in operations that are simpler to
/// implement in terms of unsigned values, such as printing the value of an
/// integer, which is just printing a '-' character in front of an absolute
/// value.
///
/// let x = -200
/// // x.magnitude == 200
///
/// The global `abs(_:)` function provides more familiar syntax when you need
/// to find an absolute value. In addition, because `abs(_:)` always returns
/// a value of the same type, even in a generic context, using the function
/// instead of the `magnitude` property is encouraged.
///
/// - SeeAlso: `abs(_:)`
var magnitude: Magnitude { get
}

/// Returns the sum of the two given values.
///
/// The sum of `lhs` and `rhs` must be representable in the same type. In the
/// following example, the result of `100 + 200` is greater than the maximum
/// representable `Int8` value:
///
/// let x: Int8 = 10 + 21
/// // x == 31
/// let y: Int8 = 100 + 121
/// // Overflow error
static func +(_ lhs: Self, _ rhs: Self) -> Self

/// Adds the given value to this value in place.
///
/// For example:
///
/// var x = 15
/// y += 7
/// // y == 22
static func +=(_ lhs: inout Self, rhs: Self
)

/// Returns the difference of the two given values.
///
/// The difference of `lhs` and `rhs` must be representable in the same type.
/// In the following example, the result of `10 - 21` is less than zero, the
/// minimum representable `UInt` value:
///
/// let x: UInt = 21 - 10
/// // x == 11
/// let y: UInt = 10 - 21
/// // Overflow error
static func -(_ lhs: Self, _ rhs: Self) -> Self

/// Subtracts the given value from this value in place.
///
/// For example:
///
/// var x = 15
/// y -= 7
/// // y == 8
static func -=(_ lhs: inout Self, rhs: Self
)

/// Returns the product of the two given values.
///
/// The product of `lhs` and `rhs` must be representable in the same type. In
/// the following example, the result of `10 * 50` is greater than the
/// maximum representable `Int8` value.
///
/// let x: Int8 = 10 * 5
/// // x == 50
/// let y: Int8 = 10 * 50
/// // Overflow error
static func *(_ lhs: Self, _ rhs: Self) -> Self

/// Multiples this value by the given value in place.
///
/// For example:
///
/// var x = 15
/// y *= 7
/// // y == 105
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
static func /(_ lhs: Self, _ rhs: Self) -> Self

/// Divides this value by the given value in place.
///
/// For example:
///
/// var x = 15
/// y /= 7
/// // y == 2
static func /=(_ lhs: inout Self, rhs: Self
)
}

extension Arithmetic
{

public init() { self = 0
}

public static prefix func + (x: Self) -> Self
{

return
x
}
}

SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic
{

/// Returns the additive inverse of this value.
///
/// let x = 21
/// let y = -x
/// // y == -21
///
/// - Returns: The additive inverse of this value.
///
/// - SeeAlso: `negate()`
static prefix func - (_ operand: Self) -> Self

/// Replaces this value with its additive inverse.
///
/// The following example uses the `negate()` method to negate the value of
/// an integer `x`:
///
/// var x = 21
/// x.negate()
/// // x == -21
///
/// - SeeAlso: The unary minus operator (`-`).
mutating func negate
()
}

extension SignedArithmetic
{

public static prefix func - (_ operand: Self) -> Self
{

var result =
operand
   result.
negate
()

return
result
}

public mutating func negate
() {

self = Self() - self

}
}

BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

   • Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

   • Extend or truncate the value to fit into Self

   • Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable
{

/// 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.
static var isSigned: Bool { get
}

/// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
init?<T : FloatingPoint>(exactly source
: T)

/// Creates an integer from the given floating-point value, truncating any
/// fractional part.
///
/// Truncating the fractional part of `source` is equivalent to rounding
/// 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 truncation, a
/// runtime error may occur.
///
/// let z = UInt(-21.5)
/// // Error: ...the result would be less than UInt.min
///
/// - Parameter source: A floating-point value to convert to an integer.
/// `source` must be representable in this type after truncation.
init<T : FloatingPoint>(_ source
: T)

/// Creates an 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.
init<T : BinaryInteger>(_ source
: T)

/// Creates a new instance from the bit pattern of the given instance by
/// sign-extending 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
/// least-significant bits of `source`. For example, when converting a
/// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
/// // x == -21
/// // 'x' has a binary representation of 11111111_11101011
/// let y = UInt16(extendingOrTruncating: w)
/// // y == 65515
/// // 'y' has a binary representation of 11111111_11101011
///
/// - Parameter source: An integer to convert to this type.
init<T : BinaryInteger>(extendingOrTruncating source
: T)

/// 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.
init<T : BinaryInteger>(clamping source
: T)

/// Returns the n-th word, counting from the least significant to most
/// significant, of this value's binary representation.
///
/// The `word(at:)` method returns negative values in two's complement
/// representation, regardless of a type's underlying implementation. If `n`
/// is greater than the number of words in this value's current
/// representation, the result is `0` for positive numbers and `~0` for
/// negative numbers.
///
/// - Parameter n: The word to return, counting from the least significant to
/// most significant. `n` must be greater than or equal to zero.
/// - Returns: An word-sized, unsigned integer with the bit pattern of the
/// n-th word of this value.
func word(at n: Int) -> UInt

/// The number of bits in the current binary representation of this value.
///
/// This property is a constant for instances of fixed-width integer
/// types.
var bitWidth : Int { get
}

/// The number of trailing zeros in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number -8 has three trailing zeros.
///
/// let x = Int8(bitPattern: 0b1111_1000)
/// // x == -8
/// // x.trailingZeros == 3
var trailingZeros: Int { get
}

/// Returns the remainder of dividing the first value by the second.
///
/// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
///
/// let x = 22 % 5
/// // x == 2
/// let y = 22 % -5
/// // y == 2
/// let z = -22 % -5
/// // z == -2
///
/// - Parameters:
/// - lhs: The value to divide.
/// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
static func %(_ lhs: Self, _ rhs: Self) -> Self

/// Replaces this value with the remainder of itself divided by the given
/// value. For example:
///
/// var x = 15
/// x %= 7
/// // x == 1
///
/// - Parameter rhs: The value to divide this value by. `rhs` must not be
/// zero.
///
/// - SeeAlso: `remainder(dividingBy:)`
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).
static prefix func ~ (_ x: Self) -> Self

/// Returns the result of performing a bitwise AND operation on this value
/// and the given value.
///
/// 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
static func &(_ lhs: Self, _ rhs: Self) -> Self

static func &=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise OR operation on this value and
/// the given value.
///
/// 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
static func |(_ lhs: Self, _ rhs: Self) -> Self

static func |=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of performing a bitwise XOR operation on this value
/// and the given value.
///
/// 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
static func ^(_ lhs: Self, _ rhs: Self) -> Self

static func ^=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
/// specified number of digits to the right.
///
/// In a *masking shift*, the bit pattern of the value passed as `rhs` is
/// masked to produce a value between zero and the bit width of `lhs`. The
/// shift is performed using this masked value. Masking shifts require more
/// care to use correctly than a traditional bit shift, but are likely to be
/// more efficient when used with shift amounts that are not compile-time
/// constants. On most architectures, a masking shift compiles down to a
/// single instruction.
///
/// For example, if you shift an 8-bit, unsigned integer by 2, the shift
/// amount requires no masking.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y = x &>> 2
/// // y == 7 // 0b00000111
///
/// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
/// uses that masked value as the number of bits to shift `x`.
///
/// let z = x &>> 11
/// // z == 3 // 0b00000011
///
/// Relationship to the Right Shift Operator
/// ----------------------------------------
///
/// The masking right shift operator handles attempted overshifts and
/// undershifts differently from the right shift operator (`>>`). When the
/// value passed as `rhs` in a masking shift is within the range
/// `0...<bitWidth`, the operation is equivalent to using the right shift
/// operator.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y1 = x &>> 2
/// // y1 == 7 // 0b00000111
/// let y2 = x >> 2
/// // y2 == 7 // 0b00000111
///
/// The right shift operator does not mask its right-hand-side argument, so
/// passing `11` as `rhs` shifts all the bits of `x` to zero.
///
/// let z1 = x &>> 11
/// // z1 == 240 // 0b00000011
/// let z2 = x >> 11
/// // z2 == 0 // 0b00000000
///
/// - Parameter rhs: The number of bits to shift this value to the right. If
/// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
/// value within that range.
/// - Returns: The result of shifting this value by the masked `rhs` to the
/// right.
///
/// - SeeAlso: `&<<`, `>>`
static func &>>(_ lhs: Self, _ rhs: Self) -> Self

static func &>>=(_ lhs: inout Self, _ rhs: Self
)

/// Returns the result of shifting this value's binary representation the
/// specified number of digits to the left.
///
/// In a *masking shift*, the bit pattern of the value passed as `rhs` is
/// masked to produce a value between zero and the bit width of `lhs`. The
/// shift is performed using this masked value. Masking shifts require more
/// care to use correctly than a traditional bit shift, but are likely to be
/// more efficient when used with shift amounts that are not compile-time
/// constants. On most architectures, a masking shift compiles down to a
/// single instruction.
///
/// For example, if you shift an 8-bit, unsigned integer by 2, the shift
/// amount requires no masking.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y = x &>> 2
/// // y == 120 // 0b01111000
///
/// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
/// uses that masked value as the number of bits to shift `x`.
///
/// let z = x &<< 11
/// // z == 240 // 0b11110000
///
/// Relationship to the Left Shift Operator
/// ---------------------------------------
///
/// The masking left shift operator handles attempted overshifts and
/// undershifts differently from the left shift operator (`<<`). When the
/// value passed as `rhs` in a masking shift is within the range
/// `0...<bitWidth`, the operation is equivalent to using the left shift
/// operator.
///
/// let x: UInt8 = 30 // 0b00011110
/// let y1 = x &<< 2
/// // y1 == 120 // 0b01111000
/// let y2 = x << 2
/// // y2 == 120 // 0b01111000
///
/// The left shift operator does not mask its right-hand-side argument, so
/// passing `11` as `rhs` shifts all the bits of `x` to zero.
///
/// let z1 = x &<< 11
/// // z1 == 240 // 0b11110000
/// let z2 = x << 11
/// // z2 == 0 // 0b00000000
///
/// - Parameter rhs: The number of bits to shift this value to the left. If
/// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
/// value within that range.
/// - Returns: The result of shifting this value by the masked `rhs` to the
/// left.
///
/// - SeeAlso: `&>>`, `<<`
static func &<<(_ lhs: Self, _ rhs: Self) -> Self

static func &<<=(_ lhs: inout Self, _ rhs: Self
)

/// 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.
/// - Returns: A tuple containing the quotient and remainder of this value
/// divided by `rhs`.
func quotientAndRemainder(dividingBy rhs: Self
)

-> (quotient: Self, remainder: Self
)

/// Returns `-1` if this value is negative and `1` if it's positive;
/// otherwise, `0`.
///
/// - Returns: The sign of this number, expressed as an integer of the same
/// type.
func signum() -> Self

}

FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger
{

/// The number of bits used for the underlying binary representation of
/// values of this type.
///
/// An unsigned, fixed-width integer type can represent values from 0 through
/// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
/// fixed-width integer type can represent values from
/// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
/// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
/// the range `-128...127`.
static var bitWidth : Int { get
}

/// The maximum representable integer in this type.
///
/// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
/// `**` is exponentiation. For signed integer types, this value is
/// `(2 ** bitWidth - 1) - 1`.
static var max: Self { get
}

/// The minimum representable value.
///
/// For unsigned integer types, this value is always `0`. For signed integer
/// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
/// exponentiation.
static var min: Self { get
}

/// Returns the sum of this value and the given value along with a flag
/// indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to add to this value.
/// - Returns: A tuple containing the result of the addition along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire sum. If
/// the `overflow` component is `.overflow`, an overflow occurred and the
/// `partialValue` component contains the truncated sum of this value and
/// `other`.
///
/// - SeeAlso: `+`
func addingWithOverflow(_ other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the difference of this value and the given value along with a
/// flag indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to subtract from this value.
/// - Returns: A tuple containing the result of the subtraction along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire
/// difference. If the `overflow` component is `.overflow`, an overflow
/// occurred and the `partialValue` component contains the truncated
/// result of `other` subtracted from this value.
///
/// - SeeAlso: `-`
func subtractingWithOverflow(_ other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the product of this value and the given value along with a flag
/// indicating whether overflow occurred in the operation.
///
/// - Parameter other: The value to multiply by this value.
/// - Returns: A tuple containing the result of the multiplication along with
/// a flag indicating whether overflow occurred. If the `overflow`
/// component is `.none`, the `partialValue` component contains the entire
/// product. If the `overflow` component is `.overflow`, an overflow
/// occurred and the `partialValue` component contains the truncated
/// product of this value and `other`.
///
/// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
func multipliedWithOverflow(by other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns the quotient of dividing this value by the given value along with
/// a flag indicating whether overflow occurred in the operation.
///
/// For a value `x`, if zero is passed as `other`, the result is
/// `(x, .overflow)`.
///
/// - Parameter other: The value to divide this value by.
/// - Returns: A tuple containing the result of the division along with a
/// flag indicating whether overflow occurred. If the `overflow` component
/// is `.none`, the `partialValue` component contains the entire quotient.
/// If the `overflow` component is `.overflow`, an overflow occurred and
/// the `partialValue` component contains the truncated quotient.
///
/// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
func dividedWithOverflow(by other: Self
)

-> (partialValue: Self, overflow
: ArithmeticOverflow)

/// Returns a tuple containing the high and low parts of the result of
/// multiplying its arguments.
///
/// Use this method to calculate the full result of a product that would
/// otherwise overflow. Unlike traditional truncating multiplication, the
/// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
/// parts of the product of `lhs` and `rhs`. The following example uses this
/// method to multiply two `UInt8` values that normally overflow when
/// multiplied:
///
/// let x: UInt8 = 100
/// let y: UInt8 = 20
/// let result = UInt8.doubleWidthMultiply(100, 20)
/// // result.high == 0b00000111
/// // result.low == 0b11010000
///
/// The product of `x` and `y` is 2000, which is too large to represent in a
/// `UInt8` instance. The `high` and `low` components of the `result` tuple
/// represent 2000 when concatenated to form a double-width integer; that
/// is, using `result.high` as the high byte and `result.low` as the low byte
/// of a `UInt16` instance.
///
/// let z = UInt16(result.high) << 8 | UInt16(result.low)
/// // z == 2000
///
/// - Parameters:
/// - lhs: A value to multiply.
/// - rhs: Another value to multiply.
/// - Returns: A tuple containing the high and low parts of the result of
/// multiplying `lhs` and `rhs`.
///
/// - SeeAlso: `multipliedWithOverflow(by:)`
static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self
)

-> (high: Self, low
: Magnitude)

/// Returns a tuple containing the quotient and remainder of dividing the
/// first argument by the second.
///
/// The resulting quotient must be representable within the bounds of the
/// type. If the quotient of dividing `lhs` by `rhs` is too large to
/// represent in the type, a runtime error may occur.
///
/// - Parameters:
/// - lhs: A tuple containing the high and low parts of a double-width
/// integer. The `high` component of the tuple carries the sign, if the
/// type is signed.
/// - rhs: The integer to divide into `lhs`.
/// - Returns: A tuple containing the quotient and remainder of `lhs` divided
/// by `rhs`.
static func doubleWidthDivide
(

_ lhs: (high: Self, low: Magnitude), _ rhs: Self
)

-> (quotient: Self, remainder: Self
)

/// The number of bits equal to 1 in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number 31 has five bits equal to 1.
///
/// let x: Int8 = 0b0001_1111
/// // x == 31
/// // x.popcount == 5
var popcount: Int { get
}

/// The number of leading zeros in this value's binary representation.
///
/// For example, in a fixed-width integer type with a `bitWidth` value of 8,
/// the number 31 has three leading zeros.
///
/// let x: Int8 = 0b0001_1111
/// // x == 31
/// // x.leadingZeros == 3
/// - SeeAlso: `BinaryInteger.trailingZeros`
var leadingZeros: Int { get
}

/// Creates an integer from its big-endian representation, changing the
/// byte order if necessary.
init(bigEndian value: Self
)

/// Creates an integer from its little-endian representation, changing the
/// byte order if necessary.
init(littleEndian value: Self
)

/// The big-endian representation of this integer.
///
/// If necessary, the byte order of this value is reversed from the typical
/// byte order of this integer type. On a big-endian platform, for any
/// integer `x`, `x == x.bigEndian`.
///
/// - SeeAlso: `littleEndian`
var bigEndian: Self { get
}

/// The little-endian representation of this integer.
///
/// If necessary, the byte order of this value is reversed from the typical
/// byte order of this integer type. On a little-endian platform, for any
/// integer `x`, `x == x.littleEndian`.
///
/// - SeeAlso: `bigEndian`
var littleEndian: Self { get
}

/// A representation of this integer with the byte order swapped.
var byteSwapped: Self { get
}
}

Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger
{

associatedtype Magnitude : BinaryInteger

}

public protocol SignedInteger : BinaryInteger, SignedArithmetic
{

associatedtype Magnitude : BinaryInteger

}

DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

Extra operators

In addition to the operators described in the protocols section, we also provide a few extensions that are not protocol requirements:

Heterogeneous shifts

extension BinaryInteger
{

// Masking shifts
static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

// 'Smart' shifts
static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)

static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self

static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs
: Other)
}

Heterogeneous equality and comparison

extension BinaryInteger
{

// Equality
static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

// Comparison
static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

}

Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) ->
T

public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
Non-goals

This proposal:

   • DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

   • DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

   • Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

   • Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

   • Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave


(Dave Abrahams) #17

Really glad to see this coming back :slight_smile:

I have a couple of questions:

1) How does Strideable relate to Arithmetic?

My understanding is that Strideable allows non-numeric types to express
different-type addition and subtraction, and that Arithmetic is for numeric
types only (derives from ExpressibleByIntegerLiteral) and allows then to
express same-type operations. Is that correct?

My understanding was that heterogeneous addition and subtraction using
operators are not supported not merely due to compiler limitations but as a
fundamental philosophy, because the type of the intended result can be
unclear to human readers and unintentional promotion is to be avoided?

No, not really. We'd like to introduce a promotion model.

In that vein, my understanding was that having those operators
available for Strideable was inconsistent and overdue for removal, and
`advanced(by:)` is the intended spelling for advancing a value by a
distance of a different type.

The real reason to remove them from Strideable is that unsigned numbers
are strideable with a signed stride, which made preventing people from
adding signed and unsigned numbers unintentionally messy and unreliable.

If so, it would be nice to add it to the proposal so people know when they
should conform (or set their generic constraints) to one or the other.

2) Can SignedNumber get some operators now?

Strideable.Stride is bound to this weird protocol ‘SignedNumber’. You can
create instances of it out of thin air via an integer literal, but you
can’t accumulate Strides to find the overall distance between some adjacent
Strideables.

I understood these new protocols to mean that SignedNumber is headed for
deprecation?

That's the plan.

Also, #1 is why I don’t like the Strideable operator deprecation being
part of the proposal (and therefore part of the language specification). It
doesn’t solve the underlying issue, which is that our integer literal
protocols aren’t really good enough - they’re not useful enough outside the
standard library (see: https://bugs.swift.org/browse/SR-920), and
evidently the compiler isn’t able to use them to infer types correctly.
Perhaps fixing it is a low priority, and that’s fine, but what about if
somebody else defines this operator in their library? They start of break
lots of valid code because the compiler can’t do the right thing. Improved
literal protocols may be the better way to resolve that problem.

I agree totally that literals are aching for improvements as outlined in
SR-920.

Indeedy.

···

on Mon Jan 16 2017, Xiaodi Wu <swift-evolution@swift.org> wrote:

On Mon, Jan 16, 2017 at 11:57 AM, Karl Wagner via swift-evolution < > swift-evolution@swift.org> wrote:

Not sure how it relates to integer protocols though. What are some
examples of valid code that get broken today because of compiler
limitations?

- Karl
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave


(Xiaodi Wu) #18

Really glad to see this coming back :slight_smile:

I have a couple of questions:

1) How does Strideable relate to Arithmetic?

My understanding is that Strideable allows non-numeric types to express
different-type addition and subtraction, and that Arithmetic is for numeric
types only (derives from ExpressibleByIntegerLiteral) and allows then to
express same-type operations. Is that correct?

My understanding was that heterogeneous addition and subtraction using
operators are not supported not merely due to compiler limitations but as a
fundamental philosophy, because the type of the intended result can be
unclear to human readers and unintentional promotion is to be avoided? In
that vein, my understanding was that having those operators available for
Strideable was inconsistent and overdue for removal, and `advanced(by:)` is
the intended spelling for advancing a value by a distance of a different
type.

If so, it would be nice to add it to the proposal so people know when they
should conform (or set their generic constraints) to one or the other.

2) Can SignedNumber get some operators now?

Strideable.Stride is bound to this weird protocol ‘SignedNumber’. You can
create instances of it out of thin air via an integer literal, but you
can’t accumulate Strides to find the overall distance between some adjacent
Strideables.

I understood these new protocols to mean that SignedNumber is headed for
deprecation?

Also, #1 is why I don’t like the Strideable operator deprecation being
part of the proposal (and therefore part of the language specification). It
doesn’t solve the underlying issue, which is that our integer literal
protocols aren’t really good enough - they’re not useful enough outside the
standard library (see: https://bugs.swift.org/browse/SR-920), and
evidently the compiler isn’t able to use them to infer types correctly.
Perhaps fixing it is a low priority, and that’s fine, but what about if
somebody else defines this operator in their library? They start of break
lots of valid code because the compiler can’t do the right thing. Improved
literal protocols may be the better way to resolve that problem.

I agree totally that literals are aching for improvements as outlined in
SR-920. Not sure how it relates to integer protocols though. What are some
examples of valid code that get broken today because of compiler
limitations?

···

On Mon, Jan 16, 2017 at 11:57 AM, Karl Wagner via swift-evolution < swift-evolution@swift.org> wrote:

- Karl
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Karl) #19

Really glad to see this coming back :slight_smile:

I have a couple of questions:

1) How does Strideable relate to Arithmetic?

My understanding is that Strideable allows non-numeric types to express different-type addition and subtraction, and that Arithmetic is for numeric types only (derives from ExpressibleByIntegerLiteral) and allows then to express same-type operations. Is that correct?

My understanding was that heterogeneous addition and subtraction using operators are not supported not merely due to compiler limitations but as a fundamental philosophy, because the type of the intended result can be unclear to human readers and unintentional promotion is to be avoided? In that vein, my understanding was that having those operators available for Strideable was inconsistent and overdue for removal, and `advanced(by:)` is the intended spelling for advancing a value by a distance of a different type.

If so, it would be nice to add it to the proposal so people know when they should conform (or set their generic constraints) to one or the other.

2) Can SignedNumber get some operators now?

Strideable.Stride is bound to this weird protocol ‘SignedNumber’. You can create instances of it out of thin air via an integer literal, but you can’t accumulate Strides to find the overall distance between some adjacent Strideables.

I understood these new protocols to mean that SignedNumber is headed for deprecation?

It would be nice if the proposal said that, then (and mentioned the corresponding change to Strideable.Stride). I assume it will be replaced with SignedArithmetic, then.

Also, #1 is why I don’t like the Strideable operator deprecation being part of the proposal (and therefore part of the language specification). It doesn’t solve the underlying issue, which is that our integer literal protocols aren’t really good enough - they’re not useful enough outside the standard library (see: https://bugs.swift.org/browse/SR-920), and evidently the compiler isn’t able to use them to infer types correctly. Perhaps fixing it is a low priority, and that’s fine, but what about if somebody else defines this operator in their library? They start of break lots of valid code because the compiler can’t do the right thing. Improved literal protocols may be the better way to resolve that problem.

I agree totally that literals are aching for improvements as outlined in SR-920. Not sure how it relates to integer protocols though. What are some examples of valid code that get broken today because of compiler limitations?

The PR that implemented this fixed a bug with integer literals - basically, the thrust of it (as I understand) is that the compiler can’t figure out which is the preferred overload. It doesn’t know to prefer same-type arithmetic when resolving literals involved in operators.

My problem with just fixing the problem by removing that operator is that anybody could add it back in their own code, and that should be perfectly allowable, but if they did so basic expressions would fail to compile. To me it sounds preferable to leave this as a implementation artefact until we get a chance to make the literal protocols better.

Strideable isn’t some esoteric protocol just for collection indexes, you know. It’s very useful for any quasi-numeric type whose absolute value is semantically different from a difference. For example, I have strongly-typed wrappers for a ByteOffset within a binary file and a LineNumber inside a text file. These wrappers allow me to write extensions (for example to clamp to the bounds of a particular file), and ensure that I don’t accidentally mix semantically different values. They are both Strideable by Int, which is a better semantic fit than Arithmetic (LineNumbers are absolute, should you be able to add them? What does LineNumber * LineNumber mean?).

So my point is basically that it’s an important protocol (maybe not so much in the standard library, but certainly beyond).

- Karl

···

On 16 Jan 2017, at 20:53, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:
On Mon, Jan 16, 2017 at 11:57 AM, Karl Wagner via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:


(Max Moiseev) #20

Hi Anton,

Arithmetic refines RepresentableByIntegerLiteral, so it is quite possible to use `0` and `1` when you need them.

Max

···

On Jan 25, 2017, at 7:59 AM, Anton Mironov <antonvmironov@gmail.com> wrote:

Hi everyone,

I want to suggest a tiny extension to an Arithmetic protocol. It would be nice to have an additive identity and a multiplicative identity constants. Basically zero and one.

protocol Arithmetic {
  /* ... */
  static var zero: Self { get }  // additive identity: (value + .zero) == value
  static var one: Self { get }   // multiplicative identity: (value * .one) == value
}

These constants will ease implementation of math structures: vectors, matrices and etc.
I’m sorry if I’m duplicating someone’s suggestion. It is really hard to search for something in a long thread.

Thanks,
Anton Mironov

On Jan 13, 2017, at 10:47 PM, Max Moiseev via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Hi everyone,

Back in June 2016 we discussed the new design of the integer types for the standard library. It even resulted in acceptance of SE-0104 <https://github.com/apple/swift-evolution/blob/master/proposals/0104-improved-integers.md> for Swift 3. Unfortunately we were not able to implement it in time for the release.

But it was not forgotten, although, as time went by, a few changes needed to be made in order to reflect the current state of the language.
Without further introduction, please welcome the refined proposal to make integers in Swift more suitable for generic programming.

Available in this gist https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c and also inlined below.

Max

Protocol-oriented integers (take 2)

Proposal: SE-NNNN <https://gist.github.com/moiseev/0000-even-more-improved-integers.md>
Authors: Dave Abrahams <https://github.com/dabrahams>, Maxim Moiseev <https://github.com/moiseev>
Review Manager: TBD
Status: Awaiting review
Bug: SR-3196 <https://bugs.swift.org/browse/SR-3196>
Previous Proposal: SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#introduction>Introduction

This proposal is an evolution of SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>. The goal is still to clean up Swifts integer APIs and make them more useful for generic programming.

The language has evolved in ways that affect integers APIs since the time the original proposal was approved for Swift 3. We also attempted to implement the proposed model in the standard library and found that some essential APIs were missing, whereas others could be safely removed.

Major changes to the APIs introduced by this proposal (as compared to SE-0104 <https://gist.github.com/moiseev/0104-improved-integers.md>) are listed in a dedicated section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#motivation>Motivation

Swift's integer protocols don't currently provide a suitable basis for generic programming. See this blog post <http://blog.krzyzanowskim.com/2015/03/01/swift_madness_of_generic_integer/> for an example of an attempt to implement a generic algorithm over integers.

The way the Arithmetic protocol is defined, it does not generalize to floating point numbers and also slows down compilation by requiring every concrete type to provide an implementation of arithmetic operators, thus polluting the overload set.

Converting from one integer type to another is performed using the concept of the 'maximum width integer' (see MaxInt), which is an artificial limitation. The very existence of MaxInt makes it unclear what to do should someone implement Int256, for example.

Another annoying problem is the inability to use integers of different types in comparison and bit-shift operations. For example, the following snippets won't compile:

var x: Int8 = 42
let y = 1
let z = 0

x <<= y // error: binary operator '<<=' cannot be applied to operands of type 'Int8' and 'Int'
if x > z { ... } // error: binary operator '>' cannot be applied to operands of type 'Int8' and 'Int'
Currently, bit-shifting a negative number of (or too many) bits causes a trap on some platforms, which makes low-level bit manipulations needlessly dangerous and unpredictable.

Finally, the current design predates many of the improvements that came since Swift 1, and hasn't been revised since then.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#proposed-solution>Proposed solution

We propose a new model that does not have above mentioned problems and is more easily extensible.

                +--------------+ +-------------+
        +------>+ Arithmetic | | Comparable |
        > > (+,-,*,/) | | (==,<,>,...)|
        > +-------------++ +---+---------+
        > ^ ^
+-------+------------+ | |
> SignedArithmetic | +-+-------+-----------+
> (unary -) | | BinaryInteger |
+------+-------------+ |(words,%,bitwise,...)|
       ^ ++---+-----+----------+
       > +-----------^ ^ ^---------------+
       > > > >
+------+---------++ +---------+---------------+ +--+----------------+
> SignedInteger | | FixedWidthInteger | | UnsignedInteger |
> > >(endianness,overflow,...)| | |
+---------------+-+ +-+--------------------+--+ +-+-----------------+
                ^ ^ ^ ^
                > > > >
                > > > >
               ++--------+-+ +-+-------+-+
               >Int family |-+ |UInt family|-+
               +-----------+ | +-----------+ |
                 +-----------+ +-----------+
There are several benefits provided by this model over the old one:

It allows mixing integer types in generic functions.

The possibility to initialize instances of any concrete integer type with values of any other concrete integer type enables writing functions that operate on more than one type conforming to BinaryInteger, such as heterogeneous comparisons or bit shifts, described later.

It removes the overload resolution overhead.

Arithmetic and bitwise operations can now be defined as generic operators on protocols. This approach significantly reduces the number of overloads for those operations, which used to be defined for every single concrete integer type.

It enables protocol sharing between integer and floating point types.

Note the exclusion of the % operation from Arithmetic. Its behavior for floating point numbers is sufficiently different from the one for integers that using it in generic context would lead to confusion. The FloatingPoint protocol introduced by SE-0067 <https://gist.github.com/moiseev/0067-floating-point-protocols.md> should now refine SignedArithmetic.

It makes future extensions possible.

The proposed model eliminates the 'largest integer type' concept previously used to interoperate between integer types (see toIntMax in the current model) and instead provides access to machine words. It also introduces thedoubleWidthMultiply, doubleWidthDivide, and quotientAndRemainder methods. Together these changes can be used to provide an efficient implementation of bignums that would be hard to achieve otherwise.

The implementation of proposed model in the standard library is available in the new-integer-protocols branch <https://github.com/apple/swift/tree/new-integer-protocols>.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#a-note-on-bit-shifts>A note on bit shifts

This proposal introduces the concepts of smart shifts and masking shifts.

The semantics of shift operations are often undefined <http://llvm.org/docs/LangRef.html#bitwise-binary-operations> in under- or over-shift cases. Smart shifts, implemented by >> and <<, are designed to address this problem and always behave in a well defined way, as shown in the examples below:

x << -2 is equivalent to x >> 2

(1 as UInt8) >> 42) will evaluate to 0

(-128 as Int8) >> 42) will evaluate to 0xff or -1

In most scenarios, the right hand operand is a literal constant, and branches for handling under- and over-shift cases can be optimized away. For other cases, this proposal provides masking shifts, implemented by &>> and &<<. A masking shift logically preprocesses the right hand operand by masking its bits to produce a value in the range 0...(x-1) where x is the number of bits in the left hand operand. On most architectures this masking is already performed by the CPU's shift instructions and has no cost. Both kinds of shift avoid undefined behavior and produce uniform semantics across architectures.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#detailed-design>Detailed design

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#whats-new-since-se-0104>What's new since SE-0104

SE-0091 <https://gist.github.com/moiseev/0091-improving-operators-in-protocols.md> removed the necessity to dispatch generic operators through special methods.

All operators are now declared by protocols as static funcs.

Standard Library no longer provides + and - operators for Strideable types.

They were problematic, as one could have written mixed-type code like let x: Int64 = 42; x += (1 as Int), which would compile, but shouldn't. Besides, since the Stride of an unsigned type is signed, Standard Library had to implement a hack to make code like let x: UInt = 42; x += (1 as Int) ambiguous. These operators were only necessary because they made advancing collection indices convenient, which is no longer the case since the introduction of the new indexing model <https://gist.github.com/moiseev/0065-collections-move-indices.md> in Swift 3.

Shifts and other bitwise operations were moved from FixedWidthInteger to BinaryInteger.

Left shift operation on an unbounded integer should infinitely extend the number, and never drop set bits when they reach the most significant position in the underlying representation.

BitwiseOperations protocol was deprecated.

We believe there are no useful entities that support bitwise operations, but at the same time are not binary integers.

minimumSignedRepresentationBitWidth property was removed.

trailingZeros property was added to the BinaryInteger protocol.

leadingZeros and popcount properties are still defined by the FixedWidthInteger protocol.

Endian-converting initializers and properties were added to the FixedWidthInteger protocol.

Standard library introduces the new type DoubleWidth<T>.

See this section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth> for more details.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>Protocols

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#arithmetic>Arithmetic

The Arithmetic protocol declares binary arithmetic operators – such as +, -, and * — and their mutating counterparts.

It provides a suitable basis for arithmetic on scalars such as integers and floating point numbers.

Both mutating and non-mutating operations are declared in the protocol, however only the mutating ones are required, as default implementations of the non-mutating ones are provided by a protocol extension.

The Magnitude associated type is able to hold the absolute value of any possible value of Self. Concrete types do not have to provide a type alias for it, as it can be inferred from the magnitude property. This property can be useful in operations that are simpler to implement in terms of unsigned values, for example, printing a value of an integer, which is just printing a '-' character in front of an absolute value.

Please note that for ordinary work, the magnitude property should not be preferred to the abs(_) function, whose return value is of the same type as its argument.

public protocol Arithmetic : Equatable, ExpressibleByIntegerLiteral {
  /// Creates a new instance from the given integer, 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 `100`, while the attempt to initialize the
  /// constant `y` from `1_000` fails because the `Int8` type can represent
  /// `127` at maximum:
  ///
  /// let x = Int8(exactly: 100)
  /// // x == Optional(100)
  /// let y = Int8(exactly: 1_000)
  /// // y == nil
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  init?<T : BinaryInteger>(exactly source: T)

  /// A type that can represent the absolute value of any possible value of the
  /// conforming type.
  associatedtype Magnitude : Equatable, ExpressibleByIntegerLiteral

  /// The magnitude of this value.
  ///
  /// For any numeric value `x`, `x.magnitude` is the absolute value of `x`.
  /// You can use the `magnitude` property in operations that are simpler to
  /// implement in terms of unsigned values, such as printing the value of an
  /// integer, which is just printing a '-' character in front of an absolute
  /// value.
  ///
  /// let x = -200
  /// // x.magnitude == 200
  ///
  /// The global `abs(_:)` function provides more familiar syntax when you need
  /// to find an absolute value. In addition, because `abs(_:)` always returns
  /// a value of the same type, even in a generic context, using the function
  /// instead of the `magnitude` property is encouraged.
  ///
  /// - SeeAlso: `abs(_:)`
  var magnitude: Magnitude { get }

  /// Returns the sum of the two given values.
  ///
  /// The sum of `lhs` and `rhs` must be representable in the same type. In the
  /// following example, the result of `100 + 200` is greater than the maximum
  /// representable `Int8` value:
  ///
  /// let x: Int8 = 10 + 21
  /// // x == 31
  /// let y: Int8 = 100 + 121
  /// // Overflow error
  static func +(_ lhs: Self, _ rhs: Self) -> Self

  /// Adds the given value to this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y += 7
  /// // y == 22
  static func +=(_ lhs: inout Self, rhs: Self)

  /// Returns the difference of the two given values.
  ///
  /// The difference of `lhs` and `rhs` must be representable in the same type.
  /// In the following example, the result of `10 - 21` is less than zero, the
  /// minimum representable `UInt` value:
  ///
  /// let x: UInt = 21 - 10
  /// // x == 11
  /// let y: UInt = 10 - 21
  /// // Overflow error
  static func -(_ lhs: Self, _ rhs: Self) -> Self

  /// Subtracts the given value from this value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y -= 7
  /// // y == 8
  static func -=(_ lhs: inout Self, rhs: Self)

  /// Returns the product of the two given values.
  ///
  /// The product of `lhs` and `rhs` must be representable in the same type. In
  /// the following example, the result of `10 * 50` is greater than the
  /// maximum representable `Int8` value.
  ///
  /// let x: Int8 = 10 * 5
  /// // x == 50
  /// let y: Int8 = 10 * 50
  /// // Overflow error
  static func *(_ lhs: Self, _ rhs: Self) -> Self

  /// Multiples this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y *= 7
  /// // y == 105
  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
  static func /(_ lhs: Self, _ rhs: Self) -> Self

  /// Divides this value by the given value in place.
  ///
  /// For example:
  ///
  /// var x = 15
  /// y /= 7
  /// // y == 2
  static func /=(_ lhs: inout Self, rhs: Self)
}

extension Arithmetic {
  public init() { self = 0 }

  public static prefix func + (x: Self) -> Self {
    return x
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#signedarithmetic>SignedArithmetic

The SignedArithmetic protocol is for numbers that can be negated.

public protocol SignedArithmetic : Arithmetic {
  /// Returns the additive inverse of this value.
  ///
  /// let x = 21
  /// let y = -x
  /// // y == -21
  ///
  /// - Returns: The additive inverse of this value.
  ///
  /// - SeeAlso: `negate()`
  static prefix func - (_ operand: Self) -> Self

  /// Replaces this value with its additive inverse.
  ///
  /// The following example uses the `negate()` method to negate the value of
  /// an integer `x`:
  ///
  /// var x = 21
  /// x.negate()
  /// // x == -21
  ///
  /// - SeeAlso: The unary minus operator (`-`).
  mutating func negate()
}

extension SignedArithmetic {
  public static prefix func - (_ operand: Self) -> Self {
    var result = operand
    result.negate()
    return result
  }

  public mutating func negate() {
    self = Self() - self
  }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#binaryinteger>BinaryInteger

The BinaryInteger protocol is the basis for all the integer types provided by the standard library.

This protocol adds a few new initializers. Two of them allow to create integers from floating point numbers, others support construction from instances of any type conforming to BinaryInteger, using different strategies:

Initialize Self with the value, provided that the value is representable. The precondition should be satisfied by the caller.

Extend or truncate the value to fit into Self

Clamp the value to the representable range of Self

BinaryInteger also declares bitwise and shift operators.

public protocol BinaryInteger :
  Comparable, Hashable, Arithmetic, CustomStringConvertible, Strideable {

  /// 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.
  static var isSigned: Bool { get }

  /// Creates an integer from the given floating-point 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 floating-point value to convert to an integer.
  init?<T : FloatingPoint>(exactly source: T)

  /// Creates an integer from the given floating-point value, truncating any
  /// fractional part.
  ///
  /// Truncating the fractional part of `source` is equivalent to rounding
  /// 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 truncation, a
  /// runtime error may occur.
  ///
  /// let z = UInt(-21.5)
  /// // Error: ...the result would be less than UInt.min
  ///
  /// - Parameter source: A floating-point value to convert to an integer.
  /// `source` must be representable in this type after truncation.
  init<T : FloatingPoint>(_ source: T)

  /// Creates an 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.
  init<T : BinaryInteger>(_ source: T)

  /// Creates a new instance from the bit pattern of the given instance by
  /// sign-extending 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
  /// least-significant bits of `source`. For example, when converting a
  /// 16-bit value to an 8-bit 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(extendingOrTruncating: 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 *sign-extended* 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(extendingOrTruncating: 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(extendingOrTruncating: w)
  /// // x == -21
  /// // 'x' has a binary representation of 11111111_11101011
  /// let y = UInt16(extendingOrTruncating: w)
  /// // y == 65515
  /// // 'y' has a binary representation of 11111111_11101011
  ///
  /// - Parameter source: An integer to convert to this type.
  init<T : BinaryInteger>(extendingOrTruncating source: T)

  /// 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.
  init<T : BinaryInteger>(clamping source: T)

  /// Returns the n-th word, counting from the least significant to most
  /// significant, of this value's binary representation.
  ///
  /// The `word(at:)` method returns negative values in two's complement
  /// representation, regardless of a type's underlying implementation. If `n`
  /// is greater than the number of words in this value's current
  /// representation, the result is `0` for positive numbers and `~0` for
  /// negative numbers.
  ///
  /// - Parameter n: The word to return, counting from the least significant to
  /// most significant. `n` must be greater than or equal to zero.
  /// - Returns: An word-sized, unsigned integer with the bit pattern of the
  /// n-th word of this value.
  func word(at n: Int) -> UInt

  /// The number of bits in the current binary representation of this value.
  ///
  /// This property is a constant for instances of fixed-width integer
  /// types.
  var bitWidth : Int { get }

  /// The number of trailing zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number -8 has three trailing zeros.
  ///
  /// let x = Int8(bitPattern: 0b1111_1000)
  /// // x == -8
  /// // x.trailingZeros == 3
  var trailingZeros: Int { get }

  /// Returns the remainder of dividing the first value by the second.
  ///
  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
  ///
  /// let x = 22 % 5
  /// // x == 2
  /// let y = 22 % -5
  /// // y == 2
  /// let z = -22 % -5
  /// // z == -2
  ///
  /// - Parameters:
  /// - lhs: The value to divide.
  /// - rhs: The value to divide `lhs` by. `rhs` must not be zero.
  static func %(_ lhs: Self, _ rhs: Self) -> Self

  /// Replaces this value with the remainder of itself divided by the given
  /// value. For example:
  ///
  /// var x = 15
  /// x %= 7
  /// // x == 1
  ///
  /// - Parameter rhs: The value to divide this value by. `rhs` must not be
  /// zero.
  ///
  /// - SeeAlso: `remainder(dividingBy:)`
  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).
  static prefix func ~ (_ x: Self) -> Self

  /// Returns the result of performing a bitwise AND operation on this value
  /// and the given value.
  ///
  /// 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
  static func &(_ lhs: Self, _ rhs: Self) -> Self
  static func &=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise OR operation on this value and
  /// the given value.
  ///
  /// 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
  static func |(_ lhs: Self, _ rhs: Self) -> Self
  static func |=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of performing a bitwise XOR operation on this value
  /// and the given value.
  ///
  /// 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
  static func ^(_ lhs: Self, _ rhs: Self) -> Self
  static func ^=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the right.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 7 // 0b00000111
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &>> 11
  /// // z == 3 // 0b00000011
  ///
  /// Relationship to the Right Shift Operator
  /// ----------------------------------------
  ///
  /// The masking right shift operator handles attempted overshifts and
  /// undershifts differently from the right shift operator (`>>`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the right shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &>> 2
  /// // y1 == 7 // 0b00000111
  /// let y2 = x >> 2
  /// // y2 == 7 // 0b00000111
  ///
  /// The right shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &>> 11
  /// // z1 == 240 // 0b00000011
  /// let z2 = x >> 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the right. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// right.
  ///
  /// - SeeAlso: `&<<`, `>>`
  static func &>>(_ lhs: Self, _ rhs: Self) -> Self
  static func &>>=(_ lhs: inout Self, _ rhs: Self)

  /// Returns the result of shifting this value's binary representation the
  /// specified number of digits to the left.
  ///
  /// In a *masking shift*, the bit pattern of the value passed as `rhs` is
  /// masked to produce a value between zero and the bit width of `lhs`. The
  /// shift is performed using this masked value. Masking shifts require more
  /// care to use correctly than a traditional bit shift, but are likely to be
  /// more efficient when used with shift amounts that are not compile-time
  /// constants. On most architectures, a masking shift compiles down to a
  /// single instruction.
  ///
  /// For example, if you shift an 8-bit, unsigned integer by 2, the shift
  /// amount requires no masking.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y = x &>> 2
  /// // y == 120 // 0b01111000
  ///
  /// However, if you shift it by 11, it first bitmasks `rhs` to `3`, and then
  /// uses that masked value as the number of bits to shift `x`.
  ///
  /// let z = x &<< 11
  /// // z == 240 // 0b11110000
  ///
  /// Relationship to the Left Shift Operator
  /// ---------------------------------------
  ///
  /// The masking left shift operator handles attempted overshifts and
  /// undershifts differently from the left shift operator (`<<`). When the
  /// value passed as `rhs` in a masking shift is within the range
  /// `0...<bitWidth`, the operation is equivalent to using the left shift
  /// operator.
  ///
  /// let x: UInt8 = 30 // 0b00011110
  /// let y1 = x &<< 2
  /// // y1 == 120 // 0b01111000
  /// let y2 = x << 2
  /// // y2 == 120 // 0b01111000
  ///
  /// The left shift operator does not mask its right-hand-side argument, so
  /// passing `11` as `rhs` shifts all the bits of `x` to zero.
  ///
  /// let z1 = x &<< 11
  /// // z1 == 240 // 0b11110000
  /// let z2 = x << 11
  /// // z2 == 0 // 0b00000000
  ///
  /// - Parameter rhs: The number of bits to shift this value to the left. If
  /// `rhs` is outside the range `0..<bitWidth`, it is masked to produce a
  /// value within that range.
  /// - Returns: The result of shifting this value by the masked `rhs` to the
  /// left.
  ///
  /// - SeeAlso: `&>>`, `<<`
  static func &<<(_ lhs: Self, _ rhs: Self) -> Self
  static func &<<=(_ lhs: inout Self, _ rhs: Self)

  /// 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.
  /// - Returns: A tuple containing the quotient and remainder of this value
  /// divided by `rhs`.
  func quotientAndRemainder(dividingBy rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// Returns `-1` if this value is negative and `1` if it's positive;
  /// otherwise, `0`.
  ///
  /// - Returns: The sign of this number, expressed as an integer of the same
  /// type.
  func signum() -> Self
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#fixedwidthinteger>FixedWidthInteger

The FixedWidthInteger protocol adds the notion of endianness as well as static properties for type bounds and bit width.

The WithOverflow family of methods is used in default implementations of mutating arithmetic methods (see the Arithmetic protocol). Having these methods allows the library to provide both bounds-checked and masking implementations of arithmetic operations, without duplicating code.

The doubleWidthMultiply and doubleWidthDivide methods are necessary building blocks to implement support for integer types of a greater width such as arbitrary-precision integers.

public protocol FixedWidthInteger : BinaryInteger {
  /// The number of bits used for the underlying binary representation of
  /// values of this type.
  ///
  /// An unsigned, fixed-width integer type can represent values from 0 through
  /// `(2 ** bitWidth) - 1`, where `**` is exponentiation. A signed,
  /// fixed-width integer type can represent values from
  /// `-(2 ** bitWidth - 1)` through `(2 ** bitWidth - 1) - 1`. For example,
  /// the `Int8` type has a `bitWidth` value of 8 and can store any integer in
  /// the range `-128...127`.
  static var bitWidth : Int { get }

  /// The maximum representable integer in this type.
  ///
  /// For unsigned integer types, this value is `(2 ** bitWidth) - 1`, where
  /// `**` is exponentiation. For signed integer types, this value is
  /// `(2 ** bitWidth - 1) - 1`.
  static var max: Self { get }

  /// The minimum representable value.
  ///
  /// For unsigned integer types, this value is always `0`. For signed integer
  /// types, this value is `-(2 ** bitWidth - 1)`, where `**` is
  /// exponentiation.
  static var min: Self { get }

  /// Returns the sum of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to add to this value.
  /// - Returns: A tuple containing the result of the addition along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire sum. If
  /// the `overflow` component is `.overflow`, an overflow occurred and the
  /// `partialValue` component contains the truncated sum of this value and
  /// `other`.
  ///
  /// - SeeAlso: `+`
  func addingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the difference of this value and the given value along with a
  /// flag indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to subtract from this value.
  /// - Returns: A tuple containing the result of the subtraction along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire
  /// difference. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// result of `other` subtracted from this value.
  ///
  /// - SeeAlso: `-`
  func subtractingWithOverflow(_ other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the product of this value and the given value along with a flag
  /// indicating whether overflow occurred in the operation.
  ///
  /// - Parameter other: The value to multiply by this value.
  /// - Returns: A tuple containing the result of the multiplication along with
  /// a flag indicating whether overflow occurred. If the `overflow`
  /// component is `.none`, the `partialValue` component contains the entire
  /// product. If the `overflow` component is `.overflow`, an overflow
  /// occurred and the `partialValue` component contains the truncated
  /// product of this value and `other`.
  ///
  /// - SeeAlso: `*`, `doubleWidthMultiply(_:_:)`
  func multipliedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns the quotient of dividing this value by the given value along with
  /// a flag indicating whether overflow occurred in the operation.
  ///
  /// For a value `x`, if zero is passed as `other`, the result is
  /// `(x, .overflow)`.
  ///
  /// - Parameter other: The value to divide this value by.
  /// - Returns: A tuple containing the result of the division along with a
  /// flag indicating whether overflow occurred. If the `overflow` component
  /// is `.none`, the `partialValue` component contains the entire quotient.
  /// If the `overflow` component is `.overflow`, an overflow occurred and
  /// the `partialValue` component contains the truncated quotient.
  ///
  /// - SeeAlso: `/`, `doubleWidthDivide(_:_:)`
  func dividedWithOverflow(by other: Self)
    -> (partialValue: Self, overflow: ArithmeticOverflow)

  /// Returns a tuple containing the high and low parts of the result of
  /// multiplying its arguments.
  ///
  /// Use this method to calculate the full result of a product that would
  /// otherwise overflow. Unlike traditional truncating multiplication, the
  /// `doubleWidthMultiply(_:_:)` method returns both the `high` and `low`
  /// parts of the product of `lhs` and `rhs`. The following example uses this
  /// method to multiply two `UInt8` values that normally overflow when
  /// multiplied:
  ///
  /// let x: UInt8 = 100
  /// let y: UInt8 = 20
  /// let result = UInt8.doubleWidthMultiply(100, 20)
  /// // result.high == 0b00000111
  /// // result.low == 0b11010000
  ///
  /// The product of `x` and `y` is 2000, which is too large to represent in a
  /// `UInt8` instance. The `high` and `low` components of the `result` tuple
  /// represent 2000 when concatenated to form a double-width integer; that
  /// is, using `result.high` as the high byte and `result.low` as the low byte
  /// of a `UInt16` instance.
  ///
  /// let z = UInt16(result.high) << 8 | UInt16(result.low)
  /// // z == 2000
  ///
  /// - Parameters:
  /// - lhs: A value to multiply.
  /// - rhs: Another value to multiply.
  /// - Returns: A tuple containing the high and low parts of the result of
  /// multiplying `lhs` and `rhs`.
  ///
  /// - SeeAlso: `multipliedWithOverflow(by:)`
  static func doubleWidthMultiply(_ lhs: Self, _ rhs: Self)
    -> (high: Self, low: Magnitude)

  /// Returns a tuple containing the quotient and remainder of dividing the
  /// first argument by the second.
  ///
  /// The resulting quotient must be representable within the bounds of the
  /// type. If the quotient of dividing `lhs` by `rhs` is too large to
  /// represent in the type, a runtime error may occur.
  ///
  /// - Parameters:
  /// - lhs: A tuple containing the high and low parts of a double-width
  /// integer. The `high` component of the tuple carries the sign, if the
  /// type is signed.
  /// - rhs: The integer to divide into `lhs`.
  /// - Returns: A tuple containing the quotient and remainder of `lhs` divided
  /// by `rhs`.
  static func doubleWidthDivide(
    _ lhs: (high: Self, low: Magnitude), _ rhs: Self)
    -> (quotient: Self, remainder: Self)

  /// The number of bits equal to 1 in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has five bits equal to 1.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.popcount == 5
  var popcount: Int { get }

  /// The number of leading zeros in this value's binary representation.
  ///
  /// For example, in a fixed-width integer type with a `bitWidth` value of 8,
  /// the number 31 has three leading zeros.
  ///
  /// let x: Int8 = 0b0001_1111
  /// // x == 31
  /// // x.leadingZeros == 3
  /// - SeeAlso: `BinaryInteger.trailingZeros`
  var leadingZeros: Int { get }

  /// Creates an integer from its big-endian representation, changing the
  /// byte order if necessary.
  init(bigEndian value: Self)

  /// Creates an integer from its little-endian representation, changing the
  /// byte order if necessary.
  init(littleEndian value: Self)

  /// The big-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a big-endian platform, for any
  /// integer `x`, `x == x.bigEndian`.
  ///
  /// - SeeAlso: `littleEndian`
  var bigEndian: Self { get }

  /// The little-endian representation of this integer.
  ///
  /// If necessary, the byte order of this value is reversed from the typical
  /// byte order of this integer type. On a little-endian platform, for any
  /// integer `x`, `x == x.littleEndian`.
  ///
  /// - SeeAlso: `bigEndian`
  var littleEndian: Self { get }

  /// A representation of this integer with the byte order swapped.
  var byteSwapped: Self { get }
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#auxiliary-protocols>Auxiliary protocols

public protocol UnsignedInteger : BinaryInteger {
  associatedtype Magnitude : BinaryInteger
}
public protocol SignedInteger : BinaryInteger, SignedArithmetic {
  associatedtype Magnitude : BinaryInteger
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#doublewidth>DoubleWidth

The DoubleWidth<T> type allows to create wider fixed-width integer types from the ones available in the standard library.

Standard library currently provides fixed-width integer types of up to 64 bits. A value of DoubleWidth<Int64> will double the range of the underlying type and implement all the FixedWidthInteger requirements. Please note though that the implementation will not necessarily be the most efficient one, so it would not be a good idea to use DoubleWidth<Int32>instead of a built-in Int64.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#extra-operators>Extra operators

In addition to the operators described in the protocols section <https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#protocols>, we also provide a few extensions that are not protocol requirements:

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-shifts>Heterogeneous shifts

extension BinaryInteger {
  // Masking shifts
  static func &>> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &>>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func &<< <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func &<<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)

  // 'Smart' shifts
  static func >> <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func >>= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
  static func << <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Self
  static func <<= <Other : BinaryInteger>(lhs: inout Self, rhs: Other)
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#heterogeneous-equality-and-comparison>Heterogeneous equality and comparison

extension BinaryInteger {
  // Equality
  static func == <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func != <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool

  // Comparison
  static func < <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func <= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func > <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
  static func >= <Other : BinaryInteger>(lhs: Self, rhs: Other) -> Bool
}
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#masking-arithmetic>Masking arithmetic

public func &* <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &- <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
public func &+ <T: FixedWidthInteger>(lhs: T, rhs: T) -> T
<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#non-goals>Non-goals

This proposal:

DOES NOT solve the integer promotion problem, which would allow mixed-type arithmetic. However, we believe that it is an important step in the right direction.

DOES NOT include the implementation of a BigInt type, but allows it to be implemented in the future.

<https://gist.github.com/moiseev/62ffe3c91b66866fdebf6f3fcc7cad8c#source-compatibility>Source compatibility

The proposed change is designed to be as non-breaking as possible, and it has been proven that it does not break code on concrete integer types. However, there are still a few API breaking changes in the realm of generic code:

Integer protocols in Swift up to and including version 3 were not particularly useful for generic programming, but were rather a means of sharing implementation between conforming types. Therefore we believe the amount of code that relied on these protocols is relatively small. The breakage can be further reduced by introducing proper aliases for the removed protocols with deprecation warnings.

Deprecation of the BitwiseOperations protocol. We find it hard to imagine a type that conforms to this protocol, but is not a binary integer type.

Addition of 'smart' shifts will change the behavior of existing code. It will still compile, but will be potentially less performant due to extra logic involved. In a case, where this becomes a problem, newly introduced masking shift operators can be used instead. Unfortunately, performance characteristics of the code cannot be statically checked, and thus migration cannot be provided.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution