### Quick Start Example

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/README.md

Demonstrates basic usage of the rs-fsrs library for repeating a card and logging review results. Requires chrono for time operations.

```rust
use chrono::Utc;
use rs_fsrs::{FSRS, Card, Rating};

fn main() {
    let fsrs = FSRS::default();
    let card = Card::new();
    
    let record_log = fsrs.repeat(card, Utc::now());
    for rating in Rating::iter() {
        let item = record_log[rating].to_owned();
        println!("Card: {:?}", item.card);
        println!("Review Log: {:?}", item.review_log);
    }
}
```

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

### FSRS Configuration Guide

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/_COMPLETION_REPORT.txt

This guide details all configuration options for the FSRS library, including their default values, recommended ranges, and code examples for implementation.

```APIDOC
## Configuration Guide

### Description
Details all configuration options available for the FSRS system, including their default values, recommended usage, and code examples.

### Options
- **Total Options**: 8 configuration options.
- **Default Values**: Verified against `Cargo.toml` and source code.
- **Ranges & Recommendations**: Provided for each option.

### Usage
Refer to `configuration.md` for detailed explanations and `examples.md` for code samples related to configuration.
```

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

### Quickstart: Basic FSRS Card Scheduling

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/README.md

Demonstrates the basic usage of the FSRS scheduler to repeat a card and log the review results.

```rust
use chrono::Utc;
use rs_fsrs::{FSRS, Card, Rating};

fn main() {
    let fsrs = FSRS::default();
    let card = Card::new();

    let record_log = fsrs.repeat(card, Utc::now());
    for rating in Rating::iter() {
        let item = record_log[rating].to_owned();
        println!("{:?}", item.card);
        println!("{:?}", item.review_log);
    }
}
```

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

### Import and Initialize FSRS Scheduler

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Demonstrates how to import necessary types and initialize the FSRS scheduler with default parameters. This is the basic setup for using the library.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

fn main() {
    // Create scheduler with default parameters
    let fsrs = FSRS::default();
    
    // Create new card
    let card = Card::new();
    
    // Get current time
    let now = Utc::now();
    
    println!("Scheduler ready!");
}
```

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

### FSRS::next() Execution Example - New Card, Good Rating

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/architecture.md

Demonstrates the step-by-step calculation for `FSRS::next()` when a 'Good' rating is applied to a new card. It shows the initial state, the function calls, the state transitions, and the final resulting card state.

```rust
Initial State:
  Card { state: New, stability: 0, difficulty: 0, reps: 0, ... }
  Rating: Good

1. FSRS::next(card, now, Good)
2. BasicScheduler::new(params, card, now)
3. BasicScheduler::review(Good)
   → match State::New { new_state(Good) }
4. new_state(Good):
   a. difficulty = params.init_difficulty(Good)
      = (w[4] - e^(w[5] * 2) + 1).clamp(1.0, 10.0)
      ≈ 3.0
   
   b. stability = params.init_stability(Good)
      = w[2] = 3.1262
   
   c. scheduled_days = 5  (intermediate state → next_interval calc)
   
   d. due = now + Duration::days(5)
   
   e. state = Review (Easy from new → Review; others → Learning)
   
   f. ReviewLog = { rating: Good, elapsed_days: 0, ... }
   
   g. Return SchedulingInfo { card: {...}, review_log: {...} }

Result:
  Card {
    state: Review,
    stability: 3.1262,
    difficulty: 3.0,
    scheduled_days: 5,
    due: now + 5 days,
    ...
  }
```

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

### Get Next Card State and Review Log

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Demonstrates how to get the next scheduling information for a card after a review using the `next` method. This is useful for processing a single review event and updating the card's state and logging the review.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();
let info = fsrs.next(card, Utc::now(), Rating::Good);

println!("Next due: {:?}", info.card.due);
println!("Review recorded: {:?}", info.review_log.rating);
```

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

### Previewing Card Scheduling Results for All Ratings

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/rating.md

An example of using `Rating::iter()` within a loop to preview the scheduling results for each possible rating. This requires initializing the FSRS algorithm and a card.

```rust
use chrono::Utc;
use rs_fsrs::{FSRS, Card, Rating};

let fsrs = FSRS::default();
let card = Card::new();

let results = fsrs.repeat(card, Utc::now());

for rating in Rating::iter() {
    let info = &results[rating];
    println!("{:?}: due in {} days", rating, info.card.scheduled_days);
}

```

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

### Create FSRS Scheduler with Default Parameters

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fsrs.md

Instantiate the FSRS scheduler using its built-in default parameters. This is a convenient way to get started.

```rust
use rs_fsrs::FSRS;

let fsrs = FSRS::default();
```

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

### Create Default FSRS Parameters

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/parameters.md

Instantiate the FSRS Parameters with default values optimized for typical spaced repetition. This is useful for quick setup when custom tuning is not required.

```rust
use rs_fsrs::Parameters;

let params = Parameters::default();
assert_eq!(params.request_retention, 0.9);
assert_eq!(params.maximum_interval, 36500);
```

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

### Get Scheduler Implementation

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fsrs.md

