4.2 The players and the cards

Let’s demonstrate how to manipulate players and cards.

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif /* HAVE_CONFIG_H */

#include <tarot.h>
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include <string.h>

#ifndef LOCALEDIR
#define LOCALEDIR "/usr/share/locale"
#endif /* NOT LOCALEDIR */

int
main ()
{
  TarotCard card;
  TarotNumber number;
  TarotSuit suit;
  char *name;
  char *end;
  static const char *ks = "KS";
  if (tarot_init (LOCALEDIR) != 0)
    {
      fprintf (stderr, "Error: could not initialize libtarot.\n");
      return EXIT_FAILURE;
    }
  if (tarot_of (TAROT_KING, TAROT_SPADES, &card) != 0)
    {
      fprintf (stderr, "Computing the king of spades failed.\n");
      return EXIT_FAILURE;
    }
  if (tarot_decompose (card, &number, &suit) != 0)
    {
      fprintf (stderr, "Could not decompose the king of spades.\n");
      return EXIT_FAILURE;
    }
  assert (number == TAROT_KING && suit == TAROT_SPADES);
  if (tarot_decompose (TAROT_EXCUSE, &number, &suit) == 0)
    {
      fprintf (stderr, "Impossible: decomposing the excuse is an error.\n");
      return EXIT_FAILURE;
    }
  name = tarot_card_to_string_alloc (card);
  assert (strcmp (name, "KS") == 0);
  free (name);
  card = tarot_card_parse (ks, &end);
  if ((const char *) end == ks)
    {
      fprintf (stderr, "Could not parse '%s' at all.\n", ks);
    }
  else if (*end == '\0')
    {
      printf ("%s parsed successfully\n", ks);
    }
  else
    {
      fprintf (stderr, "Trailing garbage: '%s'\n", end);
    }
  tarot_quit ();
  return EXIT_SUCCESS;
}

typedef unsigned int: TarotCard

Each card is represented as a number. The values range to 0 inclusive to 78 exclusive. The constant ‘TAROT_EXCUSE’ refers to the excuse.

typedef unsigned int: TarotNumber

The number of a card, between 1 and ‘TAROT_KING’ or 21 (if the suit is trumps). The constants ‘TAROT_ACE’, ‘TAROT_JACK’, ‘TAROT_KNIGHT’, ‘TAROT_QUEEN’ and ‘TAROT_KING’ provide the ace and the face card numbers.

enum: TarotSuit

Enumeration of all the possible suits:

• ‘TAROT_HEARTS’;
• ‘TAROT_CLUBS’;
• ‘TAROT_DIAMONDS’;
• ‘TAROT_SPADES’;
• ‘TAROT_TRUMPS’;

typedef unsigned int: TarotPlayer

The player ID of someone is simply the number of players that play before her.

Function: int tarot_of (TarotNumber number, TarotSuit suit, TarotCard *card)

Function: int tarot_decompose (TarotCard card, TarotNumber *number, TarotSuit *suit)

Try to compose or decompose card as the number of suit. If this is not possible, return an error code. Otherwise, return 0.

Function: TarotCard tarot_string_to_card (const char *text)

Function: TarotCard tarot_string_to_card_c (const char *text)

Function: TarotPlayer tarot_string_to_player (const char *text)

Function: TarotPlayer tarot_string_to_player_c (const char *text)

Convert text to a card, or a player. The functions with the ‘_c’ suffix ignore the current locale, so they are suitable for serialization, but not for interaction with the user. The value (-1) converted to an unsigned int is returned, if the conversion failed.

Function: TarotCard tarot_card_parse (const char *text, char **end)

Function: TarotCard tarot_card_parse_c (const char *text, char **end)

Function: TarotPlayer tarot_player_parse (const char *text, char **end)

Function: TarotPlayer tarot_player_parse_c (const char *text, char **end)

This is similar to the ‘tarot_string_to_*’ functions, except now this is a proper parsing function. The output parameter end is set to the first byte that is not part of the player or card representation. So if it points directly to text, then the parsing failed entirely. If it does not point to an empty string, then this is the suffix that could not be parsed as part of the card or player.

Function: size_t tarot_card_to_string (TarotCard c, size_t max, char *dest)

Function: size_t tarot_card_to_string_c (TarotCard c, size_t max, char *dest)

Function: size_t tarot_player_to_string (TarotPlayer p, size_t max, char *dest)

Function: size_t tarot_player_to_string_c (TarotPlayer p, size_t max, char *dest)

Function: char * tarot_card_to_string_alloc (TarotCard c)

Function: char * tarot_card_to_string_c_alloc (TarotCard c)

Function: char * tarot_player_to_string_alloc (TarotPlayer p)

Function: char * tarot_player_to_string_c_alloc (TarotPlayer p)

Get the string representation of card c or player p. The functions without an ‘_alloc’ suffix write the representation to dest (up to max bytes), including the final ‘NUL’ character if max is not 0, and return the number of bytes needed (except the final ‘NUL’). So you should call this function again with at least one more byte than the return value in dest / max. The functions with the ‘_alloc’ suffix allocate the string representation when returning it. So you should use ‘free()’ on the return value.

As with the other string related functions, the ‘_c’ part indicates that the locale is ignored.