Go

Find Missing Number - Algoritmo Modular

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.

📚 Índice

Estructura del Proyecto

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

Módulos y Responsabilidades

1. pkg/algorithm/ - Algoritmo Principal

2. internal/testutil/ - Utilidades de Testing

3. cmd/find_number/ - Punto de Entrada

Características del Algoritmo

Universalidad

✅ 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

Manejo de Errores

🆕 NUEVO: El algoritmo ahora retorna *int (puntero) en lugar de int:

Restricción Fundamental

⚠️ 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:

Ejemplos inválidos (indeterminados):

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.

Rendimiento

Elementos Tiempo de Ejecución
100 ~100-200 ns
1,000 ~700-800 ns
5,000 ~3.6 µs
1,000,000 ~720 µs

Uso

Compilación y Ejecución

Usando Makefile (Recomendado)

# 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

Usando Go directamente

# 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

Uso del Algoritmo

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")
    }
}

Principios de Diseño Aplicados

1. Single Responsibility Principle (SRP)

2. Don’t Repeat Yourself (DRY)

3. Clean Architecture

4. Go Best Practices

5. Testabilidad

Ventajas de la Modularización

  1. Mantenibilidad: Cambios localizados y fáciles de implementar
  2. Reutilización: Algoritmo puede ser importado en otros proyectos
  3. Testing: Tests organizados y fáciles de extender
  4. Legibilidad: Código más claro y bien documentado
  5. Escalabilidad: Fácil agregar nuevos tipos de tests o algoritmos

Análisis Matemático

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.

Optimización de Binarios

Para técnicas avanzadas de optimización de tamaño y velocidad del binario, consulta la Guía de Optimización que incluye:

Documentación Adicional

🌐 Documentación HTML: Para una mejor experiencia de navegación, genera la documentación HTML con make docs y abre docs/index.html en tu navegador.

Generar Documentación HTML

# 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 --mathjax y --mathml, garantizando que las ecuaciones se rendericen correctamente tanto online como offline. 🎨 Nota sobre diagramas Mermaid: Los diagramas interactivos en docs/analysis.md se convierten automáticamente a SVG en la documentación HTML usando mermaid-filter, proporcionando visualizaciones claras y escalables.