Obtain the appropriate scheduler (Basic or Longterm) based on the card and current time. This method is useful for understanding the scheduler's internal logic for a given card.

```rust
use chrono::Utc;
use rs_fsrs::{FSRS, Card};

let fsrs = FSRS::default();
let card = Card::new();
let scheduler = fsrs.scheduler(card, Utc::now());
```

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

### Create and Print ReviewLog

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/reviewlog.md

Demonstrates how to create a ReviewLog instance with sample data and print its fields. Ensure you have the `chrono` crate for `Utc::now()`.

```rust
use rs_fsrs::{ReviewLog, Rating, State};
use chrono::Utc;

let log = ReviewLog {
    rating: Rating::Good,
    elapsed_days: 5,
    scheduled_days: 7,
    state: State::Review,
    reviewed_date: Utc::now(),
};

println!("Reviewed: {:?}", log.reviewed_date);
println!("Rating: {:?}", log.rating);
println!("Elapsed: {} days", log.elapsed_days);
```

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

### Safe HashMap Access with get() and Iteration

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Illustrates safe ways to access results from the FSRS repeat method. It shows using `get()` for optional access and iterating over all possible ratings, which are guaranteed to be present.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

fn main() {
    let fsrs = FSRS::default();
    let results = fsrs.repeat(Card::new(), Utc::now());
    
    // Safe method 1: Using get()
    match results.get(&Rating::Good) {
        Some(info) => println!("Good: {} days", info.card.scheduled_days),
        None => println!("No Good result"),  // Won't happen with repeat()
    }
    
    // Safe method 2: Iterate
    for rating in Rating::iter() {
        let info = &results[rating];  // Safe, always present
        println!("{:?}: {} days", rating, info.card.scheduled_days);
    }
    
    // Unsafe method (can panic if not present):
    // let info = &results[&Rating::Good];  // OK if present
}
```

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

### Basic rs-fsrs Usage

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/00-START-HERE.md

Demonstrates the fundamental steps to initialize the FSRS scheduler, create a card, and calculate the next review state based on a user's rating. This is useful for understanding the core workflow.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

// Create scheduler
let fsrs = FSRS::default();

// Create card
let card = Card::new();

// Get next state for a rating
let result = fsrs.next(card, Utc::now(), Rating::Good);

// Use updated card
println!("Next due: {:?}", result.card.due);
println!("Interval: {} days", result.card.scheduled_days);
```

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

### Preview All Ratings with repeat()

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Demonstrates how to use the `repeat` method to preview the SchedulingInfo for all possible ratings (Good, Easy, etc.) for a given card state. This is useful for understanding how different ratings would affect the card's next review date.

```rust
use rs_fsrs::{FSRS, Card};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();
let record_log = fsrs.repeat(card, Utc::now());

// record_log is HashMap<Rating, SchedulingInfo>
// Access results for each rating
let good_result = &record_log[&Rating::Good];
let easy_result = &record_log[&Rating::Easy];
```

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

### Default State

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/state.md

Demonstrates how to initialize a new card and shows that the default state for a card is 'New'.

```APIDOC
## Default State

When a new card is created, its state defaults to `State::New`.

### Usage Example

```rust
use rs_fsrs::{Card, State};

let card = Card::new();
assert_eq!(card.state, State::New);

// State also implements Default trait
let default_state = State::default();
assert_eq!(default_state, State::New);
```
```

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

### Initialize and Use FSRS

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/modules.md

Demonstrates how to initialize the FSRS struct and use its primary methods for repeating and scheduling card reviews.

```rust
use rs_fsrs::FSRS;

let fsrs = FSRS::default();
let results = fsrs.repeat(card, now);
let next = fsrs.next(card, now, Rating::Good);
```

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

### Create FSRS from Application Configuration

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/configuration.md

Demonstrates how to create an FSRS instance by mapping application-specific configuration values to the Parameters struct. This approach centralizes configuration management within your application.

```rust
use rs_fsrs::{FSRS, Parameters};

fn create_fsrs_from_config(config: MyConfig) -> FSRS {
    let mut params = Parameters::default();
    params.request_retention = config.retention_rate;
    params.maximum_interval = config.max_days;
    params.enable_short_term = config.use_learning_phase;
    FSRS::new(params)
}
```

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

### Getting Seed String Value with `inner_str` in Rust

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/seed.md

Demonstrates how to retrieve the underlying string representation of a Seed. For custom seeds, it returns the provided string. For default seeds, it returns a string representation of the timestamp.

```rust
use rs_fsrs::Seed;

let seed = Seed::new("test_seed");
assert_eq!(seed.inner_str(), "test_seed");

let default_seed = Seed::default();
// Returns a string representation of the timestamp
```

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

### Development Commands

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/README.md

Common commands for formatting, linting, and testing the project during development.

```sh
cargo fmt
car go clippy -- -D clippy::nursery
cargo test --release
```

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

### FSRS API Reference Overview

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/_COMPLETION_REPORT.txt

The FSRS library provides a comprehensive API reference covering every exported type and method. Each API includes its signature, parameter tables, and usage examples, ensuring developers have all the necessary information for integration.

