|
// 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.Diagnostics.CodeAnalysis;
namespace System.Collections.Immutable
{
/// <summary>
/// A set of initialization methods for instances of <see cref="ImmutableStack{T}"/>.
/// </summary>
public static class ImmutableStack
{
/// <summary>
/// Returns an empty collection.
/// </summary>
/// <typeparam name="T">The type of items stored by the collection.</typeparam>
/// <returns>The immutable collection.</returns>
public static ImmutableStack<T> Create<T>()
{
return ImmutableStack<T>.Empty;
}
/// <summary>
/// Creates a new immutable collection prefilled with the specified item.
/// </summary>
/// <typeparam name="T">The type of items stored by the collection.</typeparam>
/// <param name="item">The item to prepopulate.</param>
/// <returns>The new immutable collection.</returns>
public static ImmutableStack<T> Create<T>(T item)
{
return ImmutableStack<T>.Empty.Push(item);
}
/// <summary>
/// Creates a new immutable collection prefilled with the specified items.
/// </summary>
/// <typeparam name="T">The type of items stored by the collection.</typeparam>
/// <param name="items">The items to prepopulate.</param>
/// <returns>The new immutable collection.</returns>
public static ImmutableStack<T> CreateRange<T>(IEnumerable<T> items)
{
Requires.NotNull(items, nameof(items));
ImmutableStack<T> stack = ImmutableStack<T>.Empty;
foreach (T item in items)
{
stack = stack.Push(item);
}
return stack;
}
/// <summary>
/// Creates a new immutable collection prefilled with the specified items.
/// </summary>
/// <typeparam name="T">The type of items stored by the collection.</typeparam>
/// <param name="items">The items to prepopulate.</param>
/// <returns>The new immutable collection.</returns>
public static ImmutableStack<T> Create<T>(params T[] items)
{
Requires.NotNull(items, nameof(items));
return Create((ReadOnlySpan<T>)items);
}
/// <summary>
/// Creates a new immutable stack that contains the specified array of items.
/// </summary>
/// <typeparam name="T">The type of items in the immutable stack.</typeparam>
/// <param name="items">A span that contains the items to prepopulate the stack with.</param>
/// <returns>A new immutable stack that contains the specified items.</returns>
public static ImmutableStack<T> Create<T>(params ReadOnlySpan<T> items)
{
ImmutableStack<T> stack = ImmutableStack<T>.Empty;
foreach (T item in items)
{
stack = stack.Push(item);
}
return stack;
}
/// <summary>
/// Pops the top element off the stack.
/// </summary>
/// <typeparam name="T">The type of values contained in the stack.</typeparam>
/// <param name="stack">The stack to modify.</param>
/// <param name="value">The value that was removed from the stack.</param>
/// <returns>
/// A stack; never <c>null</c>
/// </returns>
/// <exception cref="InvalidOperationException">Thrown when the stack is empty.</exception>
public static IImmutableStack<T> Pop<T>(this IImmutableStack<T> stack, out T value)
{
Requires.NotNull(stack, nameof(stack));
value = stack.Peek();
return stack.Pop();
}
}
}
|