From 6cb17bb94b8bc31bd0a32e3c2d0a4453bc914eab Mon Sep 17 00:00:00 2001
From: Stephen Diehl <stephen.m.diehl@gmail.com>
Date: Sat, 10 Dec 2016 16:01:47 +0000
Subject: [PATCH] utility functions

---
 docs/Applicative.md | 13 +++++++++++
 docs/Bits.md        | 55 +++++++++++++++++++++++++++++++++++++++++++++
 docs/Bool.md        |  4 ++++
 docs/Exceptions.md  | 18 +++++++++++++--
 docs/Function.md    | 16 +++++++++++++
 docs/List.md        |  4 ++++
 docs/Monad.md       | 16 +++++++++++++
 docs/Monoid.md      | 35 +++++++++++++++++++++++++++++
 8 files changed, 159 insertions(+), 2 deletions(-)

diff --git a/docs/Applicative.md b/docs/Applicative.md
index ef14d9b28..d21dd9b99 100644
--- a/docs/Applicative.md
+++ b/docs/Applicative.md
@@ -41,6 +41,11 @@ orEmpty :: Alternative f => Bool -> a -> f a
 eitherA :: (Alternative f) => f a -> f b -> f (Either a b)
 ```
 
+```haskell
+pass :: Applicative f => f ()
+```
+
+
 Alternative 
 -------
 
@@ -75,3 +80,11 @@ liftA :: Applicative f => (a -> b) -> f a -> f b
 ```haskell
 empty :: Alternative f => f a
 ```
+
+```haskell
+guarded :: (Alternative f) => (a -> Bool) -> a -> f a
+```
+
+```haskell
+guardedA :: (Functor f, Alternative t) => (a -> f Bool) -> a -> f (t a)
+```
diff --git a/docs/Bits.md b/docs/Bits.md
index c9c32e97e..9fd8afc4e 100644
--- a/docs/Bits.md
+++ b/docs/Bits.md
@@ -1,6 +1,14 @@
 Bits
 ====
 
+```haskell
+{-# LANGUAGE BinaryLiterals #-}
+```
+
+```python
+42 = 0b101010
+```
+
 Bit Operations
 --------------
 
@@ -28,12 +36,31 @@ xor :: Bits a => a -> a -> a
 
 *Example*:
 
+```haskell
+> True `xor` False
+True
+
+> True `xor` True
+False
+
+> 0b101 `xor` 0b011
+6 -- 0b110
+```
+
 #### complement
 
 ```haskell
 complement :: Bits a => a -> a
 ```
 
+```haskell
+> complement True
+False
+
+> complement 0b101
+-2 -- -0b010
+```
+
 *Example*:
 
 #### shift
@@ -81,19 +108,47 @@ setBit :: Bits a => a -> Int -> a
 clearBit :: Bits a => a -> Int -> a
 ```
 
+#### complementBit
+
 ```haskell
 complementBit :: Bits a => a -> Int -> a
 ```
 
+*Example*:
+
+```haskell
+λ> 0b100 `complementBit` 1
+6 -- 0b110
+```
+
+#### testBit
+
 ```haskell
 testBit :: Bits a => a -> Int -> Bool
 ```
 
+*Example*:
+
+```haskell
+> 0b10 `testBit` 0
+False
+> 0b10 `testBit` 1
+True
+```
+
+#### isSigned
 
 ```haskell
 isSigned :: Bits a => a -> Bool
 ```
 
+```haskell
+> isSigned 42
+True
+> isSigned True
+False
+```
+
 Bit Size
 ------------
 
diff --git a/docs/Bool.md b/docs/Bool.md
index 897a6ae65..d1ea2ca21 100644
--- a/docs/Bool.md
+++ b/docs/Bool.md
@@ -1,2 +1,6 @@
 Bool
 =====
+
+```haskell
+bool :: a -> a -> Bool -> a
+```
diff --git a/docs/Exceptions.md b/docs/Exceptions.md
index 4817c97bd..88bd82f89 100644
--- a/docs/Exceptions.md
+++ b/docs/Exceptions.md
@@ -1,5 +1,5 @@
-Exception Handling
-==================
+Exceptions
+==========
 
 #### MonadError
 
@@ -61,6 +61,20 @@ throwSTM :: Exception e => e -> STM a
 throwError :: MonadError e m => e -> m a
 ```
 
+#### Utilities
+
+```haskell
+hush :: Alternative m => Either e a -> m a
+```
+
+```haskell
+note :: (MonadError e m, Applicative m) => e -> Maybe a -> m a
+```
+
+```haskell
+tryIO :: MonadIO m => IO a -> ExceptT IOException m a
+```
+
 #### Fatal Errors
 
 ```haskell
diff --git a/docs/Function.md b/docs/Function.md
index c28a7b4e2..120377cc6 100644
--- a/docs/Function.md
+++ b/docs/Function.md
@@ -68,8 +68,24 @@ identity :: a -> a
 
 The identity function maps any value to itself.
 
+#### applyN
+
+Apply a function to a value `n` times.
+
 *Example*:
 
+```haskell
+applyN :: Int -> (a -> a) -> a -> a
+```
+
+```haskell
+> applyN 25 (+2) 0
+50
+
+> applyN 3 (1:) []
+[1,1,1]
+```
+
 Strictness
 -----------
 
diff --git a/docs/List.md b/docs/List.md
index 97e40763e..7c3b64ba6 100644
--- a/docs/List.md
+++ b/docs/List.md
@@ -59,6 +59,10 @@ uncons :: [a] -> Maybe (a, [a])
 unsnoc :: [x] -> Maybe ([x],x)
 ```
 
+```haskell
+list :: [b] -> (a -> b) -> [a] -> [b]
+```
+
 Sorting
 ---------
 
diff --git a/docs/Monad.md b/docs/Monad.md
index 9e0e3e6ee..78d0ea4fa 100644
--- a/docs/Monad.md
+++ b/docs/Monad.md
@@ -119,6 +119,22 @@ ap :: Monad m => m (a -> b) -> m a -> m b
 (<$!>) :: Monad m => (a -> b) -> m a -> m b
 ```
 
+```haskell
+whenM :: Monad m => m Bool -> m () -> m ()
+```
+
+```haskell
+unlessM :: Monad m => m Bool -> m () -> m ()
+```
+
+```haskell
+ifM :: Monad m => m Bool -> m a -> m a -> m a
+```
+
+```haskell
+guardM :: MonadPlus m => m Bool -> m ()
+```
+
 MonadPlus
 -----
 
diff --git a/docs/Monoid.md b/docs/Monoid.md
index 86bbceb38..fbe4c7956 100644
--- a/docs/Monoid.md
+++ b/docs/Monoid.md
@@ -1,2 +1,37 @@
 Monoid
 ======
+
+Monoid
+------
+
+Semigroup
+---------
+
+
+```haskell
+option :: b -> (a -> b) -> Option a -> b
+```
+
+```haskell
+diff :: Semigroup m => m -> Endo m
+```
+
+```haskell
+cycle1 :: Semigroup m => m -> m
+```
+
+```haskell
+stimesMonoid :: (Integral b, Monoid a) => b -> a -> a
+```
+
+```haskell
+stimesIdempotent :: Integral b => b -> a -> a
+```
+
+```haskell
+stimesIdempotentMonoid :: (Integral b, Monoid a) => b -> a -> a
+```
+
+```haskell
+mtimesDefault :: (Integral b, Monoid a) => b -> a -> a
+```