CardCollection

java.lang.Object
- wcg.games.CardCollection

All Implemented Interfaces:

java.lang.Iterable<Card>
```
public class CardCollection
extends java.lang.Object
implements java.lang.Iterable<Card>
```
A collection of cards that may represent a full deck, a player's hand or the cards on the table, for instance. As the name suggests, it contains a collection of Card and their order is relevant. This class provides several methods to operate on card collections.

This class can be instantiated but instances can also be obtained using static methods such as getDeck() to create a collections with cards of all suits and values.

Each instance has a CardComparator that is used if a particular card order needs to be considered such as in getHighestCard(). If a comparator is not not provided then DefaultCardComparator is used.

Methods with a get prefix simply return a card without changing the collection. Methods with a take prefix remove a card from the collection. If a collection is empty, methods that would return a card will return null instead.

Several methods return a CardCollection to enable chaining, including the static methods for generating a deck. For instance:
```
 CardCollection allSpades = CardCollection.getDeck().getAllCardsWithSuit(CardSuit.SPADE);
 Card lowestHeartonHand = hand.getAllCardsWithSuit(CardSuit.HEARTS).getLowestCard();
 
```
In card collections the order of cards is relevant and they may hold repeated cards. If needed, the removeRepeated() method removes duplicates and returns the collections itself for possible chaining;
Author:

José Paulo Leal jpleal@fc.up.pt

Field Summary

Fields
Modifier and Type Field and Description

(package private) java.util.LinkedList<Card> cards

(package private) CardComparator comparator

Fields
Modifier and Type	Field and Description
`(package private) java.util.LinkedList<Card>`	`cards`
`(package private) CardComparator`	`comparator`

Constructor Summary

Constructors
Constructor and Description
`CardCollection()` An empty instance backed by the `DefaultCardComparator`.
`CardCollection(CardComparator comparator)` An empty instance backed by the given `CardComparator`.
`CardCollection(CardComparator comparator, java.util.List<Card> cards)` An instance backed by the given `CardComparator` and populated with given list of cards.
`CardCollection(java.util.List<Card> cards)` An instance backed by the by the `DefaultCardComparator` and populated with given list of cards.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CardCollection`	`addAllCards(java.util.List<Card> cards)` Add a list of cards to this collection.
`CardCollection`	`addCard(Card card)` Add a single card to this collection.
`CardCollection`	`addCard(CardSuit suit, CardValue value)` Convenience methods to add card given suit and value.
`CardCollection`	`addCardCollection(CardCollection collection)` Add another collection to this one.
`java.util.List<Card>`	`asList()` Return cards as a new list of cards.
`CardCollection`	`clearCards()` Clear all cards from this collection
`boolean`	`containsCard(Card card)` Collection contains this card?
`boolean`	`equals(java.lang.Object obj)`
`CardComparator`	`getCardComparator()` Card comparator used by this card collection.
`CardCollection`	`getCardsFromSuit(CardSuit suit)` New collection with same comparator only with cards from given suit.
`CardCollection`	`getCardsLargerThan(Card limit)` New collection with same comparator and only with cards larger than given card
`CardCollection`	`getCardsNotFromSuit(CardSuit suit)` New collection with same comparator only with cards other than given suit.
`CardCollection`	`getCardsSmallerThan(Card limit)` New collection with same comparator and only with cards smaller than given card
`CardCollection`	`getCardsWithValue(CardValue value)` New collection with same comparator and the cards with given value from any suit.
`static CardCollection`	`getDeck()` A `CardCollection` with a deck cards of all suits and values, backed by the default card comparator
`static CardCollection`	`getDeck(CardComparator comparator)` A {code CardCollection} with a deck of cards of all suits and values with given card comparator
`Card`	`getFirstCard()` Get first card from collection.
`static CardCollection`	`getFullDeck()` A `CardCollection` with a full deck of cards, including 2 jokers, backed by the default card comparator
`static CardCollection`	`getFullDeck(CardComparator comparator)` A `CardCollection` with a full deck of cards, including 2 jokers, backed by the given card comparator
`Card`	`getHighestCard()` Get the highest card using this collection comparator If this collection is empty returns `null`.
`CardCollection`	`getHighestValueCards()` New collection with same comparator and the cards with the highest value from any suit.
`Card`	`getLastCard()` Get first card from collection If this collection is empty returns `null`.
`Card`	`getLowestCard()` Get the lowest card using this collection comparator.
`CardCollection`	`getLowestValueCards()` New collection with same comparator and the cards with the lowest value from any suit.
`Card`	`getRandomCard()` A random card from this collection.
`int`	`hashCode()`
`boolean`	`isEmpty()` Is this card collection is empty?
`java.util.Iterator<Card>`	`iterator()` An iterator over the cards in this collection.
`CardCollection`	`removeRepeated()` Removes duplicates in this collection.
`CardCollection`	`shuffle()` Shuffle the cards in this collection.
`int`	`size()` Number of cards in this collection.
`Card`	`takeCard(Card card)` Take a specific card and return it, if collection has at least one card; otherwise return `null`.
`Card`	`takeFirstCard()` Take the first card and return it, if collection has at least one card.
`CardCollection`	`takeFirstCards(int count)` Take given count of cards from the beginning of this collection.
`Card`	`takeLastCard()` Take the last card and return it, if collection has at least one card; otherwise return `null`.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - cards
```
java.util.LinkedList<Card> cards
```
  - comparator
```
CardComparator comparator
```
- Constructor Detail
  - CardCollection
```
public CardCollection()
```
    An empty instance backed by the DefaultCardComparator.
  - CardCollection
```
public CardCollection(java.util.List<Card> cards)
```
    An instance backed by the by the DefaultCardComparator and populated with given list of cards.
    
    Parameters:
    
    cards - to populate this collection.
  - CardCollection
```
public CardCollection(CardComparator comparator)
```
    An empty instance backed by the given CardComparator.
    
    Parameters:
    
    comparator - of cards.
  - CardCollection
```
public CardCollection(CardComparator comparator,
                      java.util.List<Card> cards)
