Add README.md for package:collections_helpers.

pkg/collection_helpers/README.md

Index: pkg/collection_helpers/README.md
diff --git a/pkg/collection_helpers/README.md b/pkg/collection_helpers/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..db6cce34d1f40c40cc0298ad51a6d4e2a5921962
--- /dev/null
+++ b/pkg/collection_helpers/README.md
@@ -0,0 +1,54 @@
+Helper libraries for working with collections.
+
+The collection_helpers package contains a number of separate libraries

[Søren Gjesse, 2013/11/01 10:29:52]

collection_helpers in ``'s

+with utility functions and classes that makes working with collections easier.
+
+## Using
+
+The collection_helpers library can be imported as separate libraries, or
+in totality:
+
+    import 'package:collection_helpers/equality.dart';
+    import 'package:collection_helpers/algorithms.dart';
+    import 'package:collection_helpers/wrappers.dart';
+
+or
+
+    import 'package:collection_helpers/all.dart';
+
+## Equality
+
+The equality library gives a way to specify equality of elements and
+collections.
+
+Collections in dart have no inherent equality. Two sets are not equal, even

[Søren Gjesse, 2013/11/01 10:29:52]

Dart with uppercase D.

+if they contain exactly the same objects as elements.
+
+The equality library provides a way to say define such an equality. In this
+case, for example, `const SetEquality(const IdentityEquality())` is an equality
+that considers two sets equal exactly if they contain identical elements.
+
+The library provides ways to define equalities on iterables, lists, sets, and

[Søren Gjesse, 2013/11/01 10:29:52]

Maybe iterables -> `Iterable`s (and for lists and sets as well).

+maps, as well as combinations of these, such as:
+
+    const MapEquality(const IdentityEquality(), const ListEquality());
+
+

[Søren Gjesse, 2013/11/01 10:29:52]

Maybe explain what this equality actually expresses.

+## Algorithms
+
+The algorithms library contains functions that operate on lists.
+
+It contains ways to shuffle a list, do binary search on a sorted list, and

[Søren Gjesse, 2013/11/01 10:29:52]

list -> `List`

+some different sorting algorithms.
+
+
+## Wrappers
+
+The wrappers library contains classes that "wrap" a collection.
+
+A wrapper class contains an object of the same type, and it forwards all
+methods to the wrapped object.
+
+Wrapper classes can be used in various ways, for example to restrict the type
+of an object to that of a supertype, or to change the behavior of selected
+functions on an existing object.