+ ZipApplicative docs

Author: gusty

docsrc/content/abstraction-applicative.fsx

@@ -26,9 +26,11 @@ Other operations
 
 * ``lift2``
 *)
+
 (**
-   static member Lift2 (f: 'T1 -> 'T2 -> 'T, x1: 'Applicative<'T1>, x2: 'Applicative<'T2>) : 'Applicative<'T>
+    static member Lift2 (f: 'T1 -> 'T2 -> 'T, x1: 'Applicative<'T1>, x2: 'Applicative<'T2>) : 'Applicative<'T>
 *)
+
 (**
 
 
@@ -62,44 +64,44 @@ From F#
  -  ``IObservable<'T>``
  -  ``Lazy<'T>``
  -  ``Async<'T>``
- -  ``Result<'T,'U>`` 
- -  ``Choice<'T,'U>``
- -  ``KeyValuePair<'Key,'T>``
+ -  ``Result<'T, 'U>`` 
+ -  ``Choice<'T, 'U>``
+ -  ``KeyValuePair<'Key, 'T>``
  -  ``'Monoid * 'T``
  -  ``ValueTuple<'Monoid, 'T>``
  -  ``Task<'T>``
  -  ``ValueTask<'T>``
- -  ``'R->'T``
+ -  ``'R -> 'T``
  -  ``Expr<'T>``
  -  ``ResizeArray<'T>``
  
 From F#+
 
  -  [``Identity<'T>``](type-identity.html)
- -  [``Cont<'R,'T>``](type-cont.html)
- -  [``ContT<'R,'T>``](type-contt.html)
- -  [``Reader<'R,'T>``](type-reader.html)
- -  [``ReaderT<'R,'Monad<'T>>``](type-readert.html)
- -  [``Writer<'Monoid,'T>``](type-writer.html)
+ -  [``Cont<'R, 'T>``](type-cont.html)
+ -  [``ContT<'R, 'T>``](type-contt.html)
+ -  [``Reader<'R, 'T>``](type-reader.html)
+ -  [``ReaderT<'R, 'Monad<'T>>``](type-readert.html)
+ -  [``Writer<'Monoid, 'T>``](type-writer.html)
  -  [``WriterT<'Monad<'T * 'Monoid>>``](type-writert.html)
- -  [``State<'S,'T * 'S>``](type-state.html)
- -  [``StateT<'S,'Monad<'T * 'S>>``](type-statet.html)
+ -  [``State<'S, 'T * 'S>``](type-state.html)
+ -  [``StateT<'S, 'Monad<'T * 'S>>``](type-statet.html)
  -  [``OptionT<'Monad<option<'T>>``](type-optiont.html)
  -  [``ValueOptionT<'Monad<voption<'T>>``](type-valueoptiont.html)
  -  [``SeqT<'Monad<seq<'T>>``](type-seqt.html)
  -  [``ListT<'Monad<list<'T>>``](type-listt.html)
- -  [``ResultT<'Monad<Result<'T,'TError>>``](type-resultt.html)
- -  [``ChoiceT<'Monad<Choice<'T,'TError>>``](type-choicet.html)
- -  [``Free<'Functor<'T>,'T>``](type-free.html)
+ -  [``ResultT<'Monad<Result<'T, 'TError>>``](type-resultt.html)
+ -  [``ChoiceT<'Monad<Choice<'T, 'TError>>``](type-choicet.html)
+ -  [``Free<'Functor<'T>, 'T>``](type-free.html)
  -  [``NonEmptyList<'T>``](type-nonempty.html)
- -  [``Validation<'Error,'T>``](type-validation.html)
+ -  [``Validation<'Error, 'T>``](type-validation.html)
  -  [``ZipList<'T>``](type-ziplist.html)
  -  [``ParallelArray<'T>``](type-parallelarray.html)
- -  [``Const<'C,'T>``](type-const.html)
+ -  [``Const<'C, 'T>``](type-const.html)
  -  [``Compose<'Applicative1<'Applicative2<'T>>>``](type-compose.html)
  -  [``DList<'T>``](type-dlist.html)
- -  [``Vector<'T,'Dimension>``](type-vector.html)
- -  [``Matrix<'T,'Rows,'Columns>``](type-matrix.html)
+ -  [``Vector<'T, 'Dimension>``](type-vector.html)
+ -  [``Matrix<'T, 'Rows, 'Columns>``](type-matrix.html)
  
 Restricted:
  -  ``string``

docsrc/content/abstraction-misc.fsx

@@ -32,11 +32,6 @@ let res113 = foldi (fun s i t -> t * s - i) 2 [|3;4;5|]
 let resSomeId20 = traversei (fun k t -> Some (10 + t)) (Tuple 10)
 
 
-// ZipFunctor
-
-let (x, y) = zip (async { return 1 }) (async { return '2' }) |> Async.RunSynchronously
-
-
 // Collection
 
 let a = skip 3 [1..10]

docsrc/content/abstraction-traversable.fsx

@@ -30,7 +30,7 @@ Minimal complete definition
 Other operations
 ----------------
 
- * ``gather f x`` | ``transpose x`` (same as traverse and sequence but operating on ZipApplicatives)
+ * ``gather f x`` | ``transpose x`` (same as ``traverse`` and ``sequence`` but operating on [ZipApplicatives](abstraction-zipapplicative.html) )
 *)
 (**
     static member Gather (t: 'Traversable<'T>, f: 'T -> 'ZipApplicative<'U>) : 'ZipApplicative<'Traversable<'U>>
@@ -55,7 +55,7 @@ Related Abstractions
 --------------------
 
  - [Functor](abstraction-functor.html): A traversable is generic on the Traversable type parameter and the (Applicative) Functor inner type parameter.
- - [Applicative](abstraction-applicative.html): An applicative is a functor whose ``map`` operation can be splitted in ``return`` and ``(<*>)`` operations. 
+ - [Applicative](abstraction-applicative.html): An applicative is a functor whose ``map`` operation can be splitted in ``return`` and ``(<*>)`` operations.
  - [Foldable](abstraction-foldable.html) : All traversables are foldables.
 
 

docsrc/content/abstraction-zipapplicative.fsx

@@ -4,13 +4,13 @@
 #r @"../../src/FSharpPlus/bin/Release/netstandard2.0/FSharpPlus.dll"
 
 (**
-ZipApplicative
-==============
+Zip Applicative (aka Non-sequential Applicative)
+================================================
 A functor with application, providing operations to embed pure expressions (``pur``), run computations pointwise and/or paralell and combine their results (``<.>``).
 ___
 Minimal complete definition
 ---------------------------
- * ``pur x`` &nbsp; . &nbsp; ``result x``
+ * ``pur x`` &nbsp;
  * ``(<.>) f x``
 *)
 (**
@@ -26,40 +26,59 @@ Other operations
 * ``zip``
 *)
 (**
-   static member Zip (x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>) : 'ZipApplicative<'T1 * 'T2>
+    static member Zip (x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>) : 'ZipApplicative<'T1 * 'T2>
+*)
+(**
+* ``unzip``
+*)
+(**
+    static member Unzip (x: 'ZipApplicative<'T1 * 'T2>) : 'ZipApplicative<'T1> * 'ZipApplicative<'T2>
 *)
 (**
 * ``map2``
 *)
 (**
-   static member Map2 (f: 'T1 -> 'T2 -> 'T, x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>) : 'ZipApplicative<'T>
+    static member Map2 (f: 'T1 -> 'T2 -> 'T, x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>) : 'ZipApplicative<'T>
 *)
 
 (**
 * ``map3``
 *)
 (**
-   static member Map3 (f: 'T1 -> 'T2 -> 'T3 -> 'T, x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>, x3: 'ZipApplicative<'T3>) : 'ZipApplicative<'T>
+    static member Map3 (f: 'T1 -> 'T2 -> 'T3 -> 'T, x1: 'ZipApplicative<'T1>, x2: 'ZipApplicative<'T2>, x3: 'ZipApplicative<'T3>) : 'ZipApplicative<'T>
 *)
 
 (**
 
 
 Rules
 -----
+
 *)
 (**
+
+Since ZipApplicatives are Applicatives they obey the same applicative rules:
+
     pur id <.> v = v
     pur (<<) <.> u <.> v <.> w = u <.> (v <.> w)
     pur f <*> pur x = pur (f x)
     u <*> pur y = pur ((|>) y) <.> u
 *)
+(**
+
+But they have some additional rules:
+
+    zip x y = tuple2 <!> x <.> y
+    unzip = map fst &&& map snd
+    id = unzip >> (<||) zip = (<||) zip >> unzip
+*)
+
 (**
 Related Abstractions
 --------------------
  - [Functor](abstraction-functor.html): A zipApplicative is a functor whose ``map`` operation can be splitted in ``pur`` and ``(<.>)`` operations,
  
- - [ZipApplicative](abstraction-applicative.html) : ZipApplicatives are applicatives which usually don't form a [Monad](abstraction-monad.html).
+ - [Applicative](abstraction-applicative.html) : ZipApplicatives are applicatives which usually don't form a [Monad](abstraction-monad.html), therefore the Applicative instance normally is not the same.
 
 Concrete implementations
 ------------------------
@@ -88,7 +107,7 @@ From F#+
  -  [``NonEmptyList<'T>``](type-nonempty.html)
  -  [``Compose<'ZipApplicative1<'ZipApplicative2<'T>>>``](type-compose.html)
 
- (*) The operation is the same as that for the normal applicative
+ (*) The operations are the same as those for the normal applicative
  
 
 Only for <*> operation:
@@ -115,8 +134,11 @@ Examples
 
 open FSharpPlus
 
+let (x, y) = zip (async { return 1 }) (async { return '2' }) |> Async.RunSynchronously
+// val y: char = '2'
+
 
-// pointwise operations
+// crossproduct vs pointwise operations
 
 let arr1 = (+) <!> [|1;2;3|] <*> [|10;20;30|]
 let arr2 = (+) <!> [|1;2;3|] <.> [|10;20;30|]
@@ -129,10 +151,10 @@ let arr2 = (+) <!> [|1;2;3|] <.> [|10;20;30|]
 
 let validated = applicative2' {
     let! x = async { return Ok 1 }
-    and! y = async { return Ok 2 }
-    and! z = async { return Error ["Error"] }
+    and! y = async { return Error ["Error1"] }
+    and! z = async { return Error ["Error2"] }
     return x + y + z
 }
 
 validated |> Async.RunSynchronously
-// val it: Result<int,string list> = Error ["Error"]
+// val it: Result<int,string list> = Error ["Error1"; "Error2"]

docsrc/content/computation-expressions.fsx

@@ -12,9 +12,11 @@ Computations Expressions
 
 This library allows to use some common computation expressions without writing any boiler plate code.
 
-For applicatives there is single computation expression: ``applicative { .. }``. Additionally ``applicative2 { .. }`` and ``applicative3 { .. }`` exists for composed (aka layered) applicatives.
+For [Applicatives](abstraction-applicative.html) there is single computation expression: ``applicative { .. }``. Additionally ``applicative2 { .. }`` and ``applicative3 { .. }`` exists for composed (aka layered) applicatives.
 
-For monadic code there is a single computation expression: ``monad { .. }`` but it comes in 4 flavours:
+For [ZipApplicatives](abstraction-zipapplicative.html) there is a counterpart set of computation expressions: ``applicative' { .. }``, ``applicative2' { .. }`` and ``applicative3' { .. }``.
+
+For [monadic](abstraction-monad.html) code there is a single computation expression: ``monad { .. }`` but it comes in 4 flavours:
 
  - Delayed or strict
 

docsrc/tools/templates/abstractions.plantuml

@@ -48,6 +48,14 @@ abstract class Alternative [[http://fsprojects.github.io/FSharpPlus/abstraction-
   + mfilter p x
 }
 
+abstract class ZipApplicative [[http://fsprojects.github.io/FSharpPlus/abstraction-zipapplicative.html]] {
+  + pur x
+  + (<.>) f x
+  ==
+  + map f x
+  + map2 f x y
+}
+
 abstract class Monad [[http://fsprojects.github.io/FSharpPlus/abstraction-monad.html]] {
   + return x
   + (>>=) x f
@@ -117,13 +125,15 @@ Functor  --|> Bifunctor
 Functor  --|> Applicative
 Applicative  --|> Monad
 Applicative  --|> Alternative
+ZipApplicative  --|> Alternative
 Monoid ..|> Monad
 Monoid ..|> Foldable
 Monoid ..|> Bifoldable
 Functor --|> Comonad
 Functor --|> Traversable
 Foldable --|> Traversable
 Bifoldable --|> Bitraversable
+Applicative ..|> ZipApplicative
 Applicative ..|> Bitraversable
 Applicative ..|> Traversable
 Monoid ..|> Alternative