"Exercise: CircularBuffer"

circularBuffer
"A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.
  A circular buffer first starts empty and of some predefined length. For example, this is a 7-element buffer:
  [ ][ ][ ][ ][ ][ ][ ]
  Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer).
  [ ][ ][ ][1][ ][ ][ ]
  Then assume that two more elements are added -- 2 & 3 -- which get appended after the 1.
  [ ][ ][ ][1][2][3][ ]
  If two elements are then removed from the buffer, the oldest values inside the buffer are removed. The two elements removed, in this case, are 1 & 2, leaving the buffer with just a 3.
  [ ][ ][ ][ ][ ][3][ ]
  If the buffer has 7 elements then it is completely full.
  [5][6][7][8][9][3][4]
  When the buffer is full an error will be raised, alerting the client that further writes are blocked until a slot becomes free.
  When the buffer is full, the client can opt to overwrite the oldest data with a forced write. In this case, two more elements -- A & B -- are added and they overwrite the 3 & 4.
  [5][6][7][8][9][A][B]
  3 & 4 have been replaced by A & B making 5 now the oldest data in the buffer. Finally, if two elements are removed then what would be returned is 5 & 6 yielding the buffer.
  [ ][ ][7][8][9][A][B]
  Because there is space available, if the client again uses overwrite to store C & D then the space where 5 & 6 were stored previously will be used not the location of 7 & 8. 7 is still the oldest element and the buffer is once again full.
  [C][D][7][8][9][A][B]"
"([ :buf | (buf at: #capacity:) value: 1. (buf at: #write:) value: 1. (buf at: #read) value ] value: (self new circularBuffer)) >>> 1"
| buffer capacity bufferFull read write overwrite clear setCapacity raiseEmpty raiseFull api |
  buffer := OrderedCollection new.
  capacity := nil.

  bufferFull := [ capacity notNil and: [ buffer size >= capacity ] ].

  raiseEmpty := [ Error signal: 'Cannot read from empty buffer!' ].
  raiseFull := [ Error signal: 'Cannot write to full buffer!' ].

  read := [
    buffer isEmpty ifTrue: [ ^ raiseEmpty value ].
    buffer removeFirst
  ].

  write := [ :aValue |
    (bufferFull value) ifTrue: [ ^ raiseFull value ].
    buffer addLast: aValue
  ].

  overwrite := [ :aValue |
    (bufferFull value) ifTrue: [ buffer removeFirst ].
    write value: aValue
  ].

  clear := [ buffer removeAll ].
  setCapacity := [ :aNumber | capacity := aNumber ].

  api := Dictionary new.
  api at: #capacity: put: setCapacity;
      at: #write: put: write;
      at: #read put: read;
      at: #overwrite: put: overwrite;
      at: #clear put: clear.
  ^ api


"Tests"
testCircularBuffer
| buf result |

  "reading empty buffer should fail"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  self should: [ (buf at: #read) value ] raise: Error.

  "can read an item just written"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  result := (buf at: #read) value.
  self assert: result equals: 1.

  "each item may only be read once"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  self should: [ (buf at: #read) value ] raise: Error.

  "items are read in the order they are written"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 2.
  (buf at: #write:) value: 1.
  (buf at: #write:) value: 2.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  result := (buf at: #read) value.
  self assert: result equals: 2.

  "full buffer can't be written to"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  self should: [ (buf at: #write:) value: 2 ] raise: Error.

  "a read frees up capacity for another write"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  (buf at: #write:) value: 2.
  result := (buf at: #read) value.
  self assert: result equals: 2.

  "read position is maintained even across multiple writes"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 3.
  (buf at: #write:) value: 1.
  (buf at: #write:) value: 2.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  (buf at: #write:) value: 3.
  result := (buf at: #read) value.
  self assert: result equals: 2.
  result := (buf at: #read) value.
  self assert: result equals: 3.

  "items cleared out of buffer can't be read"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  (buf at: #clear) value.
  self should: [ (buf at: #read) value ] raise: Error.

  "clear frees up capacity for another write"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #write:) value: 1.
  (buf at: #clear) value.
  (buf at: #write:) value: 2.
  result := (buf at: #read) value.
  self assert: result equals: 2.

  "clear does nothing on empty buffer"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 1.
  (buf at: #clear) value.
  (buf at: #write:) value: 1.
  result := (buf at: #read) value.
  self assert: result equals: 1.

  "overwrite acts like write on non-full buffer"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 2.
  (buf at: #write:) value: 1.
  (buf at: #overwrite:) value: 2.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  result := (buf at: #read) value.
  self assert: result equals: 2.

  "overwrite replaces the oldest item on full buffer"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 2.
  (buf at: #write:) value: 1.
  (buf at: #write:) value: 2.
  (buf at: #overwrite:) value: 3.
  result := (buf at: #read) value.
  self assert: result equals: 2.
  result := (buf at: #read) value.
  self assert: result equals: 3.

  "overwrite replaces the oldest item remaining in buffer following a read"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 3.
  (buf at: #write:) value: 1.
  (buf at: #write:) value: 2.
  (buf at: #write:) value: 3.
  result := (buf at: #read) value.
  self assert: result equals: 1.
  (buf at: #write:) value: 4.
  (buf at: #overwrite:) value: 5.
  result := (buf at: #read) value.
  self assert: result equals: 3.
  result := (buf at: #read) value.
  self assert: result equals: 4.
  result := (buf at: #read) value.
  self assert: result equals: 5.

  "initial clear does not affect wrapping around"
  buf := task circularBuffer.
  (buf at: #capacity:) value: 2.
  (buf at: #clear) value.
  (buf at: #write:) value: 1.
  (buf at: #write:) value: 2.
  (buf at: #overwrite:) value: 3.
  (buf at: #overwrite:) value: 4.
  result := (buf at: #read) value.
  self assert: result equals: 3.
  result := (buf at: #read) value.
  self assert: result equals: 4.
  self should: [ (buf at: #read) value ] raise: Error.