ks.common.model
Class Stack

java.lang.Object
  ks.common.model.Element
      ks.common.model.Stack

Direct Known Subclasses:

BuildablePile, Column, Deck, Pile

public class Stack

extends Element

Models a stack of cards.

A stack of cards is a linear sequence of cards with a bottom (position 0) and a top card (position n-1 where n is the number of cards in the stack). Each card maintains its own state (i.e., its value, whether it is face up, whether it is selected).

Cards can be added to the top of the stack with the add (Card c) or the push (Stack s) method. If a Stack of cards is pushed onto the top of the stack, the bottom-most card of the stack s is added to the top of the target stack. Any state changing operation in the stack (add, get, push, getSelected, select) resets the selected status of all cards in the stack.

The Card get() method removes and returns the top card in the stack.

The boolean select() method selects just the top card in the stack. The boolean select(int n) method selects the top n cards, if available. The selected state of the desired cards is altered.

The Stack getSelected() method removes and returns a stack of cards, s, from the top of the stack such that all cards in s are selected, if any are selected.

Stack has some basic helper methods that may prove useful, such as alternatingColors, ascending, descending, sameColor, sameRank, sameSuit. The methods rank() and suit() return the rank and suit (respectively) of the topmost card in the Stack, if one exists; if not, then Integer.MAX_VALUE is returned by default.

Creation date: (9/30/01 9:45:50 PM)

Constructor Summary

Stack()
Construct an empty stack with auto-generated name.

Stack(java.lang.String name)
Create an empty Stack with the given name.

Method Summary

void	add(Card c) Add a card into the stack.
boolean	alternatingColors() Determines whether Cards in the Stack are all alternating in color.
boolean	alternatingColors(int start, int end) Determines whether Cards in the Stack are all alternating in color.
boolean	ascending() Determines whether Cards in the Stack are all ascending in rank order.
boolean	ascending(int start, int end) Determines whether Cards in the Stack are all ascending in rank order.
int	count() Returns the number of Cards in the Stack.
boolean	descending() Determines whether Cards in the Stack are all descending in rank order.
boolean	descending(int start, int end) Determines whether Cards in the Stack are all descending in rank order.
boolean	deselect() Reset all card selections.
boolean	empty() Determines whether the Stack is empty.
Card	get() Remove top card from the pile and return it to the callee (or return null if empty).
int	getNumSelectedCards() Returns the number of Cards that are selected from the stack.
Stack	getSelected() Return Stack of the selected cards.
Card	peek() Peek and return a copy of the top-most card (or null if empty).
Card	peek(int idx) Peek and return a copy of the card identified by idx in the stack.
void	push(Stack s) Push Stack onto existing stack; the stack parameter object is unchanged.
int	rank() Returns the rank of the top card.
void	removeAll() Remove All cards from the stack.
boolean	sameColor() Determines whether Cards in the Stack are all of the same color.
boolean	sameColor(int start, int end) Determines whether Cards in the Stack are all of the same color.
boolean	sameRank() Determines whether Cards in the Stack are all of the same rank.
boolean	sameRank(int start, int end) Determines whether Cards in the Stack are all of the same rank.
boolean	sameSuit() Determines whether Cards in the Stack are all of the same suit.
boolean	sameSuit(int start, int end) Determines whether Cards in the Stack are all of the same suit.
boolean	select() Select the top-most card in the Stack.
boolean	select(int newNumSelectedCards) Select the top n cards in the Stack, where n is a number from 1 - count().
int	suit() Return the suit of the topmost card in the Stack.
java.lang.String	toString() Return String representation of Stack

Methods inherited from class ks.common.model.Element

getListener, getName, setListener, setName

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Stack

public Stack()

Construct an empty stack with auto-generated name.

Stack

public Stack(java.lang.String name)

Create an empty Stack with the given name.

Parameters:

name - the name of this Stack model element.

Method Detail

add

public void add(Card c)

Add a card into the stack.

Generates modelChanged action if c is non-null

Parameters:

c - ks.common.model.Card

alternatingColors

public boolean alternatingColors()

Determines whether Cards in the Stack are all alternating in color.

Returns true if the stack is empty.

Returns:

boolean

alternatingColors

public boolean alternatingColors(int start,
                                 int end)

Determines whether Cards in the Stack are all alternating in color.

Throws exception if Stack is empty.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

ascending

public boolean ascending()

