Deque

Author: krotname

src/main/java/algorithms/sprint2/Deque.java

@@ -5,6 +5,49 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/*
+Принцип работы алгоритма
+Используется дек фиксированного размера m, реализованный на массиве как кольцевой буфер.
+Храним:
+- a[] — массив ёмкости m;
+- head — индекс первого элемента дека;
+- tail — индекс позиции "после последнего" элемента дека;
+- size — текущее количество элементов.
+
+Индексы head и tail двигаются по кругу: при выходе за границу массива переходят в начало/конец.
+Операции:
+- push_back(x): записать x в a[tail], сдвинуть tail вперёд по кругу, увеличить size.
+- push_front(x): сдвинуть head назад по кругу, записать x в a[head], увеличить size.
+- pop_front(): взять a[head], сдвинуть head вперёд, уменьшить size.
+- pop_back(): сдвинуть tail назад, взять a[tail], уменьшить size.
+
+Корректность (почему работает)
+Поддерживаются инварианты:
+1) size всегда в диапазоне [0..m].
+2) head указывает на первый элемент (если size > 0).
+3) tail указывает на позицию сразу после последнего элемента (если size > 0).
+4) Элементы дека в порядке обхода лежат в a по циклу, начиная с head и длиной size.
+
+Проверка по операциям:
+- push_back при size < m кладёт новый элемент ровно в позицию tail, затем tail сдвигается на следующую
+  позицию по кругу, поэтому tail снова указывает на "после последнего", а порядок элементов сохраняется.
+- push_front при size < m сначала сдвигает head на предыдущую позицию по кругу и кладёт туда новый элемент,
+  поэтому head начинает указывать на добавленный элемент (он становится первым), а порядок сохраняется.
+- pop_front при size > 0 читает первый элемент из a[head], затем сдвигает head вперёд, уменьшая size:
+  новым первым становится следующий элемент, инварианты сохраняются.
+- pop_back при size > 0 сначала сдвигает tail назад (на позицию последнего элемента), читает его и уменьшает size:
+  tail снова становится "после последнего", инварианты сохраняются.
+
+Ошибки "error" выводятся только когда операция невозможна:
+- push_* при size == m (переполнение),
+- pop_* при size == 0 (пустой дек).
+В этих случаях состояние (head, tail, size) не меняется, что сохраняет инварианты.
+
+Сложность
+Каждая операция дека выполняет константное число действий: O(1) по времени.
+Память: массив из m элементов и несколько целых переменных: O(m) по памяти.
+*/
+
 public class Deque {
 
     // -------------------- FAST INPUT --------------------
@@ -296,7 +339,7 @@ private static void test() throws Exception {
                 )
         );
 
-        // Емкость 1 + переполнение
+        // Емкость 1 + переполнение + попытка pop из пустого
         assertEq(
                 "error\n1\nerror\n",
                 solveIO(
@@ -309,7 +352,7 @@ private static void test() throws Exception {
                 )
         );
 
-        // Проверка кольцевого перехода (wrap-around)
+        // Wrap-around: head/tail должны корректно "перепрыгивать" границу массива
         assertEq(
                 "1\n4\n2\n3\n",
                 solveIO(