vendor/instant/README.md

   1 # Instant
   2
   3 If you call `std::time::Instant::now()` on a WASM platform, it will panic. This crate provides a partial
   4 replacement 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
  12 Note that even if the **stdweb** or **wasm-bindgen** feature is enabled, this crate will continue to rely on `std::time::Instant`
  13 as 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`.
  16 By 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
  21 The result is expressed in milliseconds.
  22
  23 ## Examples
  24 ### Using `instant` for a native platform.
  25 _Cargo.toml_:
  26 ```toml
  27 [dependencies]
  28 instant = "0.1"
  29 ```
  30
  31 _main.rs_:
  32 ```rust
  33 fn 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.
  42 This example shows the use of the `stdweb` feature. It would be similar with `wasm-bindgen`.
  43
  44 _Cargo.toml_:
  45 ```toml
  46 [dependencies]
  47 instant = { version = "0.1", features = [ "stdweb" ] }
  48 ```
  49
  50 _main.rs_:
  51 ```rust
  52 fn 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.
  61 This example shows the use of the `inaccurate` feature.
  62
  63 _Cargo.toml_:
  64 ```toml
  65 [dependencies]
  66 instant = { version = "0.1", features = [ "wasm-bindgen", "inaccurate" ] }
  67 ```
  68
  69 _main.rs_:
  70 ```rust
  71 fn 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]
  84 stdweb = [ "instant/stdweb" ]
  85 wasm-bindgen = [ "instant/wasm-bindgen" ]
  86
  87 [dependencies]
  88 instant = "0.1"
  89 ```
  90
  91 _lib.rs_:
  92 ```rust
  93 fn 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]
 106 stdweb = [ "instant/stdweb" ]
 107 wasm-bindgen = [ "instant/wasm-bindgen" ]
 108
 109 [dependencies]
 110 instant = { version = "0.1", features = [ "now" ] }
 111 ```
 112
 113 _lib.rs_:
 114 ```rust
 115 fn 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]
 127 instant = { version = "0.", features = [ "now" ] }
 128 ```
 129
 130 _lib.rs_:
 131 ```rust
 132 fn 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
 141 function now() {
 142         return Date.now() / 1000.0;
 143 }
 144 ```