From 25f74081580f4ff8268951ea3fec1a556f709339 Mon Sep 17 00:00:00 2001
From: kinou-p <alexpomms@gmail.com>
Date: Thu, 2 Oct 2025 10:15:17 +0200
Subject: [PATCH] docs: add detailed README for STL containers implementation

---
 README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 187 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7b0efae
--- /dev/null
+++ b/README.md
@@ -0,0 +1,187 @@
+# ft_containers
+
+## Description
+ft_containers est un projet de l'École 42 qui consiste à ré-implémenter plusieurs conteneurs de la STL (Standard Template Library) de C++. Ce projet permet de comprendre en profondeur le fonctionnement interne des conteneurs et des itérateurs.
+
+## Objectifs pédagogiques
+- Maîtriser la **programmation générique** en C++
+- Comprendre l'implémentation des **structures de données**
+- Implémenter des **itérateurs** conformes aux standards
+- Respecter les **spécifications STL**
+- Optimiser les **performances** des algorithmes
+
+## Conteneurs implémentés
+
+### Vector
+- Tableau dynamique redimensionnable
+- Accès aléatoire en O(1)
+- Insertion/suppression en fin en O(1) amorti
+- Support complet des itérateurs
+
+### Map
+- Conteneur associatif ordonné (Red-Black Tree)
+- Recherche, insertion, suppression en O(log n)
+- Itérateurs bidirectionnels
+- Ordre basé sur les clés
+
+### Stack
+- Adaptateur de conteneur (LIFO)
+- Basé sur un conteneur sous-jacent (vector par défaut)
+- Opérations push, pop, top
+
+### Set (Bonus)
+- Conteneur d'éléments uniques ordonnés
+- Même structure interne que map
+- Itérateurs bidirectionnels
+
+## Technologies utilisées
+- **C++98** (standard imposé par 42)
+- **Templates** pour la généricité
+- **STL allocators** custom
+- **Red-Black Tree** pour map/set
+- **SFINAE** pour la métaprogrammation
+
+## Fonctionnalités clés
+
+### Itérateurs
+- **Iterator traits** complets
+- **Random access iterators** (vector)
+- **Bidirectional iterators** (map/set)
+- **Reverse iterators** pour tous les conteneurs
+
+### Allocateurs
+- Support des **allocateurs personnalisés**
+- Gestion mémoire optimisée
+- Compatible STL allocator
+
+### Comparateurs
+- **Foncteurs de comparaison** personnalisables
+- Support des types de base et classes
+- Optimisation pour les types triviaux
+
+## Installation et compilation
+
+### 1. Cloner le projet
+```bash
+git clone <repository-url>
+cd ft_containers
+```
+
+### 2. Compiler les tests
+```bash
+make
+```
+
+### 3. Exécuter les tests
+```bash
+./ft_containers
+```
+
+### 4. Tests de performance
+```bash
+make test_performance
+```
+
+## Structure du projet
+```
+ft_containers/
+├── Makefile              # Compilation
+├── main.cpp              # Tests principaux
+├── ft_containers.hpp     # Header principal
+├── containers/           # Implémentations
+│   ├── vector.hpp
+│   ├── map.hpp
+│   ├── stack.hpp
+│   └── set.hpp          # Bonus
+├── iterators/           # Itérateurs
+│   ├── iterator_traits.hpp
+│   ├── reverse_iterator.hpp
+│   └── random_access_iterator.hpp
+├── utils/               # Utilitaires
+│   ├── pair.hpp
+│   ├── make_pair.hpp
+│   ├── equal.hpp
+│   ├── lexicographical_compare.hpp
+│   └── enable_if.hpp
+└── tests/               # Fichiers de test
+```
+
+## Utilisation
+
+### Vector
+```cpp
+ft::vector<int> vec;
+vec.push_back(42);
+vec.push_back(21);
+
+for (ft::vector<int>::iterator it = vec.begin(); it != vec.end(); ++it)
+    std::cout << *it << std::endl;
+```
+
+### Map
+```cpp
+ft::map<std::string, int> map;
+map["answer"] = 42;
+map["half"] = 21;
+
+ft::map<std::string, int>::iterator it = map.find("answer");
+if (it != map.end())
+    std::cout << it->second << std::endl;
+```
+
+### Stack
+```cpp
+ft::stack<int> stack;
+stack.push(42);
+stack.push(21);
+
+while (!stack.empty()) {
+    std::cout << stack.top() << std::endl;
+    stack.pop();
+}
+```
+
+## Tests et validation
+
+### Tests de conformité
+- Comparaison avec la **STL originale**
+- Tests de **performance**
+- Validation des **edge cases**
+- Tests de **compilation** avec différents types
+
+### Outils de test
+- **Unit tests** complets
+- **Memory leak detection**
+- **Performance benchmarks**
+- **Stress tests**
+
+## Complexités respectées
+
+| Conteneur | Opération | Complexité |
+|-----------|-----------|------------|
+| Vector | accès [] | O(1) |
+| Vector | push_back | O(1) amorti |
+| Vector | insert | O(n) |
+| Map | find/insert/erase | O(log n) |
+| Map | iteration | O(n) |
+| Stack | push/pop/top | O(1) |
+
+## Normes et contraintes 42
+- **C++98** uniquement
+- Pas de **fonctions interdites**
+- Pas de **memory leaks**
+- **Orthodox Canonical Form** respectée
+- **Templates** obligatoires
+
+## Compétences développées
+- Programmation générique avancée
+- Structures de données complexes
+- Optimisation mémoire et performance
+- Métaprogrammation C++
+- Debugging avancé
+
+## Auteur
+Alexandre Pommier (apommier) - École 42
+
+## Licence
+Projet académique - École 42
\ No newline at end of file