feat: add vector core structure

Author: jeresoftx

src/vector.rs

@@ -2,3 +2,218 @@
 //!
 //! Este modulo enseñara capacidad, longitud, crecimiento amortizado, acceso por
 //! indice y las compensaciones de memoria contigua.
+
+/// Arreglo dinamico contiguo para estudiar longitud, capacidad y crecimiento.
+///
+/// Esta primera implementacion prioriza invariantes visibles y Rust seguro. Usa
+/// `Option<T>` como celda inicializada para evitar gestion manual de memoria; el
+/// capitulo explica que una implementacion industrial usa memoria sin inicializar
+/// y requiere `unsafe` cuidadosamente justificado.
+#[derive(Debug)]
+pub struct Vector<T> {
+    items: Box<[Option<T>]>,
+    len: usize,
+}
+
+/// Error al insertar en una posicion que no existe.
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub struct InsertError {
+    /// Indice solicitado por quien llama.
+    pub index: usize,
+    /// Longitud del vector en el momento de la operacion.
+    pub len: usize,
+}
+
+impl<T> Vector<T> {
+    /// Crea un vector vacio sin capacidad reservada.
+    ///
+    /// Complejidad: O(1) tiempo y O(1) espacio.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            items: allocate_slots(0),
+            len: 0,
+        }
+    }
+
+    /// Crea un vector vacio con capacidad para `capacity` elementos.
+    ///
+    /// Complejidad: O(n) tiempo y O(n) espacio, donde `n` es `capacity`, porque
+    /// esta version segura inicializa cada celda con `None`.
+    #[must_use]
+    pub fn with_capacity(capacity: usize) -> Self {
+        Self {
+            items: allocate_slots(capacity),
+            len: 0,
+        }
+    }
+
+    /// Devuelve el numero de elementos almacenados.
+    ///
+    /// Complejidad: O(1).
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.len
+    }
+
+    /// Devuelve la cantidad de elementos que caben sin crecer.
+    ///
+    /// Complejidad: O(1).
+    #[must_use]
+    pub fn capacity(&self) -> usize {
+        self.items.len()
+    }
+
+    /// Indica si el vector no contiene elementos.
+    ///
+    /// Complejidad: O(1).
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len == 0
+    }
+
+    /// Agrega `value` al final del vector.
+    ///
+    /// Complejidad: O(1) amortizado. Cuando la capacidad se agota, crecer cuesta
+    /// O(n) porque se mueven los elementos al nuevo bloque.
+    pub fn push(&mut self, value: T) {
+        if self.len == self.capacity() {
+            self.grow();
+        }
+
+        self.items[self.len] = Some(value);
+        self.len += 1;
+    }
+
+    /// Remueve y devuelve el ultimo elemento, si existe.
+    ///
+    /// Complejidad: O(1).
+    pub fn pop(&mut self) -> Option<T> {
+        if self.is_empty() {
+            return None;
+        }
+
+        self.len -= 1;
+        self.items[self.len].take()
+    }
+
+    /// Devuelve una referencia al elemento en `index`, si existe.
+    ///
+    /// Complejidad: O(1).
+    #[must_use]
+    pub fn get(&self, index: usize) -> Option<&T> {
+        if index >= self.len {
+            return None;
+        }
+
+        self.items[index].as_ref()
+    }
+
+    /// Devuelve una referencia mutable al elemento en `index`, si existe.
+    ///
+    /// Complejidad: O(1).
+    pub fn get_mut(&mut self, index: usize) -> Option<&mut T> {
+        if index >= self.len {
+            return None;
+        }
+
+        self.items[index].as_mut()
+    }
+
+    /// Inserta `value` en `index`, desplazando a la derecha los elementos
+    /// posteriores.
+    ///
+    /// `index == len` es valido y equivale a `push`. Un indice mayor que `len`
+    /// devuelve `InsertError`.
+    ///
+    /// Complejidad: O(n) en el peor caso por el desplazamiento.
+    pub fn insert(&mut self, index: usize, value: T) -> Result<(), InsertError> {
+        if index > self.len {
+            return Err(InsertError {
+                index,
+                len: self.len,
+            });
+        }
+
+        if self.len == self.capacity() {
+            self.grow();
+        }
+
+        for current in (index..self.len).rev() {
+            self.items[current + 1] = self.items[current].take();
+        }
+
+        self.items[index] = Some(value);
+        self.len += 1;
+
+        Ok(())
+    }
+
+    /// Remueve y devuelve el elemento en `index`, si existe.
+    ///
+    /// Complejidad: O(n) en el peor caso por el desplazamiento.
+    pub fn remove(&mut self, index: usize) -> Option<T> {
+        if index >= self.len {
+            return None;
+        }
+
+        let removed = self.items[index].take();
+
+        for current in index + 1..self.len {
+            self.items[current - 1] = self.items[current].take();
+        }
+
+        self.len -= 1;
+        self.items[self.len] = None;
+
+        removed
+    }
+
+    /// Remueve todos los elementos sin liberar la capacidad reservada.
+    ///
+    /// Complejidad: O(n).
+    pub fn clear(&mut self) {
+        for index in 0..self.len {
+            self.items[index] = None;
+        }
+
+        self.len = 0;
+    }
+
+    /// Itera sobre referencias a los elementos almacenados.
+    ///
+    /// Complejidad: O(1) para crear el iterador y O(n) para consumirlo completo.
+    pub fn iter(&self) -> impl Iterator<Item = &T> {
+        self.items[..self.len]
+            .iter()
+            .map(|slot| slot.as_ref().expect("occupied slots before len"))
+    }
+
+    fn grow(&mut self) {
+        let next_capacity = if self.capacity() == 0 {
+            1
+        } else {
+            self.capacity() * 2
+        };
+
+        let mut next_items = allocate_slots(next_capacity);
+        for index in 0..self.len {
+            next_items[index] = self.items[index].take();
+        }
+
+        self.items = next_items;
+    }
+}
+
+impl<T> Default for Vector<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn allocate_slots<T>(capacity: usize) -> Box<[Option<T>]> {
+    std::iter::repeat_with(|| None)
+        .take(capacity)
+        .collect::<Vec<_>>()
+        .into_boxed_slice()
+}

