Este proyecto implementa un algoritmo eficiente para encontrar números faltantes en secuencias consecutivas de enteros, siguiendo las mejores prácticas de Go para código modular y mantenible.
find_number/
├── README.md # Este archivo - Documentación principal
├── go.mod # Módulo Go
├── Makefile # Automatización de tareas
├── cmd/
│ └── find_number/
│ └── main.go # Punto de entrada principal
├── pkg/
│ └── algorithm/
│ ├── missing_number.go # Algoritmo principal
│ └── optimized.go # Versiones optimizadas
├── internal/
│ └── testutil/
│ ├── utils.go # Utilidades de testing
│ ├── testcases.go # Definición de casos de prueba
│ └── runner.go # Ejecución de tests
├── scripts/
│ ├── optimize.sh # Script de optimización automatizada
│ └── open-docs.sh # Script para navegar documentación
├── bin/ # Binarios compilados
└── docs/ # Documentación técnica
├── index.html # Índice principal de documentación
├── README.html # Documentación principal (HTML)
├── analysis.md # Análisis matemático detallado
├── analysis.html # Análisis matemático (HTML)
├── optimization.md # Guía de optimización
├── optimization.html # Guía de optimización (HTML)
└── style.css # Estilos CSS para documentación
pkg/algorithm/ - Algoritmo Principalmissing_number.go: Algoritmo core usando la fórmula de suma aritméticaoptimized.go: Versiones optimizadas (bit shifting, branchless, SIMD-like)FindMissingNumber(numbers []int) *int*int (puntero a entero, nil para casos de error)internal/testutil/ - Utilidades de Testingutils.go: Utilidades generales para testing
GenerateSequence(start, end int, removeMissing bool) ([]int, *int): Genera secuencias con/sin elemento faltanteGenerateDynamicTestCase(start, end int) ([]int, *int): Crea casos de prueba dinámicosBenchmarkFunction(numbers []int, iterations int) time.Duration: Mide rendimientotestcases.go: Definición de casos de prueba
TestCase: Estructura para tests estáticos (con campo Expected *int)DynamicTestCase: Estructura para tests dinámicosGetStaticTestCases(): Casos predefinidos (naturales, negativos, cruzan cero, casos de error)GetDynamicTestCases(): Configuraciones para tests de rendimientorunner.go: Ejecución de tests
RunStaticTests(): Ejecuta tests con casos predefinidosRunDynamicTests(): Ejecuta tests de rendimientoRunAllTests(): Punto de entrada para suite completacmd/find_number/ - Punto de Entradamain.go: Función principal que orquesta la ejecución✅ Números naturales (1, 2, 3, …) ✅ Enteros positivos incluyendo cero (0, 1, 2, …) ✅ Números negativos (…, -3, -2, -1) ✅ Secuencias que cruzan cero (-n, …, -1, 0, 1, …, n) ✅ Cualquier rango de enteros consecutivos
🆕 NUEVO: El algoritmo ahora retorna *int (puntero) en lugar de int:
nil: Indica casos de error o indeterminados:
*int válido: Apunta al número faltante encontrado⚠️ IMPORTANTE: El algoritmo requiere que los valores extremos (mínimo y máximo) de la secuencia completa estén presentes en el slice de entrada. El número faltante debe estar entre estos extremos (inclusive).
Ejemplos válidos:
[1, 2, 4, 5] → falta 3 (extremos 1 y 5 presentes) ✅[-3, -2, 0, 1] → falta -1 (extremos -3 y 1 presentes) ✅[0, 2, 3, 4, 5] → falta 1 (extremos 0 y 5 presentes) ✅Ejemplos inválidos (indeterminados):
[2, 3, 4, 5] → ¿falta 1 o 6? (extremo faltante) ❌[1, 2, 3, 4] → ¿falta 0 o 5? (extremo faltante) ❌Esta restricción es matemáticamente necesaria porque sin conocer los extremos reales de la secuencia, es imposible determinar si falta un valor al inicio, al final, o en el medio.
| Elementos | Tiempo de Ejecución |
|---|---|
| 100 | ~100-200 ns |
| 1,000 | ~700-800 ns |
| 5,000 | ~3.6 µs |
| 1,000,000 | ~720 µs |
# Ver todos los comandos disponibles
make help
# Compilar el programa
make build
# Ejecutar directamente
make run
# Ejecutar tests completos
make test
# Optimizar binarios
make optimize
# Desarrollo completo (verificar + test)
make dev
# Ejecutar directamente con Go
go run ./cmd/find_number
# Compilar manualmente
go build -o bin/find_number ./cmd/find_number
# Usar script de optimización
./scripts/optimize.sh
package main
import (
"fmt"
"example/find_number/pkg/algorithm"
)
func main() {
// Ejemplo con números naturales
numbers := []int{1, 2, 3, 5, 6, 7, 8, 9, 10}
missing := algorithm.FindMissingNumber(numbers)
if missing != nil {
fmt.Printf("Número faltante: %d\n", *missing) // Output: 4
} else {
fmt.Println("No se encontró número faltante o entrada inválida")
}
// Ejemplo con números negativos
negativeNumbers := []int{-5, -4, -3, -1, 0, 1, 2}
missingNegative := algorithm.FindMissingNumber(negativeNumbers)
if missingNegative != nil {
fmt.Printf("Número faltante: %d\n", *missingNegative) // Output: -2
}
// Ejemplo de caso de error
invalidNumbers := []int{1, 3, 5} // No consecutivo
missingInvalid := algorithm.FindMissingNumber(invalidNumbers)
if missingInvalid == nil {
fmt.Println("Entrada inválida: secuencia no consecutiva")
}
}
internal/testutil/El algoritmo utiliza la fórmula de suma de secuencias aritméticas:
\[S_n = \frac{n \cdot (a_1 + a_n)}{2}\]Donde:
Esta fórmula es válida para cualquier secuencia aritmética con diferencia común de 1, independientemente del signo de los números.
Para técnicas avanzadas de optimización de tamaño y velocidad del binario, consulta la Guía de Optimización que incluye:
-ldflags="-s -w")🌐 Documentación HTML: Para una mejor experiencia de navegación, genera la documentación HTML con
make docsy abredocs/index.htmlen tu navegador.
# Generar toda la documentación HTML
make docs
# Servir documentación en localhost:8080
make docs-serve
# Abrir documentación en el navegador
make docs-open
# Ver opciones de navegación
make docs-browse
# Usar script directamente
./scripts/open-docs.sh analysis # Abrir análisis matemático
./scripts/open-docs.sh optimization # Abrir guía de optimización
./scripts/open-docs.sh serve # Servir localmente
📊 Nota sobre ecuaciones matemáticas: La documentación HTML se genera con soporte completo para fórmulas matemáticas usando
--mathjaxy--mathml, garantizando que las ecuaciones se rendericen correctamente tanto online como offline. 🎨 Nota sobre diagramas Mermaid: Los diagramas interactivos endocs/analysis.mdse convierten automáticamente a SVG en la documentación HTML usandomermaid-filter, proporcionando visualizaciones claras y escalables.