extension Dictionary {

    /// Creates a new dictionary whose keys are the groupings returned by the
    /// given closure and whose values are collections of the elements, using a
    /// given type, that returned each key.
    ///
    /// The collections 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 a string, then creates a dictionary from
    /// that string by grouping by a filtering predicate.
    ///
    ///     let vowels = Set<Character> = ["a", "e", "i", "o", "u"]
    ///     let swiftMessage = "Swift Dictionary"
    ///     let swiftMsgByType = Dictionary(grouping: swiftMessage, as: String.self, by: { vowels.contains($0) })
    ///     // [false: "Swft Dctnry", true: "iiioa"]
    ///
    /// The new `swiftMsgByType` dictionary has two entries, one grouping
    /// non-vowels (key `false`) and one group with vowels (key `true`).
    ///
    /// - Parameters:
    ///   - values: A sequence of values to group into a dictionary.
    ///   - type: A metatype specifier for the per-key collection type of
    ///     elements.
    ///   - keyForValue: A closure that returns a key for each element in
    ///     `values`.
    @inlinable
    public init<S: Sequence>(grouping values: S, as type: Value.Type, by keyForValue: (S.Element) throws -> Key) rethrows where Value: RangeReplaceableCollection, Value.Element == S.Element {
        let arrayedDictionary = try Dictionary<Key, [Value.Element]>(grouping: values, by: keyForValue)
        self = arrayedDictionary.mapValues(Value.init)
    }

}