From ff75838f186ed512759160139ca59e0d8c63cf72 Mon Sep 17 00:00:00 2001 From: Sean 'Shaleh' Perry Date: Thu, 7 Sep 2017 11:12:13 -0700 Subject: [PATCH 1/2] circular-buffer: Clarify the operation of overwrite Overwrite replaces the oldest item in the buffer if the buffer is empty. Otherwise it is just like write. This commit documents what overwrite on a buffer with available space looks like and clarifies what the oldest element is after an overwrite operation succeeds. Closes: 889 --- exercises/circular-buffer/description.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/exercises/circular-buffer/description.md b/exercises/circular-buffer/description.md index 51bc8df531..35bb1c4157 100644 --- a/exercises/circular-buffer/description.md +++ b/exercises/circular-buffer/description.md @@ -29,14 +29,21 @@ If the buffer has 7 elements then it is completely full: When the buffer is full an error will be raised, alerting the client that further writes are blocked until a slot becomes free. -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: +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: [6][7][8][9][A][B][5] -Finally, if two elements are now removed then what would be returned is -not 3 & 4 but 5 & 6 because A & B overwrote the 3 & the 4 yielding the -buffer with: +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. + + [D][7][8][9][A][B][C] From 42632051668412fef91665d3edf8905b5dc98be8 Mon Sep 17 00:00:00 2001 From: Sean 'Shaleh' Perry Date: Thu, 7 Sep 2017 11:16:03 -0700 Subject: [PATCH 2/2] circular-buffer: Clarify description of test cases for overwrite. As discussed in #889, the documentation for the overwrite operation was vague. overwrite replaces the oldest element in the buffer if the buffer is full and is just a normal write if there is space available. --- exercises/circular-buffer/canonical-data.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/exercises/circular-buffer/canonical-data.json b/exercises/circular-buffer/canonical-data.json index 5d20c1dfbd..d0c4fb0b97 100644 --- a/exercises/circular-buffer/canonical-data.json +++ b/exercises/circular-buffer/canonical-data.json @@ -1,6 +1,6 @@ { "exercise": "circular-buffer", - "version": "1.0.0", + "version": "1.0.1", "comments": [ "In general, these circular buffers are expected to be stateful,", "and each language will operate on them differently.", @@ -13,7 +13,7 @@ " If it should succeed, it should produce the item at `expected`. ", " If it should fail, `expected` will not be present. ", "write: Writing the item located at `item` should succeed if and only if `should_succeed` is true.", - "overwrite: Write the item located at `item` into the buffer, removing the oldest item if necessary.", + "overwrite: Write the item located at `item` into the buffer, replacing the oldest item if necessary.", "clear: Clear the buffer.", "", "Failure of either `read` or `write` may be indicated in a manner appropriate for your language:", @@ -273,7 +273,7 @@ ] }, { - "description": "overwrite removes the oldest item on full buffer", + "description": "overwrite replaces the oldest item on full buffer", "property": "run", "capacity": 2, "operations": [ @@ -304,7 +304,7 @@ ] }, { - "description": "overwrite doesn't remove an already-read item", + "description": "overwrite replaces the oldest item remaining in buffer following a read", "property": "run", "capacity": 3, "operations": [