Macro poker::cards

macro_rules! cards {
    ($($rank:ident, $suit:ident);+ $(;)?) => { ... };
    ($($rank:ident of $suit:ident),+ $(,)?) => { ... };
    ($card_string:expr, $($card_strings:expr),+ $(,)?) => { ... };
    ($card_strings_together:expr) => { ... };
}

A utility macro for creating multiple cards.

Examples

You can specify multiple cards by entering a comma-separated pair of capitalized rank and suit, and with each pair being separated by a semicolon. The reason for the zapitalized names is because the macro inlines these as enum variants of Rank and Suit. This is const-friendly and results in an array type.

use poker::{cards, Card, Rank, Suit};

const KING_AND_QUEEN: [Card; 2] = cards!(
    King, Hearts;
    Queen, Hearts; // trailing semicolon supported
);
assert_eq!(
    KING_AND_QUEEN,
    [
        Card::new(Rank::King, Suit::Hearts),
        Card::new(Rank::Queen, Suit::Hearts)
    ]
);

Secondly, you can specify multiple cards by separating rank and suit with “of” and then separating each card with a comma. This may be more readable. As in the previous example, this is const-friendly and returns an array.

use poker::{cards, Card, Rank, Suit};

const KING_AND_QUEEN: [Card; 2] = cards!(
    King of Hearts,
    Queen of Hearts, // trailing comma supported
);
assert_eq!(
    KING_AND_QUEEN,
    [
        Card::new(Rank::King, Suit::Hearts),
        Card::new(Rank::Queen, Suit::Hearts)
    ]
);

As a third option, you can pass in a comma separated list of strings representing cards, where each string is parsed individually. This returns an iterator that will parse each string, yielding Ok(Card) on success, and Err(ParseCardError) on failure. This macro calls Card::parse_to_iter internally, so you can use try_collect on the iterator.

use poker::{cards, Card, Rank, Suit};

// Collect into a `Vec<Card>` by using `collect::<Result<_, _>>()` on an iterator that
// yields `Result` types.
let king_and_queen: Vec<_> = cards!("Kh", "Qh")
    .try_collect()
    .expect("couldn't parse cards");

assert_eq!(
    king_and_queen,
    [
        Card::new(Rank::King, Suit::Hearts),
        Card::new(Rank::Queen, Suit::Hearts)
    ]
);

Finally, you can pass in a single string expression of cards, separated by whitespace. This also returns an iterator over each card expression, yielding a Result. You can also call try_collect in this case.

use poker::{cards, Card, Rank, Suit};

let king_and_queen: Vec<_> = cards!("Kh Qh").try_collect().expect("couldn't parse cards");

assert_eq!(
    king_and_queen,
    [
        Card::new(Rank::King, Suit::Hearts),
        Card::new(Rank::Queen, Suit::Hearts)
    ]
);