inonit.domain.game.card
Class CardArray

java.lang.Object
  |
  +--inonit.domain.game.card.CardArray
All Implemented Interfaces:
java.io.Serializable

public class CardArray
extends java.lang.Object
implements java.io.Serializable

An ordered collection of Card objects, which can be manipulated in various ways. CardArray instances are mutable, but can acquire some of the benefits of immutability by using the copy method to create new copies for clients who should not change the original CardArray.

CardArray objects can contain duplicate Cards as necessary, and can be filtered and sorted in various ways.

CardArray objects are not currently thread-safe, and should only be accessed by a single thread at a time.

See Also:
Serialized Form

Constructor Summary
CardArray()
          Creates a new, empty CardArray.
CardArray(Card[] cards)
          Creates a new CardArray, initialized with the given Cards.
 
Method Summary
 CardArray add(Card card)
          Appends the given Card to the end of this CardArray.
 CardArray add(CardArray array)
          Appends the Cards (if any) in the given CardArray to the end of this CardArray.
static CardArray combine(CardArray[] arrays)
          Returns the aggregation of the given CardArrays.
 boolean contains(Card card)
          Returns whether this CardArray contains the given Card.
 boolean containsAll(CardArray array)
          Returns whether this CardArray contains all of the Cards in the given CardArray.
 boolean containsOne(CardArray array)
          Returns whether this CardArray contains at least one Card which is also contained in the given CardArray.
 CardArray copy()
          Returns a copy of this CardArray.
 Card[] get()
          Returns an array containing the Cards in this CardArray.
 Card get(int index)
          Returns the Card at the given index in this CardArray.
 CardArray get(Suit suit)
          Returns a CardArray containing the Cards in this CardArray which are of the given Suit.
 int getCount(Suit suit)
          Returns the number of cards in this CardArray which are of the given Suit.
 int getLength()
          Returns the current number of Cards in this CardArray.
static CardArray intersection(CardArray[] arrays)
          Returns a CardArray containing all of the Cards that are found in all the argument CardArrays.
 boolean isEmpty()
          Returns whether this CardArray is currently empty.
 CardArray remove(Card card)
          Removes at most one instance (the first) of the given Card from this CardArray.
 CardArray remove(CardArray array)
          Removes all of the Cards in the given CardArray from this CardArray.
 CardArray shuffle()
          Shuffles the Cards in this CardArray into random order.
 CardArray sort(Sort.Order order)
          Sorts the Cards in this CardArray into the given Sort.Order.
 java.lang.String toString()
          Returns a String which lists the Cards in this CardArray, which may be useful for debugging.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CardArray

public CardArray(Card[] cards)
Creates a new CardArray, initialized with the given Cards.
Parameters:
cards - The Cards to put into the CardArray. Must not be null. Must not contain null elements.

CardArray

public CardArray()
Creates a new, empty CardArray.
Method Detail

combine

public static CardArray combine(CardArray[] arrays)
Returns the aggregation of the given CardArrays. If the component CardArrays contain duplicate cards, the CardArray returned will contain the duplicates. The returned CardArray will preserve order from the individual CardArrays; the first Card in the result will be the first Card from the first CardArray, followed by the second Card from the first CardArray, and so on, until the first CardArray is exhausted. The next Card will be the first Card from the second CardArray, and so on.
Parameters:
arrays - The CardArrays which will be combined to create the result. Must not be null. Must not contain null elements.
Returns:
A CardArray containing all of the Cards from the individual CardArray objects in arrays.

toString

public java.lang.String toString()
Returns a String which lists the Cards in this CardArray, which may be useful for debugging.
Overrides:
toString in class java.lang.Object
Returns:
A brief list of the Cards in this CardArray.

getLength

public int getLength()
Returns the current number of Cards in this CardArray.
Returns:
the number of Cards in this CardArray.

isEmpty

public boolean isEmpty()
Returns whether this CardArray is currently empty. Equivalent to getLength() == 0.
Returns:
true if this CardArray does not contain any cards; false otherwise.

get

public CardArray get(Suit suit)
Returns a CardArray containing the Cards in this CardArray which are of the given Suit.
Parameters:
suit - The Suit for which to search this CardArray.
Returns:
A new CardArray containing all the cards (if any) of the given Suit in this CardArray.

