Class Pile<T>
Base type to represent a pile of objects, mostly tailored for use in card games.
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 SourcePile()
Initializes a new pile to an empty state.
Declaration
protected Pile()
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 |
|
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 |
|
Properties
| Improve this Doc View SourceCanBrowse
Indicates whether or not this pile is freely browsable.
Declaration
public abstract bool CanBrowse { get; }
Property Value
Type | Description |
---|---|
Boolean |
CanClear
Indicates whether or not this pile can be cleared.
Declaration
public abstract bool CanClear { get; }
Property Value
Type | Description |
---|---|
Boolean |
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 |
CanDraw
Indicates whether or not this pile allows drawing items from the top.
Declaration
public abstract bool CanDraw { get; }
Property Value
Type | Description |
---|---|
Boolean |
CanDrawBottom
Indicates whether or not this pile allows drawing items from the bottom.
Declaration
public abstract bool CanDrawBottom { get; }
Property Value
Type | Description |
---|---|
Boolean |
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 |
CanPeek
Indicates whether or not this pile allows peeking at items.
Declaration
public abstract bool CanPeek { get; }
Property Value
Type | Description |
---|---|
Boolean |
CanPut
Indicates whether or not this pile allows putting items on the top.
Declaration
public abstract bool CanPut { get; }
Property Value
Type | Description |
---|---|
Boolean |
CanPutBottom
Indicates whether or not this pile allows putting items on the bottom.
Declaration
public abstract bool CanPutBottom { get; }
Property Value
Type | Description |
---|---|
Boolean |
CanShuffle
Indicates whether or not this pile can be reshuffled.
Declaration
public abstract bool CanShuffle { get; }
Property Value
Type | Description |
---|---|
Boolean |
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 |
Count
The amount of items currently in the pile.
Declaration
public int Count { get; }
Property Value
Type | Description |
---|---|
Int32 |
Methods
| Improve this Doc View SourceAsEnumerable()
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. |
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. |
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. |
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. |
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 |
|
IndexOutOfRangeException | One or more of the selected indices was not within the provided indices. |
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. |
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 |
|
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 |
|
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 |
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 |
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 |
Exceptions
Type | Condition |
---|---|
InvalidOperationException | The instance does not allow drawing items |
ArgumentOutOfRangeException |
|
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 |
|
ArgumentOutOfRangeException |
|
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 |
|
ArgumentOutOfRangeException |
|
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 |
ArgumentNullException |
|
OnLastRemoved()
Automatically called when the last item is removed from the pile.
Declaration
protected virtual void OnLastRemoved()
Remarks
note
Does nothing by default.
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.
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. |
Exceptions
Type | Condition |
---|---|
InvalidOperationException | The instance does not allow browsing or peeking items. |
ArgumentOutOfRangeException |
|
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. |
Exceptions
Type | Condition |
---|---|
InvalidOperationException | The instance does not allow browsing or peeking items. |
ArgumentOutOfRangeException |
|
PeekTop(Int32)
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 |
|
Put(T)
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 |
|
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 |
|
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 |
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.
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 |
|
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 |
|