# RsEven Splitter

A Rust crate for evenly splitting a total number into batches, with customizable maximum batch size.

## Features

- Split a total number into even batches
- Specify a maximum batch size
- Returns both the number of batches and the size of each batch
- Handles edge cases and provides meaningful errors

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
rseven-splitter = "0.1.0"
```

## Usage

```rust
use rseven_splitter::even_split;

fn main() {
    match even_split(128, 8) {
        Ok((num_batches, batch_sizes)) => {
            println!("Number of batches: {}", num_batches);
            println!("Batch sizes: {:?}", batch_sizes);
        },
        Err(e) => println!("Error: {}", e),
    }
}
```

## API

```rust
pub fn even_split(total: usize, max_batch_size: usize) -> Result<(usize, Vec<NonZeroUsize>), String>
```

- `total`: The total number to be split.
- `max_batch_size`: The maximum allowed size for each batch.

Returns a tuple containing:
1. The number of batches.
2. A vector of `NonZeroUsize` representing the size of each batch.

## Examples

```rust
use std::num::NonZeroUsize;

assert_eq!(even_split(50, 8), Ok((10, vec![NonZeroUsize::new(5).unwrap(); 10])));
assert_eq!(even_split(128, 8), Ok((16, vec![NonZeroUsize::new(8).unwrap(); 16])));
assert_eq!(even_split(46, 8), Ok((46, vec![NonZeroUsize::new(1).unwrap(); 46])));
assert_eq!(even_split(7, 8), Ok((1, vec![NonZeroUsize::new(7).unwrap()])));
assert_eq!(even_split(17, 8), Ok((17, vec![NonZeroUsize::new(1).unwrap(); 17])));
```

Note: The function always returns the largest possible batch size that evenly divides the total, without exceeding the `max_batch_size`. If no such division is possible, it returns batches of size 1.

## Use Cases

RsEven Splitter is versatile and can be applied to various scenarios:

1. **Task Distribution**: Evenly distribute tasks among workers in parallel processing systems.
2. **Load Balancing**: Distribute network traffic or database queries across multiple servers.
3. **Resource Allocation**: Allocate resources (e.g., memory, disk space) evenly across different processes or users.
4. **Inventory Management**: Divide inventory items evenly across different storage locations or shipments.
5. **Time Management**: Split a total time duration into even segments for schedules or timetables.
6. **Financial Applications**: Divide sums of money evenly for budgeting or investment purposes.
7. **Data Partitioning**: Evenly partition large datasets for distributed processing or storage.
8. **Batch Processing**: Create evenly sized batches for any kind of batch processing operation.
9. **UI/UX Design**: Evenly distribute elements in user interfaces, such as grid layouts or menu items.
10. **Educational Applications**: Create equal-sized groups of students for group projects or activities.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

Please make sure to update tests as appropriate.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/aeromilai/rseven-splitter/tags).

## Authors

* **aeromilai** - *Initial work* - [aeromilai](https://github.com/aeromilai)

See also the list of [contributors](https://github.com/aeromilai/rseven-splitter/contributors) who participated in this project.

## Acknowledgements

- Inspired by the need for efficient and flexible resource distribution in various domains.
- Thanks to the Rust community for providing excellent tools and libraries.

## Changelog

For details on our releases, see the [Changelog](CHANGELOG.md).