Files

T

kingchenc 747d1a5b1b examples: move Rust examples into a top-level examples/rust/ crate

The three Rust examples (backtest, fetch_btcusdt, live_binance) used to
live each in their own crate's examples/ dir, splitting the example set
across crates and burying it inside the source tree. Move them into a new
workspace member crate at `examples/rust/` (package `wickra-examples`,
`publish = false`) so all language examples sit under one top-level
`examples/<lang>/` tree.

* `examples/rust/Cargo.toml` declares the per-binary deps (wickra,
  wickra-data with the `live-binance` feature always on, serde_json, tokio
  for the macro and current-thread runtime).
* `examples/rust/src/bin/{backtest,fetch_btcusdt,live_binance}.rs` are the
  three migrated binaries; their doc-comments and the fetch_btcusdt output
  path are updated for the new location and run command
  (`cargo run -p wickra-examples --bin <name>`).
* Workspace `Cargo.toml` lists the new member; the now-empty
  `[dev-dependencies]` extras (`wickra`, `tokio` in wickra-data and
  `serde_json` in wickra) that existed only for these examples are dropped.
* The `[[example]] live_binance` table is removed from wickra-data's
  manifest since the file moved out.
* README "Languages" + project-layout, examples/README.md, Quickstart-Rust
  and Data-Layer are pointed at the new paths and commands.

`cargo build -p wickra-examples` and `cargo run --release -p wickra-examples
--bin backtest -- examples/data/btcusdt-1d.csv` both succeed; the rest of
the workspace (core, data, wickra) builds, clippies (`--all-targets -D
warnings`) and tests (508 core + 28 data + 1 integration + 74+3+1
doctests) all stay green.

2026-05-23 00:07:07 +02:00

4.6 KiB

Raw Blame History

Quickstart: Rust

A five-minute tour of the Wickra Rust crate. By the end you will have run a batch SMA, fed an RSI tick by tick, and composed two indicators with Chain.

Install

cargo add wickra

The default features pull in parallel (rayon-based batch_parallel); turn them off with cargo add wickra --no-default-features if you want a leaner build. The wickra crate is a thin façade that re-exports everything from wickra-core; you can also depend on wickra-core directly if you want to skip the façade.

The published crate is at version 0.1.4 on crates.io.

The `Indicator` trait in 30 seconds

Every indicator implements the same trait:

pub trait Indicator {
    type Input;
    type Output;
    fn update(&mut self, input: Self::Input) -> Option<Self::Output>;
    fn reset(&mut self);
    fn warmup_period(&self) -> usize;
    fn is_ready(&self) -> bool;
    fn name(&self) -> &'static str;
}

update is O(1) in the input length. The companion trait BatchExt is a blanket extension that adds a batch(&[Self::Input]) method to every indicator — its default implementation is literally a loop over update, so batch and streaming results are bit-for-bit identical.

Batch and streaming side by side

use wickra::{BatchExt, Indicator, Rsi, Sma};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Batch: SMA(3) over five prices.
    let mut sma = Sma::new(3)?;
    let out: Vec<Option<f64>> = sma.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("{:?}", out);
    // -> [None, None, Some(2.0), Some(3.0), Some(4.0)]

    // 2. Streaming: feed Wilder's textbook example into RSI(14).
    let mut rsi = Rsi::new(14)?;
    let prices = [
        44.34, 44.09, 44.15, 43.61, 44.33, 44.83, 45.10, 45.42, 45.84, 46.08,
        45.89, 46.03, 45.61, 46.28, 46.28, 46.00, 46.03, 46.41,
    ];
    for (tick, price) in prices.iter().enumerate() {
        if let Some(v) = rsi.update(*price) {
            println!("tick {:2}  close={:.2}  rsi={:.4}", tick + 1, price, v);
        }
    }
    Ok(())
}

The streaming loop prints:

tick 15  close=46.28  rsi=70.4641
tick 16  close=46.00  rsi=66.2496
tick 17  close=46.03  rsi=66.4809
tick 18  close=46.41  rsi=69.3469

The first value lands on tick 15 because Rsi::new(14)?.warmup_period() == 15 (14 diffs to seed Wilder's smoothing, so the 15th input emits the first RSI). The 70.4641 value matches the textbook value pinned by the unit test classic_wilder_textbook_values in crates/wickra-core/src/indicators/rsi.rs.

Composing indicators with `Chain`

Chain<A, B> wires the output of A straight into the input of B, provided both stages agree on f64 as the bridging type. The chain itself is an Indicator, so you can stack three stages with .then(c), or four with .then(c).then(d).

use wickra::{Chain, Ema, Indicator, Rsi};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // RSI(7) computed on the output of EMA(14).
    let mut chain = Chain::new(Ema::new(14)?, Rsi::new(7)?);
    for i in 1..=22 {
        if let Some(v) = chain.update(f64::from(i)) {
            println!("chain emitted at input #{i}: {v}");
        }
    }
    println!("chain.warmup_period() = {}", chain.warmup_period());
    Ok(())
}

Output:

chain emitted at input #21: 100
chain emitted at input #22: 100
chain.warmup_period() = 22

Ema::new(14) needs 14 inputs to seed and Rsi::new(7) needs 8 more once the EMA starts flowing, so the chain emits its first value at input 21. The warmup_period() reported by Chain is a conservative first + second sum (here 14 + 8 = 22); see Indicator Chaining for the exact contract.

A deeper example

examples/rust/src/bin/backtest.rs (in the wickra-examples workspace crate) computes a panel of indicators (RSI, EMA, Bollinger, MACD, ATR, ADX, OBV) over an OHLCV CSV by way of wickra-data:

cargo run --release -p wickra-examples --bin backtest -- path/to/ohlcv.csv

For live-data work, wickra-data ships a streaming CSV reader, a tick-to-candle aggregator, a candle resampler, and a Binance kline WebSocket adapter under the live-binance feature. examples/rust/src/bin/live_binance.rs is the canonical example for the latter.

4.6 KiB Raw Blame History