Class Pile<T>

Base type to represent a pile of objects, mostly tailored for use in card games.

Inheritance

Pile<T>

Namespace: Discord.Addons.MpGame.Collections

Assembly: Discord.Addons.MpGame.dll

Syntax

public abstract class Pile<T>
    where TCard : class

Type Parameters

Name	Description
T	The item type.

Constructors

| Improve this Doc View Source

Pile()

Initializes a new pile to an empty state.

Declaration

protected Pile()

| Improve this Doc View Source

Pile(IEnumerable<T>)

Initializes a new pile with the specified items.

Declaration

protected Pile(IEnumerable<T> items)

Parameters

Type	Name	Description
IEnumerable<T>	items	The items to put in the pile.

Remarks

note

This constructor will filter out any items in items that are null or are pointing to the same object instance.

Exceptions

Type	Condition
ArgumentNullException	`items` was null.

| Improve this Doc View Source

Pile(IEnumerable<T>, Boolean)

Initializes a new pile with the specified items and a flag to determine if those should be shuffled beforehand.

Declaration

protected Pile(IEnumerable<T> items, bool initShuffle)

Parameters

Type	Name	Description
IEnumerable<T>	items	The items to put in the pile.
Boolean	initShuffle	A flag to indicate the items should be shuffled by the Pile.

Remarks

note

This constructor will filter out any items in items that are null or are pointing to the same object instance.

Exceptions

Type	Condition
ArgumentNullException	`items` was null.

Properties

| Improve this Doc View Source

CanBrowse

Indicates whether or not this pile is freely browsable.

Declaration