```APIDOC
## API Reference

### Description
Provides detailed documentation for all exported types and methods within the FSRS library. This includes method signatures, parameter descriptions, and practical usage examples.

### Structure
- **Types**: Documentation for all 13 core types.
- **Methods**: Documentation for over 50 methods, including signatures and parameter details.
- **Parameters**: Reference for all 8 configuration options and their default values.
- **Examples**: Usage examples for each API method.

### Access
API details can be found via `INDEX.md` which links to `api-reference/` and `types.md`.
```

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

### Using SchedulingInfo with `next()`

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Demonstrates how to use the `next()` method of the FSRS algorithm to process a single card review and obtain SchedulingInfo. This is useful for updating card states and logging individual review events.

```APIDOC
## Method: FSRS::next()

### Description
Processes a single card review for a given rating and returns `SchedulingInfo` containing the updated card state and review log.

### Usage
```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();

// Process a single review with a specific rating (e.g., Rating::Hard)
let info: SchedulingInfo = fsrs.next(card, Utc::now(), Rating::Hard);

// Use the returned SchedulingInfo to update your database and log the review
// update_card(&info.card);
// log_review(&info.review_log);
```

### Parameters
- **card** (Card) - The current state of the card.
- **review_time** (DateTime<Utc>) - The timestamp of the review.
- **rating** (Rating) - The user's rating for the review (e.g., `Rating::Good`, `Rating::Hard`, `Rating::Easy`, `Rating::Again`).

### Returns
- **SchedulingInfo** - An object containing the updated `card` and a `review_log` entry.
```

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

### Clone and Compare ReviewLog Instances

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/reviewlog.md

Shows how to create a copy of a ReviewLog using `clone()` and compare two logs for equality using the `==` operator. This is useful for verifying data integrity or tracking changes.

```rust
use rs_fsrs::ReviewLog;

let log1 = ReviewLog { rating: Rating::Good, elapsed_days: 5, scheduled_days: 7, state: State::Review, reviewed_date: Utc::now() };
let log2 = log1.clone();

if log1 == log2 {
    println!("Same review!");
}
```

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

### Time Utilities Import

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/modules.md

Imports FractionalDays for precise time representation and chrono's Duration for time-based calculations.

```rust
use rs_fsrs::FractionalDays;
use chrono::Duration;
```

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

### Initialize FSRS Scheduler with Custom Parameters

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Shows how to configure the FSRS scheduler with custom parameters for more aggressive retention, longer maximum intervals, and reproducible results using a seed.

```rust
use rs_fsrs::{FSRS, Parameters, Seed};

fn main() {
    let mut params = Parameters::default();
    params.request_retention = 0.85;      // More aggressive
    params.maximum_interval = 1825;       // 5 years max
    params.enable_short_term = true;      // Learning phases
    params.enable_fuzz = true;            // Add randomness
    params.seed = Seed::new("my_seed");   // Reproducible
    
    let fsrs = FSRS::new(params);
}
```

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

### BasicScheduler::new

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/scheduler.md

Creates a BasicScheduler instance for a given card, algorithm parameters, and current time. This scheduler distinguishes between learning, relearning, and review states.

```APIDOC
## BasicScheduler::new

### Description
Creates a BasicScheduler for a card.

### Method
Constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use rs_fsrs::{BasicScheduler, Card, Parameters};
use chrono::Utc;

let params = Parameters::default();
let card = Card::new();
let scheduler = BasicScheduler::new(params, card, Utc::now());
```

### Response
#### Success Response
- **Self** (BasicScheduler) - A new BasicScheduler instance.

#### Response Example
None
```

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

### Enabling Fuzzing and Seeding for Testing

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/INDEX.md

Shows how to enable fuzz testing and set a specific seed for reproducible test runs. Requires importing Seed.

```rust
params.enable_fuzz = true;
params.seed = Seed::new("test_seed");
```

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

### Create BasicScheduler Instance

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/scheduler.md

Instantiate a BasicScheduler with default parameters, a new card, and the current time. This is used for cards following distinct learning phases.

```rust
use rs_fsrs::{BasicScheduler, Card, Parameters};
use chrono::Utc;

let params = Parameters::default();
let card = Card::new();
let scheduler = BasicScheduler::new(params, card, Utc::now());
```

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

### JSON Serialization with Serde

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Demonstrates how to serialize and deserialize Card and Parameters structs to and from JSON using the 'serde_json' crate. Requires the 'serde' feature to be enabled.

```rust
#[cfg(feature = "serde")]
fn example_serde() {
    use rs_fsrs::{Card, Rating, Parameters};
    use serde_json;
    
    let card = Card::new();
    let json = serde_json::to_string(&card).unwrap();
    println!("Card JSON: {}", json);
    
    let restored: Card = serde_json::from_str(&json).unwrap();
    
    let params = Parameters::default();
    let params_json = serde_json::to_string(&params).unwrap();
    let restored_params: Parameters = serde_json::from_str(&params_json).unwrap();
}
```

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

### Default Preview Implementation

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/scheduler.md

Provides a default implementation for the `preview` method, which iterates through all ratings and collects scheduling information.

```rust
fn preview(&mut self) -> RecordLog {
    Rating::iter()
        .map(|&rating| (rating, self.review(rating)))
        .collect()
}
```

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

### Initialize FSRS Scheduler

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/configuration.md

Demonstrates how to initialize the FSRS scheduler using default parameters or custom configurations. Customization involves modifying fields like request_retention, maximum_interval, and enabling features like fuzz and short-term learning.

```rust
use rs_fsrs::{FSRS, Parameters, Seed};

