[stdlib] extendingOrTruncating: => truncatingIfNeeded:

(cherry picked from commit a5ff35c)

Author: Maxim Moiseev

stdlib/private/StdlibUnicodeUnittest/Collation.swift

@@ -338,13 +338,13 @@ public struct StringComparisonTest {
 
 public func sortKey(forCollationElements ces: [UInt64]) -> ([UInt16], [UInt16], [UInt16]) {
   func L1(_ ce: UInt64) -> UInt16 {
-    return UInt16(extendingOrTruncating: ce &>> 32)
+    return UInt16(truncatingIfNeeded: ce &>> 32)
   }
   func L2(_ ce: UInt64) -> UInt16 {
-    return UInt16(extendingOrTruncating: ce &>> 16)
+    return UInt16(truncatingIfNeeded: ce &>> 16)
   }
   func L3(_ ce: UInt64) -> UInt16 {
-    return UInt16(extendingOrTruncating: ce)
+    return UInt16(truncatingIfNeeded: ce)
   }
 
   var result1: [UInt16] = []

stdlib/public/core/ASCII.swift

@@ -41,7 +41,7 @@ extension Unicode.ASCII : Unicode.Encoding {
     _ source: Unicode.Scalar
   ) -> EncodedScalar? {
     guard source.value < (1&<<7) else { return nil }
-    return EncodedScalar(UInt8(extendingOrTruncating: source.value))
+    return EncodedScalar(UInt8(truncatingIfNeeded: source.value))
   }
 
   @inline(__always)
@@ -80,7 +80,7 @@ extension Unicode.ASCII.Parser : Unicode.Parser {
   where I.Element == Encoding.CodeUnit {
     let n = input.next()
     if _fastPath(n != nil), let x = n {
-      guard _fastPath(Int8(extendingOrTruncating: x) >= 0)
+      guard _fastPath(Int8(truncatingIfNeeded: x) >= 0)
       else { return .error(length: 1) }
       return .valid(Unicode.ASCII.EncodedScalar(x))
     }

stdlib/public/core/ArrayBody.swift

@@ -32,7 +32,7 @@ internal struct _ArrayBody {
     _storage = _SwiftArrayBodyStorage(
       count: count,
       _capacityAndFlags:
-        (UInt(extendingOrTruncating: capacity) &<< 1) |
+        (UInt(truncatingIfNeeded: capacity) &<< 1) |
         (elementTypeIsBridgedVerbatim ? 1 : 0))
   }
 

stdlib/public/core/Builtin.swift

@@ -90,8 +90,7 @@ func _canBeClass<T>(_: T.Type) -> Int8 {
 /// - Value conversion from one integer type to another. Use the destination
 ///   type's initializer or the `numericCast(_:)` function.
 /// - Bitwise conversion from one integer type to another. Use the destination
-///   type's `init(extendingOrTruncating:)` or `init(bitPattern:)`
-///   initializer.
+///   type's `init(truncatingIfNeeded:)` or `init(bitPattern:)` initializer.
 /// - Conversion from a pointer to an integer value with the bit pattern of the
 ///   pointer's address in memory, or vice versa. Use the `init(bitPattern:)`
 ///   initializer for the destination type.

stdlib/public/core/Character.swift

@@ -130,7 +130,7 @@ public struct Character :
           shift += 16
         }
       }
-      guard _fastPath(Int64(extendingOrTruncating: bits) >= 0) else {
+      guard _fastPath(Int64(truncatingIfNeeded: bits) >= 0) else {
         break FastPath
       }
       _representation = .smallUTF16(Builtin.trunc_Int64_Int63(bits._value))
@@ -224,7 +224,7 @@ public struct Character :
 
     if _fastPath(s._core.count <= 4) {
       let b = _UIntBuffer<UInt64, Unicode.UTF16.CodeUnit>(s._core)
-      if _fastPath(Int64(extendingOrTruncating: b._storage) >= 0) {
+      if _fastPath(Int64(truncatingIfNeeded: b._storage) >= 0) {
         _representation = .smallUTF16(
           Builtin.trunc_Int64_Int63(b._storage._value))
         return

stdlib/public/core/CharacterUnicodeScalars.swift

@@ -101,7 +101,7 @@ extension Character.UnicodeScalarView : Collection {
     case .valid(let s):
       return Index(
         _encodedOffset: startOfNextScalar, _scalar: s,
-        _stride: UInt8(extendingOrTruncating: s.count))
+        _stride: UInt8(truncatingIfNeeded: s.count))
     case .error:
       return Index(
         _encodedOffset: startOfNextScalar,
@@ -138,7 +138,7 @@ extension Character.UnicodeScalarView : BidirectionalCollection {
     case .valid(let s):
       return Index(
         _encodedOffset: i._encodedOffset - s.count, _scalar: s,
-        _stride: UInt8(extendingOrTruncating: s.count))
+        _stride: UInt8(truncatingIfNeeded: s.count))
     case .error:
       return Index(
         _encodedOffset: i._encodedOffset - 1,

stdlib/public/core/FloatingPointTypes.swift.gyb

@@ -754,11 +754,11 @@ extension ${Self} : Hashable {
     %if bits <= word_bits:
       return Int(bitPattern: UInt(bitPattern))
     %elif bits == 64: # Double -> 32-bit Int
-      return Int(extendingOrTruncating: bitPattern &>> 32) ^
-             Int(extendingOrTruncating: bitPattern)
+      return Int(truncatingIfNeeded: bitPattern &>> 32) ^
+             Int(truncatingIfNeeded: bitPattern)
     %elif word_bits == 32: # Float80 -> 32-bit Int
-      return Int(extendingOrTruncating: significandBitPattern &>> 32) ^
-             Int(extendingOrTruncating: significandBitPattern) ^
+      return Int(truncatingIfNeeded: significandBitPattern &>> 32) ^
+             Int(truncatingIfNeeded: significandBitPattern) ^
              Int(_representation.signAndExponent)
     %else: # Float80 -> 64-bit Int
       return Int(bitPattern: UInt(significandBitPattern)) ^

stdlib/public/core/IntegerParsing.swift

@@ -18,14 +18,14 @@ internal func _asciiDigit<CodeUnit : UnsignedInteger, Result : BinaryInteger>(
   let lower = _ascii16("a")..._ascii16("z")
   let upper = _ascii16("A")..._ascii16("Z")
 
-  let u = UInt16(extendingOrTruncating: u_)
+  let u = UInt16(truncatingIfNeeded: u_)
   let d: UInt16
   if _fastPath(digit ~= u) { d = u &- digit.lowerBound }
   else if _fastPath(upper ~= u) { d = u &- upper.lowerBound &+ 10 }
   else if _fastPath(lower ~= u) { d = u &- lower.lowerBound &+ 10 }
   else { return nil }
   guard _fastPath(d < radix) else { return nil }
-  return Result(extendingOrTruncating: d)
+  return Result(truncatingIfNeeded: d)
 }
 
 @inline(__always)

stdlib/public/core/Integers.swift.gyb

@@ -1242,7 +1242,7 @@ extension Numeric {
 /// Bit Pattern Conversion
 /// ----------------------
 ///
-/// Use the `init(extendingOrTruncating:)` initializer to create a new instance
+/// Use the `init(truncatingIfNeeded:)` initializer to create a new instance
 /// with the same bit pattern as the passed value, extending or truncating the
 /// value's representation as necessary. Note that the value may not be
 /// preserved, particularly when converting between signed to unsigned integer
@@ -1253,11 +1253,11 @@ extension Numeric {
 ///     let q: Int16 = 850
 ///     // q == 0b00000011_01010010
 ///
-///     let r = Int8(extendingOrTruncating: q)      // truncate 'q' to fit in 8 bits
+///     let r = Int8(truncatingIfNeeded: q)      // truncate 'q' to fit in 8 bits
 ///     // r == 82
 ///     //   == 0b01010010
 ///
-///     let s = Int16(extendingOrTruncating: s)     // extend 'r' to fill 16 bits
+///     let s = Int16(truncatingIfNeeded: s)     // extend 'r' to fill 16 bits
 ///     // s == 82
 ///     //   == 0b00000000_01010010
 ///
@@ -1272,15 +1272,15 @@ extension Numeric {
 ///     // t == -100
 ///     // t's binary representation == 0b10011100
 ///
-///     let u = UInt8(extendingOrTruncating: t)
+///     let u = UInt8(truncatingIfNeeded: t)
 ///     // u == 156
 ///     // u's binary representation == 0b10011100
 ///
-///     let v = Int16(extendingOrTruncating: t)
+///     let v = Int16(truncatingIfNeeded: t)
 ///     // v == -100
 ///     // v's binary representation == 0b11111111_10011100
 ///
-///     let w = UInt16(extendingOrTruncating: t)
+///     let w = UInt16(truncatingIfNeeded: t)
 ///     // w == 65436
 ///     // w's binary representation == 0b11111111_10011100
 ///
@@ -1377,7 +1377,7 @@ public protocol BinaryInteger :
   ///
   ///     let p: Int16 = -500
   ///     // 'p' has a binary representation of 11111110_00001100
-  ///     let q = Int8(extendingOrTruncating: p)
+  ///     let q = Int8(truncatingIfNeeded: p)
   ///     // q == 12
   ///     // 'q' has a binary representation of 00001100
   ///
@@ -1388,21 +1388,21 @@ public protocol BinaryInteger :
   ///
   ///     let u: Int8 = 21
   ///     // 'u' has a binary representation of 00010101
-  ///     let v = Int16(extendingOrTruncating: u)
+  ///     let v = Int16(truncatingIfNeeded: u)
   ///     // v == 21
   ///     // 'v' has a binary representation of 00000000_00010101
   ///
   ///     let w: Int8 = -21
   ///     // 'w' has a binary representation of 11101011
-  ///     let x = Int16(extendingOrTruncating: w)
+  ///     let x = Int16(truncatingIfNeeded: w)
   ///     // x == -21
   ///     // 'x' has a binary representation of 11111111_11101011
-  ///     let y = UInt16(extendingOrTruncating: w)
+  ///     let y = UInt16(truncatingIfNeeded: 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)
+  init<T : BinaryInteger>(truncatingIfNeeded source: T)
 
   /// Creates a new instance with the representable value that's closest to the
   /// given integer.
@@ -1675,16 +1675,16 @@ extension BinaryInteger {
     //    sign bit. Therefore it is safe to convert to the unsigned type.
 
     if lhs.bitWidth < rhs.bitWidth {
-      return Other(extendingOrTruncating: lhs) == rhs
+      return Other(truncatingIfNeeded: lhs) == rhs
     }
     if lhs.bitWidth > rhs.bitWidth {
-      return lhs == Self(extendingOrTruncating: rhs)
+      return lhs == Self(truncatingIfNeeded: rhs)
     }
 
     if Self.isSigned {
-      return Other(extendingOrTruncating: lhs) == rhs
+      return Other(truncatingIfNeeded: lhs) == rhs
     }
-    return lhs == Self(extendingOrTruncating: rhs)
+    return lhs == Self(truncatingIfNeeded: rhs)
   }
 
   /// Returns a Boolean value indicating whether the two given values are not
@@ -1735,14 +1735,14 @@ extension BinaryInteger {
     // values of the other type. Otherwise, lhs and rhs are positive, and one
     // of Self, Other may be signed and the other unsigned.
 
-    let rhsAsSelf = Self(extendingOrTruncating: rhs)
+    let rhsAsSelf = Self(truncatingIfNeeded: rhs)
     let rhsAsSelfNegative = rhsAsSelf < (0 as Self)
 
 
     // Can we round-trip rhs through Other?
-    if Other(extendingOrTruncating: rhsAsSelf) == rhs &&
+    if Other(truncatingIfNeeded: rhsAsSelf) == rhs &&
       // This additional check covers the `Int8.max < (128 as UInt8)` case.
-      // Since the types are of the same width, init(extendingOrTruncating:)
+      // Since the types are of the same width, init(truncatingIfNeeded:)
       // will result in a simple bitcast, so that rhsAsSelf would be -128, and
       // `lhs < rhsAsSelf` will return false.
       // We basically guard against that bitcast by requiring rhs and rhsAsSelf
@@ -1751,7 +1751,7 @@ extension BinaryInteger {
       return lhs < rhsAsSelf
     }
 
-    return Other(extendingOrTruncating: lhs) < rhs
+    return Other(truncatingIfNeeded: lhs) < rhs
   }
 
   /// Returns a Boolean value indicating whether the value of the first
@@ -1861,7 +1861,7 @@ extension BinaryInteger {
 ///         var binaryString: String {
 ///             var result: [String] = []
 ///             for i in 0..<(Self.bitWidth / 8) {
-///                 let byte = UInt8(extendingOrTruncating: self >> (i * 8))
+///                 let byte = UInt8(truncatingIfNeeded: self >> (i * 8))
 ///                 let byteString = String(byte, radix: 2)
 ///                 let padding = String(repeating: "0",
 ///                                      count: 8 - byteString.count)
@@ -2125,7 +2125,7 @@ ${operatorComment(x.operator, False)}
   public static func ${x.operator} <
     Other : BinaryInteger
   >(lhs: Self, rhs: Other) -> Self {
-    return lhs ${x.operator} Self(extendingOrTruncating: rhs)
+    return lhs ${x.operator} Self(truncatingIfNeeded: rhs)
   }
 
   // Heterogeneous masking shift assignment
@@ -2191,7 +2191,7 @@ ${operatorComment(x.nonMaskingOperator, True)}
     let overshiftL: Self = 0
     if _fastPath(rhs >= 0) {
       if _fastPath(rhs < Self.bitWidth) {
-        return lhs ${x.operator} Self(extendingOrTruncating: rhs)
+        return lhs ${x.operator} Self(truncatingIfNeeded: rhs)
       }
       return overshift${'LR'[isRightShift]}
     }
@@ -2214,7 +2214,7 @@ extension FixedWidthInteger {
     else if _slowPath(source > Self.max) {
       self = Self.max
     }
-    else { self = Self(extendingOrTruncating: source) }
+    else { self = Self(truncatingIfNeeded: source) }
   }
 
 % for x in binaryArithmetic['Numeric'] + binaryArithmetic["BinaryInteger"][:1]:
@@ -2253,7 +2253,7 @@ ${unsafeOperationComment(x.operator)}
 % end
 
   @inline(__always)
-  public init<T : BinaryInteger>(extendingOrTruncating source: T) {
+  public init<T : BinaryInteger>(truncatingIfNeeded source: T) {
     if Self.bitWidth <= ${word_bits} {
       self = Self.init(_truncatingBits: source._lowWord)
     }
@@ -2322,7 +2322,7 @@ extension UnsignedInteger {
   /// A textual representation of this value.
   public var description: String {
     if self.bitWidth <= ${word_bits} {
-      return _uint64ToString(UInt64(extendingOrTruncating: self))
+      return _uint64ToString(UInt64(truncatingIfNeeded: self))
     }
     if self == (0 as Self) {
       return "0"
@@ -2342,7 +2342,7 @@ extension UnsignedInteger {
       x /= 10
       buf.append(
         Unicode.Scalar(
-          ascii0 + Int(UInt(extendingOrTruncating: r)._value))!)
+          ascii0 + Int(UInt(truncatingIfNeeded: r)._value))!)
     }
     while x != (0 as Self)
     return String(buf.reversed().lazy.map { Character($0) })
@@ -2362,7 +2362,7 @@ extension UnsignedInteger where Self : FixedWidthInteger {
       _precondition(source <= Self.max,
         "Not enough bits to represent a signed value")
     }
-    self.init(extendingOrTruncating: source)
+    self.init(truncatingIfNeeded: source)
   }
 
   @_semantics("optimize.sil.specialize.generic.partial.never")
@@ -2377,7 +2377,7 @@ extension UnsignedInteger where Self : FixedWidthInteger {
        source > Self.max {
       return nil
     }
-    self.init(extendingOrTruncating: source)
+    self.init(truncatingIfNeeded: source)
   }
 
   /// The maximum representable integer in this type.
@@ -2415,7 +2415,7 @@ extension SignedInteger {
   /// A textual representation of this value.
   public var description: String {
     if self.bitWidth <= ${word_bits} {
-      return _int64ToString(Int64(extendingOrTruncating: self))
+      return _int64ToString(Int64(truncatingIfNeeded: self))
     }
 
     let base = magnitude.description
@@ -2444,7 +2444,7 @@ extension SignedInteger where Self : FixedWidthInteger {
       _precondition(source <= Self.max,
         "Not enough bits to represent a signed value")
     }
-    self.init(extendingOrTruncating: source)
+    self.init(truncatingIfNeeded: source)
   }
 
   @_semantics("optimize.sil.specialize.generic.partial.never")
@@ -2460,7 +2460,7 @@ extension SignedInteger where Self : FixedWidthInteger {
        source > Self.max {
       return nil
     }
-    self.init(extendingOrTruncating: source)
+    self.init(truncatingIfNeeded: source)
   }
 
   /// The maximum representable integer in this type.
@@ -2954,8 +2954,8 @@ extension ${Self} : Hashable {
 % elif bits == word_bits * 2:
       // We have twice as many bits as we need to return.
       return
-        Int(extendingOrTruncating: self) ^
-        Int(extendingOrTruncating: self &>> 32)
+        Int(truncatingIfNeeded: self) ^
+        Int(truncatingIfNeeded: self &>> 32)
 % else:
       _Unimplemented()
 % end
@@ -2986,7 +2986,7 @@ extension ${Self} {
   ///
   /// - Parameter source: An integer to use as the source of the new value's
   ///   bit pattern.
-  @available(swift, obsoleted: 4.0, renamed: "init(extendingOrTruncating:)")
+  @available(swift, obsoleted: 4.0, renamed: "init(truncatingIfNeeded:)")
   @_transparent
   public init(truncatingBitPattern source: ${Src}) {
     let src = source._value

stdlib/public/core/SipHash.swift.gyb

@@ -248,7 +248,7 @@ struct ${Self} {
   internal mutating func _finalizeAndReturnIntHash() -> Int {
     let hash: UInt64 = finalizeAndReturnHash()
 #if arch(i386) || arch(arm)
-    return Int(extendingOrTruncating: hash)
+    return Int(truncatingIfNeeded: hash)
 #elseif arch(x86_64) || arch(arm64) || arch(powerpc64) || arch(powerpc64le) || arch(s390x)
     return Int(Int64(bitPattern: hash))
 #endif