Fix cargo bench --features=bench

This commit makes `use std:convert::TryInto` conditional via
`#[cfg(debug_assertions)]`.  This avoids the following build error:

    ```
    $ cargo bench
    ...
    error: unused import: `std::convert::TryInto`
     --> src/cast.rs:1:5
      |
    1 | use std::convert::TryInto;
      |     ^^^^^^^^^^^^^^^^^^^^^
    ```

This commit also opts into the `test` feature (only if the "bench"
feature is requested, because benchmarking is only available in the
nightly version of the compiler) and declares the `extern crate test`
dependency on the compiler-provided `test` crate. This avoids the
following build errors:

    ```
    $ cargo bench
    ...
    error[E0433]: failed to resolve: use of undeclared crate or module `test`
       --> src/optimize.rs:710:33
        |
    710 | fn bench_optimize(bencher: &mut test::Bencher) {
        |                                 ^^^^
                   use of undeclared crate or module `test`
    ```

    ```
    $ cargo bench
    ...
    error[E0658]: use of unstable library feature 'test'
       --> src/optimize.rs:710:33
        |
    710 | fn bench_optimize(bencher: &mut test::Bencher) {
        |                                 ^^^^^^^^^^^^^
        |
        = note: see issue #50297
                <rust-lang/rust#50297>
                for more information
        = help: add `#![feature(test)]` to the crate attributes to enable
    ```

This commit also makes small tweaks to how `README.md` is included.
It seems that this doesn't actually test the examples in the `README.md`
file (this commit adds a TODO for this observation), but it does avoid
the following build error:

    ```
    $ cargo bench --features=bench
    ...
    error: unknown `doc` attribute `include`
      --> src/lib.rs:14:36
       |
    14 | #![cfg_attr(feature = "bench", doc(include = "../README.md"))]
       |                                ----^^^^^^^^^^^^^^^^^^^^^^^^- help:
       |                                use `doc = include_str!` instead:
       |                           `#![doc = include_str!("../README.md")]`
       |
       = warning: this was previously accepted by the compiler but is being
         phased out; it will become a hard error in a future release!
       = note: for more information, see issue #82730
         <rust-lang/rust#82730>
    ```

Finally, this commit declares the "bench" feature in `Cargo.toml`.
After these changes the following command line succeeds:

    ```
    $ cargo bench --features=bench
    ...
    test bits::bench_find_min_version    ... bench:           1 ns/iter (+/- 0)
    test bits::bench_push_splitted_bytes ... bench:       3,862 ns/iter (+/- 58)
    test optimize::bench_optimize        ... bench:          19 ns/iter (+/- 0)
    ```

Cargo.toml

@@ -23,6 +23,7 @@ rand = "0.7.3"
 hex = "0.4.2"
 
 [features]
+#bench = [] - uncomment if using rustc nigthly and want to run benchmarks
 bmp = ["bmp-monochrome"]
 decode = ["g2p"]
 fuzz = ["arbitrary"]

src/cast.rs

@@ -1,4 +1,6 @@
+#[cfg(debug_assertions)]
 use std::convert::TryInto;
+
 use std::fmt::Display;
 
 // TODO remove this, use try_into wher as_* is used

src/lib.rs

@@ -12,12 +12,20 @@
     clippy::match_like_matches_macro, // MSRV is lower than what's needed for matches!
     clippy::wrong_self_convention, // TODO fix code and remove
 )]
-#![cfg_attr(feature = "bench", doc(include = "../README.md"))]
-// ^ make sure we can test our README.md.
+// TODO: Fix coverage of examples from our README.md - apparently the incantation below is not
+// sufficient for this.
+#![cfg_attr(feature = "bench", doc = include_str!("../README.md"))]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // No `unsafe` please.  If `unsafe` is really needed, then please
 // consider encapsulating it in a separate crates.io crate.
 #![forbid(unsafe_code)]
+// Using `#[bench]`, `test::Bencher`, and `cargo bench` requires opting into the unstable `test`
+// feature.  See https://github.com/rust-lang/rust/issues/50297 for more details.  Unstable
+// features are only available in the nightly versions of the Rust compiler - to keep stable
+// builds working we only enable benching behind the "bench" feature.
+#![cfg_attr(feature = "bench", feature(test))]
+#[cfg(feature = "bench")]
+extern crate test;
 
 // Re-exported dependencies.
 #[cfg(feature = "bmp")]