Determines whether Cards in the Stack are all ascending in rank order.

Returns true if the stack is empty.

Returns:

boolean

ascending

public boolean ascending(int start,
                         int end)

Determines whether Cards in the Stack are all ascending in rank order.

Throws exception if Stack is empty.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

count

public int count()

Returns the number of Cards in the Stack.

Returns:

int

descending

public boolean descending()

Determines whether Cards in the Stack are all descending in rank order.

Returns true if the stack is empty.

Returns:

boolean

descending

public boolean descending(int start,
                          int end)

Determines whether Cards in the Stack are all descending in rank order.

Throws Exception if the stack is empty.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

deselect

public boolean deselect()

Reset all card selections.

Equivalent to select (0).

Generates modelChanged action.

Returns:

boolean

Since:

v1.6.12

empty

public boolean empty()

Determines whether the Stack is empty.

Returns:

boolean

get

public Card get()

Remove top card from the pile and return it to the callee (or return null if empty).

Generates modelChanged action only if stack is non-empty.

Returns:

ks.common.model.Card

getNumSelectedCards

public int getNumSelectedCards()

Returns the number of Cards that are selected from the stack.

Returns:

int

getSelected

public Stack getSelected()

Return Stack of the selected cards.

The cards in the Stack returned by this function are all de-selected.

Generates modelChanged action only if there were some selected cards.

Returns:

ks.common.model.Stack

peek

public Card peek()

Peek and return a copy of the top-most card (or null if empty).

Returns:

ks.common.model.Card

peek

public Card peek(int idx)

Peek and return a copy of the card identified by idx in the stack. Note that:
peek() == peek (count() - 1)

Parameters:

idx - int (a number between 0 and numCards-1)

Returns:

ks.common.model.Card

push

public void push(Stack s)

Push Stack onto existing stack; the stack parameter object is unchanged.

Generates modelChanged action only if Stack s is non-empty.

Parameters:

s - ks.common.model.Stack

rank

public int rank()

Returns the rank of the top card. If no card, then returns MAX_VALUE

Returns:

int

Since:

V1.5.1 returns MAX_VALUE on error, V2.0 throws IllegalArgumentException on empty stack.

removeAll

public void removeAll()

Remove All cards from the stack.

Generates modelChanged action only if stack had cards.

sameColor

public boolean sameColor()

Determines whether Cards in the Stack are all of the same color.

Note that an empty stack returns true as the degenerate case.

Returns:

boolean

sameColor

public boolean sameColor(int start,
                         int end)

Determines whether Cards in the Stack are all of the same color.

Throws an exception on an empty stack.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

sameRank

public boolean sameRank()

Determines whether Cards in the Stack are all of the same rank. Note that an empty stack returns true as the degenerate case.

Returns:

boolean

sameRank

public boolean sameRank(int start,
                        int end)

Determines whether Cards in the Stack are all of the same rank.

Throws an exception on an empty stack.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

sameSuit

public boolean sameSuit()

Determines whether Cards in the Stack are all of the same suit. Note that an empty stack returns true as the degenerate case. Creation date: (9/30/01 10:16:30 PM)

Returns:

boolean

sameSuit

public boolean sameSuit(int start,
                        int end)

Determines whether Cards in the Stack are all of the same suit.

Throws an exception on an empty stack.

Parameters:

start - the start of the range (zero as first card in Stack)

end - the end of the range (not included in the check, and no greater than count())

Returns:

boolean

Since:

V2.0 as helper method that can be exposed

select

public boolean select()

Select the top-most card in the Stack.

Generates modelChanged action if Stack is non-empty.

Returns:

boolean

select

public boolean select(int newNumSelectedCards)

Select the top n cards in the Stack, where n is a number from 1 - count().

Generates modelChanged action (because some games might wish to show selected cards in a different light than non-selected cards).

Parameters:

newNumSelectedCards - int

Returns:

boolean false if not enough cards in the stack to be selected.

Since:

V1.5.1 (was previously called setNumSelectedCards(int))

suit

public int suit()

Return the suit of the topmost card in the Stack. If no card, then returns MAX_VALUE

Returns:

int

Since:

V1.5.1 returns MAX_VALUE on error, V2.0 throws IllegalArgumentException if no cards in stack.

toString

public java.lang.String toString()

Return String representation of Stack

Overrides:

toString in class Element

Returns:

String

Since:

V1.5.1