obitools4/autodoc/docmd/pkg_obiutils.md

# `obiutils` — Semantic Feature Overview

The **`obiutils`** package is a collection of low- and mid-level utilities for numerical computation, string manipulation, file I/O, concurrency control, data conversion, and format detection—specifically designed for bioinformatics pipelines in the OBITools 4 ecosystem. All public APIs are **type-safe**, **well-documented**, and optimized for performance or correctness depending on use case.

## Core Functional Categories

### 🔢 Numerical Utilities
- **`Abs[T constraints.Signed](x T) T`**: Generic absolute value for signed integers and floats (via `golang.org/x/exp/constraints`).  
- **`Min/Max(...)`**: Unified functions accepting scalars, slices, or maps—uses reflection for heterogeneous inputs; returns errors on empty/unsupported types.  
- **`MinMaxSlice[T constraints.Ordered]([]T) (min, max T)`**: Efficient min/max for ordered slices; panics on empty input.  
- **`MinMultiset[T]`**: Lazy-delete min-priority multiset with O(log n) insertion, amortized O(1) minimum access.

### 📦 Data Structures
- **`Set[E comparable]`**: Generic set using `map[E]struct{}` for O(1) membership; supports union, intersection, add/contains/members.  
- **`Vector[T]`, `Matrix[T][][]T`**: Row-major 2D structures with methods:  
  - `.Column(i)`, `.Rows(indices...)`, `.Dim()` (safe for nil/jagged matrices).  
  - `Make2DArray[T]`, `Make2DNumericArray[T](rows, cols int, zeroed bool)` for allocation.

### 🧠 Type Conversion & Validation
- **`InterfaceToString(i interface{}) string`**,  
  `CastableToInt(...)`,  
  `InterfaceToBool(...)` / `Int` / `Float64`: Safe conversions with typed errors (`NotAnInteger`, etc.).  
- **`MapToMapInterface(...)`, `InterfaceToIntMap(...)` / `StringMap`: Converts generic maps to concrete types via reflection.  
- **`InterfaceToStringSlice(...)`**: Normalizes `[]interface{}` or string slices to `[]string`.

### 📄 File & Stream I/O
- **`ReadLines(path string) ([]string, error)`**: Buffered line-by-line file reading.  
- **`Wfile` abstraction** (`OpenWritingFile`, `CompressStream`) with transparent gzip (via `pgzip`), buffering, and append support.  
- **`Ropen/Wopen(...)`**: Unified opener for files/stdin/HTTP/pipes, auto-detecting gzip/xz/zstd/bzip2 via magic bytes.  
- **`DownloadFile(url, path string)`**: Simple HTTP download with progress bar (no retries/timeouts).  
- **`TarFileReader(r io.Reader, path string)`**: Extracts a single file from TAR by exact name match.

### 🔤 String & ASCII Processing
- **`InPlaceToLower([]byte) []byte`**: Zero-copy uppercase→lowercase conversion for ASCII using bitwise OR (`| 32`).  
- **`UnsafeStringFromBytes([]byte) string`, `UnsafeBytes(string) []byte`**: Zero-copy conversions (⚠️ unsafe; no bounds checks).  
- **`AsciiSet[256]bool`**: Predefined sets (`Space`, `Digit`, `Alpha`) + operations (union, intersect) and helpers:  
  - `.FirstWord(...)`, `TrimLeft(s string)` (via method), `RightSplitInTwo(...)`.

### 📏 Memory & Path Utilities
- **`ParseMemSize(s string) (int, error)`**: Parses `"128K"`, `"5MB"` → bytes.  
- **`FormatMemSize(n int) string`**: Formats byte counts as `"1.5K"`, `"2M"` (powers of 1024).  
- **`RemoveAllExt(path string)`, `Basename(path string)`**: Strip *all* extensions from paths (e.g., `"file.tar.gz"` → `"file"`).

### 📡 Format Detection & MIME Handling
- **`HasBOM([]byte) bool, BOMType`**: Detects UTF-8/16/32 byte order marks.  
- **`DropLastLine([]byte) []byte`**: Trims final newline-delimited line (for truncated files).  
- **`RegisterOBIMimeType(...)`**: Extends MIME detection for bioformats (FASTA/FASTQ, CSV, ecoPCR2, GenBank) via regex/magic headers.

### 🔄 Concurrency & Synchronization
- **`AtomicCounter(start int)`**: Thread-safe counter with `Inc()`, `Dec()`, `Value()` (mutex-protected).  
- **`RegisterAPipe/UnregisterPipe()`, `WaitForLastPipe()`**: Lightweight pipeline sync via `sync.WaitGroup` (logs active goroutines).

### 📊 Ranking & Ordering
- **`IntOrder(data []int) []int`, `ReverseIntOrder(...)`: Returns index permutation for ascending/descending sort (original slice unchanged).  
- **`Order[T sort.Interface](data T) []int`: Generic stable index-based sorting.

### 🧪 Testing & Reliability
- All functions include **unit tests** (table-driven, `reflect.DeepEqual`, subtests).  
- Error handling is explicit and typed; logging via Logrus for debugging.  
- No external dependencies beyond `golang.org/x/exp/constraints` (for generics) and optional libraries (`progressbar`, `pgzip`).  
- Designed for portability across Unix/Windows (uses standard library paths).