fix: Add docs and tests to IsBalanced (#326)

Author: tikhoplav

other/nested_brackets/nestedbrackets.go

@@ -1,51 +1,62 @@
-// The nested brackets problem is a problem that determines if a sequence of
-// brackets are properly nested.  A sequence of brackets s is considered properly nested
+// Package nested_brackets provides functions for testing 
+// strings propper brackets nesting.
+package nested_brackets
+
+// IsBalanced returns true if provided input string is properly nested.
+//
+// Input is a sequence of brackets: '(', ')', '[', ']', '{', '}'.
+//
+// A sequence of brackets `s` is considered properly nested
 // if any of the following conditions are true:
-// 	- s is empty
-// 	- s has the form (U) or [U] or {U} where U is a properly nested string
-// 	- s has the form VW where V and W are properly nested strings
+// 	- `s` is empty;
+// 	- `s` has the form (U) or [U] or {U} where U is a properly nested string;
+// 	- `s` has the form VW where V and W are properly nested strings.
+//
 // For example, the string "()()[()]" is properly nested but "[(()]" is not.
-// The function called isBalanced takes as input a string which is a sequence of brackets and
-// returns true if input is nested and false otherwise.
-//note that only an even number of brackets can be properly nested
-
-package nested_brackets
+//
+// **Note** Providing characters other then brackets would return false,
+// despite brackets sequence in the string. Make sure to filter
+// input before useage.
+func IsBalanced(input string) bool {
+	if len(input) == 0 {
+		return true
+	}
 
-// IsBalanced function which checks whether the number of brackets are balanced
-func IsBalanced(input string) string {
 	if len(input)%2 != 0 {
-		return input + "is not balanced."
+		return false
 	}
-	if len(input) > 0 {
-		var stack []byte
-		for i := 0; i < len(input); i++ {
-			if input[i] == '(' || input[i] == '{' || input[i] == '[' {
-				stack = append(stack, input[i])
-			} else {
-				if len(stack) > 0 {
-					pair := string(stack[len(stack)-1]) + string(input[i])
-					stack = stack[:len(stack)-1]
 
-					if pair != "[]" && pair != "{}" && pair != "()" {
-						return input + " is not balanced."
-					}
-				} else {
-					return input + " is not balanced."
+	// Brackets such as '{', '[', '(' are valid UTF-8 characters,
+	// which means that only one byte is required to code them,
+	// so can be stored as bytes.
+	var stack []byte
+
+	for i := 0; i < len(input); i++ {
+		if input[i] == '(' || input[i] == '{' || input[i] == '[' {
+			stack = append(stack, input[i])
+		} else {
+			if len(stack) > 0 {
+				pair := string(stack[len(stack)-1]) + string(input[i])
+				stack = stack[:len(stack)-1]
+
+				if pair != "[]" && pair != "{}" && pair != "()" {
+					// This means that two types of brackets has
+					// been mixed together, for example "([)]",
+					// which makes seuqence invalid by definition.
+					return false
 				}
+			} else {
+				// This means that closing bracket is encountered
+				// before opening one, which makes all sequence
+				// invalid by definition.
+				return false
 			}
 		}
-		if len(stack) == 0 {
-			return input + " is balanced."
-		}
 	}
-	return "Please enter a sequence of brackets."
-}
-
-// func main() {
-// 	reader := bufio.NewReader(os.Stdin)
-// 	fmt.Print("Enter sequence of brackets: ")
-// 	text, _ := reader.ReadString('\n')
 
-// 	text = strings.TrimSpace(text)
-// 	fmt.Println(isBalanced(text))
-// }
+	// If sequence is properly nested, all elements in stack
+	// has been paired with closing elements. If even one
+	// element has not been paired with a closing bracket,
+	// means that sequence is invalid by definition.
+	return len(stack) == 0
+}

other/nested_brackets/nestedbrackets_test.go

@@ -0,0 +1,79 @@
+package nested_brackets
+
+import (
+	"testing"
+)
+
+func TestIsBalancedSimple(t *testing.T) {
+	input := "{[()]}"
+
+	got := IsBalanced(input)
+	want := true
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func TestIsBalancedFalty(t *testing.T) {
+	input := "{([()]}"
+
+	got := IsBalanced(input)
+	want := false
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func TestIsBalancedHandlesEmpty(t *testing.T) {
+	input := ""
+
+	got := IsBalanced(input)
+	want := true
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func TestIsBalancedHandlesOneChar(t *testing.T) {
+	input := "{"
+
+	got := IsBalanced(input)
+	want := false
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func TestIsBalancedHandlesNonBracketsCorrectly(t *testing.T) {
+	input := "aaaa"
+
+	got := IsBalanced(input)
+	want := false
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func TestIsBalancedHandlesOrdering(t *testing.T) {
+	input := "([)]"
+
+	got := IsBalanced(input)
+	want := false
+
+	if got != want {
+		t.Errorf("\nInput: %s\nGot: %v\nWant: %v\n", input, got, want)
+	}
+}
+
+func BenchmarkIsBalanced(b *testing.B) {
+	input := "{[()]}"
+
+	for i := 0; i < b.N; i++ {
+		IsBalanced(input)
+	}
+}