getCount

public int getCount(Suit suit)
Returns the number of cards in this CardArray which are of the given Suit.
Parameters:
suit - A Suit. Must not be null.
Returns:
The number of cards in this CardArray which are of the given Suit.

remove

public CardArray remove(Card card)
Removes at most one instance (the first) of the given Card from this CardArray.
Parameters:
card - the Card to be removed. If null, this method will have no effect.
Returns:
This CardArray (for convenience); the CardArray is not copied.

remove

public CardArray remove(CardArray array)
Removes all of the Cards in the given CardArray from this CardArray. Does not remove duplicates unless they are also in the argument; for example, if this CardArray contains two instances equals to Card.TWO_CLUBS, and the argument CardArray contains one, only the first instance equal to Card.TWO_CLUBS will be removed from this CardArray
Parameters:
array - A CardArray containing the Cards to be removed from this CardArray. Must not be null.
Returns:
This CardArray (for convenience); the CardArray is not copied.

add

public CardArray add(Card card)
Appends the given Card to the end of this CardArray.
Parameters:
card - The card to add to this CardArray. If null, this method will have no effect.
Returns:
This CardArray (for convenience); the CardArray is not copied.

add

public CardArray add(CardArray array)
Appends the Cards (if any) in the given CardArray to the end of this CardArray.
Parameters:
array - A CardArray containing the Cards to add to this CardArray. Must not be null.
Returns:
This CardArray (for convenience); the CardArray is not copied.

get

public Card get(int index)
Returns the Card at the given index in this CardArray.
Parameters:
index - the index of the Card to return. Indices are zero-based; i.e., an argument of 0 will return the first Card in the array. Must be not be negative. Must be less than the length of this CardArray, as returned by getLength.
Returns:
The Card at index in this CardArray.

contains

public boolean contains(Card card)
Returns whether this CardArray contains the given Card.
Parameters:
card - The card for which to search this CardArray. If null, this method will always return false.
Returns:
true if this CardArray contains at least one Card equal to card; false otherwise.

containsAll

public boolean containsAll(CardArray array)
Returns whether this CardArray contains all of the Cards in the given CardArray. This CardArray must contain at least as many instances of every Card as the argument CardArray in order to return true. For example, if the argument CardArray contains two Cards equal to Card.TWO_CLUBS, this CardArray must also contain two cards equal to Card.TWO_CLUBS.
Parameters:
array - The CardArray which may be contained within this CardArray.
Returns:
true if this CardArray contains at least as many copies of each Card as array; false otherwise.

containsOne

public boolean containsOne(CardArray array)
Returns whether this CardArray contains at least one Card which is also contained in the given CardArray.
Parameters:
array - The CardArray containing the Cards for which to search this CardArray.
Returns:
true if this CardArray contains one of the Cards contained in array.

get

public Card[] get()
Returns an array containing the Cards in this CardArray.
Returns:
An array containing the Cards in this CardArray, in the same order in which they are contained.

copy

public CardArray copy()
Returns a copy of this CardArray. This may be useful in situations when it is undesirable to allow a CardArray to be mutated.
Returns:
A duplicate of this CardArray.

sort

public CardArray sort(Sort.Order order)
Sorts the Cards in this CardArray into the given Sort.Order. The Cards are sorted in place; this method mutates this CardArray.
Parameters:
order - The order into which to sort the Cards. It may be convenient to use an subclass of Card.Order as the argument.
Returns:
This CardArray (for convenience); the CardArray is not copied.

shuffle

public CardArray shuffle()
Shuffles the Cards in this CardArray into random order. The Cards are sorted in place; this method mutates this CardArray.
Returns:
This CardArray (for convenience); the CardArray is not copied.

intersection

public static CardArray intersection(CardArray[] arrays)
Returns a CardArray containing all of the Cards that are found in all the argument CardArrays. The returned CardArray will contain as many copies of each Card as are found in each component CardArray.
Parameters:
arrays - A CardArray[]. Must not be null. Must not be zero-length.
Returns:
A CardArray containing the subset of Cards which can be found in all of the argument CardArrays. May contain duplicates if all of the CardArrays in arrays also contain duplicates of the same Card.