### Build and Use the 'test' CLI Program

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Demonstrates end-to-end library usage via the command line. Accepts positional arguments for schedule parameters and an optional --rng flag for seeding.

```bash
# Build the library and test binary
make

# Usage
./test <num_divisions> <num_teams_per_division> \
       <num_games_vs_division> <num_games_vs_non_division> [--rng=<seed>|TIME]

# Example: 2 divisions, 5 teams each, 4 div games, 2 non-div games, fixed seed
./test 2 5 4 2 --rng=42

# Example: 1 division, 6 teams, 3 games each, reproducible seed
./test 1 6 3 0 --rng=100

# Example: time-based (random) seed (default)
./test 2 4 2 1

# Capture schedule to file, stats to separate file
./test 2 6 4 2 --rng=99 > schedule.txt 2> stats.txt

# View just stats
./test 2 4 2 2 --rng=0 2>&1 >/dev/null
```

--------------------------------

### SsSchedule::print(file)

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Outputs the entire schedule to a specified file pointer in a human-readable format, including division headers and daily matchups.

```APIDOC
## `SsSchedule::print(file)` — Human-Readable Schedule Output

Prints the full schedule to any `FILE*` in a structured format. Teams are listed by division header (`DIV A`, `DIV B`), then each game day is printed with matchups in the form `<away> at <home>`, using `BYE` where applicable. Team numbers are printed one-based.

### Parameters
#### Path Parameters
- **file** (FILE*) - Required - A pointer to the file stream where the schedule will be printed.

### Example Usage
```cpp
#include "schedule.hpp"
#include <stdio.h>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 1;
    params.num_teams_per_division = 4;
    params.num_games_vs_division  = 2;
    params.num_games_vs_non_division = 0;
    params.seed                   = 0;

    SsSchedule schedule(params);

    // Print to stdout
    schedule.print(stdout);

    // Or print to a file
    FILE *f = fopen("schedule.txt", "w");
    if (f) {
        schedule.print(f);
        fclose(f);
    }
    return 0;
}
```
```

--------------------------------

### Print Human-Readable Schedule to File

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Outputs the entire schedule to a FILE pointer in a structured format. Requires including <stdio.h>.

```cpp
#include "schedule.hpp"
#include <stdio.h>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 1;
    params.num_teams_per_division = 4;
    params.num_games_vs_division  = 2;
    params.num_games_vs_non_division = 0;
    params.seed                   = 0;

    SsSchedule schedule(params);

    // Print to stdout
    schedule.print(stdout);

    // Or print to a file
    FILE *f = fopen("schedule.txt", "w");
    if (f) {
        schedule.print(f);
        fclose(f);
    }
    return 0;
}
```

--------------------------------

### Configure Schedule Parameters

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Define schedule parameters including divisions, teams per division, games against division and non-division opponents, and a random seed for reproducibility. Ensure all divisions have an equal number of teams.

```cpp
#include "schedule.hpp"

ss_schedule_params_t params;
params.num_divisions          = 2;   // Two divisions (max supported)
params.num_teams_per_division = 5;   // 5 teams per division (10 total)
params.num_games_vs_division  = 4;   // Each team plays each division rival 4 times
params.num_games_vs_non_division = 2; // Each team plays each non-division rival 2 times
params.seed                   = 42;  // Reproducible schedule; use -1 for time-based seed
```

--------------------------------

### SsSchedule::get_matches(day)

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Retrieves a list of all games scheduled for a specific day. Each game entry details the away and home teams, with special handling for byes.

```APIDOC
## `SsSchedule::get_matches(day)` — Retrieve Games for a Day

Returns a `const std::vector<ss_game_t>&` containing all games scheduled for the given zero-based day index. Each `ss_game_t` has a two-element array `teams`: `teams[AWAY]` is the away team index and `teams[HOME]` is the home team index (both zero-based). A value of `BYE` (`-1`) in either slot indicates a bye.

### Parameters
#### Path Parameters
- **day** (size_t) - Required - The zero-based day index for which to retrieve games.

### Response
#### Success Response (200)
- **games** (const std::vector<ss_game_t>&) - A constant reference to a vector of `ss_game_t` objects, each representing a game.
  - **ss_game_t**
    - **teams** (int[2]) - A two-element array where `teams[AWAY]` is the away team index and `teams[HOME]` is the home team index. `BYE` (-1) indicates a bye.

### Example Usage
```cpp
#include "schedule.hpp"
#include <iostream>

// After constructing SsSchedule schedule(params) ...