// Use defaults
let fsrs = FSRS::default();

// Custom configuration
let mut params = Parameters::default();
params.request_retention = 0.85;  // More aggressive retention
params.maximum_interval = 20000;  // Shorter max interval
params.enable_fuzz = true;
params.enable_short_term = true;

let fsrs = FSRS::new(params);
```

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

### Seed Variants and Constructors

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/seed.md

Demonstrates how to create and use different variants of the Seed type, including default, custom string, and empty seeds. Also shows the Seed::new constructor for creating seeds from various displayable types.

```APIDOC
## Seed Variants and Constructors

### Variants

- **String(String)**: Custom seed value for reproducible randomness.
- **Empty**: Falls back to default (timestamp-based).
- **Default**: Auto-generates timestamp-based seed at construction time.

### Constructors

#### `Seed::new<T: Display>(value: T) -> Self`

Creates a Seed from any type implementing Display. Empty strings become Seed::Default.

**Parameters:**
- **value** (T): Value to convert to seed string.

**Returns:** Seed variant

#### `Seed::default() -> Self`

Creates a Seed with current UTC timestamp in milliseconds. Useful for unique seeds on each call.

**Returns:** Seed::String with timestamp in milliseconds
```

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

### Previewing All FSRS Scheduling Outcomes

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/INDEX.md

Illustrates how to use the `repeat` method to preview the next card state for all possible ratings. This is useful for understanding scheduling variations.

```rust
let results = fsrs.repeat(card, now);  // All 4 ratings
for rating in Rating::iter() {
    let next_state = results[rating].card;
}
```

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

### Interval Fuzzing with Fractional Days

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fractionaldays.md

Shows how to combine a base interval defined in fractional days with additional durations (e.g., hours) to calculate a total time. Useful for scheduling with flexible intervals.

```rust
use chrono::Duration;
use rs_fsrs::FractionalDays;

let base_interval = Duration::fractional_days(7.5);
let hours_to_add = Duration::hours(3);
let total = base_interval + hours_to_add;

let days = total.num_fractional_days();
println!("Total: {:.3} days", days);
```

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

### Converting Between Time Systems using Fractional Days

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fractionaldays.md

Illustrates converting time values between systems that use hours and systems that use fractional days. This is helpful for interoperability between different time representations.

```rust
use chrono::Duration;
use rs_fsrs::FractionalDays;

// From system using hours
let hours_value = 36.0;
let duration = Duration::hours(hours_value as i64);
let days = duration.num_fractional_days();  // 1.5

// Back to hours
let back_to_duration = Duration::fractional_days(days);
assert_eq!(back_to_duration.num_hours(), 36);
```

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

### Using SchedulingInfo with `repeat()`

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Illustrates how to use the `repeat()` method of the FSRS algorithm to preview the scheduling information for all possible ratings for a given card. This method returns a HashMap where keys are ratings and values are SchedulingInfo objects.

```APIDOC
## Method: FSRS::repeat()

### Description
Previews the scheduling information for all possible ratings for a given card at the current time. Returns a HashMap mapping each `Rating` to its corresponding `SchedulingInfo`.

### Usage
```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();

// Get scheduling information for all ratings
let record_log: std::collections::HashMap<Rating, SchedulingInfo> = fsrs.repeat(card, Utc::now());

// Access results for specific ratings
// let good_result = &record_log[&Rating::Good];
// let easy_result = &record_log[&Rating::Easy];
```

### Parameters
- **card** (Card) - The current state of the card.
- **review_time** (DateTime<Utc>) - The timestamp of the review.

### Returns
- **HashMap<Rating, SchedulingInfo>** - A map where keys are `Rating` enums and values are `SchedulingInfo` objects, representing the outcome for each possible rating.
```

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

### Precise Time Calculations with Fractional Days

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fractionaldays.md

Demonstrates calculating elapsed time in fractional days, maintaining sub-hour precision. Useful for scenarios requiring fine-grained time differences.

```rust
use chrono::Duration;
use rs_fsrs::FractionalDays;

// Calculate elapsed time in days with hour precision
let elapsed = Duration::hours(42);
let days = elapsed.num_fractional_days();
println!("Elapsed: {:.2} days", days);  // 1.75 days
```

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

### Initialize Card Difficulty

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/parameters.md

Calculates the initial difficulty for a new card. The resulting difficulty is clamped to a range of 1.0 to 10.0.

```rust
use rs_fsrs::{Parameters, Rating};

