|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System.Collections.Generic;
using System.Runtime.CompilerServices;
namespace System.Collections.Immutable
{
/// <summary>
/// A set of elements that can only be modified by creating a new instance of the set.
/// </summary>
/// <typeparam name="T">The type of element stored in the set.</typeparam>
/// <remarks>
/// Mutations on this set generate new sets. Incremental changes to a set share as much memory as possible with the prior versions of a set,
/// while allowing garbage collection to clean up any unique set data that is no longer being referenced.
/// </remarks>
[CollectionBuilder(typeof(ImmutableHashSet), nameof(ImmutableHashSet.Create))]
public interface IImmutableSet<T> : IReadOnlyCollection<T>
{
/// <summary>
/// Gets an empty set that retains the same sort or unordered semantics that this instance has.
/// </summary>
IImmutableSet<T> Clear();
/// <summary>
/// Determines whether this set contains the specified value.
/// </summary>
/// <param name="value">The value.</param>
/// <returns>
/// <c>true</c> if the set contains the specified value; otherwise, <c>false</c>.
/// </returns>
bool Contains(T value);
/// <summary>
/// Adds the specified value to this set.
/// </summary>
/// <param name="value">The value to add.</param>
/// <returns>A new set with the element added, or this set if the element is already in this set.</returns>
IImmutableSet<T> Add(T value);
/// <summary>
/// Removes the specified value from this set.
/// </summary>
/// <param name="value">The value to remove.</param>
/// <returns>A new set with the element removed, or this set if the element is not in this set.</returns>
IImmutableSet<T> Remove(T value);
/// <summary>
/// Searches the set for a given value and returns the equal value it finds, if any.
/// </summary>
/// <param name="equalValue">The value to search for.</param>
/// <param name="actualValue">The value from the set that the search found, or <paramref name="equalValue"/> if the search yielded no match.</param>
/// <returns>A value indicating whether the search was successful.</returns>
/// <remarks>
/// This can be useful when you want to reuse a previously stored reference instead of
/// a newly constructed one (so that more sharing of references can occur) or to look up
/// a value that has more complete data than the value you currently have, although their
/// comparer functions indicate they are equal.
/// </remarks>
bool TryGetValue(T equalValue, out T actualValue);
/// <summary>
/// Produces a set that contains elements that exist in both this set and the specified set.
/// </summary>
/// <param name="other">The set to intersect with this one.</param>
/// <returns>A new set that contains any elements that exist in both sets.</returns>
IImmutableSet<T> Intersect(IEnumerable<T> other);
/// <summary>
/// Removes a given set of items from this set.
/// </summary>
/// <param name="other">The items to remove from this set.</param>
/// <returns>The new set with the items removed; or the original set if none of the items were in the set.</returns>
IImmutableSet<T> Except(IEnumerable<T> other);
/// <summary>
/// Produces a set that contains elements either in this set or a given sequence, but not both.
/// </summary>
/// <param name="other">The other sequence of items.</param>
/// <returns>The new set.</returns>
IImmutableSet<T> SymmetricExcept(IEnumerable<T> other);
/// <summary>
/// Adds a given set of items to this set.
/// </summary>
/// <param name="other">The items to add.</param>
/// <returns>The new set with the items added; or the original set if all the items were already in the set.</returns>
IImmutableSet<T> Union(IEnumerable<T> other);
/// <summary>
/// Checks whether a given sequence of items entirely describe the contents of this set.
/// </summary>
/// <param name="other">The sequence of items to check against this set.</param>
/// <returns>A value indicating whether the sets are equal.</returns>
bool SetEquals(IEnumerable<T> other);
/// <summary>
/// Determines whether the current set is a proper (strict) subset of a specified collection.
/// </summary>
/// <param name="other">The collection to compare to the current set.</param>
/// <returns>true if the current set is a correct subset of other; otherwise, false.</returns>
bool IsProperSubsetOf(IEnumerable<T> other);
/// <summary>
/// Determines whether the current set is a proper superset of a specified collection.
/// </summary>
/// <param name="other">The collection to compare to the current set.</param>
/// <returns>true if the current set is a correct superset of other; otherwise, false.</returns>
bool IsProperSupersetOf(IEnumerable<T> other);
/// <summary>
/// Determines whether a set is a subset of a specified collection.
/// </summary>
/// <param name="other">The collection to compare to the current set.</param>
/// <returns>true if the current set is a subset of other; otherwise, false.</returns>
bool IsSubsetOf(IEnumerable<T> other);
/// <summary>
/// Determines whether the current set is a superset of a specified collection.
/// </summary>
/// <param name="other">The collection to compare to the current set.</param>
/// <returns>true if the current set is a superset of other; otherwise, false.</returns>
bool IsSupersetOf(IEnumerable<T> other);
/// <summary>
/// Determines whether the current set overlaps with the specified collection.
/// </summary>
/// <param name="other">The collection to compare to the current set.</param>
/// <returns>true if the current set and other share at least one common element; otherwise, false.</returns>
bool Overlaps(IEnumerable<T> other);
}
}
|