@grain/stdlib 0.6.5 → 0.7.0

package/queue.md

@@ -17,6 +17,14 @@ No other changes yet.
 from "queue" include Queue
 ```
 
+```grain
+let queue = Queue.fromList([0, 1])
+Queue.push(2, queue)
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+assert Queue.pop(queue) == Some(2)
+```
+
 ## Types
 
 Type declarations included in the Queue module.
@@ -41,12 +49,12 @@ No other changes yet.
 </details>
 
 ```grain
-make : (?size: Number) => Queue<a>
+make: (?size: Number) => Queue<a>
 ```
 
 Creates a new queue with an initial storage of the given size. As values are
 added or removed, the internal storage may grow or shrink. Generally, you
-won’t need to care about the storage size of your map and can use the
+won’t need to care about the storage size of your queue and can use the
 default size.
 
 Parameters:
@@ -61,6 +69,16 @@ Returns:
 |----|-----------|
 |`Queue<a>`|An empty queue|
 
+Examples:
+
+```grain
+Queue.make() // Creates a new queue
+```
+
+```grain
+Queue.make(size=16) // Creates a new queue with an initial size of 16
+```
+
 ### Queue.**isEmpty**
 
 <details disabled>
@@ -69,7 +87,7 @@ No other changes yet.
 </details>
 
 ```grain
-isEmpty : (queue: Queue<a>) => Bool
+isEmpty: (queue: Queue<a>) => Bool
 ```
 
 Checks if the given queue contains no items.
@@ -86,6 +104,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the queue has no items or `false` otherwise|
 
+Examples:
+
+```grain
+Queue.isEmpty(Queue.make()) == true
+```
+
+```grain
+Queue.isEmpty(Queue.fromList([1, 2])) == false
+```
+
 ### Queue.**size**
 
 <details disabled>
@@ -94,7 +122,7 @@ No other changes yet.
 </details>
 
 ```grain
-size : (queue: Queue<a>) => Number
+size: (queue: Queue<a>) => Number
 ```
 
 Computes the size of the input queue.
@@ -111,6 +139,16 @@ Returns:
 |----|-----------|
 |`Number`|The count of the items in the queue|
 
+Examples:
+
+```grain
+Queue.size(Queue.make()) == 0
+```
+
+```grain
+Queue.size(Queue.fromList([1, 2])) == 2
+```
+
 ### Queue.**peek**
 
 <details disabled>
@@ -119,7 +157,7 @@ No other changes yet.
 </details>
 
 ```grain
-peek : (queue: Queue<a>) => Option<a>
+peek: (queue: Queue<a>) => Option<a>
 ```
 
 Provides the value at the beginning of the queue, if it exists.
@@ -136,6 +174,18 @@ Returns:
 |----|-----------|
 |`Option<a>`|`Some(value)` containing the value at the beginning of the queue or `None` otherwise.|
 
+Examples:
+
+```grain
+Queue.peek(Queue.make()) == None
+```
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.peek(queue) == Some(1)
+```
+
 ### Queue.**push**
 
 <details disabled>
@@ -144,7 +194,7 @@ No other changes yet.
 </details>
 
 ```grain
-push : (value: a, queue: Queue<a>) => Void
+push: (value: a, queue: Queue<a>) => Void
 ```
 
 Adds a new item to the end of the queue.
@@ -156,6 +206,15 @@ Parameters:
 |`value`|`a`|The item to be added|
 |`queue`|`Queue<a>`|The queue being updated|
 
+Examples:
+
+```grain
+let queue = Queue.make()
+assert Queue.peek(queue) == None
+Queue.push(1, queue)
+assert Queue.peek(queue) == Some(1)
+```
+
 ### Queue.**pop**
 
 <details disabled>
@@ -164,7 +223,7 @@ No other changes yet.
 </details>
 
 ```grain
-pop : (queue: Queue<a>) => Option<a>
+pop: (queue: Queue<a>) => Option<a>
 ```
 
 Removes the item at the beginning of the queue.
@@ -181,7 +240,16 @@ Returns:
 |----|-----------|
 |`Option<a>`|The element removed from the queue|
 
-### Queue.**toList**
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.pop(queue) == Some(1)
+assert Queue.pop(queue) == None
+```
+
+### Queue.**clear**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -189,24 +257,28 @@ No other changes yet.
 </details>
 
 ```grain
