update documentation

README.md

@@ -1,8 +1,9 @@
 # Immutable
 
-| `master` | `develop` |
-|----------|-----------|
-|[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/Innmind/Immutable/?branch=master) [![Code Coverage](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/Innmind/Immutable/?branch=master) [![Build Status](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/build.png?b=master)](https://scrutinizer-ci.com/g/Innmind/Immutable/build-status/master)|[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/quality-score.png?b=develop)](https://scrutinizer-ci.com/g/Innmind/Immutable/?branch=develop) [![Code Coverage](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/coverage.png?b=develop)](https://scrutinizer-ci.com/g/Innmind/Immutable/?branch=develop) [![Build Status](https://scrutinizer-ci.com/g/Innmind/Immutable/badges/build.png?b=develop)](https://scrutinizer-ci.com/g/Innmind/Immutable/build-status/develop)|
+|  `develop` |
+|------------|
+| [![codecov](https://codecov.io/gh/Innmind/Immutable/branch/develop/graph/badge.svg)](https://codecov.io/gh/Innmind/Immutable) |
+| [![Build Status](https://travis-ci.org/Innmind/Immutable.svg?branch=develop)](https://travis-ci.org/Innmind/Immutable) |
 
 A set of classes to wrap PHP primitives to build immutable data.
 
@@ -14,15 +15,30 @@ To be used to wrap an ordered list of elements (elements can be of mixed types).
 
 ```php
 use Innmind\Immutable\Sequence;
+use function Innmind\Immutable\unwrap;
 
-$seq = new Sequence(24, 42, 'Hitchhiker', 'Magrathea');
+$seq = Sequence::of('mixed', 24, 42, 'Hitchhiker', 'Magrathea');
 $seq->get(2); // Hitchhiker
 $another = $seq->drop(2);
-$another->toPrimitive(); // [Hitchhiker, Magrathea]
-$seq->toPrimitive(); // [24, 42, Hitchhiker, Magrathea]
+unwrap($another); // [Hitchhiker, Magrathea]
+unwrap($seq); // [24, 42, Hitchhiker, Magrathea]
+
+//----
+// this example demonstrates the lazyness capability of the sequence
+// precisely here it's able to read a file line by line and echo the lines
+// that are less than 42 characters long (without requiring to load the whole
+// file in memory)
+$someFile = fopen('some/file.txt', 'r');
+$lines = Sequence::lazy('string', fn() => yield fgets($someFile))
+    ->filter(fn($line) => strlen($line) < 42);
+// at this point no reading to the file has been done because all methods
+// returning a new instance of a sequence will pipeline the operations to do,
+// allowing to chain complex logic while accessing the original data once and
+// without the need to keep the discarded data along the pipeline in memory
+$lines->foreach(fn($line) => echo($line));
 ```
 
-For a complete list of methods check [`SequenceInterface`](src/SequenceInterface.php).
+For a complete list of methods check [`Sequence`](src/Sequence.php).
 
 ## Set
 
@@ -31,40 +47,36 @@ To be used as a collection of unordered elements (elements must be of the same t
 ```php
 use Innmind\Immutable\Set;
 
-$set = new Set('int');
-$set = $set
-    ->add(24)
-    ->add(42);
-$set->equals((new Set('int'))->add(24)->add(42)); // true
+$set = Set::of('int', 24, 42);
+$set->equals(Set::of('int', 24, 42)); // true
 $set->add(42.0); // will throw as it's a float and not an integer
 ```
 
 The type passed in the constructor can be any primitive type (more precisely any type having a `is_{type}` function) or any class name.
 
-For a complete list of methods check [`SetInterface`](src/SetInterface.php).
+For a complete list of methods check [`Set`](src/Set.php).
 
 ## Map
 
 To be used as a collection of key/value pairs (both keys and values must be of the same type).
 
 ```php
 use Innmind\Immutable\Map;
-use Innmind\Immutable\Symbol;
-
-$map = new Map(Symbol::class, 'int');
-$map = $map
-    ->put(new Symbol('foo'), 42)
-    ->put($symbol = new Symbol('foo'), 24);
-$map->size(); // 2, because even if the symbols represent the same string it's 2 different instances
-$map->values()->toPrimitive(); // [42, 24]
-$map = $map->put($symbol, 66);
+use function Innmind\Immutable\unwrap;
+
+$map = Map::of('stdClass', 'int')
+    (new \stdClass, 42)
+    ($key = new \stdClass, 24);
+$map->size(); // 2, because it's 2 different instances
+unwrap($map->values()); // [42, 24]
+$map = $map->put($key, 66);
 $map->size(); // 2
-$map->values()->toPrimitive(); // [42, 66]
+unwrap($map->values()); // [42, 66]
 ```
 
 The types passed in the constructor can be any primitive type (more precisely any type having a `is_{type}` function) or any class name.
 
-For a complete list of methods check [`MapInterface`](src/MapInterface.php).
+For a complete list of methods check [`Map`](src/Map.php).
 
 **Note**: As a map is not a simple associative array, when you call `map` the return value can be an instance of [`Pair`](src/Pair.php). If this this the case, the key used to reference the original value will be replaced by the key from the `Pair` instance in the new `Map` instance.
 
@@ -73,39 +85,25 @@ For a complete list of methods check [`MapInterface`](src/MapInterface.php).
 ```php
 use Innmind\Immutable\Str;
 
-$var = new Str('the hitchhiker\'s guide to the galaxy');
+$var = Str::of('the hitchhiker\'s guide to the galaxy');
 echo $var
     ->replace('galaxy', '42') // the hitchhiker's guide to the 42
     ->substring(18) // guide to the 42
-    ->toUpper(); // outputs: GUIDE TO THE 42
-echo $var; // outputs: the hitchhiker\'s guide to the galaxy
+    ->toUpper()
+    ->toString(); // outputs: GUIDE TO THE 42
+echo $var->toString(); // outputs: the hitchhiker\'s guide to the galaxy
 ```
 
 ## Regular expressions
 
 ```php
 use Innmind\Immutable\{
     RegExp,
-    Str
+    Str,
 };
 
-$regexp = new RegExp('/(?<i>\d+)/');
+$regexp = RegExp::of('/(?<i>\d+)/');
 $regexp->matches(Str::of('foo123bar')); // true
 $regexp->matches(Str::of('foobar')); // false
-$regexp->capture(Str::of('foo123bar')); // MapInterface<scalar, Str> with index `i` set to Str::of('123')
+$regexp->capture(Str::of('foo123bar')); // Map<scalar, Str> with index `i` set to Str::of('123')
 ```
-
-## Range
-
-```php
-use Innmind\Immutable\NumericRange;
-
-$range = new NumericRange(0, 10, 1);
-$range->toPrimitive(); //[0, 1, 2, 3? 4, 5, 6, 7, 8, 9, 10]
-```
-
-`NumericRange` implements the `Iterator` interface and don't call the `range` function so you can build huge ranges as there's only the current range pointer being kept in the object.
-
-## Performance
-
-Latest [performance report](_storage/7e2/a/1d/133f0254e4c12bbe78b39429790c450a5e7e6d84.xml)