Merge pull request #1 from cloudnative0x0/stack

stack implemented, doc and test created.

Author: cloudnative0x0

main.go

@@ -0,0 +1,111 @@
+# Stack
+
+<p style="text-align: left">
+  <a href="#русский">Русский</a> ・ <a href="#english">English</a>
+</p>
+
+---
+
+## Русский
+
+Стек — линейная структура данных, работающая по принципу **LIFO** (Last In, First Out): последний вошедший элемент выходит первым.
+
+Пример: если добавить элементы в порядке `1, 2, 3`, то `3` окажется наверху и будет извлечён первым, следом `2`, затем `1`. Порядок входа и выхода полностью противоположный.
+
+### Внутреннее устройство
+
+Реализация хранит срез `arr` и число `top` — индекс последнего добавленного элемента. Активная часть стека — это `arr[1..top]`, где:
+
+- `arr[1]` — нижний, самый первый добавленный элемент
+- `arr[top]` — вершина стека, элемент, добавленный последним
+
+Если `top == 0`, стек пуст. Если `top == n` (максимальная вместимость), попытка добавить новый элемент приводит к переполнению.
+
+Срез создаётся размером `n+1`, а не `n` — нулевая ячейка `arr[0]` физически существует, но не используется, поскольку индексация ведётся с 1, как в оригинальном псевдокоде.
+
+### Использование
+
+```go
+s := NewStack(5)
+
+s.Push(1)
+s.Push(2)
+s.Push(3)
+
+val, err := s.Pop() // val = 3, err = nil
+```
+
+### Операции
+
+| Операция | Сложность | Описание |
+|---|---|---|
+| `Push(x)` | O(1) | добавить элемент на вершину |
+| `Pop()` | O(1) | снять и вернуть элемент с вершины |
+| `IsEmpty()` | O(1) | проверка на пустоту |
+| `IsFull()` | O(1) | проверка на переполнение |
+| `Size()` | O(1) | текущее количество элементов |
+
+### Сборка и тестирование
+
+```bash
+go test -v ./...
+```
+
+Корректность проверяется stress-тестом — реализация сравнивается с обычным срезом, работающим как стек, на большом числе случайных последовательностей операций.
+
+---
+
+## English
+
+A stack is a linear data structure that follows the **LIFO** principle (Last In, First Out): the element inserted last is the first one to leave.
+
+Example: inserting elements in the order `1, 2, 3` places `3` on top, so it comes out first, followed by `2`, then `1`. The exit order is the exact reverse of the entry order.
+
+### Internal layout
+
+The implementation keeps a slice `arr` and a number `top` — the index of the most recently inserted element. The active part of the stack is `arr[1..top]`, where:
+
+- `arr[1]` is the bottom, the very first element inserted
+- `arr[top]` is the top of the stack, the most recently inserted element
+
+If `top == 0`, the stack is empty. If `top == n` (the fixed capacity), inserting another element causes an overflow.
+
+The slice is allocated with size `n+1`, not `n` — the zero cell `arr[0]` exists but is never used, since indexing starts at 1, matching the original pseudocode.
+
+### Usage
+
+```go
+s := NewStack(5)
+
+s.Push(1)
+s.Push(2)
+s.Push(3)
+
+val, err := s.Pop() // val = 3, err = nil
+```
+
+### Operations
+
+| Operation | Complexity | Description |
+|---|---|---|
+| `Push(x)` | O(1) | insert an element on top |
+| `Pop()` | O(1) | remove and return the top element |
+| `IsEmpty()` | O(1) | check whether the stack is empty |
+| `IsFull()` | O(1) | check whether the stack is at capacity |
+| `Size()` | O(1) | current number of elements |
+
+### Build and test
+
+```bash
+go test -v ./...
+```
+
+Correctness is checked with a stress test — the implementation is compared against a plain slice used as a stack, over a large number of randomized operation sequences.
+
+---
+
+<br>
+
+> Стек не помнит, кто был первым. Он помнит только, кто был последним — и отдаёт именно его. Так устроена память толпы, поколений, целых цивилизаций: наверху всегда то, что случилось недавно, а самое первое, изначальное, погребено глубже всего и достаётся последним, если вообще достаётся.
+>
+> *A stack has no memory of who came first. It only remembers who came last — and gives that one back. This is how the memory of a crowd works, of generations, of entire civilizations: what happened recently always sits on top, while the very first, the original, lies buried deepest and is reached last, if it is reached at all.*

stack/README.md

