Struct poker::Card

pub struct Card { /* fields omitted */ }

A single playing card.

Some things to note:

• There are multiple ways to create singular and multiple cards besides Card::new
• When printed in Display mode, cards are printed to look like physical cards.
• Joker cards are not supported.

Example

You can create a card using the verbose Card::new constructor. This constructor qualifies as a const fn:

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

const ACE_OF_SPADES: Card = Card::new(Rank::Ace, Suit::Spades);

// `to_string()` converts a value to its `Display` form
assert_eq!(ACE_OF_SPADES.to_string(), "[ A♠ ]");

Implementations

impl Card

pub const fn new(rank: Rank, suit: Suit) -> Self

Create a new, singular Card given a Rank and a Suit variant. This constructor is verbose, but explicit. It is not often that you need to construct a single Card, but other functions for conveniently creating Cards rely on this one.

Example

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

let three_of_clubs = Card::new(Rank::Three, Suit::Clubs);
let card_display = three_of_clubs.to_string();
assert_eq!(card_display, "[ 3♣ ]");
println!("Is this your card? {}", card_display);

pub fn try_from_chars(
    rank_char: char,
    suit_char: char
) -> Result<Self, ParseCardError>

Try to create a single Card using char types instead of Rank and Suit enumeration types.

Errors

This function will fail with a ParseCardError if rank_char is anything other than one of ‘23456789TJQKA’, and suit_char is anything other than one of ‘chsd’. This is case-sensitive!

Example

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

let card_one = Card::new(Rank::Eight, Suit::Diamonds);
let card_two = Card::try_from_chars('8', 'd').expect("invalid rank or suit character");
assert_eq!(card_one, card_two);

pub const fn rank(self) -> Rank

Obtain this Card’s rank, which is one of clubs, hearts, diamonds, or spades.

Example

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

let some_card = Card::new(Rank::Queen, Suit::Hearts);
assert_eq!(some_card.rank(), Rank::Queen);

pub const fn suit(self) -> Suit

Obtain this Card’s suit, which is one of two, three, four, five, six, seven, eight, nine, ten, jack, queen, king, or ace.

Example

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

let some_card = Card::new(Rank::King, Suit::Diamonds);
assert_eq!(some_card.suit(), Suit::Diamonds);

pub const fn unique_integer(self) -> i32

Obtain this Card’s unique integer encoding, which distinguishes it from other cards. See the module level documentation for more about what this number encodes.

Example

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

const ACE_OF_SPADES: Card = Card::new(Rank::Ace, Suit::Spades);
assert_eq!(
    ACE_OF_SPADES.unique_integer(),
    0b0010000_00000000_00011100_00101001
);

pub fn rank_suit_string(self) -> String

Obtain a two-character String representation of this Card. This will be in the same format that other Card-producing parsing functions accept.

Example

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

let card_one = Card::new(Rank::Seven, Suit::Clubs);
let card_one_string = card_one.rank_suit_string();
assert_eq!(card_one_string, "7c");
let card_two = card_one_string.parse().expect("couldn't parse string");
assert_eq!(card_one, card_two);

pub fn generate_deck() -> impl Iterator<Item = Self>

Generate an iterator that will yield every card in a standard 52-card deck once. The order in which the cards are yielded is not random.

Example

use std::collections::HashSet;

use poker::Card;

let deck: Vec<_> = Card::generate_deck().collect();
assert_eq!(deck.len(), 52);
let mut unique_cards = HashSet::new();
for card in deck {
    // `insert()` returns false if the item is already present
    assert!(unique_cards.insert(card));
}

pub fn generate_shuffled_deck() -> Box<[Self]>

Like Card::generate_deck, but generate a shuffled deck using rand and returned a boxed slice of Cards.

pub fn parse_to_vec<S, T>(strings: S) -> Result<Vec<Self>, ParseCardError> where
    S: IntoIterator<Item = T>,
    T: AsRef<str>, 

👎 Deprecated since 0.2.0:

please use Card::parse_to_iter().try_collect::<Vec<_>>() instead. This will disappear soon.

Attempt to parse a Vec of Cards from an Iterator that yields items which are AsRef<str>; String or &str work fine!

Errors

This function will fail with a ParseCardError if one of the strings encountered is not:

• exactly two characters in length
• contains one of ‘23456789TJQKA’ followed by one of ‘chsd’. This is case-sensitive!

One invalid string is enough to make the entire function fail, and the implementation is short-circuiting. This means that the function will return as soon as an error is encountered.

Example

use poker::{Card, Rank, Suit};
let card_strings = ["Td", "Qc"];
let parsed_cards = Card::parse_to_vec(&card_strings).expect("couldn't parse strings");
assert_eq!(
    parsed_cards,
    [
        Card::new(Rank::Ten, Suit::Diamonds),
        Card::new(Rank::Queen, Suit::Clubs)
    ]
);

pub fn parse_to_iter<S, T>(
    strings: S
) -> ParseToIter<impl Iterator<Item = Result<Self, ParseCardError>>> where
    S: IntoIterator<Item = T>,
    T: AsRef<str>, 

From an iterator that yields strings, return a new Iterator that yields Result<Card, ParseCardError>. Similar to Card::parse_to_vec, but does not allocate a vector by default. The iterator adaoptor returned by this associated function has a special method try_collect, which is a shortcut over using collect::<Result<_, _>, _>(). This was inspired by the itertools crate.

Errors

The returned iterator will yield a ParseCardError if one of the strings encountered is not:

• exactly two characters in length
• contains one of ‘23456789TJQKA’ followed by one of ‘chsd’. This is case-sensitive!

This implementation is not short-circuiting and you will be responsible for dealing with the Results.

Example

use poker::{Card, Rank, Suit};
let cards = Card::parse_to_iter("As Ad".split_whitespace())
    .try_collect::<Vec<_>>()
    .expect("couldn't parse cards");
assert_eq!(
    cards,
    [
        Card::new(Rank::Ace, Suit::Spades),
        Card::new(Rank::Ace, Suit::Diamonds)
    ]
);

Trait Implementations

impl Clone for Card

fn clone(&self) -> Card

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Card

impl Debug for Card

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Card

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Card

impl FromStr for Card

type Err = ParseCardError

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Card

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for Card

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Card> for Card

fn eq(&self, other: &Card) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Card) -> bool

This method tests for !=.

impl PartialOrd<Card> for Card

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralEq for Card

impl StructuralPartialEq for Card