Replace dh_init_deck() with deck dh_get_new_deck();

Author: andy5995

deckhandler.c

@@ -59,7 +59,7 @@ void dh_pcg_srand_auto(void) {
   pcg32_srandom_r(&rng, initstate, initseq);
 }
 
-void dh_init_deck(struct dh_deck *deck) {
+static void dh_init_deck(struct dh_deck *deck) {
   deck->top_card = 0;
 
   int card = 0;
@@ -77,10 +77,15 @@ void dh_init_deck(struct dh_deck *deck) {
 
     card++;
   }
-
   return;
 }
 
+struct dh_deck dh_get_new_deck(void) {
+  struct dh_deck deck;
+  dh_init_deck(&deck);
+  return deck;
+}
+
 struct dh_card dh_deal_top_card(struct dh_deck *deck) {
   if (deck->top_card == CARDS_IN_DECK) {
     deck->top_card = 0;

deckhandler.h

@@ -88,12 +88,25 @@ void dh_pcg_srand(uint64_t initstate, uint64_t initseq);
 void dh_pcg_srand_auto(void);
 
 /**
- * @brief Initialize a deck in a sorted order (no shuffling).
+ * @brief Create and initialize a new deck of cards.
  *
- * @param deck_dh Pointer to the deck to initialize.
+ * This function returns a new `dh_deck` struct that is initialized to a full, shuffled deck.
+ * Internally, it calls `dh_init_deck()` to perform the initialization.
+ *
+ * @return A fully initialized deck of cards.
  */
-void dh_init_deck(struct dh_deck *deck);
+struct dh_deck dh_get_new_deck(void);
 
+/**
+ * @brief Deal the top card from the deck.
+ *
+ * Deals the card currently at the top of the deck and advances the deck position.
+ * If all cards have been dealt (`top_card == CARDS_IN_DECK`), the deck wraps and begins from the
+ * top again, resetting `top_card` to 0 and printing a warning message.
+ *
+ * @param deck Pointer to the deck from which to deal a card.
+ * @return The card at the current top position of the deck.
+ */
 struct dh_card dh_deal_top_card(struct dh_deck *deck);
 
 /**

test/test_01.c

@@ -37,10 +37,7 @@ int main(int argc, char *argv[]) {
   (void)argc;
   (void)argv;
   /* declare a deck using type "struct dh_deck" (defined in deckhandler.h) */
-  struct dh_deck deck_a;
-
-  /* initialize the deck */
-  dh_init_deck(&deck_a);
+  struct dh_deck deck_a = dh_get_new_deck();
 
   int deals_num = 0;
   int deals_max = 3;
@@ -100,12 +97,12 @@ int main(int argc, char *argv[]) {
   puts("\n\n\t]=[ Create 4 decks, shuffle each one, and deal them all out ]=[\n");
   int total_decks = 4;
   struct dh_deck deck_num[total_decks];
+  for (int i = 0; i < total_decks; i++)
+    deck_num[i] = dh_get_new_deck();
 
   int which_deck;
-  for (which_deck = 0; which_deck < total_decks; which_deck++) {
-    dh_init_deck(&deck_num[which_deck]);
+  for (which_deck = 0; which_deck < total_decks; which_deck++)
     dh_shuffle_deck(&deck_num[which_deck]);
-  }
 
   /* There's no function in the library (yet) that shuffles multiple decks
    * together, but using the method below will provide a close simulation */