for (size_t day = 0; day < schedule.num_days(); ++day) {
    const std::vector<ss_game_t> &games = schedule.get_matches(day);
    std::cout << "=== Day " << (day + 1) << " ===\n";
    for (const ss_game_t &game : games) {
        int away = game.teams[AWAY];
        int home = game.teams[HOME];

        if (away == BYE) {
            std::cout << "  BYE at " << (home + 1) << "\n";
        } else if (home == BYE) {
            std::cout << "  " << (away + 1) << " at BYE\n";
        } else {
            // Print 1-based team numbers
            std::cout << "  " << (away + 1) << " @ " << (home + 1) << "\n";
        }
    }
}
```
```

--------------------------------

### test CLI Program

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

A command-line interface program for generating schedules based on specified parameters and outputting the schedule and statistics.

```APIDOC
## `test` CLI Program — Command-Line Schedule Generator

The included `test` binary (built via `make`) demonstrates end-to-end library usage. It accepts four positional arguments and an optional `--rng` flag, generates a schedule, prints it to `stdout`, and prints stats to `stderr`.

### Usage
```bash
./test <num_divisions> <num_teams_per_division> \
       <num_games_vs_division> <num_games_vs_non_division> [--rng=<seed>|TIME]
```

### Arguments
- **num_divisions**: Number of divisions for the schedule.
- **num_teams_per_division**: Number of teams within each division.
- **num_games_vs_division**: Number of games each team plays against teams within their division.
- **num_games_vs_non_division**: Number of games each team plays against teams outside their division.
- **--rng=\<seed\>|TIME**: Optional. Specifies the random seed for schedule generation. Can be a specific integer or `TIME` for a time-based seed.

### Examples
```bash
# Build the library and test binary
make

# Example: 2 divisions, 5 teams each, 4 div games, 2 non-div games, fixed seed
./test 2 5 4 2 --rng=42

# Example: 1 division, 6 teams, 3 games each, reproducible seed
./test 1 6 3 0 --rng=100

# Example: time-based (random) seed (default)
./test 2 4 2 1

# Capture schedule to file, stats to separate file
./test 2 6 4 2 --rng=99 > schedule.txt 2> stats.txt

# View just stats
./test 2 4 2 2 --rng=0 2>&1 >/dev/null
```
```

--------------------------------

### Generate Sports Schedule

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Construct a complete sports schedule using the defined parameters. The constructor handles the round-robin algorithm, inter-division matchups, and shuffling. Catches std::runtime_error for invalid division counts.

```cpp
#include "schedule.hpp"
#include <stdexcept>
#include <iostream>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 2;
    params.num_teams_per_division = 4;
    params.num_games_vs_division  = 3;
    params.num_games_vs_non_division = 2;
    params.seed                   = 7;

    try {
        SsSchedule schedule(params);
        // Schedule is fully generated and ready to query
        std::cout << "Schedule generated: "
                  << schedule.num_days() << " days\n";
    } catch (const std::runtime_error &e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}
// Output: Schedule generated: 26 days
```

--------------------------------

### Print Schedule Statistics to File

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Generates and prints detailed schedule statistics, including crosstables and per-team game counts, to a FILE pointer. Requires including <stdio.h>.

```cpp
#include "schedule.hpp"
#include <stdio.h>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 2;
    params.num_teams_per_division = 3;
    params.num_games_vs_division  = 4;
    params.num_games_vs_non_division = 2;
    params.seed                   = 1;

    SsSchedule schedule(params);

    // Print schedule to stdout, stats to stderr (mirrors the test program)
    schedule.print(stdout);
    schedule.print_stats(stderr);
    return 0;
}
```

--------------------------------

### SsSchedule::print_stats(file)

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Generates and prints a detailed statistical analysis of the schedule to a specified file pointer, including game crosstables and team summaries.

```APIDOC
## `SsSchedule::print_stats(file)` — Schedule Statistics Output

Prints a detailed statistical breakdown to any `FILE*`. Output includes a full away-vs-home game crosstable (how many times team X visited team Y), a half-crosstable of total games per pair of opponents, and a per-team summary of total home and away games, plus the total day count.

### Parameters
#### Path Parameters
- **file** (FILE*) - Required - A pointer to the file stream where the statistics will be printed.

### Example Usage
```cpp
#include "schedule.hpp"
#include <stdio.h>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 2;
    params.num_teams_per_division = 3;
    params.num_games_vs_division  = 4;
    params.num_games_vs_non_division = 2;
    params.seed                   = 1;

    SsSchedule schedule(params);

    // Print schedule to stdout, stats to stderr (mirrors the test program)
    schedule.print(stdout);
    schedule.print_stats(stderr);
    return 0;
}
```
```

--------------------------------

