Struct StatId 

pub struct StatId(/* private fields */);

Interned string identifier for stats.

Uses Arc<str> for memory efficiency and fast comparison. Multiple StatId instances with the same string content share the same underlying allocation.

Examples

use zzstat::StatId;

let hp = StatId::from_str("HP");
let atk = StatId::from_str("ATK");

// Can be created from string slices or owned strings
let hp2: StatId = "HP".into();
let hp3: StatId = String::from("HP").into();

assert_eq!(hp, hp2);
assert_eq!(hp, hp3);

Implementations

impl StatId

pub fn from_str(s: &str) -> Self

Create a new StatId from a string slice.

Examples

use zzstat::StatId;

let stat_id = StatId::from_str("HP");
assert_eq!(stat_id.as_str(), "HP");

Examples found in repository

examples/basic.rs (line 17)

fn main() -> Result<(), StatError> {
    // Create a new stat resolver
    let mut resolver = StatResolver::new();

    // Define a stat ID
    let hp_id = StatId::from_str("HP");

    // Register multiple sources (they will be summed)
    println!("Registering sources for HP:");
    resolver.register_source(hp_id.clone(), Box::new(ConstantSource(100.0)));
    println!("  - Base HP: 100");

    resolver.register_source(hp_id.clone(), Box::new(ConstantSource(50.0)));
    println!("  - Item bonus: +50");

    // Register a transform (percentage modifier)
    println!("\nRegistering transform:");
    resolver.register_transform(hp_id.clone(), Box::new(MultiplicativeTransform::new(1.2)));
    println!("  - 20% bonus multiplier");

    // Create context (empty for this example)
    let context = StatContext::new();

    // Resolve the stat
    println!("\nResolving HP...");
    let resolved = resolver.resolve(&hp_id, &context)?;

    // Display results
    println!("\n=== Resolved Stat ===");
    println!("Stat ID: {}", resolved.stat_id);
    println!("Final Value: {:.2}", resolved.value);

    println!("\nSource Breakdown:");
    for (desc, value) in &resolved.sources {
        println!("  {}: {:.2}", desc, value);
    }

    println!("\nTransform Breakdown:");
    for (desc, value) in &resolved.transforms {
        println!("  {}: {:.2}", desc, value);
    }

    println!("\nCalculation: (100 + 50) * 1.2 = {:.2}", resolved.value);

    Ok(())
}

examples/dependencies.rs (line 16)

fn main() -> Result<(), StatError> {
    let mut resolver = StatResolver::new();

    // Define stat IDs
    let str_id = StatId::from_str("STR");
    let dex_id = StatId::from_str("DEX");
    let atk_id = StatId::from_str("ATK");
    let crit_id = StatId::from_str("CRIT");

    println!("=== Setting up base stats ===");

    // Base stats (no dependencies)
    resolver.register_source(str_id.clone(), Box::new(ConstantSource(10.0)));
    println!("STR: 10 (base)");

    resolver.register_source(dex_id.clone(), Box::new(ConstantSource(15.0)));
    println!("DEX: 15 (base)");

    println!("\n=== Setting up derived stats ===");

    // ATK depends on STR
    resolver.register_source(atk_id.clone(), Box::new(ConstantSource(50.0)));
    resolver.register_transform(
        atk_id.clone(),
        Box::new(ScalingTransform::new(str_id.clone(), 2.0)),
    );
    println!("ATK: 50 (base) + STR * 2.0");

    // CRIT depends on DEX
    resolver.register_source(crit_id.clone(), Box::new(ConstantSource(5.0)));
    resolver.register_transform(
        crit_id.clone(),
        Box::new(ScalingTransform::new(dex_id.clone(), 1.5)),
    );
    println!("CRIT: 5 (base) + DEX * 1.5");

    let context = StatContext::new();

    println!("\n=== Resolving all stats ===");
    let results = resolver.resolve_all(&context)?;

    // Display results
    println!("\n=== Results ===");
    for (stat_id, resolved) in &results {
        println!("\n{}:", stat_id);
        println!("  Final Value: {:.2}", resolved.value);

        if !resolved.sources.is_empty() {
            println!("  Sources:");
            for (desc, value) in &resolved.sources {
                println!("    {}: {:.2}", desc, value);
            }
        }

        if !resolved.transforms.is_empty() {
            println!("  Transforms:");
            for (desc, value) in &resolved.transforms {
                println!("    {}: {:.2}", desc, value);
            }
        }
    }

    println!("\n=== Verification ===");
    println!("STR: {:.2} (expected: 10.00)", results[&str_id].value);
    println!("DEX: {:.2} (expected: 15.00)", results[&dex_id].value);
    println!(
        "ATK: {:.2} (expected: 70.00 = 50 + 10*2)",
        results[&atk_id].value
    );
    println!(
        "CRIT: {:.2} (expected: 27.50 = 5 + 15*1.5)",
        results[&crit_id].value
    );

    Ok(())
}

