From 1b3c0f0bc785c04275f7aaa35090818d49816d73 Mon Sep 17 00:00:00 2001
From: cloudnative0x0 <>
Date: Thu, 1 Oct 2026 14:31:41 +0300
Subject: [PATCH] trees added.
---
trees/bfs/README.md | 159 ++++++++++++++++++++++++++
trees/bfs/binary_tree.go | 162 +++++++++++++++++++++++++++
trees/bfs/binary_tree_test.go | 204 ++++++++++++++++++++++++++++++++++
trees/dfs/README.md | 177 +++++++++++++++++++++++++++++
trees/dfs/binary_tree.go | 120 ++++++++++++++++++++
trees/dfs/binary_tree_test.go | 119 ++++++++++++++++++++
6 files changed, 941 insertions(+)
create mode 100644 trees/bfs/README.md
create mode 100644 trees/bfs/binary_tree.go
create mode 100644 trees/bfs/binary_tree_test.go
create mode 100644 trees/dfs/README.md
create mode 100644 trees/dfs/binary_tree.go
create mode 100644 trees/dfs/binary_tree_test.go
diff --git a/trees/bfs/README.md b/trees/bfs/README.md
new file mode 100644
index 0000000..33948a3
--- /dev/null
+++ b/trees/bfs/README.md
@@ -0,0 +1,159 @@
+# Breadth-First Search (BFS) Binary Tree
+
+
+ Русский ・ English
+
+
+---
+
+## Русский
+
+Этот пакет содержит обычное бинарное дерево и показывает **поиск в ширину** (Breadth-First Search, BFS). BFS посещает дерево уровень за уровнем: сначала корень, затем всех его детей, потом внуков и так далее. Поэтому алгоритм использует очередь FIFO: первый обнаруженный узел обрабатывается первым.
+
+Для дерева
+
+```text
+ 1
+ / \
+ 2 3
+ / \ / \
+ 4 5 6 7
+```
+
+порядок BFS будет `1, 2, 3, 4, 5, 6, 7`.
+
+### Внутреннее устройство
+
+`Node` хранит целое значение и две ссылки: `Left` и `Right`. `New` по очереди передаёт значения в `Insert`. Вставка выполняет BFS и помещает новый узел в первую свободную позицию слева направо. Благодаря этому дерево остаётся **полным**: все уровни, кроме последнего, заполнены, а последний заполняется слева направо.
+
+`Search` тоже выполняет BFS и возвращает первый найденный узел. Если значения повторяются, это будет самое верхнее совпадение, а на одном уровне — самое левое.
+
+`Delete` находит целевой узел, копирует в него значение самого глубокого правого узла, а затем удаляет последний узел. Такой способ сохраняет форму полного бинарного дерева, но не поддерживает порядок бинарного дерева поиска: здесь нет правила `left < root < right`.
+
+Помимо BFS пакет предоставляет классические глубинные обходы:
+
+- `TraversePreOrder`: корень → левое поддерево → правое поддерево;
+- `TraverseInOrder`: левое поддерево → корень → правое поддерево;
+- `TraversePostOrder`: левое поддерево → правое поддерево → корень;
+- `TraverseBFS`: уровень за уровнем слева направо.
+
+### Зачем нужен BFS
+
+BFS полезен, когда бизнес-правило зависит от расстояния или уровня: поиск ближайшего сотрудника в иерархии, обход категорий по уровням, минимальное число переходов в невзвешенном графе, поиск ближайшего элемента интерфейса или заполнение дерева без разрывов. Для поиска глубокого решения при ограниченной памяти чаще подходит DFS.
+
+### Использование
+
+```go
+root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+found := root.Search(6) // узел со значением 6
+
+var values []int
+root.TraverseBFS(func(v int) {
+ values = append(values, v)
+}) // [1 2 3 4 5 6 7]
+
+root = Delete(root, 3)
+```
+
+### Операции и сложность
+
+Пусть `n` — число узлов, `w` — максимальная ширина дерева, `h` — его высота.
+
+| Операция | Время | Доп. память | Описание |
+|---|---:|---:|---|
+| `New(values)` | O(n²) | O(w) | текущая реализация вызывает BFS-вставку для каждого значения |
+| `Insert(root, value)` | O(n) | O(w) | найти первую свободную позицию по уровням |
+| `Search(value)` | O(n) | O(w) | найти первое совпадение в порядке BFS |
+| `Delete(root, value)` | O(n) | O(w) | поиск цели и последнего узла |
+| `TraverseBFS(visit)` | O(n) | O(w) | обойти дерево по уровням |
+| DFS-обходы | O(n) | O(h) | рекурсивный pre/in/post-order обход |
+
+В худшем случае очередь BFS хранит целый уровень. Для полного бинарного дерева это O(n). Рекурсивные DFS-обходы расходуют память стека пропорционально высоте.
+
+### Сборка и тестирование
+
+```bash
+go test -v ./trees/bfs
+```
+
+---
+
+## English
+
+This package contains a plain binary tree and demonstrates **breadth-first search** (BFS). BFS visits the tree level by level: the root first, then all of its children, then its grandchildren, and so on. It therefore uses a FIFO queue: the first discovered node is processed first.
+
+For this tree:
+
+```text
+ 1
+ / \
+ 2 3
+ / \ / \
+ 4 5 6 7
+```
+
+the BFS order is `1, 2, 3, 4, 5, 6, 7`.
+
+### Internal layout
+
+`Node` stores an integer value and two links, `Left` and `Right`. `New` passes values to `Insert` one by one. Insertion runs BFS and puts the new node into the first free position from left to right. This keeps the tree **complete**: every level except possibly the last is full, and the final level is filled from the left.
+
+`Search` also runs BFS and returns the first matching node. With duplicate values, this means the shallowest match, and the leftmost one among matches on the same level.
+
+`Delete` finds the target, copies the value of the deepest rightmost node into it, and removes that final node. This preserves the shape of a complete binary tree, but it does not maintain binary-search-tree ordering: there is no `left < root < right` rule here.
+
+The package also exposes the classic depth-first traversals:
+
+- `TraversePreOrder`: root → left subtree → right subtree;
+- `TraverseInOrder`: left subtree → root → right subtree;
+- `TraversePostOrder`: left subtree → right subtree → root;
+- `TraverseBFS`: level by level, left to right.
+
+### Why BFS is useful
+
+BFS fits business rules based on distance or level: finding the nearest employee in an organization hierarchy, processing category levels, finding the fewest hops in an unweighted graph, locating the nearest UI element, or filling a tree without gaps. DFS is often a better fit for deep exploration under a tighter memory budget.
+
+### Usage
+
+```go
+root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+found := root.Search(6) // node containing 6
+
+var values []int
+root.TraverseBFS(func(v int) {
+ values = append(values, v)
+}) // [1 2 3 4 5 6 7]
+
+root = Delete(root, 3)
+```
+
+### Operations and complexity
+
+Let `n` be the number of nodes, `w` the maximum tree width, and `h` its height.
+
+| Operation | Time | Extra space | Description |
+|---|---:|---:|---|
+| `New(values)` | O(n²) | O(w) | the current implementation performs one BFS insertion per value |
+| `Insert(root, value)` | O(n) | O(w) | find the first free level-order position |
+| `Search(value)` | O(n) | O(w) | find the first match in BFS order |
+| `Delete(root, value)` | O(n) | O(w) | locate the target and final node |
+| `TraverseBFS(visit)` | O(n) | O(w) | visit the tree level by level |
+| DFS traversals | O(n) | O(h) | recursive pre/in/post-order traversal |
+
+At worst, the BFS queue holds an entire level. For a complete binary tree that is O(n). Recursive DFS traversals use call-stack space proportional to the height.
+
+### Build and test
+
+```bash
+go test -v ./trees/bfs
+```
+
+---
+
+
+
+> BFS не спешит в глубину: сначала он выслушивает всех, кто рядом. Поэтому первым найденным ответом часто оказывается ближайший.
+>
+> *BFS does not rush into the depths: it first listens to everyone nearby. That is why the first answer it finds is often the closest one.*
diff --git a/trees/bfs/binary_tree.go b/trees/bfs/binary_tree.go
new file mode 100644
index 0000000..52737e4
--- /dev/null
+++ b/trees/bfs/binary_tree.go
@@ -0,0 +1,162 @@
+package bfs
+
+type Node struct {
+ Value int
+ Left *Node
+ Right *Node
+}
+
+func New(slice []int) *Node {
+ var root *Node
+
+ for _, v := range slice {
+ root = Insert(root, v)
+ }
+
+ return root
+}
+
+func Insert(root *Node, value int) *Node {
+ newNode := &Node{Value: value}
+ if root == nil {
+ return newNode
+ }
+
+ queue := []*Node{root}
+ for len(queue) > 0 {
+ cur := queue[0]
+ queue = queue[1:]
+
+ if cur.Left == nil {
+ cur.Left = newNode
+
+ return root
+ }
+ queue = append(queue, cur.Left)
+
+ if cur.Right == nil {
+ cur.Right = newNode
+
+ return root
+ }
+ queue = append(queue, cur.Right)
+ }
+
+ return root
+}
+
+func (n *Node) Search(value int) *Node {
+ if n == nil {
+ return nil
+ }
+
+ queue := []*Node{n}
+ for len(queue) > 0 {
+ cur := queue[0]
+ queue = queue[1:]
+
+ if cur.Value == value {
+ return cur
+ }
+ if cur.Left != nil {
+ queue = append(queue, cur.Left)
+ }
+ if cur.Right != nil {
+ queue = append(queue, cur.Right)
+ }
+ }
+
+ return nil
+}
+
+func Delete(root *Node, value int) *Node {
+ if root == nil {
+ return nil
+ }
+
+ target := root.Search(value)
+ if target == nil {
+ return root
+ }
+
+ var lastParent, last *Node
+ queue := []*Node{root}
+
+ for len(queue) > 0 {
+ cur := queue[0]
+ queue = queue[1:]
+
+ if cur.Left != nil {
+ lastParent, last = cur, cur.Left
+ queue = append(queue, cur.Left)
+ }
+ if cur.Right != nil {
+ lastParent, last = cur, cur.Right
+ queue = append(queue, cur.Right)
+ }
+ }
+
+ if last == nil {
+ return nil
+ }
+
+ target.Value = last.Value
+
+ if lastParent.Right == last {
+ lastParent.Right = nil
+ } else {
+ lastParent.Left = nil
+ }
+
+ return root
+}
+
+func (n *Node) TraversePreOrder(visit func(int)) {
+ if n == nil {
+ return
+ }
+
+ visit(n.Value)
+ n.Left.TraversePreOrder(visit)
+ n.Right.TraversePreOrder(visit)
+}
+
+func (n *Node) TraverseInOrder(visit func(int)) {
+ if n == nil {
+ return
+ }
+
+ n.Left.TraverseInOrder(visit)
+ visit(n.Value)
+ n.Right.TraverseInOrder(visit)
+}
+
+func (n *Node) TraversePostOrder(visit func(int)) {
+ if n == nil {
+ return
+ }
+
+ n.Left.TraversePostOrder(visit)
+ n.Right.TraversePostOrder(visit)
+ visit(n.Value)
+}
+
+func (n *Node) TraverseBFS(visit func(int)) {
+ if n == nil {
+ return
+ }
+
+ queue := []*Node{n}
+ for len(queue) > 0 {
+ cur := queue[0]
+ queue = queue[1:]
+
+ visit(cur.Value)
+ if cur.Left != nil {
+ queue = append(queue, cur.Left)
+ }
+ if cur.Right != nil {
+ queue = append(queue, cur.Right)
+ }
+ }
+}
diff --git a/trees/bfs/binary_tree_test.go b/trees/bfs/binary_tree_test.go
new file mode 100644
index 0000000..afc8e34
--- /dev/null
+++ b/trees/bfs/binary_tree_test.go
@@ -0,0 +1,204 @@
+package bfs
+
+import "testing"
+
+func TestBinaryTree(t *testing.T) {
+ root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+ var bfs []int
+ root.TraverseBFS(func(v int) { bfs = append(bfs, v) })
+ want := []int{1, 2, 3, 4, 5, 6, 7}
+ if !equal(bfs, want) {
+ t.Fatalf("BFS после вставки = %v, хотел %v", bfs, want)
+ }
+
+ if root.Left.Value != 2 || root.Right.Value != 3 {
+ t.Fatalf("первый уровень собран неверно: left=%d right=%d", root.Left.Value, root.Right.Value)
+ }
+ if root.Left.Left.Value != 4 || root.Left.Right.Value != 5 {
+ t.Fatalf("второй уровень (слева) собран неверно")
+ }
+
+ if found := root.Search(6); found == nil || found.Value != 6 {
+ t.Fatalf("Search(6) = %v", found)
+ }
+ if found := root.Search(42); found != nil {
+ t.Fatalf("Search(42) = %v, ожидал nil", found)
+ }
+
+ root = Delete(root, 3)
+
+ if root.Right.Value != 7 {
+ t.Fatalf("после Delete(3) на месте узла должно быть значение 7, получили %d", root.Right.Value)
+ }
+ if root.Right.Right != nil {
+ t.Fatalf("последний узел (7) должен был отрезаться, но он всё ещё на месте")
+ }
+ if root.Search(3) != nil {
+ t.Fatalf("значение 3 всё ещё находится после удаления")
+ }
+
+ for _, v := range []int{7, 6, 5, 4, 2} {
+ root = Delete(root, v)
+ }
+ if root == nil || root.Value != 1 || root.Left != nil || root.Right != nil {
+ t.Fatalf("ожидал единственный узел со значением 1, получили %+v", root)
+ }
+ root = Delete(root, 1)
+ if root != nil {
+ t.Fatalf("после удаления последнего узла дерево должно быть nil, получили %+v", root)
+ }
+}
+
+func TestBinaryEmptyTree(t *testing.T) {
+ if root := New(nil); root != nil {
+ t.Fatalf("New(nil) = %v, ожидал nil", root)
+ }
+ if root := New([]int{}); root != nil {
+ t.Fatalf("New([]int{}) = %v, ожидал nil", root)
+ }
+
+ var root *Node
+
+ if found := root.Search(1); found != nil {
+ t.Fatalf("Search на пустом дереве = %v, ожидал nil", found)
+ }
+ if got := Delete(root, 1); got != nil {
+ t.Fatalf("Delete на пустом дереве = %v, ожидал nil", got)
+ }
+
+ var visited []int
+ visit := func(v int) { visited = append(visited, v) }
+ root.TraversePreOrder(visit)
+ root.TraverseInOrder(visit)
+ root.TraversePostOrder(visit)
+ root.TraverseBFS(visit)
+ if len(visited) != 0 {
+ t.Fatalf("обходы пустого дерева что-то посетили: %v", visited)
+ }
+}
+
+func TestBinaryInsertOnNilRoot(t *testing.T) {
+ got := Insert(nil, 5)
+ if got == nil || got.Value != 5 {
+ t.Fatalf("Insert(nil, 5) = %v, ожидал узел со значением 5", got)
+ }
+}
+
+func TestBinarySingleElement(t *testing.T) {
+ root := New([]int{7})
+ if root == nil || root.Value != 7 || root.Left != nil || root.Right != nil {
+ t.Fatalf("New([]int{7}) = %+v, ожидал единственный узел 7", root)
+ }
+
+ root = Delete(root, 7)
+ if root != nil {
+ t.Fatalf("Delete последнего узла = %v, ожидал nil", root)
+ }
+}
+
+func TestBinaryDeleteNonExistent(t *testing.T) {
+ root := New([]int{1, 2, 3, 4, 5})
+
+ got := Delete(root, 999)
+ if got != root {
+ t.Fatalf("Delete несуществующего значения должен вернуть то же дерево без изменений")
+ }
+
+ var bfs []int
+ got.TraverseBFS(func(v int) { bfs = append(bfs, v) })
+ if !equal(bfs, []int{1, 2, 3, 4, 5}) {
+ t.Fatalf("дерево изменилось после неудачного Delete: %v", bfs)
+ }
+}
+
+func manualTree() *Node {
+ n4 := &Node{Value: 4}
+ n2 := &Node{Value: 2, Left: n4}
+ n3 := &Node{Value: 3}
+ return &Node{Value: 1, Left: n2, Right: n3}
+}
+
+func TestBinaryTraversalOrders(t *testing.T) {
+ root := manualTree()
+
+ cases := []struct {
+ name string
+ run func(func(int))
+ want []int
+ }{
+ {"PreOrder", root.TraversePreOrder, []int{1, 2, 4, 3}},
+ {"InOrder", root.TraverseInOrder, []int{4, 2, 1, 3}},
+ {"PostOrder", root.TraversePostOrder, []int{4, 2, 3, 1}},
+ {"BFS", root.TraverseBFS, []int{1, 2, 3, 4}},
+ }
+
+ for _, c := range cases {
+ t.Run(c.name, func(t *testing.T) {
+ var got []int
+ c.run(func(v int) { got = append(got, v) })
+ if !equal(got, c.want) {
+ t.Fatalf("%s = %v, хотел %v", c.name, got, c.want)
+ }
+ })
+ }
+}
+
+func isComplete(root *Node) bool {
+ queue := []*Node{root}
+ seenGap := false
+
+ for len(queue) > 0 {
+ n := queue[0]
+ queue = queue[1:]
+
+ if n == nil {
+ seenGap = true
+ continue
+ }
+ if seenGap {
+ return false
+ }
+ queue = append(queue, n.Left, n.Right)
+ }
+
+ return true
+}
+
+func TestBinaryStaysCompleteAfterInsertsAndDeletes(t *testing.T) {
+ var root *Node
+ for v := 1; v <= 15; v++ {
+ root = Insert(root, v)
+ if !isComplete(root) {
+ t.Fatalf("дерево перестало быть полным после вставки %d", v)
+ }
+ }
+
+ for _, v := range []int{8, 1, 15, 7, 3, 12} {
+ root = Delete(root, v)
+ if !isComplete(root) {
+ t.Fatalf("дерево перестало быть полным после удаления %d", v)
+ }
+ if root.Search(v) != nil {
+ t.Fatalf("значение %d всё ещё найдено после удаления", v)
+ }
+ }
+
+ var remaining []int
+ root.TraverseBFS(func(v int) { remaining = append(remaining, v) })
+ if len(remaining) != 9 {
+ t.Fatalf("осталось %d значений, ожидал 9: %v", len(remaining), remaining)
+ }
+}
+
+func equal(a, b []int) bool {
+ if len(a) != len(b) {
+ return false
+ }
+ for i := range a {
+ if a[i] != b[i] {
+ return false
+ }
+ }
+ return true
+}
diff --git a/trees/dfs/README.md b/trees/dfs/README.md
new file mode 100644
index 0000000..d4197aa
--- /dev/null
+++ b/trees/dfs/README.md
@@ -0,0 +1,177 @@
+# Depth-First Search (DFS) Binary Tree
+
+
+ Русский ・ English
+
+
+---
+
+## Русский
+
+Этот пакет демонстрирует **поиск в глубину** (Depth-First Search, DFS) на бинарном дереве. DFS выбирает ветку и идёт по ней настолько глубоко, насколько возможно. Когда продолжать некуда, алгоритм возвращается к ближайшей развилке и исследует следующую ветку.
+
+Для дерева
+
+```text
+ 1
+ / \
+ 2 3
+ / \ / \
+ 4 5 6 7
+```
+
+основной обход `TraverseDFS` использует pre-order и выдаёт `1, 2, 4, 5, 3, 6, 7`.
+
+### Внутреннее устройство
+
+`Node` хранит `Value` и ссылки `Left`/`Right`. `New` принимает значения в порядке уровней и за O(n) строит полное бинарное дерево: для элемента с индексом `i` дети находятся по индексам `2*i+1` и `2*i+2`.
+
+`Search` и `TraverseDFS` реализованы итеративно через стек LIFO. Сначала в стек кладётся правый ребёнок, затем левый: левый оказывается на вершине и обрабатывается первым. Итеративный вариант не расходует стек вызовов Go и поэтому подходит для очень глубоких деревьев лучше рекурсии.
+
+Пакет также содержит три классических рекурсивных порядка:
+
+- **pre-order** (`root → left → right`) — копирование дерева, сериализация, выполнение выражения в префиксной форме;
+- **in-order** (`left → root → right`) — получение отсортированных значений у бинарного дерева поиска;
+- **post-order** (`left → right → root`) — удаление дерева, подсчёт размера каталогов, вычисление выражений снизу вверх.
+
+`New` создаёт обычное полное бинарное дерево, а не бинарное дерево поиска. Поэтому `Search` не может отбросить половину дерева по сравнению значений и в худшем случае проверяет каждый узел.
+
+### Зачем нужен DFS
+
+DFS применяют там, где нужно полностью исследовать одну ветку перед переходом к следующей: обход файлов и DOM, анализ зависимостей, поиск циклов, топологическая сортировка, backtracking-задачи, проверка существования пути и обработка вложенных категорий. В отличие от BFS, первый найденный DFS путь не обязан быть кратчайшим.
+
+### Использование
+
+```go
+root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+found := root.Search(6) // узел со значением 6
+
+var values []int
+root.TraverseDFS(func(v int) {
+ values = append(values, v)
+}) // [1 2 4 5 3 6 7]
+```
+
+Дерево можно собрать вручную, если нужна конкретная форма:
+
+```go
+root := &Node{
+ Value: 10,
+ Left: &Node{Value: 5},
+ Right: &Node{Value: 20},
+}
+```
+
+### Операции и сложность
+
+Пусть `n` — число узлов, `h` — высота дерева.
+
+| Операция | Время | Доп. память | Описание |
+|---|---:|---:|---|
+| `New(values)` | O(n) | O(n) | создать узлы и связать их по индексам |
+| `Search(value)` | O(n) | O(h) в среднем, O(n) в худшем | найти первое совпадение в pre-order DFS |
+| `TraverseDFS(visit)` | O(n) | O(h) в среднем, O(n) в худшем | итеративный pre-order обход |
+| `TraversePreOrder` | O(n) | O(h) | рекурсивный обход root-left-right |
+| `TraverseInOrder` | O(n) | O(h) | рекурсивный обход left-root-right |
+| `TraversePostOrder` | O(n) | O(h) | рекурсивный обход left-right-root |
+
+Для сбалансированного дерева `h = O(log n)`. Для дерева-цепочки `h = O(n)`. У итеративного DFS фактический размер стека зависит от числа ещё не исследованных развилок: на цепочке он может оставаться O(1), но общая верхняя граница — O(n).
+
+### Сборка и тестирование
+
+```bash
+go test -v ./trees/dfs
+```
+
+Тесты проверяют построение дерева, все порядки обхода, отсутствующие и повторяющиеся значения, nil-получатели и итеративный обход цепочки из 100 000 узлов.
+
+---
+
+## English
+
+This package demonstrates **depth-first search** (DFS) on a binary tree. DFS selects one branch and follows it as deeply as possible. Once it cannot continue, it backtracks to the nearest fork and explores the next branch.
+
+For this tree:
+
+```text
+ 1
+ / \
+ 2 3
+ / \ / \
+ 4 5 6 7
+```
+
+the primary `TraverseDFS` traversal uses pre-order and produces `1, 2, 4, 5, 3, 6, 7`.
+
+### Internal layout
+
+`Node` stores a `Value` and `Left`/`Right` links. `New` accepts values in level order and builds a complete binary tree in O(n): the children of item `i` are located at indices `2*i+1` and `2*i+2`.
+
+`Search` and `TraverseDFS` are iterative and use a LIFO stack. The right child is pushed before the left one, leaving the left child on top to be processed first. The iterative form does not consume the Go call stack, so it is safer than recursion for very deep trees.
+
+The package also provides three classic recursive orders:
+
+- **pre-order** (`root → left → right`) — copying a tree, serialization, prefix-expression evaluation;
+- **in-order** (`left → root → right`) — obtaining sorted values from a binary search tree;
+- **post-order** (`left → right → root`) — deleting a tree, computing directory sizes, bottom-up expression evaluation.
+
+`New` creates a plain complete binary tree, not a binary search tree. Therefore `Search` cannot discard half of the tree by comparing values and may inspect every node in the worst case.
+
+### Why DFS is useful
+
+DFS is useful when one branch must be fully explored before moving to the next: traversing file trees and the DOM, dependency analysis, cycle detection, topological sorting, backtracking, reachability checks, and processing nested categories. Unlike BFS, the first path found by DFS is not necessarily the shortest one.
+
+### Usage
+
+```go
+root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+found := root.Search(6) // node containing 6
+
+var values []int
+root.TraverseDFS(func(v int) {
+ values = append(values, v)
+}) // [1 2 4 5 3 6 7]
+```
+
+Build the tree manually when a specific shape is required:
+
+```go
+root := &Node{
+ Value: 10,
+ Left: &Node{Value: 5},
+ Right: &Node{Value: 20},
+}
+```
+
+### Operations and complexity
+
+Let `n` be the number of nodes and `h` their tree height.
+
+| Operation | Time | Extra space | Description |
+|---|---:|---:|---|
+| `New(values)` | O(n) | O(n) | allocate nodes and link them by index |
+| `Search(value)` | O(n) | O(h) average, O(n) worst case | find the first pre-order DFS match |
+| `TraverseDFS(visit)` | O(n) | O(h) average, O(n) worst case | iterative pre-order traversal |
+| `TraversePreOrder` | O(n) | O(h) | recursive root-left-right traversal |
+| `TraverseInOrder` | O(n) | O(h) | recursive left-root-right traversal |
+| `TraversePostOrder` | O(n) | O(h) | recursive left-right-root traversal |
+
+For a balanced tree, `h = O(log n)`. For a chain-shaped tree, `h = O(n)`. The actual iterative DFS stack size depends on the number of unexplored forks: it can stay O(1) on a chain, while its general upper bound is O(n).
+
+### Build and test
+
+```bash
+go test -v ./trees/dfs
+```
+
+Tests cover tree construction, every traversal order, missing and duplicate values, nil receivers, and iterative traversal of a 100,000-node chain.
+
+---
+
+
+
+> DFS выбирает путь и следует ему до конца. Глубина даёт ответ быстрее, когда нужная ветка выбрана верно, но не обещает, что найденный путь окажется кратчайшим.
+>
+> *DFS chooses a path and follows it to the end. Depth finds an answer quickly when the right branch is chosen, but it never promises that the discovered path is the shortest.*
diff --git a/trees/dfs/binary_tree.go b/trees/dfs/binary_tree.go
new file mode 100644
index 0000000..eb43658
--- /dev/null
+++ b/trees/dfs/binary_tree.go
@@ -0,0 +1,120 @@
+package dfs
+
+// Node is a node of a binary tree.
+type Node struct {
+ Value int
+ Left *Node
+ Right *Node
+}
+
+// New builds a complete binary tree from values given in level order.
+// For example, []int{1, 2, 3} creates a root 1 with children 2 and 3.
+func New(values []int) *Node {
+ if len(values) == 0 {
+ return nil
+ }
+
+ nodes := make([]*Node, len(values))
+ for i, value := range values {
+ nodes[i] = &Node{Value: value}
+ }
+
+ for i := range nodes {
+ left := 2*i + 1
+ right := 2*i + 2
+ if left < len(nodes) {
+ nodes[i].Left = nodes[left]
+ }
+ if right < len(nodes) {
+ nodes[i].Right = nodes[right]
+ }
+ }
+
+ return nodes[0]
+}
+
+// Search performs iterative depth-first search in pre-order and returns the
+// first node whose value matches. The left subtree is explored before the
+// right subtree.
+func (n *Node) Search(value int) *Node {
+ if n == nil {
+ return nil
+ }
+
+ stack := []*Node{n}
+ for len(stack) > 0 {
+ last := len(stack) - 1
+ current := stack[last]
+ stack = stack[:last]
+
+ if current.Value == value {
+ return current
+ }
+
+ // The stack is LIFO, so push right first to visit left first.
+ if current.Right != nil {
+ stack = append(stack, current.Right)
+ }
+ if current.Left != nil {
+ stack = append(stack, current.Left)
+ }
+ }
+
+ return nil
+}
+
+// TraverseDFS performs iterative pre-order DFS: root, left, right.
+// A nil visit function is treated as a no-op.
+func (n *Node) TraverseDFS(visit func(int)) {
+ if n == nil || visit == nil {
+ return
+ }
+
+ stack := []*Node{n}
+ for len(stack) > 0 {
+ last := len(stack) - 1
+ current := stack[last]
+ stack = stack[:last]
+
+ visit(current.Value)
+ if current.Right != nil {
+ stack = append(stack, current.Right)
+ }
+ if current.Left != nil {
+ stack = append(stack, current.Left)
+ }
+ }
+}
+
+// TraversePreOrder visits root, left subtree, then right subtree.
+func (n *Node) TraversePreOrder(visit func(int)) {
+ if n == nil || visit == nil {
+ return
+ }
+
+ visit(n.Value)
+ n.Left.TraversePreOrder(visit)
+ n.Right.TraversePreOrder(visit)
+}
+
+// TraverseInOrder visits left subtree, root, then right subtree.
+func (n *Node) TraverseInOrder(visit func(int)) {
+ if n == nil || visit == nil {
+ return
+ }
+
+ n.Left.TraverseInOrder(visit)
+ visit(n.Value)
+ n.Right.TraverseInOrder(visit)
+}
+
+// TraversePostOrder visits left subtree, right subtree, then root.
+func (n *Node) TraversePostOrder(visit func(int)) {
+ if n == nil || visit == nil {
+ return
+ }
+
+ n.Left.TraversePostOrder(visit)
+ n.Right.TraversePostOrder(visit)
+ visit(n.Value)
+}
diff --git a/trees/dfs/binary_tree_test.go b/trees/dfs/binary_tree_test.go
new file mode 100644
index 0000000..4b5c32c
--- /dev/null
+++ b/trees/dfs/binary_tree_test.go
@@ -0,0 +1,119 @@
+package dfs
+
+import (
+ "slices"
+ "testing"
+)
+
+func TestNewBuildsCompleteTree(t *testing.T) {
+ root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+ if root == nil || root.Value != 1 {
+ t.Fatalf("root = %+v, want node 1", root)
+ }
+ if root.Left.Value != 2 || root.Right.Value != 3 {
+ t.Fatalf("first level = (%d, %d), want (2, 3)", root.Left.Value, root.Right.Value)
+ }
+ if root.Left.Left.Value != 4 || root.Left.Right.Value != 5 {
+ t.Fatalf("children of node 2 are incorrect")
+ }
+ if root.Right.Left.Value != 6 || root.Right.Right.Value != 7 {
+ t.Fatalf("children of node 3 are incorrect")
+ }
+}
+
+func TestNewEmpty(t *testing.T) {
+ if got := New(nil); got != nil {
+ t.Fatalf("New(nil) = %+v, want nil", got)
+ }
+ if got := New([]int{}); got != nil {
+ t.Fatalf("New(empty) = %+v, want nil", got)
+ }
+}
+
+func TestTraverseOrders(t *testing.T) {
+ root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+ tests := []struct {
+ name string
+ run func(func(int))
+ want []int
+ }{
+ {name: "DFS", run: root.TraverseDFS, want: []int{1, 2, 4, 5, 3, 6, 7}},
+ {name: "pre-order", run: root.TraversePreOrder, want: []int{1, 2, 4, 5, 3, 6, 7}},
+ {name: "in-order", run: root.TraverseInOrder, want: []int{4, 2, 5, 1, 6, 3, 7}},
+ {name: "post-order", run: root.TraversePostOrder, want: []int{4, 5, 2, 6, 7, 3, 1}},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ var got []int
+ tt.run(func(value int) { got = append(got, value) })
+ if !slices.Equal(got, tt.want) {
+ t.Fatalf("order = %v, want %v", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestSearch(t *testing.T) {
+ root := New([]int{1, 2, 3, 4, 5, 6, 7})
+
+ if got := root.Search(6); got == nil || got.Value != 6 {
+ t.Fatalf("Search(6) = %+v, want node 6", got)
+ }
+ if got := root.Search(42); got != nil {
+ t.Fatalf("Search(42) = %+v, want nil", got)
+ }
+}
+
+func TestSearchReturnsFirstMatchInDFSOrder(t *testing.T) {
+ leftMatch := &Node{Value: 9}
+ rightMatch := &Node{Value: 9}
+ root := &Node{
+ Value: 1,
+ Left: &Node{Value: 2, Left: leftMatch},
+ Right: rightMatch,
+ }
+
+ if got := root.Search(9); got != leftMatch {
+ t.Fatalf("Search(9) = %p, want left DFS match %p", got, leftMatch)
+ }
+}
+
+func TestNilReceiverAndNilVisitor(t *testing.T) {
+ var root *Node
+ if got := root.Search(1); got != nil {
+ t.Fatalf("Search on nil tree = %+v, want nil", got)
+ }
+
+ root.TraverseDFS(nil)
+ root.TraversePreOrder(nil)
+ root.TraverseInOrder(nil)
+ root.TraversePostOrder(nil)
+
+ nonEmpty := New([]int{1, 2, 3})
+ nonEmpty.TraverseDFS(nil)
+ nonEmpty.TraversePreOrder(nil)
+ nonEmpty.TraverseInOrder(nil)
+ nonEmpty.TraversePostOrder(nil)
+}
+
+func TestIterativeDFSHandlesDeepTree(t *testing.T) {
+ const depth = 100_000
+ root := &Node{Value: 0}
+ current := root
+ for i := 1; i < depth; i++ {
+ current.Left = &Node{Value: i}
+ current = current.Left
+ }
+
+ visited := 0
+ root.TraverseDFS(func(int) { visited++ })
+ if visited != depth {
+ t.Fatalf("visited %d nodes, want %d", visited, depth)
+ }
+ if got := root.Search(depth - 1); got == nil || got.Value != depth-1 {
+ t.Fatalf("failed to find deepest node: %+v", got)
+ }
+}