Struct pgn_filter::games::Games

pub struct Games { /* fields omitted */ }

This struct is used to hold a collection of games, providing methods to load, search and save the game collection.

Users can create a new collection in two ways.

1. by reading directly from a pgn file:

let games = pgn_filter::Games::from_file("favourite-games.pgn").unwrap();

2. by creating an instance of Games and adding games from PGN files to it:

let mut games = pgn_filter::Games::new();
games.add_games("favourite-games.pgn").unwrap();

The main purpose of this library is to filter games based on some piece combination: this is done using the self::search() method.

Once a selection has been made, the new collection can be saved back out as a PGN file using the self::to_file() method.

The collection provides a self::iter() method, for processing each self::Game in turn.

Implementations

impl Games

pub fn new() -> Games

Creates an empty instance of games.

pub fn from_file(filename: &str) -> Result<Games>

Creates a collection of games from a PGN file.

Example

Read a file containing your favourite games:

let favs = pgn_filter::Games::from_file("favourite-games.pgn").unwrap();

Error

An error is returned if there is a problem in reading the PGN file.

pub fn add_games(&mut self, filename: &str) -> Result<()>

Adds games to the current collection from a PGN file.

Example

Read and combine two files containing your favourite games:

let mut favs = pgn_filter::Games::from_file("favourite-games.pgn").unwrap();
favs.add_games("more-favourites.pgn").unwrap();

Error

An error is returned if there is a problem in reading the PGN file.

pub fn iter(&self) -> Iter<'_, Game>

Provides access to an iterator over the stored games.

Example

Counting the games in a collection:

let favs = pgn_filter::Games::from_file("favourite-games.pgn").unwrap();
println!("Read {} games", favs.iter().count());

pub fn search(&self, filter: &BoardFilter) -> Games

Returns a new collection of games for those from the current collection which satisfy the given filter.

Example

The following code constructs a filter for 5-4 rook endings, loads in a (user-supplied!) pgn file, and extracts the rook endings as a new Games collection.

let filter = pgn_filter::Board::must_have()
                            .exactly(1, "R")
                            .exactly(1, "r")
                            .exactly(5, "P")
                            .exactly(4, "p");
let fischer = pgn_filter::Games::from_file("fischer.pgn").unwrap();
let rook_endings = fischer.search(&filter);

Panics

Panics if an invalid move occurs in any of the games.

pub fn to_file(&self, filename: &str) -> Result<()>

Saves the game collection in PGN format to the given filename.

(Note that the order of the header is not preserved, apart from Event/Site/Date/Round/White/Black/Result, which always appear first.)

Error

An error is returned if there was some problem in writing to the file.