examples/cycle_detection.rs (line 15)

fn main() {
    let mut resolver = StatResolver::new();

    // Create stats that depend on each other in a cycle
    let a_id = StatId::from_str("A");
    let b_id = StatId::from_str("B");
    let c_id = StatId::from_str("C");

    println!("=== Setting up circular dependencies ===\n");

    // A depends on B
    resolver.register_source(a_id.clone(), Box::new(ConstantSource(10.0)));
    resolver.register_transform(
        a_id.clone(),
        Box::new(ScalingTransform::new(b_id.clone(), 1.0)),
    );
    println!("A: 10 (base) + B * 1.0");

    // B depends on C
    resolver.register_source(b_id.clone(), Box::new(ConstantSource(20.0)));
    resolver.register_transform(
        b_id.clone(),
        Box::new(ScalingTransform::new(c_id.clone(), 1.0)),
    );
    println!("B: 20 (base) + C * 1.0");

    // C depends on A (creates cycle: A -> B -> C -> A)
    resolver.register_source(c_id.clone(), Box::new(ConstantSource(30.0)));
    resolver.register_transform(
        c_id.clone(),
        Box::new(ScalingTransform::new(a_id.clone(), 1.0)),
    );
    println!("C: 30 (base) + A * 1.0");

    println!("\n=== Attempting to resolve (should detect cycle) ===\n");

    let context = StatContext::new();
    match resolver.resolve(&a_id, &context) {
        Err(StatError::CycleDetected(cycle)) => {
            println!("✓ Cycle detected successfully!");
            println!("\nCycle path:");
            for (i, stat_id) in cycle.iter().enumerate() {
                if i < cycle.len() - 1 {
                    print!("{} -> ", stat_id);
                } else {
                    println!("{}", stat_id);
                }
            }
        }
        Err(e) => {
            println!("✗ Unexpected error: {}", e);
        }
        Ok(_) => {
            println!("✗ ERROR: Cycle was not detected! This should not happen.");
        }
    }

    println!("\n=== Valid dependency chain (no cycle) ===\n");

    // Reset resolver
    let mut resolver2 = StatResolver::new();

    let x_id = StatId::from_str("X");
    let y_id = StatId::from_str("Y");
    let z_id = StatId::from_str("Z");

    // Linear chain: X -> Y -> Z (no cycle)
    resolver2.register_source(x_id.clone(), Box::new(ConstantSource(10.0)));
    println!("X: 10 (base)");

    resolver2.register_source(y_id.clone(), Box::new(ConstantSource(20.0)));
    resolver2.register_transform(
        y_id.clone(),
        Box::new(ScalingTransform::new(x_id.clone(), 1.0)),
    );
    println!("Y: 20 (base) + X * 1.0");

    resolver2.register_source(z_id.clone(), Box::new(ConstantSource(30.0)));
    resolver2.register_transform(
        z_id.clone(),
        Box::new(ScalingTransform::new(y_id.clone(), 1.0)),
    );
    println!("Z: 30 (base) + Y * 1.0");

    println!("\n=== Resolving valid chain ===\n");

    let results = resolver2.resolve_all(&context).unwrap();

    println!("Results:");
    println!("  X: {:.2}", results[&x_id].value);
    println!("  Y: {:.2} (20 + 10)", results[&y_id].value);
    println!("  Z: {:.2} (30 + 30)", results[&z_id].value);

    println!("\n✓ Valid dependency chain resolved successfully!");
}

examples/context.rs (line 15)

