Add documentation about PinLayout’s performance.

The performance are really incredible, I didn’t know they would be that great.

As you can see in the following chart, PinLayout's performance is as fast as manual layouting, and up to **12x faster than auto layout**, and **16x faster than UIStackViews**. LayoutKit is also realy fast, slightly slower than PinLayout and manual layouting.

These results also means that PinLayout is by far faster than any layout frameworks that is built over auto layout ([SnapKit](https://github.com/SnapKit/SnapKit), [Stevia](https://github.com/freshOS/Stevia), [PureLayout](https://github.com/PureLayout/PureLayout), ...).

It takes almost half a second (0.468 ms) to render 100 UICollectionView's cells using UIStackViews, and 1/3 of second (0.344) using auto layout. And all these results are on a iPhone 6S device.

Author: Luc Dion

Docs/Benchmark.md

@@ -0,0 +1,50 @@
+<p align="center">
+	<img src="pinlayout-logo-small.png" alt="PinLayout Performance" width=100/>
+</p>
+
+<h1 align="center" style="color: #376C9D; font-family: Arial Black, Gadget, sans-serif; font-size: 1.5em">PinLayout Benchmark</h1>
+
+## Methodology
+
+##### LayoutKit Benchmark
+PinLayout's performance has been tested using a fork of [LayoutKit](https://github.com/mirego/LayoutKit). LayoutKit's example app include a really nice benchmark. 
+
+The benchmark has been modified to also include PinLayout. [See PinLayout implementation source code](https://github.com/mirego/LayoutKit/blob/master/LayoutKitSampleApp/Benchmarks/FeedItemPinLayoutView.swift). Remark that PinLayout's layout code is concise, clean and doesn't contain any computation in `layoutSubviews()`, compared to [Manual Layouting source code](https://github.com/mirego/LayoutKit/blob/master/LayoutKitSampleApp/Benchmarks/FeedItemManualView.swift)
+
+The benchmark include tests for the following layout systems:
+
+* Auto layout
+* Auto layout using UIStackViews
+* LayoutKit
+* Manual layout (i.e. set UIView's frame directly)
+* PinLayout
+
+Anyone who would like to integrate any other layout frameworks to this GitHub repository is welcome.
+
+##### Benchmark details
+The LayoutKit benchmark layout UICollectionView and UITableView cells in multiple pass, each pass contains more cells than the previous one. The **X axis** in following charts indicates the number of cell contained for each pass. The **Y axis** indicates the number of miliseconds to render all cells from one pass.
+
+Here are the rendering results to compare visual results:
+ 
+* [Auto layout rendering result](Benchmark/Benchmark-Autolayout.png)
+* [LayoutKit rendering result](Benchmark/Benchmark-PinLayout.png)
+* [PinLayout rendering result](Benchmark/Benchmark-LayoutKit.png)
+
+## Results
+
+As you can see in the following chart, PinLayout's performance is as fast as manual layouting, and up to **12x faster than auto layout**, and **16x faster than UIStackViews**. LayoutKit is also realy fast, slightly slower than PinLayout and manual layouting.
+
+These results also means that PinLayout is by far faster than any layout frameworks that is built over auto layout ([SnapKit](https://github.com/SnapKit/SnapKit), [Stevia](https://github.com/freshOS/Stevia), [PureLayout](https://github.com/PureLayout/PureLayout), ...). 
+
+It takes almost half a second (0.468 ms) to render 100 UICollectionView's cells using UIStackViews, and 1/3 of second (0.344) using auto layout. And all these results are on a iPhone 6S device.
+
+
+<p align="center">iPhone 6S - iOS 10.3.2</p>
+<p align="center">
+  <a href="https://mirego.github.io/PinLayout/"><img src="Benchmark/Chart-iPhone6S.png" alt="PinLayout Performance"/></a>
+<p align="center" style="font-size:10px;">X axis in the number cells in a UICollectionView, and Y axis is the time in miliseconds to layout all cells.</p>
+</p> 
+
+You can have a look at the [spreadsheet containing all the data](Benchmark/Benchmark-iPhone6S.xlsx)
+
+### Other device's chart will be coming soon...

Docs/Benchmark/Benchmark-Autolayout.png

@@ -16,14 +16,14 @@
 
 <br>
 
-Swift manual views layouting without auto layout, no magic, pure code, full control. Concise syntax, readable & chainable.
+Swift manual views layouting without auto layout, no magic, pure code, full control and FAST! Concise syntax, readable & chainable.
 
 > "No auto-layout constraints attached"
 
 <br>
 
 * [PinLayout principles and philosophy](#introduction)
-* [Installation](#installation)
+* [Performance](#performance)
 * [Documentation](#documentation)
     * [Layout using distances from superview’s edges](#distance_from_superview_edge) 	  
     * [Anchors](#anchors)
@@ -34,6 +34,7 @@ Swift manual views layouting without auto layout, no magic, pure code, full cont
    	* [Warnings](#warnings)
    	* [More examples](#more_examples)
 
+* [Installation](#installation)
 * [FAQ](#faq)
 * [Comments, ideas, suggestions, issues, ....](#comments)
 
@@ -42,6 +43,7 @@ Swift manual views layouting without auto layout, no magic, pure code, full cont
 ## PinLayout principles and philosophy <a name="introduction"></a>
 
 * Manual layouting. No magic, pure code, full control.
+* Fast, PinLayout exist to be simple and fast as possible! In fact it is fast as manual layouting. See [performance results below.](#performance)
 * Layout one view at a time. 
 * Concise syntax. Layout most views using a single line. 
 
@@ -71,39 +73,24 @@ A view can be layouted using PinLayout and later with another method/framework.
 
 <br>
 
-## Installation <a name="installation"></a>
+# PinLayout's Performance <a name="performance"></a>
 
-### CocoaPods
+PinLayout's performance has been measured using the excellent LayoutKit benchmark, which has been developped to compared LayoutKit performance over UIStackView, Auto layout and manual layouting. [PinLayout has been added to this benchmark](https://github.com/mirego/LayoutKit)
+ to compare its performance. 
 
-To integrate PinLayout into your Xcode project using CocoaPods, specify it in your `Podfile`:
+As you can see in the following chart, PinLayout's performance is as fast as manual layouting, and up to **12x faster than auto layout**, and **16x faster than UIStackViews**. 
 
-```ruby
-    pod 'PinLayout'
-```
+These results also means that **PinLayout is by far faster than any layout frameworks that is built over auto layout**. 
 
-Then, run `pod install`.
-
-### Carthage
-
-To integrate PinLayout into your Xcode project using Carthage, specify it in your `Cartfile`:
-
-```ogdl
-github "mirego/PinLayout"
-```
+[More details and explanation of the benchmark](Docs/Benchmark)
 
-Then, run `carthage update` to build the framework and drag the built `PinLayout.framework` into your Xcode project.
-
-### Swift Package Manager
-
-Once you have your Swift package set up, you only need to add PinLayout as a dependency of your `Package.swift`.
-
-```ogdl
-dependencies: [
-    .Package(url: "https://github.com/mirego/PinLayout.git", majorVersion: 1)
-]
-```
+<p align="center"> Tested on a iPhone 6S iOS 10.3.2</p>
+<p align="center">
+  <a href="https://mirego.github.io/PinLayout/"><img src="Docs/Benchmark/Chart-iPhone6S.png" alt="PinLayout Performance" width=500/></a>
+<p align="center" style="font-size:10px;">X axis in the number cells in a UICollectionView, and Y axis is the time in miliseconds to layout all cells.</p>
+</p> 
 
-<br>
+<br/>
 
 # Usage sample
 ###### Example:
@@ -133,13 +120,12 @@ override func layoutSubviews() {
 }
 ``` 
 
-:pushpin: This example and some other examples are available in the **PinLayoutSample** project. Please note that you must do a `pod install` before running the sample project. 
+:pushpin: This example and some other examples are available in the **Example** project. Please note that you must do a `pod install` before running the example project. 
 
 :pushpin: PinLayout doesn't use auto layout constraints, it is a framework that manually layout views. For that reason you need to update the layout inside either `UIView.layoutSubviews()` or `UIViewController.viewDidLayoutSubviews()` to handle container size's changes, including device rotation. You'll also need to handle UITraitCollection changes for app's that support multitask. In the example above PinLayout's commands are inside UIView's `layoutSubviews()` method.
 
 <br/>
 
-
 # Documentation <a name="documentation"></a>
 
 ## Layout using distances from superview’s edges <a name="distance_from_superview_edge"></a>
@@ -788,6 +774,40 @@ Cell D:
 
 <br>
 
+## Installation <a name="installation"></a>
+
+### CocoaPods
+
+To integrate PinLayout into your Xcode project using CocoaPods, specify it in your `Podfile`:
+
+```ruby
+    pod 'PinLayout'
+```
+
+Then, run `pod install`.
+
+### Carthage
+
+To integrate PinLayout into your Xcode project using Carthage, specify it in your `Cartfile`:
+
+```ogdl
+github "mirego/PinLayout"
+```
+
+Then, run `carthage update` to build the framework and drag the built `PinLayout.framework` into your Xcode project.
+
+### Swift Package Manager
+
+Once you have your Swift package set up, you only need to add PinLayout as a dependency of your `Package.swift`.
+
+```ogdl
+dependencies: [
+    .Package(url: "https://github.com/mirego/PinLayout.git", majorVersion: 1)
+]
+```
+
+<br>
+
 ## Coming soon <a name="coming_soon"></a>
 * minWidth/maxWidth, minHeight/maxHeight
 * CALayer support