@@ -0,0 +1,50 @@
+package stack
+
+import "fmt"
+
+type Stack struct {
+	arr []int
+	top int
+	n   int
+}
+
+func NewStack(n int) *Stack {
+	return &Stack{
+		arr: make([]int, n+1),
+		top: 0,
+		n:   n,
+	}
+}
+
+func (s *Stack) Pop() (int, error) {
+	if s.top == 0 {
+		return 0, fmt.Errorf("stack underflow")
+	}
+
+	s.top = s.top - 1
+
+	return s.arr[s.top+1], nil
+}
+
+func (s *Stack) Push(x int) error {
+	if s.IsFull() {
+		return fmt.Errorf("stack overflow")
+	}
+
+	s.top = s.top + 1
+	s.arr[s.top] = x
+
+	return nil
+}
+
+func (s *Stack) IsEmpty() bool {
+	return s.top == 0
+}
+
+func (s *Stack) IsFull() bool {
+	return s.top == s.n
+}
+
+func (s *Stack) Size() int {
+	return s.top
+}

stack/stack.go

@@ -0,0 +1,156 @@
+package stack
+
+import (
+	"math/rand"
+	"testing"
+)
+
+func TestPushPop(t *testing.T) {
+	s := NewStack(5)
+
+	if err := s.Push(10); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+
+	val, err := s.Pop()
+	if err != nil {
+		t.Fatalf("unexpected error on pop: %v", err)
+	}
+	if val != 10 {
+		t.Errorf("expected 10, got %d", val)
+	}
+}
+
+func TestLIFOOrder(t *testing.T) {
+	s := NewStack(3)
+
+	if err := s.Push(1); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+	if err := s.Push(2); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+	if err := s.Push(3); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+
+	expected := []int{3, 2, 1}
+
+	for i, want := range expected {
+		got, err := s.Pop()
+		if err != nil {
+			t.Fatalf("unexpected error on pop #%d: %v", i, err)
+		}
+		if got != want {
+			t.Errorf("pop #%d: expected %d, got %d", i, want, got)
+		}
+	}
+}
+
+func TestEmptyStack(t *testing.T) {
+	s := NewStack(3)
+
+	if !s.IsEmpty() {
+		t.Error("new stack should be empty")
+	}
+
+	_, err := s.Pop()
+	if err == nil {
+		t.Error("expected underflow error, got nil")
+	}
+}
+
+func TestFullStack(t *testing.T) {
+	s := NewStack(2)
+
+	if err := s.Push(1); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+	if err := s.Push(2); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+
+	if !s.IsFull() {
+		t.Error("stack should be full")
+	}
+
+	err := s.Push(3)
+	if err == nil {
+		t.Error("expected overflow error, got nil")
+	}
+}
+
+func TestSize(t *testing.T) {
+	s := NewStack(5)
+
+	if s.Size() != 0 {
+		t.Errorf("expected size 0, got %d", s.Size())
+	}
+
+	if err := s.Push(1); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+	if err := s.Push(2); err != nil {
+		t.Fatalf("unexpected error on push: %v", err)
+	}
+
+	if s.Size() != 2 {
+		t.Errorf("expected size 2, got %d", s.Size())
+	}
+
+	if _, err := s.Pop(); err != nil {
+		t.Fatalf("unexpected error on pop: %v", err)
+	}
+
+	if s.Size() != 1 {
+		t.Errorf("expected size 1, got %d", s.Size())
+	}
+}
+
+func TestStress(t *testing.T) {
+	rng := rand.New(rand.NewSource(42))
+
+	const iterations = 1000
+	const opsPerIteration = 50
+	const capacity = 30
+
+	for iter := 0; iter < iterations; iter++ {
+		mine := NewStack(capacity)
+		var ref []int
+
+		for op := 0; op < opsPerIteration; op++ {
+			switch rng.Intn(3) {
+			case 0: // push
+				if !mine.IsFull() {
+					val := rng.Intn(1000)
+					if err := mine.Push(val); err != nil {
+						t.Fatalf("iter %d: unexpected push error: %v", iter, err)
+					}
+					ref = append(ref, val)
+				}
+
+			case 1: // pop
+				if len(ref) > 0 {
+					want := ref[len(ref)-1]
+					ref = ref[:len(ref)-1]
+
+					got, err := mine.Pop()
+					if err != nil {
+						t.Fatalf("iter %d: unexpected pop error: %v", iter, err)
+					}
+					if got != want {
+						t.Fatalf("iter %d: mismatch on pop: expected %d, got %d", iter, want, got)
+					}
+				}
+
+			case 2:
+				if mine.Size() != len(ref) {
+					t.Fatalf("iter %d: size mismatch: expected %d, got %d", iter, len(ref), mine.Size())
+				}
+				if mine.IsEmpty() != (len(ref) == 0) {
+					t.Fatalf("iter %d: isEmpty mismatch", iter)
+				}
+			}
+		}
+	}
+}