```
    An instance backed by the given CardComparator and populated with given list of cards.
    
    Parameters:
    
    comparator - or cards.
    
    cards - to populate this collection.
- Method Detail
  - getFullDeck
```
public static CardCollection getFullDeck()
```
    A CardCollection with a full deck of cards, including 2 jokers, backed by the default card comparator
    
    Returns:
    
    deck of cards.
  - getFullDeck
```
public static CardCollection getFullDeck(CardComparator comparator)
```
    A CardCollection with a full deck of cards, including 2 jokers, backed by the given card comparator
    
    Parameters:
    
    comparator - of cards.
    
    Returns:
    
    deck of cards.
  - getDeck
```
public static CardCollection getDeck()
```
    A CardCollection with a deck cards of all suits and values, backed by the default card comparator
    
    Returns:
    
    deck of cards
  - getDeck
```
public static CardCollection getDeck(CardComparator comparator)
```
    A {code CardCollection} with a deck of cards of all suits and values with given card comparator
    
    Parameters:
    
    comparator - of cards
    
    Returns:
    
    deck of cards
  - getCardComparator
```
public CardComparator getCardComparator()
```
    Card comparator used by this card collection.
    
    Returns:
    
    comparator.
  - asList
```
public java.util.List<Card> asList()
```
    Return cards as a new list of cards. This list can be changed without affecting this instance.
    
    Returns:
    
    list of cards.
  - shuffle
```
public CardCollection shuffle()
```
    Shuffle the cards in this collection.
    
    Returns:
    
    this collection for chaining.
  - removeRepeated
```
public CardCollection removeRepeated()
```
    Removes duplicates in this collection. If a card exists multiple times, the first occurrence is kept and equals cards to the right are removed.
    
    Returns:
    
    this collection for chaining
  - isEmpty
```
public boolean isEmpty()
```
    Is this card collection is empty?
    
    Returns:
    
    true if empty; false otherwise.
  - clearCards
```
public CardCollection clearCards()
```
    Clear all cards from this collection
    
    Returns:
    
    this collection.
  - size
```
public int size()
```
    Number of cards in this collection.
    
    Returns:
    
    number of cards.
  - addCard
```
public CardCollection addCard(Card card)
```
    Add a single card to this collection.
    
    Parameters:
    
    card - to add.
    
    Returns:
    
    this collection.
  - addCard
```
public CardCollection addCard(CardSuit suit,
                              CardValue value)
