Chris Morgan  ›  Git  ›  anymap  ›  blobdiff
Revise README.md for accuracy and flow
[anymap] / README.md
diff --git a/README.md b/README.md
index 629a8e33bf3f650dd30bc0cd7aacbf8eca3fc7ac..798f925ef200ec5ddb23d56d8e1847d23bfda631 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,51 +1,82 @@
-``AnyMap``, a safe and convenient store for one value of each type
-==================================================================
+# ``AnyMap``, a safe and convenient store for one value of each type
 
 
-[![Build Status](https://travis-ci.org/chris-morgan/anymap.svg?branch=master)](https://travis-ci.org/chris-morgan/anymap)
+``AnyMap`` is a type-safe wrapper around ``HashMap<TypeId, Box<dyn Any>>`` that lets you not worry about ``TypeId`` or downcasting, but just get on with storing one each of a bag of diverse types, which is really useful for extensibility in some sorts of libraries.
+
+## Background
 
 If you’re familiar with Go and Go web frameworks, you may have come across the common “environment” pattern for storing data related to the request. It’s typically something like ``map[string]interface{}`` and is accessed with arbitrary strings which may clash and type assertions which are a little unwieldy and must be used very carefully. (Personally I would consider that it is just *asking* for things to blow up in your face.) In a language like Go, lacking in generics, this is the best that can be done; such a thing cannot possibly be made safe without generics.
 
 
 If you’re familiar with Go and Go web frameworks, you may have come across the common “environment” pattern for storing data related to the request. It’s typically something like ``map[string]interface{}`` and is accessed with arbitrary strings which may clash and type assertions which are a little unwieldy and must be used very carefully. (Personally I would consider that it is just *asking* for things to blow up in your face.) In a language like Go, lacking in generics, this is the best that can be done; such a thing cannot possibly be made safe without generics.
 
-As another example of such an interface, JavaScript objects are exactly the same—a mapping of string keys to arbitrary values. (There it is actually *more* dangerous, because methods and fields/attributes/properties are on the same plane.)
+As another example of such an interface, JavaScript objects are exactly the same—a mapping of string keys to arbitrary values. (There it is actually *more* dangerous, because methods and fields/attributes/properties are on the same plane—though it’s *possible* to use `Map` these days.)
 
 Fortunately, we can do better than these things in Rust. Our type system is quite equal to easy, robust expression of such problems.
 
 
 Fortunately, we can do better than these things in Rust. Our type system is quite equal to easy, robust expression of such problems.
 
-The ``AnyMap`` type is a friendly wrapper around a ``HashMap<TypeId, Box<Any>>``, exposing a nice, easy typed interface, perfectly safe and absolutely robust.
+## Example
 
 
-What this means is that in an ``AnyMap`` you may store zero or one values for every type.
+```rust
+let mut data = anymap::AnyMap::new();
+assert_eq!(data.get(), None::<&i32>);
+data.insert(42i32);
+assert_eq!(data.get(), Some(&42i32));
+data.remove::<i32>();
+assert_eq!(data.get::<i32>(), None);
 
 
-Instructions
-------------
+#[derive(Clone, PartialEq, Debug)]
+struct Foo {
+    str: String,
+}
 
 
-Cargo all the way: it is `anymap` on crates.io.
+assert_eq!(data.get::<Foo>(), None);
+data.insert(Foo { str: format!("foo") });
+assert_eq!(data.get(), Some(&Foo { str: format!("foo") }));
+data.get_mut::<Foo>().map(|foo| foo.str.push('t'));
+assert_eq!(&*data.get::<Foo>().unwrap().str, "foot");
+```
 
 
-Unsafe code in this library
----------------------------
+## Features
 
 
-This library uses a fair bit of unsafe code for several reasons:
+- Store up to one value for each type in a bag.
+- Add `Send` or `Send + Sync` bounds.
+- You can opt into making the map `Clone`. (In theory you could add all kinds of other functionality, but you can’t readily make this work *generically*, and the bones of it are simple enough that it becomes better to make your own extension of `Any` and reimplement `AnyMap`.)
+- no_std if you like.
+
+## Cargo features/dependencies/usage
+
+Typical Cargo.toml usage:
 
 
-- To support Any and CloneAny, unsafe code is required (because of how the `downcast` methods are defined in `impl Any` rather than being trait methods; I think this is kind of a historical detail of the structure of `std::any::Any`); if you wanted to ditch `Clone` support this unsafety could be removed.
+```toml
+[dependencies]
+anymap = "1.0.0-beta.1"
+```
 
 
-- In the interests of performance, skipping various checks that are unnecessary because of the invariants of the data structure (no need to check the type ID when it’s been statically ensured by being used as the hash map key) and simplifying hashing (type IDs are already good hashes, no need to mangle them through SipHash).
+No-std usage, using `alloc` and the [hashbrown](https://rust-lang.github.io/hashbrown) crate instead of `std::collections::HashMap`:
 
 
-It’s not possible to remove all unsafety from this library without also removing some of the functionality. Still, at the cost of the `CloneAny` functionality, the raw interface and maybe the concurrency support, you can definitely remove all unsafe code. Here’s how you could do it:
+```toml
+[dependencies]
+anymap = { version = "1.0.0-beta.1", default-features = false, features = ["hashbrown"] }
+```
 
 
-- Remove the genericness of it all;
-- Merge `anymap::raw` into the normal interface, flattening it;
-- Change things like `.map(|any| unsafe { any.downcast_unchecked() })` to `.and_then(|any| any.downcast())` (performance cost: one extra superfluous type ID comparison, indirect);
-- Ditch the `TypeIdHasher` since transmuting a `TypeId` is right out (cost: SIP mangling of a u64 on every access).
+The `std` feature is enabled by default. The `hashbrown` feature overrides it. At least one of the two must be enabled.
+
+**On stability:** hashbrown is still pre-1.0.0 and experiencing breaking changes. Because it’s useful for a small fraction of users, I am retaining it, but with *different compatibility guarantees to the typical SemVer ones*. Where possible, I will just widen the range for new releases of hashbrown, but if an incompatible change occurs, I may drop support for older versions of hashbrown with a bump to the *minor* part of the anymap version number (e.g. 1.1.0, 1.2.0). Iff you’re using this feature, this is cause to *consider* using a tilde requirement like `"~1.0"` (or spell it out as `>=1, <1.1`).
+
+## Unsafe code in this library
+
+This library uses a fair bit of unsafe code for several reasons:
 
 
-Yeah, the performance costs of going safe are quite small. The more serious matters are the loss of `Clone` and maybe `Send + Sync`.
+- To support `CloneAny`, unsafe code is currently required (because the downcast methods are defined on `dyn Any` rather than being trait methods, and upcasting is an incomplete feature in rustc); if you wanted to ditch `Clone` support this unsafety could be removed.
 
 
-But frankly, if you wanted to do all this it’d be easier and faster to write it from scratch. The core of the library is actually really simple and perfectly safe, as can be seen in [`src/lib.rs` in the first commit](https://github.com/chris-morgan/anymap/tree/a294948f57dee47bb284d6a3ae1b8f61a902a03c/src/lib.rs) (note that that code won’t run without a few syntactic alterations; it was from well before Rust 1.0 and has things like `Any:'static` where now we have `Any + 'static`).
+- For `dyn CloneAny + Send` and `dyn CloneAny + Send + Sync`’s `Clone` implementation, an unsafe block is used to attach the auto traits where safe code used to be used, in order to avoid a [spurious future-compatibility lint](https://github.com/rust-lang/rust/issues/51443#issuecomment-421988013).
 
 
-Author
-------
+- In the interests of performance, type ID checks are skipped as unnecessary because of the invariants of the data structure (though this does come at the cost of `Map::{as_raw_mut, into_raw}` being marked unsafe).
 
 
-[Chris Morgan](http://chrismorgan.info/) ([chris-morgan](https://github.com/chris-morgan)) is the primary author and maintainer of AnyMap.
+It is possible to remove all unsafe code at the cost of only `CloneAny` functionality and a little performance. The `safe` branch in the Git repository contains a couple of commits demonstrating the concept. It’s quite straightforward; the core of this library is very simple and perfectly safe.
 
 
-License
--------
+## Colophon
 
 
-This library is distributed under similar terms to Rust: dual licensed under the MIT license and the Apache license (version 2.0).
+**Authorship:** [Chris Morgan](https://chrismorgan.info/) is the author and maintainer of this library.
 
 
-See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.
+**Licensing:** this library is distributed under the terms of the
+[Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), the
+[MIT License](https://opensource.org/licenses/MIT) and the
+[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), at your choice.
+See [COPYING](COPYING) for details.