bourse_book/lib.rs
1//! Simulated order book
2//!
3//! Simulated order book designed for
4//! market simulations. Acts as
5//! matching engine, but also data
6//! structure tracking simulated orders
7//! and historical data.
8//!
9//! # Examples
10//!
11//! ## Initialisation and Updating an Order Book
12//!
13//! ```
14//! use bourse_book;
15//! use bourse_book::{types, OrderBook};
16//!
17//! let mut book: OrderBook = OrderBook::new(0, 1, true);
18//!
19//! // Create a new order
20//! let order_id = book.create_order(
21//! types::Side::Bid, 50, 101, Some(50)
22//! ).unwrap();
23//!
24//! // Place the order on the market
25//! book.place_order(order_id);
26//!
27//! // Get the current touch prices
28//! let (bid, ask) = book.bid_ask();
29//!
30//! // Set the time of the orderbook
31//! book.set_time(1000);
32//!
33//! // Cancel the order
34//! book.cancel_order(order_id);
35//! ```
36//!
37//! [OrderBook] also implements functionality
38//! to modify orders and retrieve market data.
39//! See [OrderBook] for full details of the API.
40//!
41//! ## Order & Trade Histories
42//!
43//! [OrderBook] tracks any orders created and any trades executed
44//! over the course of the order books existence. These can
45//! be retrieved using:
46//!
47//! ```
48//! # use bourse_book::OrderBook;
49//! # use bourse_book::types::{Order, Trade};
50//! # let book: OrderBook = OrderBook::new(0, 1, true);
51//! // Get references to all the orders created
52//! let order_history: Vec<&Order> = book.get_orders();
53//! // Get a reference to trade records
54//! let trade_history: &Vec<Trade> = book.get_trades();
55//! ```
56//!
57//! ## Persisting State
58//!
59//! OrderBook implements [serde::Serialize] and
60//! [serde::Deserialize] traits to allow the state of
61//! the order book to be persisted, this can be done
62//! manually, for example:
63//!
64//! ```
65//! # use bourse_book::OrderBook;
66//! # let book: OrderBook = OrderBook::new(0, 1, true);
67//! let state = serde_json::to_string(&book).unwrap();
68//! let book = serde_json::from_str::<OrderBook>(state.as_str()).unwrap();
69//! ```
70//! or the methods [OrderBook::save_json] and [OrderBook::load_json] can
71//! be used to save/load the OrderBook state to/from a JSON file:
72//!
73//! ```no_run
74//! # use bourse_book::OrderBook;
75//! # let book: OrderBook = OrderBook::new(0, 1, true);
76//! book.save_json("foo.json", true);
77//! let loaded_book: OrderBook = OrderBook::load_json("foo.json").unwrap();
78//! ```
79//!
80//! # Notes
81//!
82//! - Orders are sorted by price-time priority. To
83//! reduce any ambiguity in ordering, the simulated
84//! time of the market should be updated in
85//! between placing orders on the market.
86//! - For accuracy prices are stored as unsigned
87//! integers (as opposed to a float type), hence
88//! prices from data should be scaled based on
89//! market tick-size
90//! - Simulated orders are intended to be owned by
91//! the order book, from which agents/users can
92//! retrieve order data. Creating an order with
93//! [OrderBook::create_order] initialises a new
94//! order entry, but does not immediately place
95//! the order on the market.
96//!
97mod orderbook;
98mod side;
99pub mod types;
100
101pub use orderbook::{OrderBook, OrderError};