data_structure: add stack implementation (#67)

Author: mgstabrani

.github/workflows/tests.yml

@@ -15,6 +15,13 @@ jobs:
           directory: .
           add-to-path: true
 
+      - name: Test - data_structures
+        run: |
+          julec test -o test data_structures
+          git update-index --add --chmod=-x test
+          chmod +x test
+          ./test
+
       - name: Test - math
         run: |
           julec test -o test math

data_structures/stack.jule

@@ -0,0 +1,50 @@
+// Implementation of a generic LIFO (last-in, first-out) stack.
+// Reference: https://en.wikipedia.org/wiki/Stack_(abstract_data_type)
+
+// Stack is a generic last-in, first-out (LIFO) collection.
+struct Stack[T] {
+	items: []T
+}
+
+impl Stack {
+	// Push adds an item to the top of the stack.
+	fn Push(mut *self, item: T) {
+		self.items = append(self.items, item)
+	}
+
+	// Pop removes and returns the item at the top of the stack.
+	// The second return value reports whether an item was removed;
+	// it is false when the stack is empty.
+	fn Pop(mut *self): (item: T, ok: bool) {
+		if len(self.items) == 0 {
+			return
+		}
+		last := len(self.items) - 1
+		item = self.items[last]
+		self.items = self.items[:last]
+		ok = true
+		return
+	}
+
+	// Peek returns the item at the top of the stack without removing it.
+	// The second return value reports whether the stack has an item;
+	// it is false when the stack is empty.
+	fn Peek(*self): (item: T, ok: bool) {
+		if len(self.items) == 0 {
+			return
+		}
+		item = self.items[len(self.items)-1]
+		ok = true
+		return
+	}
+
+	// Len returns the number of items in the stack.
+	fn Len(*self): int {
+		return len(self.items)
+	}
+
+	// Empty reports whether the stack has no items.
+	fn Empty(*self): bool {
+		return len(self.items) == 0
+	}
+}

data_structures/stack_test.jule

@@ -0,0 +1,55 @@
+#build test
+
+use "std/testing"
+
+#test
+fn testStackPushPop(t: &testing::T) {
+	mut s := Stack[int]{}
+	t.Assert(s.Empty(), "new stack should be empty")
+	t.Assert(s.Len() == 0, "new stack should have length 0")
+
+	s.Push(1)
+	s.Push(2)
+	s.Push(3)
+	t.Assert(!s.Empty(), "stack with items should not be empty")
+	t.Assert(s.Len() == 3, "stack should have length 3")
+
+	v1, ok1 := s.Pop()
+	t.Assert(ok1 && v1 == 3, "pop should return the last pushed item (3)")
+
+	v2, ok2 := s.Pop()
+	t.Assert(ok2 && v2 == 2, "pop should return 2")
+
+	v3, ok3 := s.Pop()
+	t.Assert(ok3 && v3 == 1, "pop should return 1")
+
+	t.Assert(s.Empty(), "stack should be empty after popping all items")
+}
+
+#test
+fn testStackPopEmpty(t: &testing::T) {
+	mut s := Stack[int]{}
+	_, ok := s.Pop()
+	t.Assert(!ok, "pop on empty stack should report ok == false")
+}
+
+#test
+fn testStackPeek(t: &testing::T) {
+	mut s := Stack[int]{}
+	_, ok := s.Peek()
+	t.Assert(!ok, "peek on empty stack should report ok == false")
+
+	s.Push(42)
+	v, ok2 := s.Peek()
+	t.Assert(ok2 && v == 42, "peek should return the top item (42)")
+	t.Assert(s.Len() == 1, "peek should not remove the item")
+}
+
+#test
+fn testStackGenericString(t: &testing::T) {
+	mut s := Stack[string]{}
+	s.Push("a")
+	s.Push("b")
+	v, ok := s.Pop()
+	t.Assert(ok && v == "b", "generic string stack should pop \"b\"")
+}