# 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

Buffer is _immutable_, there is a `MutableBuffer` with same interface but mutable.

## 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 and modifying

Buffer implement [Array] and therefore can be accessed, and `MutableBuffers` also modified:

    import lyng.buffer
    val b1 = Buffer( 1, 2, 3)
    assertEquals( 2, b1[1] )

    val b2 = b1.toMutable()
    assertEquals( 2, b1[1] )
    b2[1]++
    b2[0] = 100
    assertEquals( Buffer(100, 3, 3), b2)

    // b2 is a mutable copy so b1 has not been changed:
    assertEquals( Buffer(1, 2, 3), b1)

    >>> 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

Please note that indexed bytes are _readonly projection_, e.g. you can't modify these with

## Comparing

Buffers are comparable with other buffers (and notice there are _mutable_ buffers, bu default buffers ar _immutable_):

    import lyng.buffer
    val b1 = Buffer(1, 2, 3)
    val b2 = Buffer(1, 2, 3)
    val b3 = MutableBuffer(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           |
| `decodeUtf8`  | decodee to String using UTF8 rules | Any           |
| `+`           | buffer concatenation               | Any           |
| `toMutable()` | create a mutable copy              | MutableBuffer |

(1)
: optimized implementation that override `Iterable` one

Also, it inherits methods from [Iterable] and [Array].


[Range]: Range.md
[Iterable]: Iterable.md