Implemented card_stack_push(). Renamed card_stack_clear() to card_stack_replace() and card_stack_upper_card() to card_stack_top(). Added documentation.

1 files changed, 35 insertions, 5 deletions

diff --git a/src/card_stack.c b/src/card_stack.c
index 13b14dd..f3bd217 100644
--- a/src/card_stack.c
+++ b/src/card_stack.c
@@ -2,6 +2,10 @@
 #include <assert.h>
 #include <stdlib.h>
 
+/**
+ * Calculates the points of a card stack. This will be the sum of the points of all cards contained in the card stack.
+ * @param[in] cs The card stack fir which the points will be calculated
+*/
 uint32_t card_stack_get_points(const card_stack_t *cs)
 {
 	assert(cs != NULL);
@@ -17,11 +21,15 @@ uint32_t card_stack_get_points(const card_stack_t *cs)
 	return points;
 }
 
-const card card_stack_upper_card(const card_stack_t *cs)
+/**
+ * Determines the uppermost card on a card stack. The card will not be removed from the stack.
+ * @param[in] cs The card stack from which the uppermost card will be retrieved
+*/
+const card card_stack_top(const card_stack_t *cs)
 {
 	assert(cs != NULL);
 
-	for(int i=0; i<MAX_CARD_STACK_SIZE; i++)
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
 	{
 		card cur = cs->cards[MAX_CARD_STACK_SIZE-1-i];
 		if(cur != 0)
@@ -31,13 +39,35 @@ const card card_stack_upper_card(const card_stack_t *cs)
 	return 0;
 }
 
-void card_stack_clear(card_stack_t *cs, const card new_card)
+/**
+ * Places a card on top of a card stack.
+ * @param[in] cs The card stack to place the card on
+ * @param[in] c The card to place
+*/
+void card_stack_push(card_stack_t *cs, const card c)
 {
 	assert(cs != NULL);
 
-	for(int i=0; i<MAX_CARD_STACK_SIZE; i++)
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
+	{
+		if(cs->cards[i] != 0)
+			continue;
+		cs->cards[i] = c;
+		break;
+	}
+}
+
+/**
+ * Replaces a card stack with a single card. All cards within the card stack will be removed adn the first card will be set to a given card.
+ * @param[in] cs The card stack to replace
+ * @param[in] new_card The new first card
+*/
+void card_stack_replace(card_stack_t *cs, const card new_card)
+{
+	assert(cs != NULL);
+
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
 		cs->cards[i] = 0;
 
 	cs->cards[0] = new_card;
 }
-