-toList : (queue: Queue<a>) => List<a>
+clear: (queue: Queue<a>) => Void
 ```
 
-Converts a queue into a list of its elements.
+Clears the queue by removing all of its elements.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to convert|
+|`queue`|`Queue<a>`|The queue to clear|
 
-Returns:
+Examples:
 
-|type|description|
-|----|-----------|
-|`List<a>`|A list containing all queue values|
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+assert Queue.size(queue) == 1
+Queue.clear(queue)
+assert Queue.size(queue) == 0
+```
 
-### Queue.**fromList**
+### Queue.**copy**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -214,24 +286,34 @@ No other changes yet.
 </details>
 
 ```grain
-fromList : (list: List<a>) => Queue<a>
+copy: (queue: Queue<a>) => Queue<a>
 ```
 
-Creates a queue from a list.
+Produces a shallow copy of the input queue.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`list`|`List<a>`|The list to convert|
+|`queue`|`Queue<a>`|The queue to copy|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Queue<a>`|A queue containing all list values|
+|`Queue<a>`|A new queue containing the elements from the input|
 
-### Queue.**clear**
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(1, queue)
+let copiedQueue = Queue.copy(queue)
+Queue.push(2, queue) // Does not affect copiedQueue
+assert Queue.pop(copiedQueue) == Some(1)
+```
+
+### Queue.**toList**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -239,18 +321,34 @@ No other changes yet.
 </details>
 
 ```grain
-clear : (queue: Queue<a>) => Void
+toList: (queue: Queue<a>) => List<a>
 ```
 
-Clears the queue by removing all of its elements
+Converts a queue into a list of its elements.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to clear|
+|`queue`|`Queue<a>`|The queue to convert|
 
-### Queue.**copy**
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|A list containing all queue values|
+
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(0, queue)
+Queue.push(1, queue)
+Queue.push(2, queue)
+assert Queue.toList(queue) == [0, 1, 2]
+```
+
+### Queue.**fromList**
 
 <details disabled>
 <summary tabindex="-1">Added in <code>0.6.0</code></summary>
@@ -258,22 +356,30 @@ No other changes yet.
 </details>
 
 ```grain
-copy : (queue: Queue<a>) => Queue<a>
+fromList: (list: List<a>) => Queue<a>
 ```
 
-Produces a shallow copy of the input queue.
+Creates a queue from a list.
 
 Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`queue`|`Queue<a>`|The queue to copy|
+|`list`|`List<a>`|The list to convert|
 
 Returns:
 
 |type|description|
 |----|-----------|
-|`Queue<a>`|A new queue containing the elements from the input|
+|`Queue<a>`|A queue containing all list values|
+
+Examples:
+
+```grain
+let queue = Queue.fromList([0, 1])
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+```
 
 ### Queue.**toArray**
 
@@ -283,7 +389,7 @@ No other changes yet.
 </details>
 
 ```grain
-toArray : (queue: Queue<a>) => Array<a>
+toArray: (queue: Queue<a>) => Array<a>
 ```
 
 Converts a queue into an array of its values.
@@ -300,6 +406,16 @@ Returns:
 |----|-----------|
 |`Array<a>`|An array containing all values from the given queue|
 
+Examples:
+
+```grain
+let queue = Queue.make()
+Queue.push(0, queue)
+Queue.push(1, queue)
+Queue.push(2, queue)
+assert Queue.toArray(queue) == [> 0, 1, 2]
+```
+
 ### Queue.**fromArray**
 
 <details disabled>
@@ -308,7 +424,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromArray : (arr: Array<a>) => Queue<a>
+fromArray: (arr: Array<a>) => Queue<a>
 ```
 
 Creates a queue from an array.
@@ -325,6 +441,14 @@ Returns:
 |----|-----------|
 |`Queue<a>`|A queue containing all values from the array|
 
+Examples:
+
+```grain
+let queue = Queue.fromArray([> 0, 1])
+assert Queue.pop(queue) == Some(0)
+assert Queue.pop(queue) == Some(1)
+```
+
 ### Queue.**(==)**
 
 <details disabled>
@@ -333,7 +457,7 @@ No other changes yet.
 </details>
 
 ```grain
-(==) : (queue1: Queue<a>, queue2: Queue<a>) => Bool
+(==): (queue1: Queue<a>, queue2: Queue<a>) => Bool
 ```
 
 Checks if two queues are equivalent by value.
@@ -351,16 +475,59 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the queues are equivalent or `false` otherwise|
 