let params = Parameters::default();
let difficulty = params.init_difficulty(Rating::Good);
println!("Initial difficulty: {:.2}", difficulty);
// Values clamped to [1.0, 10.0]
```

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

### Store and Analyze Review History

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/reviewlog.md

Demonstrates how to collect multiple `ReviewLog` entries into a `Vec` to build a history of reviews for a card. This is useful for analyzing review patterns or debugging.

```rust
use rs_fsrs::{FSRS, Card, Rating, ReviewLog};
use chrono::Utc;

let fsrs = FSRS::default();
let mut card = Card::new();
let mut history: Vec<ReviewLog> = Vec::new();

// Simulate multiple reviews
for _ in 0..3 {
    let result = fsrs.next(card.clone(), Utc::now(), Rating::Good);
    history.push(result.review_log);
    card = result.card;
}

// Analyze history
for log in history {
    println!("Review at {:?}: {:?}", log.reviewed_date, log.rating);
}
```

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

### Seed Conversions in Rust

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/seed.md

Shows how to convert various types like i32, String, and &str into a Seed using the `From` trait. It also demonstrates converting a Seed into a String.

```rust
use rs_fsrs::Seed;

// From i32
let from_int: Seed = Seed::from(42);

// From String
let from_string: Seed = Seed::from("seed_value".to_string());

// From &str
let from_str: Seed = Seed::from("seed_value");

// To String
let s: String = Seed::from(&Seed::new("test"));
```

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

### Process Single Review with next()

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Illustrates processing a single review event using the `next` method and then updating the card state and logging the review. This is a common workflow after a user provides a rating for a card.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();

// Process a single review
let info = fsrs.next(card, Utc::now(), Rating::Hard);

// Update your database with the new card state
update_card(&info.card);
// Log the review event
log_review(&info.review_log);
```

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

### Aggressive Learning Configuration

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/configuration.md

Use this preset for a higher retention target, enabling explicit learning phases and capping the maximum interval at 5 years.

```rust
use rs_fsrs::{FSRS, Parameters};

let mut params = Parameters::default();
params.request_retention = 0.80;  // Review more frequently
params.enable_short_term = true;  // Explicit learning phases
params.maximum_interval = 1825;   // Cap at 5 years
let fsrs = FSRS::new(params);
```

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

### Parameters Methods

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/FILE-LISTING.txt

Documentation for the methods related to FSRS parameters, including how to set and retrieve them.

```APIDOC
## Parameters Methods

### Description
This section details the methods for interacting with FSRS configuration parameters, including their default values and how they influence scheduling.

### API Reference Files
- `api-reference/parameters.md` (8 fields + 8 methods)
```

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

### Configure Short-Term Learning Phase

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/configuration.md

Determines whether to use the BasicScheduler for explicit learning phases or the LongtermScheduler for more uniform state handling. The default is true, utilizing a distinct New -> Learning -> Review -> Relearning state progression.

```rust
use rs_fsrs::{FSRS, Parameters};

// Default: use short-term learning phase
let fsrs = FSRS::default();

// Alternative: skip learning phase
let mut params = Parameters::default();
params.enable_short_term = false;
let fsrs = FSRS::new(params);
```

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

### Card::new()

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/card.md

Creates a new card initialized to the 'New' state with the current timestamp and default memory metrics.

```APIDOC
## Card::new()

### Description
Creates a new card in the New state with current timestamp. Initializes all memory metrics to zero/default.

### Returns
Card with:
- `state`: State::New
- `due`: Current UTC time
- `last_review`: Current UTC time
- All other fields zeroed
```

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

### Seed Variants in Rust

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/seed.md

Demonstrates the different ways to initialize a Seed: using the default timestamp-based seed, a custom string, or an empty seed which falls back to the default.

```rust
use rs_fsrs::Seed;

let default_seed = Seed::default();           // Timestamp-based
let custom_seed = Seed::String("my_key".to_string());  // Custom string
let empty_seed = Seed::Empty;                 // Falls back to default
```

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

### Initialize Card Stability

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/parameters.md

Calculates the initial stability for a new card based on the first review rating. The stability value has a minimum of 0.1.

```rust
use rs_fsrs::{Parameters, Rating};

let params = Parameters::default();
let stability = params.init_stability(Rating::Easy);
println!("Initial stability: {:.2}", stability);
```

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

### Handling Time with Fractional Days

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/INDEX.md

Demonstrates converting between chrono::Duration and the library's FractionalDays type for precise time calculations. Requires importing Duration and FractionalDays.

```rust
use chrono::Duration;
use rs_fsrs::FractionalDays;

let duration = Duration::fractional_days(1.5);
let days = duration.num_fractional_days();
```

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

### Create FSRS Scheduler with Custom Parameters

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/fsrs.md

Instantiate the FSRS scheduler with a custom set of scheduling parameters. Ensure you have imported the necessary types.

```rust
use rs_fsrs::{FSRS, Parameters};

let params = Parameters::default();
let fsrs = FSRS::new(params);
```

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

### Review Multiple Cards in Batch

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Demonstrates how to efficiently review a collection of cards using the FSRS algorithm. This function takes a vector of cards and a rating, returning the updated cards after processing.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

