# digit-counter

`digit-counter` is a high-performance Python package designed to compute digit statistics from integers, floats, strings, and `Decimal` values. It provides a unified API, batch-processing utilities, precision control, caching for performance optimization, logging capabilities, and optional CLI support.

This package is suitable for data processing pipelines, numeric analysis utilities, logging systems, and any application requiring accurate and efficient digit computation.

---

## Key Features

* Unified interface for counting digits across integers, floats, strings, and `Decimal` types
* High-performance implementations with LRU caching
* Precision-controlled handling of floating-point and decimal values
* Batch processing with detailed reporting
* Strong error handling and input validation
* Optional logging support
* Optional command-line interface
* Lightweight, production-ready implementation

---

## Installation

Stable release:

```bash
pip install digit-counter
```

---

## Quick Usage Example

```python
from digit_counter import DigitCounter

# Initialize with optional precision
counter = DigitCounter(precision=20)

result = counter.count_digits(123.456, mode="all")

print("Total digits:", result.total_digits)
print("Digits before decimal:", result.before_decimal)
print("Digits after decimal:", result.after_decimal)
```

---

## Counting Modes

| Mode     | Description                                                     |
| -------- | --------------------------------------------------------------- |
| `total`  | Returns total digits excluding sign                             |
| `before` | Returns digits before the decimal point                         |
| `after`  | Returns digits after the decimal point (trailing zeros trimmed) |
| `all`    | Returns a full metadata object (`DigitCountResult`)             |

---

## Batch Processing

```python
values = [123, 90.45, -77.002, 100.00]

counter = DigitCounter()
batch = counter.batch_process(values, mode="all")

# Access the full list of results
print(batch.results)

# Summary of performance and processing details
print(batch.summary())
```

Example summary output:

```
Processed: 4 items  
Successful: 4  
Failed: 0  
Success Rate: 100%  
Average Processing Time: 0.09 ms  
```

---

## Command-Line Usage (optional if CLI is enabled)

Count digits of a single number:

```bash
digit-counter count 123.456
```

Specify a mode:

```bash
digit-counter count 123.456 --mode before
```

Batch process from a file:

```bash
digit-counter batch input.txt --output results.json
```

Display runtime statistics:

```bash
digit-counter stats
```

Help command:

```bash
digit-counter --help
```

---

## Logging

```python
counter = DigitCounter(log_level="DEBUG")
counter.count_digits(987.654)
```

Logging supports `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL` levels.

---

## Performance Considerations

The package utilizes:

* Optimized integer digit counting without string conversion
* Decimal-aware float parsing
* LRU caching for repeated values
* Linear-time batch processing
* Precision control to reduce unnecessary computation

This design allows the library to scale from small datasets up to large numeric collections while maintaining predictable performance characteristics.

---

## Exception Handling

The library provides clear exceptions for:

* Unsupported data types
* Precision errors
* Non-numeric strings
* Invalid mode selection

All exceptions include contextual details to speed up debugging.

---

## License

This project is licensed under the MIT License. Refer to the `LICENSE` file for full terms.

---

## Contributing

Contributions are welcome. If you intend to submit pull requests, please follow standard coding style practices and ensure all changes include appropriate test coverage.

---