tests/vector_test.rs

@@ -0,0 +1,80 @@
+use rust_data_structures::vector::Vector;
+
+#[test]
+fn push_and_pop_preserve_lifo_order_at_the_back() {
+    let mut values = Vector::new();
+
+    assert!(values.is_empty());
+    assert_eq!(values.len(), 0);
+    assert_eq!(values.capacity(), 0);
+
+    values.push("a");
+    values.push("b");
+
+    assert_eq!(values.len(), 2);
+    assert!(values.capacity() >= 2);
+    assert_eq!(values.pop(), Some("b"));
+    assert_eq!(values.pop(), Some("a"));
+    assert_eq!(values.pop(), None);
+    assert!(values.is_empty());
+}
+
+#[test]
+fn get_and_get_mut_access_existing_indexes_only() {
+    let mut values = Vector::with_capacity(4);
+
+    values.push(10);
+    values.push(20);
+
+    assert_eq!(values.capacity(), 4);
+    assert_eq!(values.get(0), Some(&10));
+    assert_eq!(values.get(1), Some(&20));
+    assert_eq!(values.get(2), None);
+
+    *values.get_mut(1).expect("index 1 exists") = 25;
+
+    assert_eq!(values.get(1), Some(&25));
+}
+
+#[test]
+fn insert_and_remove_shift_elements_without_losing_order() {
+    let mut values = Vector::new();
+
+    values.push(1);
+    values.push(3);
+    values
+        .insert(1, 2)
+        .expect("index 1 is a valid insertion point");
+    values.insert(3, 4).expect("len is a valid insertion point");
+
+    assert_eq!(values.len(), 4);
+    assert_eq!(values.get(0), Some(&1));
+    assert_eq!(values.get(1), Some(&2));
+    assert_eq!(values.get(2), Some(&3));
+    assert_eq!(values.get(3), Some(&4));
+    assert!(values.insert(5, 99).is_err());
+
+    assert_eq!(values.remove(1), Some(2));
+    assert_eq!(values.remove(2), Some(4));
+    assert_eq!(values.remove(2), None);
+    assert_eq!(values.get(0), Some(&1));
+    assert_eq!(values.get(1), Some(&3));
+}
+
+#[test]
+fn iter_and_clear_expose_values_without_leaking_capacity() {
+    let mut values = Vector::with_capacity(8);
+
+    values.push("vector");
+    values.push("heap");
+    values.push("trie");
+
+    let collected = values.iter().copied().collect::<Vec<_>>();
+    assert_eq!(collected, vec!["vector", "heap", "trie"]);
+
+    values.clear();
+
+    assert!(values.is_empty());
+    assert_eq!(values.capacity(), 8);
+    assert_eq!(values.iter().next(), None);
+}