public abstract bool CanBrowse { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanClear

Indicates whether or not this pile can be cleared.

Declaration

public abstract bool CanClear { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanCut

Indicates whether or not this pile can be cut,
ie. taking a number of items from the top and putting them underneath the remainder.

Declaration

public abstract bool CanCut { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanDraw

Indicates whether or not this pile allows drawing items from the top.

Declaration

public abstract bool CanDraw { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanDrawBottom

Indicates whether or not this pile allows drawing items from the bottom.

Declaration

public abstract bool CanDrawBottom { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanInsert

Indicates whether or not this pile allows inserting items at an arbitrary index.

Declaration

public abstract bool CanInsert { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanPeek

Indicates whether or not this pile allows peeking at items.

Declaration

public abstract bool CanPeek { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanPut

Indicates whether or not this pile allows putting items on the top.

Declaration

public abstract bool CanPut { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanPutBottom

Indicates whether or not this pile allows putting items on the bottom.

Declaration

public abstract bool CanPutBottom { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanShuffle

Indicates whether or not this pile can be reshuffled.

Declaration

public abstract bool CanShuffle { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

CanTake

Indicates whether or not this pile allows taking items from an arbitrary index.

Declaration

public abstract bool CanTake { get; }

Property Value

Type	Description
Boolean

| Improve this Doc View Source

Count

The amount of items currently in the pile.

Declaration

public int Count { get; }

Property Value

Type	Description
Int32

Methods

| Improve this Doc View Source

AsEnumerable()

Iterates the contents of this pile as an IEnumerable<T>.
Requires CanBrowse.

Declaration

public IEnumerable<T> AsEnumerable()

Returns

Type	Description
IEnumerable<T>	The contents of the pile in a lazily-evaluated IEnumerable<T>.

Remarks

warning

This method holds a read lock from when you start enumerating until the enumeration ends and should be used only for fairly quick one-shot operations (e.g. LINQ).
If you need to hold the data for longer or iterate the same snapshot more than once, use Browse() instead.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow browsing the items.

| Improve this Doc View Source

Browse()

A snapshot of all the items without removing them from the pile.
Requires CanBrowse.

Declaration

public ImmutableArray<T> Browse()

Returns

Type	Description
ImmutableArray<T>

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow browsing the items.

| Improve this Doc View Source

BrowseAndTakeAsync(Func<IReadOnlyDictionary<Int32, T>, Task<Int32[]>>, Func<T, Boolean>, Boolean)

Browse for and take one or more items from the pile in a single operation.
Requires CanBrowse and CanTake.

Declaration

public Task<ImmutableArray<T>> BrowseAndTakeAsync(
    Func<IReadOnlyDictionary<int, T>, Task<int[]?>> selector,
    Func<T, bool>? filter = null,
    bool shuffle = false)

Parameters

Type	Name	Description
Func<IReadOnlyDictionary<Int32, T>, Task<Int32[]>>	selector	An asynchronous function that returns an array of the indeces of the desired items. The key of each pair is the index of that item. Returning a null or empty array is considered choosing nothing and will return an empty array.
Func<T, Boolean>	filter	An optional function to filter to items that can be taken.
Boolean	shuffle	A flag to reshuffle the pile after taking the selected items. If set, will use the implementation provided by ShuffleItems(IEnumerable<T>) Will be ignored if CanShuffle returns false.

Returns

Type	Description
Task<ImmutableArray<T>>	The items at the chosen indeces, or an empty array if it was chosen to not take any.

Examples

    // An effect was used that allows the user to
    // search their deck for a number of red items
    var picked = await deck.BrowseAndTake(async items =>
        {
            // Example: Call a method that shows
            // the available options to the user
            await ShowUser(items);

            // Example: Call a method that waits
            // for the user to make a decision, with 'num'
            // being the max amount of items they can choose
            return await UserInput(num);
        },
        // Only pass in the red items
        filter: c => c.Color == itemColor.Red,
        // Shuffle the pile afterwards
        shuffle: true);

    // Add the chosen items to the user's hand:
    player.AddToHand(picked);

Exceptions

Type	Condition
InvalidOperationException	The pile does not allow browsing AND taking
ArgumentNullException	`selector` was null.
IndexOutOfRangeException	One or more of the selected indices was not within the provided indices.

| Improve this Doc View Source

Clear()

Clears the entire pile and returns the items that were in it.
Requires CanClear.

Declaration

public ImmutableArray<T> Clear()

Returns

Type	Description
ImmutableArray<T>	The collection as it was before it is cleared.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow clearing all items.

| Improve this Doc View Source

Cut(Index)

Cuts the pile at a specified number of items from the top and places the taken items on the bottom.
Requires CanCut.

Declaration

public void Cut(Index index)

Parameters

Type	Name	Description
Index	index	The index of where to split.

Remarks

note

If amount is 0 or equal to Count, this function is a no-op.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow cutting the pile.
ArgumentOutOfRangeException	`amount` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

Cut(Int32)

Cuts the pile at a specified number of items from the top and places the taken items on the bottom.
Requires CanCut.

Declaration

public void Cut(int amount)

Parameters

Type	Name	Description
Int32	amount	The number of items to send to the bottom.

Remarks

note

If amount is 0 or equal to Count, this function is a no-op.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow cutting the pile.
ArgumentOutOfRangeException	`amount` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

Draw()

Draws the top item from the pile.
If the last item is drawn, calls OnLastRemoved().
Requires CanDraw.

Declaration

public T Draw()

Returns

Type	Description
T	If the pile's current size is greater than 0, the item currently at the top of the pile. Otherwise will throw.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow drawing items -OR- There were no items to draw.

| Improve this Doc View Source

DrawBottom()

Draws the bottom item from the pile.
If the last item is drawn, calls OnLastRemoved().
Requires CanDrawBottom.

Declaration

public T DrawBottom()

Returns

Type	Description
T	If the pile's current size is greater than 0, the item currently at the bottom of the pile. Otherwise will throw.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow drawing items -OR- There were no items to draw.

| Improve this Doc View Source

DrawMultiple(Int32)

Draws the top amount of items from the pile.
If the last item is drawn, calls OnLastRemoved().
Requires CanDraw.

Declaration

public ImmutableArray<T> DrawMultiple(int amount)

Parameters

Type	Name	Description
Int32	amount	The amount of items to draw.

Returns

Type	Description
ImmutableArray<T>	If the pile's current size is greater than or equal to `amount`, the first that many items currently at the top of the pile. Otherwise will throw.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow drawing items
ArgumentOutOfRangeException	`amount` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

InsertAt(T, Index)

Inserts an item at the given index.
Requires CanInsert.

Declaration

public void InsertAt(T item, Index index)

Parameters

Type	Name	Description
T	item	The item to insert.
Index	index

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow inserting items at an arbitrary location.
ArgumentNullException	`item` was null.
ArgumentOutOfRangeException	`index` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

InsertAt(T, Int32)

Inserts an item at the given index.
Requires CanInsert.

Declaration

public void InsertAt(T item, int index)

Parameters

Type	Name	Description
T	item	The item to insert.
Int32	index	The 0-based index to insert at.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow inserting items at an arbitrary location.
ArgumentNullException	`item` was null.
ArgumentOutOfRangeException	`index` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

Mill(Pile<T>)

Puts the top item of this pile on top of another pile.
Requires CanDraw or CanBrowse on this pile and CanPut on the target pile.

Declaration

public void Mill(Pile<T> targetPile)

Parameters

Type	Name	Description
Pile<T>	targetPile	The pile to place a item on.

Remarks

note

Calls OnPut(T) on the target pile.
If the last item of this pile was taken, calls OnLastRemoved() as well.

Exceptions

Type	Condition
InvalidOperationException	This pile does not allow drawing or browsing items -OR- `targetPile` was the same instance as the source -OR- `targetPile` does not allow placing items on top -OR- This pile was empty.
ArgumentNullException	`targetPile` was null.

| Improve this Doc View Source

OnLastRemoved()

Automatically called when the last item is removed from the pile.

Declaration

protected virtual void OnLastRemoved()

Remarks

note

Does nothing by default.

| Improve this Doc View Source

OnPut(T)

Automatically called when an item is put on top of the pile.

Declaration

protected virtual void OnPut(T item)

Parameters

Type	Name	Description
T	item	The item that is placed.

Remarks

note

Does nothing by default.

| Improve this Doc View Source

PeekAt(Index)

Peeks a single item at the specified index without removig it from the pile. Requires CanBrowse or CanPeek.

Declaration

public T PeekAt(Index index)

Parameters

Type	Name	Description
Index	index

Returns

Type	Description
T	The item at the specified index. -OR- null if the pile is empty.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow browsing or peeking items.
ArgumentOutOfRangeException	`index` was less than 0 or greater than or equal to the pile's current size.

| Improve this Doc View Source

PeekAt(Int32)

Peeks a single item at the specified index without removig it from the pile. Requires CanBrowse or CanPeek.

Declaration

public T PeekAt(int index)

Parameters

Type	Name	Description
Int32	index	The 0-based index to peek at.

Returns

Type	Description
T	The item at the specified index. -OR- null if the pile is empty.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow browsing or peeking items.
ArgumentOutOfRangeException	`index` was less than 0 or greater than or equal to the pile's current size.

| Improve this Doc View Source

PeekTop(Int32)

Peeks the top amount of items without removing them from the pile.
Requires CanBrowse or CanPeek.

Declaration

public ImmutableArray<T> PeekTop(int amount)

Parameters

Type	Name	Description
Int32	amount	The amount of items to peek.

Returns

Type	Description
ImmutableArray<T>	An array of the items currently at the top of the pile.

Remarks

note

Peeking the single top item is done better through PeekAt(Int32).

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow peeking items.
ArgumentOutOfRangeException	`amount` was less than 0 or greater than the pile's current size.

| Improve this Doc View Source

Put(T)

Puts an item on top of the pile.
Calls OnPut(T).
Requires CanPut.

Declaration

public void Put(T item)

Parameters

Type	Name	Description
T	item	The item to place on top.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow placing items onto it.
ArgumentNullException	`item` was null.

| Improve this Doc View Source

PutBottom(T)

Puts an item on the bottom of the pile.
Requires CanPutBottom.

Declaration

public void PutBottom(T item)

Parameters

Type	Name	Description
T	item	The item to place on the bottom.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow placing items on the bottom.
ArgumentNullException	`item` was null.

| Improve this Doc View Source

Shuffle()

Reshuffles the pile using ShuffleItems(IEnumerable<T>).
Requires CanShuffle.

Declaration

public void Shuffle()

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow reshuffling the items

| Improve this Doc View Source

ShuffleItems(IEnumerable<T>)

Default implementation for shuffling this pile's items.

Declaration

protected virtual IEnumerable<T> ShuffleItems(IEnumerable<T> items)

Parameters

Type	Name	Description
IEnumerable<T>	items	The items contained in this pile.

Returns

Type	Description
IEnumerable<T>	A new sequence of the same items in randomized order.

Remarks

This implementation is a Fisher-Yates shuffle slightly adapted from this StackOverflow answer.

| Improve this Doc View Source

TakeAt(Index)

Takes an item from the given index.
If the last item is taken, calls OnLastRemoved().
Requires CanTake.

Declaration

public T TakeAt(Index index)

Parameters

Type	Name	Description
Index	index

Returns

Type	Description
T	The item at the specified index.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow taking items from an arbitrary location.
ArgumentOutOfRangeException	`index` was less than 0 or greater than or equal to the pile's current size.

| Improve this Doc View Source

TakeAt(Int32)

Takes an item from the given index.
If the last item is taken, calls OnLastRemoved().
Requires CanTake.

Declaration

public T TakeAt(int index)

Parameters

Type	Name	Description
Int32	index	The 0-based index to take.

Returns

Type	Description
T	The item at the specified index.

Exceptions

Type	Condition
InvalidOperationException	The instance does not allow taking items from an arbitrary location.
ArgumentOutOfRangeException	`index` was less than 0 or greater than or equal to the pile's current size.