Skip to content

Commit

Permalink
Add circular-buffer exercise (#193)
Browse files Browse the repository at this point in the history
  • Loading branch information
ErikSchierboom authored May 21, 2024
1 parent 0ca2e66 commit 9a85711
Show file tree
Hide file tree
Showing 9 changed files with 502 additions and 0 deletions.
8 changes: 8 additions & 0 deletions config.json
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,14 @@
"practices": [],
"prerequisites": [],
"difficulty": 5
},
{
"slug": "circular-buffer",
"name": "Circular Buffer",
"uuid": "2442f2fe-3304-4d28-9539-b23a31e24c22",
"practices": [],
"prerequisites": [],
"difficulty": 7
}
]
},
Expand Down
29 changes: 29 additions & 0 deletions exercises/practice/circular-buffer/.docs/instructions.append.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Instructions append

This exercise introduces a couple of concepts you might not have seen before:

## User-defined namespace

Words in 8th all belong to a namespace, e.g. `a:new` refers to the `new` word in the `a` namespace.
One can also define custom namespaces, which is what we do at the top of the `circular-buffer.8th` file:

```8th
ns: cb
```

This means that all words within that file can be accessed via `cb:<word>`, which is a great way to group related functionality.

For more information, check out the [namespaces][namespaces] documentation.

## Exceptions

The `read` and `write` words are both expected to throw an exception when they're called on a circular buffer with an invalid state.
For more information, check the [exceptions and error handling][exceptions-and-error-handling] documentation.

## Objects

While you're free to implement the circular buffer as you like, you could consider using 8th's [object support][objects].

[namespaces]: https://8th-dev.com/manual.html#namespaces
[exceptions-and-error-handling]: https://8th-dev.com/manual.html#exceptions-and-error-handling
[objects]: https://8th-dev.com/manual.html#objects
58 changes: 58 additions & 0 deletions exercises/practice/circular-buffer/.docs/instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Instructions

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:

```text
[ ][ ][ ][ ][ ][ ][ ]
```

Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):

```text
[ ][ ][ ][1][ ][ ][ ]
```

Then assume that two more elements are added — 2 & 3 — which get appended after the 1:

```text
[ ][ ][ ][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:

```text
[ ][ ][ ][ ][ ][3][ ]
```

If the buffer has 7 elements then it is completely full:

```text
[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:

```text
[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:

```text
[ ][ ][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.

```text
[C][D][7][8][9][A][B]
```
19 changes: 19 additions & 0 deletions exercises/practice/circular-buffer/.meta/config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"authors": [
"erikschierboom"
],
"files": {
"solution": [
"circular-buffer.8th"
],
"test": [
"test.8th"
],
"example": [
".meta/example.8th"
]
},
"blurb": "A data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",
"source": "Wikipedia",
"source_url": "https://en.wikipedia.org/wiki/Circular_buffer"
}
68 changes: 68 additions & 0 deletions exercises/practice/circular-buffer/.meta/example.8th
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
ns: cb

: count \ o -- n
"count" o:@ nip
;

: capacity \ o -- n
"capacity" o:@ nip
;

: items \ o -- a
"items" o:@ nip
;

: head \ o -- n
"head" o:@ nip
;

: tail \ o -- n
"tail" o:@ nip
;

: read \ o -- o x
>r
r@ count 0 n:= if r> "circular buffer empty" throw ;then
r@ items r@ tail a:_@
r@ tail n:1+ r@ capacity n:/mod drop r@ "tail" rot o:! drop
r@ count n:1- r@ "count" rot o:!
swap
;

: overwrite \ o x -- o
swap >r
r@ items r@ head rot a:! r@ "items" rot o:!
r@ head n:1+ r@ capacity n:/mod drop "head" swap o:!
r@ count r@ capacity n:=
if
r@ head "tail" swap o:!
else
r@ count n:1+ "count" swap o:!
then
;

: write \ o x -- o
swap >r
r@ capacity r@ count n:= if drop r> "circular buffer full" throw ;then
r> swap cb:overwrite
;

: clear \ o
"head" 0 o:!
"tail" 0 o:!
"count" 0 o:!
;

: new \ n -- o
{
class: "circular-buffer",
methods: {
read: ' read,
write: ' write,
overwrite: ' overwrite
}
} o:new swap
2dup "capacity" swap o:! drop
n:1- ' noop 0 rot a:generate "items" swap o:!
cb:clear
;
52 changes: 52 additions & 0 deletions exercises/practice/circular-buffer/.meta/tests.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# This is an auto-generated file.
#
# Regenerating this file via `configlet sync` will:
# - Recreate every `description` key/value pair
# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
# - Preserve any other key/value pair
#
# As user-added comments (using the # character) will be removed when this file
# is regenerated, comments can be added via a `comment` key.

[28268ed4-4ff3-45f3-820e-895b44d53dfa]
description = "reading empty buffer should fail"

[2e6db04a-58a1-425d-ade8-ac30b5f318f3]
description = "can read an item just written"

[90741fe8-a448-45ce-be2b-de009a24c144]
description = "each item may only be read once"

[be0e62d5-da9c-47a8-b037-5db21827baa7]
description = "items are read in the order they are written"

[2af22046-3e44-4235-bfe6-05ba60439d38]
description = "full buffer can't be written to"

[547d192c-bbf0-4369-b8fa-fc37e71f2393]
description = "a read frees up capacity for another write"

[04a56659-3a81-4113-816b-6ecb659b4471]
description = "read position is maintained even across multiple writes"

[60c3a19a-81a7-43d7-bb0a-f07242b1111f]
description = "items cleared out of buffer can't be read"

[45f3ae89-3470-49f3-b50e-362e4b330a59]
description = "clear frees up capacity for another write"

[e1ac5170-a026-4725-bfbe-0cf332eddecd]
description = "clear does nothing on empty buffer"

[9c2d4f26-3ec7-453f-a895-7e7ff8ae7b5b]
description = "overwrite acts like write on non-full buffer"

[880f916b-5039-475c-bd5c-83463c36a147]
description = "overwrite replaces the oldest item on full buffer"

[bfecab5b-aca1-4fab-a2b0-cd4af2b053c3]
description = "overwrite replaces the oldest item remaining in buffer following a read"

[9cebe63a-c405-437b-8b62-e3fdc1ecec5a]
description = "initial clear does not affect wrapping around"
17 changes: 17 additions & 0 deletions exercises/practice/circular-buffer/circular-buffer.8th
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
ns: cb

: read \ x -- x x'

;

: write \ x x' -- x

;

: overwrite \ x x' -- x

;

: new \ n -- x

;
Loading

0 comments on commit 9a85711

Please sign in to comment.