fn main() -> Result<(), StatError> {
    let mut resolver = StatResolver::new();

    let atk_id = StatId::from_str("ATK");
    let def_id = StatId::from_str("DEF");

    println!("=== Setting up stats with context-dependent transforms ===\n");

    // Base ATK
    resolver.register_source(atk_id.clone(), Box::new(ConstantSource(100.0)));
    println!("ATK base: 100");

    // ATK gets +50% bonus in combat
    let combat_bonus = ConditionalTransform::new(
        |ctx| ctx.get::<bool>("in_combat").unwrap_or(false),
        Box::new(MultiplicativeTransform::new(1.5)),
        "Combat bonus +50%",
    );
    resolver.register_transform(atk_id.clone(), Box::new(combat_bonus));
    println!("ATK: +50% when in combat");

    // Base DEF
    resolver.register_source(def_id.clone(), Box::new(ConstantSource(80.0)));
    println!("DEF base: 80");

    // DEF gets +25% bonus in PvP zones
    let pvp_bonus = ConditionalTransform::new(
        |ctx| {
            ctx.get::<String>("zone_type")
                .map(|z| z == "pvp")
                .unwrap_or(false)
        },
        Box::new(MultiplicativeTransform::new(1.25)),
        "PvP zone bonus +25%",
    );
    resolver.register_transform(def_id.clone(), Box::new(pvp_bonus));
    println!("DEF: +25% in PvP zones");

    // Scenario 1: Out of combat, normal zone
    println!("\n=== Scenario 1: Out of combat, normal zone ===");
    let mut context1 = StatContext::new();
    context1.set("in_combat", false);
    context1.set("zone_type", "normal");

    let atk1 = resolver.resolve(&atk_id, &context1)?;
    let def1 = resolver.resolve(&def_id, &context1)?;

    println!("ATK: {:.2} (no bonuses)", atk1.value);
    println!("DEF: {:.2} (no bonuses)", def1.value);

    // Scenario 2: In combat, normal zone
    println!("\n=== Scenario 2: In combat, normal zone ===");
    let mut context2 = StatContext::new();
    context2.set("in_combat", true);
    context2.set("zone_type", "normal");

    // Invalidate cache to force recalculation
    resolver.invalidate(&atk_id);
    resolver.invalidate(&def_id);

    let atk2 = resolver.resolve(&atk_id, &context2)?;
    let def2 = resolver.resolve(&def_id, &context2)?;

    println!("ATK: {:.2} (combat bonus: 100 * 1.5)", atk2.value);
    println!("DEF: {:.2} (no bonuses)", def2.value);

    // Scenario 3: Out of combat, PvP zone
    println!("\n=== Scenario 3: Out of combat, PvP zone ===");
    let mut context3 = StatContext::new();
    context3.set("in_combat", false);
    context3.set("zone_type", "pvp");

    resolver.invalidate(&atk_id);
    resolver.invalidate(&def_id);

    let atk3 = resolver.resolve(&atk_id, &context3)?;
    let def3 = resolver.resolve(&def_id, &context3)?;

    println!("ATK: {:.2} (no bonuses)", atk3.value);
    println!("DEF: {:.2} (PvP bonus: 80 * 1.25)", def3.value);

    // Scenario 4: In combat, PvP zone
    println!("\n=== Scenario 4: In combat, PvP zone ===");
    let mut context4 = StatContext::new();
    context4.set("in_combat", true);
    context4.set("zone_type", "pvp");

    resolver.invalidate(&atk_id);
    resolver.invalidate(&def_id);

    let atk4 = resolver.resolve(&atk_id, &context4)?;
    let def4 = resolver.resolve(&def_id, &context4)?;

    println!("ATK: {:.2} (combat bonus: 100 * 1.5)", atk4.value);
    println!("DEF: {:.2} (PvP bonus: 80 * 1.25)", def4.value);

    println!("\n=== Summary ===");
    println!("Context allows stats to vary based on game state:");
    println!("  - Combat state affects ATK");
    println!("  - Zone type affects DEF");
    println!("  - Stats are recalculated when context changes");

    Ok(())
}

examples/complex.rs (line 17)

