Repository: apple/swift
File: stdlib/public/core/Dictionary.swift (Swift)

Code before:
  ///                                 uniquingKeysWith: { (_, last) in last })
  ///     // ["b": 4, "a": 3]
  ///
  /// - Parameters:
  ///   - keysAndValues: A sequence of key-value pairs to use for the new
  ///     dictionary.
  ///   - combine: A closure that is called with the values for any duplicate
  ///     keys that are encountered. The closure returns the desired value for
  ///     the final dictionary.
  @_alwaysEmitIntoClient
  public init<S: Sequence, E: Error>(
    _ keysAndValues: __owned S,
    uniquingKeysWith combine: (Value, Value) throws(E) -> Value
  ) throws(E) where S.Element == (Key, Value) {
    var native = _NativeDictionary<Key, Value>(
      capacity: keysAndValues.underestimatedCount)
    try native.merge(keysAndValues, isUnique: true, uniquingKeysWith: combine)
    self.init(_native: native)
  }

#if !$Embedded
  // ABI-only entrypoint for the rethrows version of init, which has been
  // superseded by the typed-throws version. Expressed as "throws", which is
  // ABI-compatible with "rethrows".
  @_spi(SwiftStdlibLegacyABI) @available(swift, obsoleted: 1)
  @usableFromInline
  @abi(
    init<S: Sequence>(
      _ keysAndValues: __owned S,
      uniquingKeysWith combine: (Value, Value) throws -> Value
    ) rethrows where S.Element == (Key, Value)
  )
  internal init<S: Sequence>(
    __rethrows_keysAndValues keysAndValues: __owned S,
    uniquingKeysWith combine: (Value, Value) throws -> Value
  ) throws where S.Element == (Key, Value) {
    try self.init(keysAndValues, uniquingKeysWith: combine)
  }
#endif

  /// Creates a new dictionary whose keys are the groupings returned by the
  /// given closure and whose values are arrays of the elements that returned
  /// each key.
  ///
  /// The arrays in the "values" position of the new dictionary each contain at
  /// least one element, with the elements in the same order as the source
  /// sequence.
  ///
  /// The following example declares an array of names, and then creates a
  /// dictionary from that array by grouping the names by first letter:
  ///

Review comment (suggestion):
It would be more readable to have `@usableFromInline` right before `internal`, since they're related.

Code after:
  ///     the final dictionary.
  @_alwaysEmitIntoClient
  public init<S: Sequence, E: Error>(
    _ keysAndValues: __owned S,
    uniquingKeysWith combine: (Value, Value) throws(E) -> Value
  ) throws(E) where S.Element == (Key, Value) {
    var native = _NativeDictionary<Key, Value>(
      capacity: keysAndValues.underestimatedCount)
    try native.merge(keysAndValues, isUnique: true, uniquingKeysWith: combine)
    self.init(_native: native)
  }

#if !$Embedded
  // ABI-only entrypoint for the rethrows version of init, which has been
  // superseded by the typed-throws version. Expressed as "throws", which is
  // ABI-compatible with "rethrows".
  @_spi(SwiftStdlibLegacyABI) @available(swift, obsoleted: 1)
  @abi(
    init<S: Sequence>(
      _ keysAndValues: __owned S,
      uniquingKeysWith combine: (Value, Value) throws -> Value
    ) throws where S.Element == (Key, Value)
  )
  @usableFromInline
  internal init<S: Sequence>(
    __rethrows_keysAndValues keysAndValues: __owned S,
    uniquingKeysWith combine: (Value, Value) throws -> Value
  ) throws where S.Element == (Key, Value) {
    try self.init(keysAndValues, uniquingKeysWith: combine)
  }
#endif

  /// Creates a new dictionary whose keys are the groupings returned by the
  /// given closure and whose values are arrays of the elements that returned
  /// each key.
  ///
  /// The arrays in the "values" position of the new dictionary each contain at
  /// least one element, with the elements in the same order as the source
  /// sequence.
  ///
  /// The following example declares an array of names, and then creates a
  /// dictionary from that array by grouping the names by first letter:
  ///
  ///     let students = ["Kofi", "Abena", "Efua", "Kweku", "Akosua"]
  ///     let studentsByLetter = Dictionary(grouping: students, by: { $0.first! })
  ///     // ["E": ["Efua"], "K": ["Kofi", "Kweku"], "A": ["Abena", "Akosua"]]
  ///
  /// The new `studentsByLetter` dictionary has three entries, with students'
  /// names grouped by the keys `"E"`, `"K"`, and `"A"`.
  ///
  /// - Parameters: