fix #33 minimal Buffer with docs, in a separate package

docs/Buffer.md

@@ -0,0 +1,110 @@
+# Binary `Buffer`
+
+Buffers are effective unsigned byte arrays of fixed size. Buffers content is mutable,
+unlike its size. Buffers are comparable and implement [Array], thus [Collection] and [Iterable]. Buffer iterators return its contents as unsigned bytes converted to `Int`
+
+Buffers needs to be imported with `import lyng.buffer`:
+
+    import lyng.buffer
+
+    assertEquals(5, Buffer("Hello").size)
+    >>> void
+
+## Constructing
+
+There are a lo of ways to construct a buffer:
+
+    import lyng.buffer
+    
+    // from string using utf8 encoding:
+    assertEquals( 5, Buffer("hello").size )
+
+    // from bytes, e.g. integers in range 0..255
+    assertEquals( 255, Buffer(1,2,3,255).last() )
+
+    // from whatever iterable that produces bytes, e.g.
+    // integers in 0..255 range:
+    assertEquals( 129, Buffer([1,2,129]).last() )
+
+    // Empty buffer of fixed size:
+    assertEquals(100, Buffer(100).size)
+    assertEquals(0, Buffer(100)[0])
+
+    // Note that you can use list iteral to create buffer with 1 byte:
+    assertEquals(1, Buffer([100]).size)
+    assertEquals(100, Buffer([100])[0])
+
+    >>> void
+
+## Accessing an modifying
+
+Buffer implement [Array] and therefore can be accessed and modified with indexing:
+
+    import lyng.buffer
+    val b1 = Buffer( 1, 2, 3)
+    assertEquals( 2, b1[1] )
+    b1[0] = 199
+    assertEquals(199, b1[0])
+    >>> void
+
+Buffer provides concatenation with another Buffer:
+
+    import lyng.buffer
+    val b = Buffer(101, 102)
+    assertEquals( Buffer(101, 102, 1, 2), b + [1,2])
+    >>> void
+
+## Comparing
+
+Buffers are comparable with other buffers:
+
+    import lyng.buffer
+    val b1 = Buffer(1, 2, 3)
+    val b2 = Buffer(1, 2, 3)
+    val b3 = Buffer(b2)
+    
+    b3[0] = 101
+
+    assert( b3 > b1 )
+    assert( b2 == b1 )
+    // longer string with same prefix is considered bigger:
+    assert( b2 + "!".characters() > b1 )
+    // note that characters() provide Iterable of characters that 
+    // can be concatenated to Buffer
+
+    >>> void
+
+## Slicing
+
+As with [List], it is possible to use ranges as indexes to slice a Buffer:
+
+    import lyng.buffer
+
+    val a = Buffer( 100, 101, 102, 103, 104, 105 )
+    assertEquals( a[ 0..1 ], Buffer(100, 101) )
+    assertEquals( a[ 0 ..< 2 ], Buffer(100, 101) )
+    assertEquals( a[  ..< 2 ], Buffer(100, 101) )
+    assertEquals( a[  4.. ], Buffer(104, 105) )
+    assertEquals( a[  2..3 ], Buffer(102, 103) )
+
+    >>> void
+
+## Members
+
+| name                | meaning                              | type  |
+|---------------------|--------------------------------------|-------|
+| `size`              | size                         | Int   |
+| `+=`                | add one or more elements             | Any   |
+| `+`, `union`         | union sets                           | Any   |
+| `-`, `subtract`     | subtract sets                        | Any   |
+| `*`, `intersect`    | subtract sets                        | Any   |
+| `remove(items...)`  | remove one or more items             | Range |
+| `contains(element)` | check the element is in the list (1) |       |
+
+(1)
+: optimized implementation that override `Iterable` one
+
+Also, it inherits methods from [Iterable].
+
+
+[Range]: Range.md

docs/Map.md

@@ -3,6 +3,8 @@
 Map is a mutable collection of key-value pars, where keys are unique. Maps could be created with
 constructor or `.toMap` methods. When constructing from a list, each list item must be a [Collection] with exactly 2 elements, for example, a [List].
 
+Important thing is that maps can't contain `null`: it is used to return from missing elements.
+
 Constructed map instance is of class `Map` and implements `Collection` (and therefore `Iterable`)
 
     val map = Map( ["foo", 1], ["bar", "buzz"] )
@@ -16,7 +18,7 @@ Map keys could be any objects (hashable, e.g. with reasonable hashCode, most of
     val map = Map( ["foo", 1], ["bar", "buzz"], [42, "answer"] )
     assert( map["bar"] == "buzz")
     assert( map[42] == "answer" )
-    assertThrows { map["nonexistent"] }
+    assertEquals( null, map["nonexisting"])
     assert( map.getOrNull(101) == null )
     assert( map.getOrPut(911) { "nine-eleven" } == "nine-eleven" )
     // now 91 entry is set:

docs/tutorial.md

@@ -530,7 +530,8 @@ The simplest way to concatenate lists is using `+` and `+=`:
     list += [2, 1]      
     // or you can append a single element:
     list += "end"
-    assert( list == [1, 2, 2, 1, "end"])
+    assertEquals( list, [1, 2, 2, 1, "end"])
+    void
     >>> void
 
 ***Important note***: the pitfall of using `+=` is that you can't append in [Iterable] instance as an object: it will always add all its contents. Use `list.add` to add a single iterable instance:
@@ -641,6 +642,11 @@ You can get ranges to extract a portion from a list:
     assertEquals( [2,3], list[1..<3])
     >>> void
 
+# Buffers
+
+[Buffer] is a special implementation of an [Array] of unsigned bytes, in the
+[separate file](Buffer.md).
+
 # Sets
 
 Set are unordered collection of unique elements, see [Set]. Sets are [Iterable] but have no indexing access.
@@ -740,13 +746,13 @@ You can thest that _when expression_ is _contained_, or not contained, in some o
 
 Typical builtin types that are containers (e.g. support `conain`):
 
-| class      | notes                                      |
-|------------|--------------------------------------------|
-| Collection | contains an element (1)                    |
-| Array      | faster maybe that Collection's             |
-| List       | faster than Array's                        |
-| String     | character in string or substring in string |
-| Range      | object is included in the range (2)        |
+| class      | notes                                          |
+|------------|------------------------------------------------|
+| Collection | contains an element (1)                        |
+| Array      | faster maybe that Collection's                 |
+| List       | faster than Array's                            |
+| String     | character in string or substring in string (3) |
+| Range      | object is included in the range (2)            |
 
 (1)
 : Iterable is not the container as it can be infinite
@@ -760,6 +766,9 @@ Typical builtin types that are containers (e.g. support `conain`):
     assert( "x" !in 'a'..'z') // string in character range: could be error
     >>> void
 
+(3)
+: `String` also can provide array of characters directly with `str.characters()`, which is [Iterable] and [Array]. String itself is not iterable as otherwise it will interfere when adding strigns to lists (it will add _characters_ it it would be iterable).
+
 So we recommend not to mix characters and string ranges; use `ch in str` that works
 as expected:
 
@@ -1216,9 +1225,10 @@ Typical set of String functions includes:
 | s1 += s2           | self-modifying concatenation                               |
 | toReal()           | attempts to parse string as a Real value                   |
 | toInt()            | parse string to Int value                                  |
-|                    |                                                            |
-
+| characters()       | create [List] of characters (1)                            |
 
+(1)
+: List is mutable therefore a new copy is created on each call.
 
 
 
@@ -1256,4 +1266,5 @@ See [math functions](math.md). Other general purpose functions are:
 [String]: String.md
 [string formatting]: https://github.com/sergeych/mp_stools?tab=readme-ov-file#sprintf-syntax-summary
 [Set]: Set.md
-[Map]: Map.md
+[Map]: Map.md
+[Buffer]: Buffer.md