fn main() -> Result<(), StatError> {
    let mut resolver = StatResolver::new();

    // Define a character's stats
    let str_id = StatId::from_str("STR");
    let dex_id = StatId::from_str("DEX");
    let int_id = StatId::from_str("INT");
    let hp_id = StatId::from_str("HP");
    let mp_id = StatId::from_str("MP");
    let atk_id = StatId::from_str("ATK");
    let crit_id = StatId::from_str("CRIT");
    let dps_id = StatId::from_str("DPS");

    println!("=== Character Stat System ===\n");

    // Base attributes
    println!("Base Attributes:");
    resolver.register_source(str_id.clone(), Box::new(ConstantSource(20.0)));
    println!("  STR: 20");

    resolver.register_source(dex_id.clone(), Box::new(ConstantSource(15.0)));
    println!("  DEX: 15");

    resolver.register_source(int_id.clone(), Box::new(ConstantSource(25.0)));
    println!("  INT: 25");

    // HP: Base + STR scaling + item bonuses
    println!("\nHP Calculation:");
    resolver.register_source(hp_id.clone(), Box::new(ConstantSource(100.0)));
    println!("  Base: 100");

    resolver.register_source(hp_id.clone(), Box::new(ConstantSource(50.0)));
    println!("  Item bonus: +50");

    resolver.register_transform(
        hp_id.clone(),
        Box::new(ScalingTransform::new(str_id.clone(), 5.0)),
    );
    println!("  STR scaling: +STR * 5");

    resolver.register_transform(hp_id.clone(), Box::new(MultiplicativeTransform::new(1.1)));
    println!("  Passive: +10%");

    // MP: Base + INT scaling
    println!("\nMP Calculation:");
    resolver.register_source(mp_id.clone(), Box::new(ConstantSource(50.0)));
    println!("  Base: 50");

    resolver.register_transform(
        mp_id.clone(),
        Box::new(ScalingTransform::new(int_id.clone(), 3.0)),
    );
    println!("  INT scaling: +INT * 3");

    // ATK: Base + STR scaling + DEX scaling
    println!("\nATK Calculation:");
    resolver.register_source(atk_id.clone(), Box::new(ConstantSource(30.0)));
    println!("  Base: 30");

    resolver.register_transform(
        atk_id.clone(),
        Box::new(ScalingTransform::new(str_id.clone(), 2.0)),
    );
    println!("  STR scaling: +STR * 2");

    resolver.register_transform(
        atk_id.clone(),
        Box::new(ScalingTransform::new(dex_id.clone(), 1.0)),
    );
    println!("  DEX scaling: +DEX * 1");

    resolver.register_transform(atk_id.clone(), Box::new(ClampTransform::new(0.0, 200.0)));
    println!("  Clamp: [0, 200]");

    // CRIT: Base + DEX scaling
    println!("\nCRIT Calculation:");
    resolver.register_source(crit_id.clone(), Box::new(ConstantSource(5.0)));
    println!("  Base: 5");

    resolver.register_transform(
        crit_id.clone(),
        Box::new(ScalingTransform::new(dex_id.clone(), 2.0)),
    );
    println!("  DEX scaling: +DEX * 2");

    // DPS: Depends on ATK and CRIT
    println!("\nDPS Calculation:");
    resolver.register_source(dps_id.clone(), Box::new(ConstantSource(0.0)));
    println!("  Base: 0");

    resolver.register_transform(
        dps_id.clone(),
        Box::new(ScalingTransform::new(atk_id.clone(), 1.0)),
    );
    println!("  ATK contribution: +ATK * 1");

    resolver.register_transform(
        dps_id.clone(),
        Box::new(ScalingTransform::new(crit_id.clone(), 0.5)),
    );
    println!("  CRIT contribution: +CRIT * 0.5");

    let context = StatContext::new();

    println!("\n=== Resolving All Stats ===\n");
    let results = resolver.resolve_all(&context)?;

    // Display final stats
    println!("=== Final Character Stats ===\n");

    let stats = vec![
        ("STR", &str_id),
        ("DEX", &dex_id),
        ("INT", &int_id),
        ("HP", &hp_id),
        ("MP", &mp_id),
        ("ATK", &atk_id),
        ("CRIT", &crit_id),
        ("DPS", &dps_id),
    ];

    for (name, id) in stats {
        if let Some(resolved) = results.get(id) {
            println!("{}: {:.2}", name, resolved.value);
        }
    }

    println!("\n=== Detailed Breakdown ===\n");

    // Show detailed breakdown for DPS
    if let Some(dps) = results.get(&dps_id) {
        println!("DPS Breakdown:");
        println!("  Final Value: {:.2}", dps.value);

        println!("\n  Sources:");
        for (desc, value) in &dps.sources {
            println!("    {}: {:.2}", desc, value);
        }

        println!("\n  Transforms:");
        for (desc, value) in &dps.transforms {
            println!("    {}: {:.2}", desc, value);
        }
    }

    Ok(())
}

pub fn as_str(&self) -> &str

Get the string representation of this StatId.

Examples

use zzstat::StatId;

let stat_id = StatId::from_str("ATK");
assert_eq!(stat_id.as_str(), "ATK");

Trait Implementations

impl Clone for StatId

fn clone(&self) -> StatId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StatId

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StatId

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for StatId

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

Formats the value using the given formatter.

impl From<&str> for StatId

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<String> for StatId

fn from(s: String) -> Self

Converts to this type from the input type.

impl FromStr for StatId

type Err = Infallible

The associated error which can be returned from parsing.

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

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

impl Hash for StatId

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for StatId

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for StatId

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for StatId

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for StatId

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for StatId

impl StructuralPartialEq for StatId