/// <summary>
        /// Because the input <see cref="IDictionary{TKey, TValue}"/> is not an <see cref="IDistinctValuedDictionary{TKey, TValue}"/>, duplicate value handling must be specified.
        /// </summary>
        public static Dictionary <TValue, TKey> Invert <TKey, TValue>(this IDictionary <TKey, TValue> dictionary,
                                                                      DuplicateValueHandling duplicateValueHandling = DuplicateValueHandling.Error)
        {
            var output = new Dictionary <TValue, TKey>();

            foreach (var pair in dictionary)
            {
                var key   = pair.Value;
                var value = pair.Key;

                if (output.ContainsKey(key))
                {
                    var existing = output[key];
                    var chosen   = duplicateValueHandling.Choose(existing, value);

                    output[key] = chosen;
                }
                else
                {
                    output.Add(key, value);
                }
            }

            return(output);
        }