bottle-song error reporting (#505)

We allow errors to be returned from recite()

This change breaks existing community solutions.

Author: keiravillekode

exercises/practice/bottle-song/.docs/instructions.append.md

@@ -0,0 +1,8 @@
+# Instructions append
+
+## Detect invalid input
+
+Use [std.debug.assert][assert] or return an [error][error].
+
+[error]: https://ziglang.org/documentation/master/#Errors
+[assert]: https://ziglang.org/documentation/master/std/#std.debug.assert

exercises/practice/bottle-song/.meta/example.zig

@@ -30,7 +30,10 @@ fn appendLine(buffer: []u8, offset: *usize, num_bottles: u32) void {
     appendString(buffer, offset, hanging_on);
 }
 
-pub fn recite(buffer: []u8, start_bottles: u32, take_down: u32) []const u8 {
+pub fn recite(buffer: []u8, start_bottles: u32, take_down: u32) ![]const u8 {
+    std.debug.assert(1 <= take_down);
+    std.debug.assert(take_down <= start_bottles);
+    std.debug.assert(start_bottles <= 10);
     var offset: usize = 0;
 
     var num_bottles = start_bottles;

exercises/practice/bottle-song/bottle_song.zig

@@ -1,4 +1,4 @@
-pub fn recite(buffer: []u8, start_bottles: u32, take_down: u32) []const u8 {
+pub fn recite(buffer: []u8, start_bottles: u32, take_down: u32) ![]const u8 {
     _ = buffer;
     _ = start_bottles;
     _ = take_down;

exercises/practice/bottle-song/test_bottle_song.zig

@@ -12,7 +12,7 @@ test "verse-single verse-first generic verse" {
         \\And if one green bottle should accidentally fall,
         \\There'll be nine green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 10, 1);
+    const actual = try bottle_song.recite(&buffer, 10, 1);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -25,7 +25,7 @@ test "verse-single verse-last generic verse" {
         \\And if one green bottle should accidentally fall,
         \\There'll be two green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 3, 1);
+    const actual = try bottle_song.recite(&buffer, 3, 1);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -38,7 +38,7 @@ test "verse-single verse-verse with 2 bottles" {
         \\And if one green bottle should accidentally fall,
         \\There'll be one green bottle hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 2, 1);
+    const actual = try bottle_song.recite(&buffer, 2, 1);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -51,7 +51,7 @@ test "verse-single verse-verse with 1 bottle" {
         \\And if one green bottle should accidentally fall,
         \\There'll be no green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 1, 1);
+    const actual = try bottle_song.recite(&buffer, 1, 1);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -69,7 +69,7 @@ test "lyrics-multiple verses-first two verses" {
         \\And if one green bottle should accidentally fall,
         \\There'll be eight green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 10, 2);
+    const actual = try bottle_song.recite(&buffer, 10, 2);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -92,7 +92,7 @@ test "lyrics-multiple verses-last three verses" {
         \\And if one green bottle should accidentally fall,
         \\There'll be no green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 3, 3);
+    const actual = try bottle_song.recite(&buffer, 3, 3);
     try testing.expectEqualStrings(expected, actual);
 }
 
@@ -150,6 +150,6 @@ test "lyrics-multiple verses-all verses" {
         \\And if one green bottle should accidentally fall,
         \\There'll be no green bottles hanging on the wall.
     ;
-    const actual = bottle_song.recite(&buffer, 10, 10);
+    const actual = try bottle_song.recite(&buffer, 10, 10);
     try testing.expectEqualStrings(expected, actual);
 }