+Examples:
+
+```grain
+use Queue.{ (==) }
+let queue1 = Queue.fromList([0, 1, 2])
+let queue2 = Queue.fromList([0, 1, 2])
+assert queue1 == queue2
+```
+
+```grain
+use Queue.{ (==) }
+let queue1 = Queue.fromList([0, 1, 2])
+let queue2 = Queue.fromList([0, 1, 3])
+assert !(queue1 == queue2)
+```
+
 ## Queue.Immutable
 
 An immutable queue implementation.
 
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+let queue = Immutable.Queue.fromList([0, 1])
+let queue = Immutable.Queue.push(2, queue)
+assert Immutable.Queue.peek(queue) == Some(0)
+let queue = Immutable.Queue.pop(queue)
+assert Immutable.Queue.peek(queue) == Some(1)
+ignore(Queue.Immutable.pop(queue)) // Does not affect the original queue
+assert Immutable.Queue.peek(queue) == Some(1)
+```
+
 ### Types
 
 Type declarations included in the Queue.Immutable module.
 
 #### Queue.Immutable.**ImmutableQueue**
 
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.5.4</code></td><td>Originally a module root API</td></tr>
+</tbody>
+</table>
+</details>
+
 ```grain
 type ImmutableQueue<a>
 ```
@@ -386,11 +553,18 @@ Functions and constants included in the Queue.Immutable module.
 </details>
 
 ```grain
-empty : ImmutableQueue<a>
+empty: ImmutableQueue<a>
 ```
 
 An empty queue.
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.isEmpty(queue)
+```
+
 #### Queue.Immutable.**isEmpty**
 
 <details>
@@ -406,7 +580,7 @@ An empty queue.
 </details>
 
 ```grain
-isEmpty : (queue: ImmutableQueue<a>) => Bool
+isEmpty: (queue: ImmutableQueue<a>) => Bool
 ```
 
 Checks if the given queue contains any values.
@@ -423,6 +597,16 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the given queue is empty or `false` otherwise|
 
+Examples:
+
+```grain
+Queue.Immutable.isEmpty(Queue.Immutable.empty) == true
+```
+
+```grain
+Queue.Immutable.isEmpty(Queue.Immutable.fromList([1, 2])) == false
+```
+
 #### Queue.Immutable.**peek**
 
 <details>
@@ -441,7 +625,7 @@ Returns:
 </details>
 
 ```grain
-peek : (queue: ImmutableQueue<a>) => Option<a>
+peek: (queue: ImmutableQueue<a>) => Option<a>
 ```
 
 Returns the value at the beginning of the queue. It is not removed from the queue.
@@ -458,6 +642,18 @@ Returns:
 |----|-----------|
 |`Option<a>`|`Some(value)` containing the value at the beginning of the queue, or `None` if the queue is empty|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.peek(queue) == Some(1)
+```
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.peek(queue) == None
+```
+
 #### Queue.Immutable.**push**
 
 <details>
@@ -476,7 +672,7 @@ Returns:
 </details>
 
 ```grain
-push : (value: a, queue: ImmutableQueue<a>) => ImmutableQueue<a>
+push: (value: a, queue: ImmutableQueue<a>) => ImmutableQueue<a>
 ```
 
 Adds a value to the end of the queue.
@@ -494,6 +690,15 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|An updated queue|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1])
+assert Queue.Immutable.size(queue) == 1
+let queue = Queue.Immutable.push(2, queue)
+assert Queue.Immutable.size(queue) == 2
+```
+
 #### Queue.Immutable.**pop**
 
 <details>
@@ -512,7 +717,7 @@ Returns:
 </details>
 
 ```grain
-pop : (queue: ImmutableQueue<a>) => ImmutableQueue<a>
+pop: (queue: ImmutableQueue<a>) => ImmutableQueue<a>
 ```
 
 Dequeues the next value in the queue.
@@ -529,6 +734,20 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|An updated queue|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+let queue = Queue.Immutable.pop(queue)
+assert Queue.Immutable.peek(queue) == Some(2)
+```
+
+```grain
+let queue = Queue.Immutable.empty
+let queue = Queue.Immutable.pop(queue)
+assert Queue.Immutable.isEmpty(queue)
+```
+
 #### Queue.Immutable.**size**
 
 <details>
