From e51f409cb8439d5af0653439b5b9efe1d8b33f14 Mon Sep 17 00:00:00 2001
From: Christophe Grand <christophe@cgrand.net>
Date: Fri, 4 Sep 2015 14:21:14 +0200
Subject: [PATCH] Explaining how partitioning works.

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index d2b95b7..49139e3 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,28 @@ Padding can be achieved using the `pad` function:
 {false {:sum 16256, :mean 127, :count 128}, true {:sum 16384, :mean 128, :count 128}}
 ```
 
+## On Partitioning
+
+Both `by-key` and `partition` takes a transducer as parameter. This transducer is used to further process each partition.
+
+It's worth noting that all transformed outputs are subsequently interleaved. See:
+
+```clj
+=> (sequence (x/partition 2 1 identity) (range 8))
+(0 1 1 2 2 3 3 4 4 5 5 6 6 7 7)
+=> (sequence (x/by-key odd? identity) (range 8))
+([false 0] [true 1] [false 2] [true 3] [false 4] [true 5] [false 6] [true 7])
+```
+
+That's why most of the time the last stage of the sub-transducer will be a `x/reduce` or a `x/into`:
+
+```clj
+=> (sequence (x/partition 2 1 (x/into [])) (range 8))
+([0 1] [1 2] [2 3] [3 4] [4 5] [5 6] [6 7] [7])
+=> (sequence (x/by-key odd? (x/into [])) (range 8))
+([false [0 2 4 6]] [true [1 3 5 7]])
+```
+
 ## License
 
 Copyright © 2015 Christophe Grand