third_party/rust/fallible_collections/README.md

   1 Fallible Collections.rs
   2 ==============
   3
   4 Implement api on rust collection wich returns a result when an allocation error occurs.
   5 This is inspired a lot by [RFC 2116](https://github.com/rust-lang/rfcs/blob/master/text/2116-alloc-me-maybe.md).
   6
   7 The api currently propose a fallible interface for Vec, Box, Arc, Btree and Rc,
   8 a TryClone trait wich is implemented for primitive rust traits and a fallible format macro.
   9
  10 You can use this with try_clone_derive crate wich derive TryClone for your own types.
  11
  12 # Getting Started
  13
  14 [fallible collections is available on crates.io](https://crates.io/crates/fallible_collections).
  15 It is recommended to look there for the newest released version, as well as links to the newest builds of the docs.
  16
  17 At the point of the last update of this README, the latest published version could be used like this:
  18
  19 Add the following dependency to your Cargo manifest...
  20 Add feature std and rust_1_57 to use the stabilized try_reserve api and the std HashMap type.
  21
  22 ```toml
  23 [dependencies]
  24 fallible_collections = "0.4"
  25
  26 # or
  27 fallible_collections = { version = "0.4", features = ["std", "rust_1_57"] }
  28 ```
  29
  30 ...and see the [docs](https://docs.rs/fallible_collections) for how to use it.
  31
  32 # Example
  33
  34 Exemple of using the FallibleBox interface.
  35 ```rust
  36 use fallible_collections::FallibleBox;
  37
  38 fn main() {
  39         // this crate an Ordinary box but return an error on allocation failure
  40         let mut a = <Box<_> as FallibleBox<_>>::try_new(5).unwrap();
  41         let mut b = Box::new(5);
  42
  43         assert_eq!(a, b);
  44         *a = 3;
  45         assert_eq!(*a, 3);
  46 }
  47 ```
  48
  49 Exemple of using the FallibleVec interface.
  50 ```rust
  51 use fallible_collections::FallibleVec;
  52
  53 fn main() {
  54         // this crate an Ordinary Vec<Vec<u8>> but return an error on allocation failure
  55         let a: Vec<Vec<u8>> = try_vec![try_vec![42; 10].unwrap(); 100].unwrap();
  56         let b: Vec<Vec<u8>> = vec![vec![42; 10]; 100];
  57         assert_eq!(a, b);
  58         assert_eq!(a.try_clone().unwrap(), a);
  59         ...
  60 }
  61 ```
  62
  63 ## License
  64
  65 Licensed under either of
  66
  67  * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
  68  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
  69
  70 at your option.
  71
  72 ### Contribution
  73
  74 Unless you explicitly state otherwise, any contribution intentionally submitted
  75 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
  76 additional terms or conditions.
  77