fn review_cards(cards: Vec<Card>, rating: Rating) -> Vec<Card> {
    let fsrs = FSRS::default();
    let now = Utc::now();
    
    cards.into_iter()
        .map(|card| {
            let result = fsrs.next(card, now, rating);
            result.card
        })
        .collect()
}

fn main() {
    let cards = vec![Card::new(), Card::new(), Card::new()];
    let updated = review_cards(cards, Rating::Good);
    
    for card in updated {
        println!("Next due: {:?}", card.due);
    }
}
```

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

### Logging Card State Transitions in Rust FSRS

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/errors.md

Shows how to log the state and review history of a card during multiple iterations using the FSRS algorithm. This is useful for debugging the progression of a card.

```rust
use rs_fsrs::{Card, FSRS, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let mut card = Card::new();

for _ in 0..3 {
    let result = fsrs.next(card.clone(), Utc::now(), Rating::Good);
    println!("Card state: {:?}", result.card);
    println!("Review log: {:?}", result.review_log);
    card = result.card;
}
```

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

### Pattern Matching on FSRS State

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/state.md

Illustrates how to use pattern matching to perform different actions based on the current State of a card. This is a common way to handle state-specific logic.

```rust
use rs_fsrs::State;

// Pattern matching on state
match state {
    State::New => println!("Never reviewed"),
    State::Learning => println!("Learning phase"),
    State::Review => println!("Long-term review"),
    State::Relearning => println!("Relearning after failure"),
}
```

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

### Parameter Validation with Clamping

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Shows how to create an FSRS instance with validated parameters. Invalid input values for retention and maximum interval are automatically clamped to reasonable, safe ranges.

```rust
use rs_fsrs::{FSRS, Parameters};

fn create_fsrs_safe(retention: f64, max_interval: i32) -> FSRS {
    let mut params = Parameters::default();
    
    // Clamp to reasonable ranges
    params.request_retention = retention.max(0.75).min(0.95);
    params.maximum_interval = max_interval.max(1).min(36500);
    
    FSRS::new(params)
}

fn main() {
    // Invalid values are automatically adjusted
    let fsrs = create_fsrs_safe(0.5, -100);  // Corrected to reasonable values
}
```

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

### BasicScheduler Flow

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/architecture.md

The BasicScheduler handles card states including New, Learning/Relearning, and Review. It utilizes short-term stability for learning states and a forgetting curve for review states, with specific transitions for 'Again' ratings.

```text
Review(card, rating):
  match card.state {
    New => new_state(rating)
      ├─ Generate initial parameters
      └─ → Learning or Review state
    
    Learning | Relearning => learning_state(rating)
      ├─ Use short_term_stability()
      ├─ Short intervals (1-10 min)
      └─ → Learning or Review state
    
    Review => review_state(rating)
      ├─ Use forgetting curve
      ├─ Long intervals (days+)
      └─ Again → Relearning; Others → Review
  }
```

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

### State Transitions

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/state.md

Illustrates the progression of a card through different learning states based on user review ratings (Again, Hard, Good, Easy).

```APIDOC
## State Transitions

The card progresses through states based on review results. The following diagram outlines the general flow:

```
        Rating::Easy
New ────────────────→ Review
 ↓
 └─ Rating::Again/Hard/Good → Learning
                           ↓
                    (multiple reviews)
                           ↓ Rating::Good/Easy
                         Review
                           ↓
                           ↓ Rating::Again
                       Relearning
                           ↓
                    (relearning phase)
                           ↓ Rating::Good
                         Review
```

### New State
- **Description**: Card has never been reviewed.
- **Transitions**: All ratings (Again, Hard, Good, Easy) initially lead to the `Learning` state, except for `Easy`, which transitions directly to `Review`.

### Learning State
- **Description**: Card is in the initial learning phase with short intervals (1-10 minutes).
- **Transitions**: Repeated reviews are expected to move the card to the `Review` state. `Again`/`Hard` ratings keep the card in `Learning`, while `Good`/`Easy` ratings move it to `Review`.

### Review State
- **Description**: Card has passed initial learning and receives longer intervals based on the FSRS algorithm.
- **Transitions**: Ratings adjust intervals (`Again` < `Hard` < `Good` < `Easy`). An `Again` rating moves the card to the `Relearning` state and increments the lapses counter.

### Relearning State
- **Description**: Card was forgotten during review and needs to be relearned, similar to the `Learning` state with short intervals.
- **Transitions**: Once relearned, it returns to the `Review` state.
```

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

### init_stability

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/parameters.md

Calculates the initial stability for a new card based on the first review rating. This method is called on an instance of Parameters.

```APIDOC
## init_stability(rating: Rating) -> f64

### Description
Calculates initial stability for a new card based on first rating.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```rust
use rs_fsrs::{Parameters, Rating};

let params = Parameters::default();
let stability = params.init_stability(Rating::Easy);
println!("Initial stability: {:.2}", stability);
```

### Response
#### Success Response (200)
- **Return Value** (f64) - Initial stability (minimum 0.1)

#### Response Example
```
10.0
```

### Calculation
Uses w[0] to w[3] based on rating index
```

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

### Working with Fractional Days

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/README.md

Shows how to convert between chrono::Duration and fractional days using the FractionalDays trait.

```rust
use chrono::Duration;
use rs_fsrs::FractionalDays;

fn main() {
    // Convert Duration to fractional days
    let duration = Duration::hours(36); // 1.5 days
    let days = duration.num_fractional_days(); // 1.5
    
    // Create Duration from fractional days
    let duration = Duration::fractional_days(2.5); // 2.5 days
}
```

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

### Clone SchedulingInfo

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/schedulinginfo.md

Shows how to clone a SchedulingInfo struct. This is useful for creating a copy of the review outcome for storage or further processing without modifying the original.

```rust
use rs_fsrs::{SchedulingInfo, Card, ReviewLog, Rating};
use chrono::Utc;

let info = SchedulingInfo {
    card: Card::new(),
    review_log: ReviewLog {
        rating: Rating::Good,
        elapsed_days: 0,
        scheduled_days: 5,
        state: State::Learning,
        reviewed_date: Utc::now(),
    },
};

let cloned = info.clone();
println!("{:?}", cloned);
```

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

### FSRS Algorithm Documentation

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/_COMPLETION_REPORT.txt

Documentation explaining the FSRS algorithm, including its state machine, forgetting curve formula, weight array explanation, and data flow diagrams.

```APIDOC
## Algorithm Documentation

### Description
Provides an in-depth explanation of the FSRS algorithm, its underlying principles, and implementation details.

### Components
- **State Machine**: Description of transitions and states.
- **Forgetting Curve**: Mathematical formula and explanation.
- **Weight Array**: Detailed explanation of its structure and purpose.
- **Data Flow**: Diagrams illustrating data processing.

### Access
Detailed algorithm explanations can be found in `architecture.md`.
```

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

### Create a New Card

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/card.md

Initializes a new card in the 'New' state with the current timestamp. All memory metrics are set to their default zero values.

```rust
use rs_fsrs::Card;

let card = Card::new();
assert_eq!(card.state, State::New);
assert_eq!(card.stability, 0.0);
assert_eq!(card.reps, 0);
```

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

### init_difficulty

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/parameters.md

Calculates the initial difficulty for a new card based on the first review rating. This method is called on an instance of Parameters.

```APIDOC
## init_difficulty(rating: Rating) -> f64

### Description
Calculates initial difficulty for a new card based on first rating.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```rust
use rs_fsrs::{Parameters, Rating};

let params = Parameters::default();
let difficulty = params.init_difficulty(Rating::Good);
println!("Initial difficulty: {:.2}", difficulty);
// Values clamped to [1.0, 10.0]
```

### Response
#### Success Response (200)
- **Return Value** (f64) - Initial difficulty clamped to [1.0, 10.0]

#### Response Example
```
5.0
```
```

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

### Efficient Bulk Card Processing

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Illustrates how to optimize bulk processing of cards by creating the FSRS instance once and reusing it for multiple operations. This approach minimizes overhead for large datasets.

```rust
use rs_fsrs::{FSRS, Parameters};

fn main() {
    // Create FSRS once
    let fsrs = FSRS::default();
    
    // Reuse for multiple cards
    for card_id in 0..10000 {
        let card = load_card(card_id);
        let now = chrono::Utc::now();
        
        // Each next() is O(1)
        let result = fsrs.next(card, now, rs_fsrs::Rating::Good);
        save_card(result.card);
    }
}

fn load_card(id: i32) -> rs_fsrs::Card {
    // Load from database
    rs_fsrs::Card::new()
}

fn save_card(card: rs_fsrs::Card) {
    // Save to database
}
```

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

### Access ReviewLog from SchedulingInfo

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/reviewlog.md

Illustrates how to obtain the `ReviewLog` from the result of the `fsrs.next()` function. This is typically used to inspect the details of the most recent review.

```rust
use rs_fsrs::{FSRS, Card, Rating};
use chrono::Utc;

let fsrs = FSRS::default();
let card = Card::new();
let result = fsrs.next(card, Utc::now(), Rating::Good);

let review_log = result.review_log;
println!("Rating: {:?}", review_log.rating);
println!("Reviewed at: {:?}", review_log.reviewed_date);
```

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

### Card Review and Scheduling Flow

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/modules.md

Illustrates the typical workflow for processing a card review, from creating a new card to obtaining updated scheduling information for different ratings.

```rust
use rs_fsrs::{Card, Rating, FSRS};

let card = Card::new();                    // Create new card
let results = fsrs.repeat(card, now);     // Get all ratings
for rating in Rating::iter() {
    let info = &results[rating];           // SchedulingInfo
    println!("{:?}", info.card);           // Updated card
    println!("{:?}", info.review_log);     // Review event
}
```

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

### Prng Constructor

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/prng.md

Creates a new Prng instance using a provided Seed. This is the entry point for using the high-level PRNG functionality.

```rust
use rs_fsrs::{Prng, Seed};

let seed = Seed::new("my_seed");
let mut prng = Prng::new(seed);
```

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

### Initialize Card with Default Values

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/card.md

Creates a new card using the Default trait implementation. Note that 'due' and 'last_review' are set to the current UTC time within the Default implementation.

```rust
use rs_fsrs::Card;

let card = Card::default();
```

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

### Seed Comparison and Equality in Rust

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/seed.md

Demonstrates how to compare Seed instances for equality using the `==` and `!=` operators. Seed implements the PartialEq trait for this purpose.

```rust
use rs_fsrs::Seed;

let seed1 = Seed::new("same");
let seed2 = Seed::new("same");
let seed3 = Seed::new("different");

assert_eq!(seed1, seed2);
assert_ne!(seed1, seed3);
```

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

### AleaState Conversions

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/prng.md

Shows how to convert between an Alea PRNG instance and its corresponding AleaState snapshot for serialization or state transfer.

```rust
use rs_fsrs::{Alea, AleaState};

// From Alea to AleaState
let state: AleaState = alea.into();

// From AleaState back to Alea
let alea: Alea = state.into();
```

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

### FSRS Methods

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/INDEX.md

Provides core functionalities for the FSRS algorithm, including initialization, repetition, and scheduling.

```APIDOC
## FSRS Methods

### `new()`

**Description**: Initializes a new FSRS instance.

**Parameters**: `Parameters`

**Returns**: `FSRS`

### `default()`

**Description**: Creates a default FSRS instance.

**Parameters**: None

**Returns**: `FSRS`

### `repeat()`

**Description**: Records a review of a card.

**Parameters**: `Card`, `DateTime`

**Returns**: `RecordLog`

### `next()`

**Description**: Calculates the next review scheduling information for a card.

**Parameters**: `Card`, `DateTime`, `Rating`

**Returns**: `SchedulingInfo`

### `scheduler()`

**Description**: Retrieves the appropriate scheduler implementation for a given card and time.

**Parameters**: `Card`, `DateTime`

**Returns**: `Box<dyn ImplScheduler>`
```

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

### Checkpoint and Restore PRNG State

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/examples.md

Shows how to manage the state of the pseudo-random number generator (PRNG) for checkpointing and restoring. This allows saving the PRNG's current state and resuming generation from that point later.

```rust
use rs_fsrs::{alea, Seed};

fn main() {
    let mut prng = alea(Seed::new("test"));
    
    // Generate some values
    let v1 = prng.gen_next();
    let v2 = prng.gen_next();
    
    // Save state
    let state = prng.get_state();
    
    // Continue generating
    let v3 = prng.gen_next();
    
    // Restore to checkpoint
    let mut prng2 = alea(Seed::new("test"));
    prng2 = prng2.import_state(state);
    let v3_again = prng2.gen_next();
    
    assert_eq!(v3, v3_again);
}
```

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

### FSRS Main Struct Methods

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/FILE-LISTING.txt

Documentation for the methods available on the FSRS main struct, detailing their functionality and usage.

```APIDOC
## FSRS Methods

### Description
This section details the methods available on the main FSRS struct, which are the primary interface for interacting with the FSRS algorithm.

### API Reference Files
- `api-reference/fsrs.md` (5 methods)
- `api-reference/card.md` (9 fields + 2 methods)
- `api-reference/rating.md` (4 variants)
- `api-reference/state.md` (4 variants + transitions)
- `api-reference/parameters.md` (8 fields + 8 methods)
- `api-reference/schedulinginfo.md` (2 fields)
- `api-reference/reviewlog.md` (5 fields)
- `api-reference/seed.md` (3 variants + 2 methods)
- `api-reference/fractionaldays.md` (2 methods)
- `api-reference/scheduler.md` (Scheduler trait & 2 implementations)
- `api-reference/prng.md` (3 types + 6 methods)
```

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

### Default FSRS Card State

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/state.md

Shows how to create a new card and checks its initial state, which defaults to 'New'. It also demonstrates obtaining the default state directly.

```rust
use rs_fsrs::{Card, State};

let card = Card::new();
assert_eq!(card.state, State::New);

// State also implements Default
let default = State::default();
assert_eq!(default, State::New);
```

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

### Choosing Between BasicScheduler and LongtermScheduler

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/api-reference/scheduler.md

Instantiate FSRS with default parameters for BasicScheduler, or customize Parameters to disable short-term memory for LongtermScheduler.

```rust
use rs_fsrs::{FSRS, Parameters};

// Uses BasicScheduler (default)
let fsrs = FSRS::default();

// Uses LongtermScheduler
let mut params = Parameters::default();
params.enable_short_term = false;
let fsrs = FSRS::new(params);
```

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

### Flashcard Application Workflow

Source: https://github.com/open-spaced-repetition/rs-fsrs/blob/master/_autodocs/INDEX.md

Illustrates the typical workflow for integrating FSRS into a flashcard application. This involves loading a card, calculating the next review state, and saving the updated card.

```plaintext
1. Load Card from database
2. fsrs.next(card, now, user_rating)
3. Save updated Card
4. Schedule next review from card.due
```