README.md
1# Instant
2
3If you call `std::time::Instant::now()` on a WASM platform, it will panic. This crate provides a partial
4replacement for `std::time::Instant` that works on WASM too. This defines the type `instant::Instant` which is:
5
6* A struct emulating the behavior of **std::time::Instant** if you are targeting `wasm32-unknown-unknown` or `wasm32-unknown-asmjs`
7**and** you enabled either the `stdweb` or the `wasm-bindgen` feature. This emulation is based on the javascript `performance.now()` function.
8* A type alias for `std::time::Instant` otherwise.
9
10
11
12Note that even if the **stdweb** or **wasm-bindgen** feature is enabled, this crate will continue to rely on `std::time::Instant`
13as long as you are not targeting wasm32. This allows for portable code that will work on both native and WASM platforms.
14
15### The feature `now`.
16By enabling the feature `now` the function `instant::now()` will be exported and will either:
17
18* Call `performance.now()` when compiling for a WASM platform with the features **stdweb** or **wasm-bindgen** enabled, or using a custom javascript function.
19* Call `time::precise_time_s() * 1000.0` otherwise.
20
21The result is expressed in milliseconds.
22
23## Examples
24### Using `instant` for a native platform.
25_Cargo.toml_:
26```toml
27[dependencies]
28instant = "0.1"
29```
30
31_main.rs_:
32```rust
33fn main() {
34 // Will be the same as `std::time::Instant`.
35 let now = instant::Instant::new();
36}
37```
38
39-----
40
41### Using `instant` for a WASM platform.
42This example shows the use of the `stdweb` feature. It would be similar with `wasm-bindgen`.
43
44_Cargo.toml_:
45```toml
46[dependencies]
47instant = { version = "0.1", features = [ "stdweb" ] }
48```
49
50_main.rs_:
51```rust
52fn main() {
53 // Will emulate `std::time::Instant` based on `performance.now()`.
54 let now = instant::Instant::new();
55}
56```
57
58-----
59
60### Using `instant` for a WASM platform where `performance.now()` is not available.
61This example shows the use of the `inaccurate` feature.
62
63_Cargo.toml_:
64```toml
65[dependencies]
66instant = { version = "0.1", features = [ "wasm-bindgen", "inaccurate" ] }
67```
68
69_main.rs_:
70```rust
71fn main() {
72 // Will emulate `std::time::Instant` based on `Date.now()`.
73 let now = instant::Instant::new();
74}
75```
76
77
78-----
79
80### Using `instant` for any platform enabling a feature transitively.
81_Cargo.toml_:
82```toml
83[features]
84stdweb = [ "instant/stdweb" ]
85wasm-bindgen = [ "instant/wasm-bindgen" ]
86
87[dependencies]
88instant = "0.1"
89```
90
91_lib.rs_:
92```rust
93fn my_function() {
94 // Will select the proper implementation depending on the
95 // feature selected by the user.
96 let now = instant::Instant::new();
97}
98```
99
100-----
101
102### Using the feature `now`.
103_Cargo.toml_:
104```toml
105[features]
106stdweb = [ "instant/stdweb" ]
107wasm-bindgen = [ "instant/wasm-bindgen" ]
108
109[dependencies]
110instant = { version = "0.1", features = [ "now" ] }
111```
112
113_lib.rs_:
114```rust
115fn my_function() {
116 // Will select the proper implementation depending on the
117 // feature selected by the user.
118 let now_instant = instant::Instant::new();
119 let now_milliseconds = instant::now(); // In milliseconds.
120}
121```
122
123### Using the feature `now` without `stdweb` or `wasm-bindgen`.
124_Cargo.toml_:
125```toml
126[dependencies]
127instant = { version = "0.", features = [ "now" ] }
128```
129
130_lib.rs_:
131```rust
132fn my_function() {
133 // Will use the 'now' javascript implementation.
134 let now_instant = instant::Instant::new();
135 let now_milliseconds = instant::now(); // In milliseconds.
136}
137```
138
139_javascript WASM bindings file_:
140```js
141function now() {
142 return Date.now() / 1000.0;
143}
144```
145