```
    Convenience methods to add card given suit and value.
    
    Parameters:
    
    suit - of card
    
    value - of card
    
    Returns:
    
    this collection
  - addAllCards
```
public CardCollection addAllCards(java.util.List<Card> cards)
```
    Add a list of cards to this collection. Cards are added to the end of this one.
    
    Parameters:
    
    cards - to add.
    
    Returns:
    
    this collection.
  - addCardCollection
```
public CardCollection addCardCollection(CardCollection collection)
```
    Add another collection to this one. Cards from other collection are added to the end of this one.
    
    Parameters:
    
    collection - to add.
    
    Returns:
    
    this collection.
  - containsCard
```
public boolean containsCard(Card card)
```
    Collection contains this card?
    
    Parameters:
    
    card - to check.
    
    Returns:
    
    true if card is contained and false otherwise.
  - getFirstCard
```
public Card getFirstCard()
```
    Get first card from collection. If this collection is empty returns null.
    
    Returns:
    
    first card or null.
  - getLastCard
```
public Card getLastCard()
```
    Get first card from collection If this collection is empty returns null.
    
    Returns:
    
    first card or null.
  - getCardsFromSuit
```
public CardCollection getCardsFromSuit(CardSuit suit)
```
    New collection with same comparator only with cards from given suit.
    
    Parameters:
    
    suit - on interest
    
    Returns:
    
    collection
  - getCardsNotFromSuit
```
public CardCollection getCardsNotFromSuit(CardSuit suit)
```
    New collection with same comparator only with cards other than given suit.
    
    Parameters:
    
    suit - of interest
    
    Returns:
    
    collection
  - getCardsLargerThan
```
public CardCollection getCardsLargerThan(Card limit)
```
    New collection with same comparator and only with cards larger than given card
    
    Parameters:
    
    limit - card
    
    Returns:
    
    collection
  - getCardsSmallerThan
```
public CardCollection getCardsSmallerThan(Card limit)
```
    New collection with same comparator and only with cards smaller than given card
    
    Parameters:
    
    limit - card
    
    Returns:
    
    collection
  - getHighestValueCards
```
public CardCollection getHighestValueCards()
```
    New collection with same comparator and the cards with the highest value from any suit. For instance, if the original collection has several aces then returns a new collection containing only those cards.
    
    Returns:
    
    collection with highest value cards
  - getLowestValueCards
```
public CardCollection getLowestValueCards()
```
    New collection with same comparator and the cards with the lowest value from any suit. For instance, if the original collection has several 2 then returns a new collection containing only those cards.
    
    Returns:
    
    collection with highest value cards
  - getCardsWithValue
```
public CardCollection getCardsWithValue(CardValue value)
```
    New collection with same comparator and the cards with given value from any suit.
    
    Parameters:
    
    value - of card (e.g. ACE).
    
    Returns:
    
    collection with given value cards.
  - getHighestCard
```
public Card getHighestCard()
```
    Get the highest card using this collection comparator If this collection is empty returns null.
    
    Returns:
    
    highest value or null.
    
    Implementation Note:
    
    consider using Collections.max(Collection,Comparator)
  - getLowestCard
```
public Card getLowestCard()
```
    Get the lowest card using this collection comparator. If this collection is empty returns null.
    
    Returns:
    
    lowest value or null.
    
    Implementation Note:
    
    consider using Collections.min(Collection,Comparator).
  - getRandomCard
```
public Card getRandomCard()
```
    A random card from this collection. If the collection is empty returns null.
    
    Returns:
    
    card at random or null.
  - takeFirstCard
```
public Card takeFirstCard()
```
    Take the first card and return it, if collection has at least one card. Otherwise return null. The returned card is removed from the collection.
    
    Returns:
    
    a single card or null.
  - takeLastCard
```
public Card takeLastCard()
```
    Take the last card and return it, if collection has at least one card; otherwise return null. The returned card is removed from the collection.
    
    Returns:
    
    card or null.
  - takeFirstCards
```
public CardCollection takeFirstCards(int count)
```
    Take given count of cards from the beginning of this collection. A smaller number of cards may be returned if not enough are available.
    
    Parameters:
    
    count - of cards to take.
    
    Returns:
    
    collection.
  - takeCard
```
public Card takeCard(Card card)
```
    Take a specific card and return it, if collection has at least one card; otherwise return null. The returned card is removed from the collection.
    
    Parameters:
    
    card - to take
    
    Returns:
    
    removed card or null
  - iterator
```
public java.util.Iterator<Card> iterator()
```
    An iterator over the cards in this collection.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<Card>
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class CardCollection

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

cards

comparator

Constructor Detail

CardCollection

CardCollection

CardCollection

CardCollection

Method Detail

getFullDeck

getFullDeck

getDeck

getDeck

getCardComparator

asList

shuffle

removeRepeated

isEmpty

clearCards

size

addCard

addCard

addAllCards

addCardCollection

containsCard

getFirstCard

getLastCard

getCardsFromSuit

getCardsNotFromSuit

getCardsLargerThan

getCardsSmallerThan

getHighestValueCards

getLowestValueCards

getCardsWithValue

getHighestCard

getLowestCard

getRandomCard

takeFirstCard

takeLastCard

takeFirstCards

takeCard

iterator

hashCode

equals

toString