Metadata-Version: 2.5
Name: iibags
Version: 0.0.2
Summary: A counting multiset with explicit arithmetic.
Project-URL: Homepage, https://github.com/lqxnjk/iibags
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: bag,counter,counting,frequency,multiset
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# iibags

A multiset that behaves the way counting code expects.

## Install

```console
pip install iibags
```

## Usage

```python
from iibags import MultiBag

bag = MultiBag(["a", "b", "a"])
bag.count("a")          # 2
bag.count("zzz")        # 0, and no key was created
bag.total()             # 3
bag.unique()            # 2
bag.most_common(1)      # [('a', 2)]

bag.discard("a", 5)     # clamps at zero, removes the key
"a" in bag              # False
```

## Differences from `Counter`

| Case | `Counter` | `MultiBag` |
| --- | --- | --- |
| reading a missing key | creates it | leaves the dict alone |
| subtracting too much | negative counts | clamps at zero, drops the key |
| negative `n_count` | accepted | `ValueError` |

Negative counts are the usual source of "why is my inventory -3" bugs, so they
are rejected instead of stored.

## License

MIT