### SsSchedule Constructor - Schedule Generator

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Constructs and generates the complete sports schedule immediately upon instantiation using the provided parameters. It handles the core scheduling algorithms and randomization.

```APIDOC
## SsSchedule::SsSchedule(params)

### Description
Constructs the complete schedule immediately. The constructor runs the round-robin algorithm for intra-division rounds, generates inter-division matchups, and then shuffles all days using the specified (or time-based) RNG seed. Throws `std::runtime_error` if `num_divisions > 2`.

### Method
`SsSchedule(ss_schedule_params_t params)`

### Parameters
- **params** (`ss_schedule_params_t`) - Required - Structure containing all schedule configuration parameters.

### Throws
- `std::runtime_error` - If `num_divisions` in `params` is greater than 2.

### Usage Example
```cpp
#include "schedule.hpp"
#include <stdexcept>
#include <iostream>

int main() {
    ss_schedule_params_t params;
    params.num_divisions          = 2;
    params.num_teams_per_division = 4;
    params.num_games_vs_division  = 3;
    params.num_games_vs_non_division = 2;
    params.seed                   = 7;

    try {
        SsSchedule schedule(params);
        // Schedule is fully generated and ready to query
        std::cout << "Schedule generated: "
                  << schedule.num_days() << " days\n";
    } catch (const std::runtime_error &e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}
// Output: Schedule generated: 26 days
```
```

--------------------------------

### Query Total Schedule Days

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Retrieve the total number of game days in the generated schedule. This method is useful for iterating through all days to access match information.

```cpp
SsSchedule schedule(params);

size_t total_days = schedule.num_days();
std::cout << "Total days in schedule: " << total_days << std::endl;

// Iterate over every day
for (size_t day = 0; day < schedule.num_days(); ++day) {
    std::cout << "Day " << (day + 1) << " has "
              << schedule.get_matches(day).size() << " game(s)\n";
}
```

--------------------------------

### ss_schedule_params_t - Schedule Parameters

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Defines the configuration for generating a sports schedule, including the number of divisions, teams per division, desired games against divisional and non-divisional opponents, and a random seed.

```APIDOC
## ss_schedule_params_t

### Description
This struct captures all configuration needed to define a schedule: the number of divisions (max 2), the number of teams per division (all divisions must be equal-sized), the number of games each team plays against division opponents, the number of games against non-division opponents, and a random seed (-1 means use the current time).

### Usage Example
```cpp
#include "schedule.hpp"

ss_schedule_params_t params;
params.num_divisions          = 2;   // Two divisions (max supported)
params.num_teams_per_division = 5;   // 5 teams per division (10 total)
params.num_games_vs_division  = 4;   // Each team plays each division rival 4 times
params.num_games_vs_non_division = 2; // Each team plays each non-division rival 2 times
params.seed                   = 42;  // Reproducible schedule; use -1 for time-based seed
```
```

--------------------------------

### Retrieve Games for a Specific Day

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Iterate through all scheduled games for a given day. Handles BYE values for teams.

```cpp
#include "schedule.hpp"
#include <iostream>

// After constructing SsSchedule schedule(params) ...

for (size_t day = 0; day < schedule.num_days(); ++day) {
    const std::vector<ss_game_t> &games = schedule.get_matches(day);
    std::cout << "=== Day " << (day + 1) << " ===\n";
    for (const ss_game_t &game : games) {
        int away = game.teams[AWAY];
        int home = game.teams[HOME];

        if (away == BYE) {
            std::cout << "  BYE at " << (home + 1) << "\n";
        } else if (home == BYE) {
            std::cout << "  " << (away + 1) << " at BYE\n";
        } else {
            // Print 1-based team numbers
            std::cout << "  " << (away + 1) << " @ " << (home + 1) << "\n";
        }
    }
}
```

--------------------------------

### SsSchedule::num_days() - Query Total Days

Source: https://context7.com/rggibson/sports-scheduling/llms.txt

Retrieves the total number of game days in the generated schedule. This can be used to iterate through all scheduled days.

```APIDOC
## SsSchedule::num_days()

### Description
Returns the total number of game days in the generated schedule as a `size_t`. Each day contains one or more games; teams with no game on a given day receive a bye.

### Method
`size_t num_days() const`

### Returns
- `size_t` - The total number of days in the schedule.

### Usage Example
```cpp
SsSchedule schedule(params);

size_t total_days = schedule.num_days();
std::cout << "Total days in schedule: " << total_days << std::endl;

// Iterate over every day
for (size_t day = 0; day < schedule.num_days(); ++day) {
    std::cout << "Day " << (day + 1) << " has "
              << schedule.get_matches(day).size() << " game(s)\n";
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.