Metadata-Version: 2.4
Name: twos_complement_practice
Version: 1.0.2
Summary: CLI tool for practicing two's complement representation of signed integers
Author-email: Clayton Cafiero <cbcafier@uvm.edu>
License: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/ccafiero/twos_complement_practice
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama
Dynamic: license-file

# Two's Complement Practice Tool

This is a command-line tool for practicing and reviewing two's complement representation of signed integers.

Developed for CS2210 (Computer Organization) at the University of Vermont by [Clayton Cafiero](mailto:cbcafier@uvm.edu).

---

## Installation

```bash
pip install twos-complement-practice
```

---

## Usage

After installing:

```bash
$ twos-practice
```

You will be prompted to choose a bit width (_e.g._, 4, 8, etc.). The program will then randomly select from three activity types:

- **Additive inverse**: Given a bitstring, provide the additive inverse in two's complement form.
- **Decimal to bitstring**: Convert a signed decimal integer to two's complement binary.
- **Bitstring to decimal**: Convert a two's complement binary string to a decimal integer.

You can exit at any prompt by typing `q`.

At the end, you'll get a summary of your performance and a list of any incorrect responses.

### Running in Python or your IDE

You can also import and run the tool interactively:

```python
import twos_complement_practice as tcp
tcp.run()
```

---

## Utility functions

The module also exposes two utility functions, `bin2dec` and `dec2bin`.

* `bin2dec` converts a bitstring to an integer representation (a Python `int`).
* `int2dec` converts a Python integer to a binary bitstring (this requires a second argument, an `int` representing the number of bits to use).

---

## Educational goals

This tool is designed to:

- reinforce understanding of signed binary number representation,
- develop fluency with two's complement conversions, and
- provide low-stakes, interactive feedback for learners.

---

## License

This project is licensed under the terms of the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html).

You are free to use, modify, and distribute this software under the conditions specified in the license.

> © 2025 Clayton Cafiero  
> For inquiries, contact [cbcafier@uvm.edu](mailto:cbcafier@uvm.edu)

---

## Dependencies

- [colorama](https://pypi.org/project/colorama/): for cross-platform colored terminal output.
