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
15This crate also exports the function `instant::now()` which returns a representation of the current time as an `f64`, expressed in milliseconds, in a platform-agnostic way. `instant::now()` will either:
16
17* Call `performance.now()` when compiling for a WASM platform with the features **stdweb** or **wasm-bindgen** enabled, or using a custom javascript function.
18* Return the time elapsed since the *Unix Epoch* on *native*, *non-WASM* platforms.
19
20*Note*: The old feature, `now`, has been deprecated. `instant::now()` is always exported and the `now` feature flag no longer has any effect. It remains listed in `Cargo.toml` to avoid introducing breaking changes and may be removed in future versions.
21
22## Examples
23### Using `instant` for a native platform.
24_Cargo.toml_:
25```toml
26[dependencies]
27instant = "0.1"
28```
29
30_main.rs_:
31```rust
32fn main() {
33    // Will be the same as `std::time::Instant`.
34    let now = instant::Instant::now();
35}
36```
37
38-----
39
40### Using `instant` for a WASM platform.
41This example shows the use of the `stdweb` feature. It would be similar with `wasm-bindgen`.
42
43_Cargo.toml_:
44```toml
45[dependencies]
46instant = { version = "0.1", features = [ "stdweb" ] }
47```
48
49_main.rs_:
50```rust
51fn main() {
52    // Will emulate `std::time::Instant` based on `performance.now()`.
53    let now = instant::Instant::now();
54}
55```
56
57-----
58
59### Using `instant` for a WASM platform where `performance.now()` is not available.
60This example shows the use of the `inaccurate` feature.
61
62_Cargo.toml_:
63```toml
64[dependencies]
65instant = { version = "0.1", features = [ "wasm-bindgen", "inaccurate" ] }
66```
67
68_main.rs_:
69```rust
70fn main() {
71    // Will emulate `std::time::Instant` based on `Date.now()`.
72    let now = instant::Instant::now();
73}
74```
75
76
77-----
78
79### Using `instant` for any platform enabling a feature transitively.
80_Cargo.toml_:
81```toml
82[features]
83stdweb = [ "instant/stdweb" ]
84wasm-bindgen = [ "instant/wasm-bindgen" ]
85
86[dependencies]
87instant = "0.1"
88```
89
90_lib.rs_:
91```rust
92fn my_function() {
93    // Will select the proper implementation depending on the
94    // feature selected by the user.
95    let now = instant::Instant::now();
96}
97```
98
99-----
100
101### Using `instant::now()`
102_Cargo.toml_:
103```toml
104[features]
105stdweb = [ "instant/stdweb" ]
106wasm-bindgen = [ "instant/wasm-bindgen" ]
107
108[dependencies]
109instant = "0.1"
110```
111
112_lib.rs_:
113```rust
114fn my_function() {
115    // Will select the proper implementation depending on the
116    // feature selected by the user.
117    let now_instant = instant::Instant::now();
118    let now_milliseconds = instant::now(); // In milliseconds.
119}
120```
121
122### Using the feature `now` without `stdweb` or `wasm-bindgen`.
123_Cargo.toml_:
124```toml
125[dependencies]
126instant = "0.1"
127```
128
129_lib.rs_:
130```rust
131fn my_function() {
132    // Will use the 'now' javascript implementation.
133    let now_instant = instant::Instant::now();
134    let now_milliseconds = instant::now(); // In milliseconds.
135}
136```
137
138_javascript WASM bindings file_:
139```js
140function now() {
141	return Date.now() / 1000.0;
142}
143```
144