@@ -544,7 +763,7 @@ Returns:
 </details>
 
 ```grain
-size : (queue: ImmutableQueue<a>) => Number
+size: (queue: ImmutableQueue<a>) => Number
 ```
 
 Get the number of values in a queue.
@@ -561,6 +780,16 @@ Returns:
 |----|-----------|
 |`Number`|The number of values in the queue|
 
+Examples:
+
+```grain
+Queue.Immutable.size(Queue.Immutable.empty) == 0
+```
+
+```grain
+Queue.Immutable.size(Queue.Immutable.fromList([1, 2])) == 2
+```
+
 #### Queue.Immutable.**toList**
 
 <details disabled>
@@ -569,7 +798,7 @@ No other changes yet.
 </details>
 
 ```grain
-toList : (queue: ImmutableQueue<a>) => List<a>
+toList: (queue: ImmutableQueue<a>) => List<a>
 ```
 
 Converts a queue into a list of its elements.
@@ -586,6 +815,25 @@ Returns:
 |----|-----------|
 |`List<a>`|A list containing all queue values|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.empty
+let queue = Queue.Immutable.push(1, queue)
+let queue = Queue.Immutable.push(2, queue)
+assert Queue.Immutable.toList(queue) == [1, 2]
+```
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.toList(queue) == [1, 2, 3]
+```
+
+```grain
+let queue = Queue.Immutable.empty
+assert Queue.Immutable.toList(queue) == []
+```
+
 #### Queue.Immutable.**fromList**
 
 <details disabled>
@@ -594,7 +842,7 @@ No other changes yet.
 </details>
 
 ```grain
-fromList : (list: List<a>) => ImmutableQueue<a>
+fromList: (list: List<a>) => ImmutableQueue<a>
 ```
 
 Creates a queue from a list.
@@ -611,3 +859,11 @@ Returns:
 |----|-----------|
 |`ImmutableQueue<a>`|A queue containing all list values|
 
+Examples:
+
+```grain
+let queue = Queue.Immutable.fromList([1, 2, 3])
+assert Queue.Immutable.peek(queue) == Some(1)
+assert Queue.Immutable.size(queue) == 3
+```
+

package/random.md

@@ -35,7 +35,7 @@ No other changes yet.
 </details>
 
 ```grain
-make : (seed: Uint64) => Random
+make: (seed: Uint64) => Random
 ```
 
 Creates a new pseudo-random number generator with the given seed.
@@ -60,7 +60,7 @@ No other changes yet.
 </details>
 
 ```grain
-makeUnseeded : () => Result<Random, Exception>
+makeUnseeded: () => Result<Random, Exception>
 ```
 
 Creates a new pseudo-random number generator with a random seed.
@@ -86,7 +86,7 @@ Returns:
 </details>
 
 ```grain
-nextUint32 : (random: Random) => Uint32
+nextUint32: (random: Random) => Uint32
 ```
 
 Generates a random 32-bit integer from the given pseudo-random number generator.
@@ -118,7 +118,7 @@ Returns:
 </details>
 
 ```grain
-nextUint64 : (random: Random) => Uint64
+nextUint64: (random: Random) => Uint64
 ```
 
 Generates a random 64-bit integer from the given pseudo-random number generator.
@@ -150,7 +150,7 @@ Returns:
 </details>
 
 ```grain
-nextUint32InRange : (random: Random, low: Uint32, high: Uint32) => Uint32
+nextUint32InRange: (random: Random, low: Uint32, high: Uint32) => Uint32
 ```
 
 Generates a random 32-bit integer from the given pseudo-random number generator
@@ -185,7 +185,7 @@ Returns:
 </details>
 
 ```grain
-nextUint64InRange : (random: Random, low: Uint64, high: Uint64) => Uint64
+nextUint64InRange: (random: Random, low: Uint64, high: Uint64) => Uint64
 ```
 
 Generates a random 64-bit integer from the given pseudo-random number generator

package/range.gr

@@ -123,10 +123,10 @@ provide module Inclusive {
    */
   provide let inRange = (value, range) => {
     match (range) {
-      { rangeStart: lower, rangeEnd: upper } when value >= lower &&
-        value <= upper => true,
-      { rangeStart: upper, rangeEnd: lower } when value >= lower &&
-        value <= upper => true,
+      { rangeStart: lower, rangeEnd: upper } when value >= lower
+        && value <= upper => true,
+      { rangeStart: upper, rangeEnd: lower } when value >= lower
+        && value <= upper => true,
       _ => false,
     }
   }