| Name | cbnumber JSON |
| Version |
1.0
JSON |
| download |
| home_page | None |
| Summary | A module representing numbers in arbitrary bases, extending the built-in `int` type. |
| upload_time | 2024-09-05 14:12:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NumberBase Module Readme
## Overview
`NumberBase` is a custom Python class that represents integers in different bases, allowing for operations such as addition, subtraction, and multiplication while retaining the base of the number. This class extends the built-in `int` type and provides a way to work with numbers in various bases, like binary, decimal, and hexadecimal, as well as user-defined bases.
## Features
- **Base conversion:** Convert integers to different bases, such as binary, decimal, or custom bases.
- **Base-preserving arithmetic operations:** Perform arithmetic operations (`+`, `-`, `*`, etc.) while retaining the original base of the numbers.
- **Immutable properties:** Certain properties like `base`, `base_map`, and `null` are immutable after the object is created.
- **String representation:** Customize the string and repr representation of the number based on its base.
## Installation
This module is intended to be integrated directly into a Python project. No external dependencies are needed beyond the standard Python library.
## Usage
### Import and Initialization
To use `NumberBase`, import the class and create an instance by providing an integer and a base mapping. The base mapping can be one of the predefined bases (decimal, binary, hexadecimal) or a custom iterable that defines the symbols used for that base.
```python
from string import digits, ascii_lowercase
from enum import Enum
# Example of creating a NumberBase instance with a custom base map
num = NumberBase(3453, digits + "ABCDEF")
```
### Example Operations
The `NumberBase` class supports all common arithmetic operations like addition, subtraction, multiplication, and more, while retaining the base of the original number.
```python
# Define a number in a custom hexadecimal-like base
num = NumberBase(3453, digits + "ABCDEF")
# Print the representation of the number in the custom base
print(repr(num)) # Output: [bn]: D7D
# Adding 1 to the number while retaining the base
result = num + 1
print(repr(result)) # Output: [bn]: D7E
```
*See [example.ipynb](./example.ipynb) for more examples*
### Custom Bases
You can define custom bases by passing an iterable that represents the symbols for that base:
```python
# Binary number (Base 2)
binary_num = NumberBase(25, [0, 1])
print(binary_num) # Output: binary representation of 25
print(binary_num + 1) # Output: binary representation of 26
```
### Enum-Based Bases
You can also use the provided `Bases` enum to initialize `NumberBase` instances with predefined bases:
```python
from enum import Enum
class Bases(Enum):
DECIMAL = "0123456789"
BINARY = "01"
HEXADECIMAL = "0123456789ABCDEF"
hex_num = NumberBase(255, Bases.HEXADECIMAL)
print(hex_num) # Output: FF (in hexadecimal)
```
## Class Details
### `NumberBase` Class
- **Attributes:**
- `base`: The length of the base map (number of symbols in the base).
- `base_map`: A tuple of symbols representing the base.
- `null`: The symbol representing zero in the base.
- **Methods:**
- `__new__(cls, x: int, base_map: Union[Iterable[object], Bases], null: object = None)`: Creates the integer instance.
- `__init__(self, x: int, base_map: Union[Iterable[object], Bases], null: object = None)`: Initializes the instance with the specified base and null value.
- `__add__`, `__sub__`, `__mul__`, etc.: Arithmetic operations that preserve the base of the `NumberBase` instance.
- `__repr__()`: Returns a custom string representation of the number in its base.
### Base Operations
The `NumberBase` class implements most arithmetic and bitwise operations (`+`, `-`, `*`, `/`, `//`, `%`, `&`, `|`, `^`, `<<`, `>>`) while ensuring that the base is preserved. Operations between two `NumberBase` instances or between a `NumberBase` and a regular integer are supported.
For instance, adding an integer to a `NumberBase` object returns a new `NumberBase` object with the result converted back to the original base.
### Immutability
Once a `NumberBase` instance is initialized, certain attributes (`base`, `base_map`, `null`) cannot be modified or deleted. Attempts to do so will raise an `AttributeError`.
```python
num = NumberBase(10, Bases.DECIMAL)
num.base = 2 # Raises AttributeError: The 'base' attribute is immutable
```
### String Representation
The `__str__()` and `__repr__()` methods provide custom representations of `NumberBase` objects. The `__str__()` method returns the number as a string in its respective base, while `__repr__()` prefixes the output with `[bn]:`.
```python
print(str(num)) # Example output: D7D
print(repr(num)) # Example output: [bn]: D7D
```
## Future Enhancements
- **Support for fractional numbers:** Extend `NumberBase` to handle floating-point numbers.
- **Custom formatting options:** Allow customization of the `repr` and `str` outputs to support different formatting conventions.
## Conclusion
The `NumberBase` class offers a flexible way to work with integers in various bases while preserving the base across arithmetic operations. This can be especially useful for tasks involving custom numeral systems or base conversions in Python.
*Licensed under MIT.*
Raw data
{
"_id": null,
"home_page": null,
"name": "cbnumber",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Jean Mo\u00efse Talec <jmtalec@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ca/cd/4739c250092e737fb774b9f91cd1169ebf072485f4c07d6e736f492e0e1a/cbnumber-1.0.tar.gz",
"platform": null,
"description": "# NumberBase Module Readme\n\n## Overview\n\n`NumberBase` is a custom Python class that represents integers in different bases, allowing for operations such as addition, subtraction, and multiplication while retaining the base of the number. This class extends the built-in `int` type and provides a way to work with numbers in various bases, like binary, decimal, and hexadecimal, as well as user-defined bases.\n\n## Features\n\n- **Base conversion:** Convert integers to different bases, such as binary, decimal, or custom bases.\n- **Base-preserving arithmetic operations:** Perform arithmetic operations (`+`, `-`, `*`, etc.) while retaining the original base of the numbers.\n- **Immutable properties:** Certain properties like `base`, `base_map`, and `null` are immutable after the object is created.\n- **String representation:** Customize the string and repr representation of the number based on its base.\n\n## Installation\n\nThis module is intended to be integrated directly into a Python project. No external dependencies are needed beyond the standard Python library.\n\n## Usage\n\n### Import and Initialization\n\nTo use `NumberBase`, import the class and create an instance by providing an integer and a base mapping. The base mapping can be one of the predefined bases (decimal, binary, hexadecimal) or a custom iterable that defines the symbols used for that base.\n\n```python\nfrom string import digits, ascii_lowercase\nfrom enum import Enum\n\n# Example of creating a NumberBase instance with a custom base map\nnum = NumberBase(3453, digits + \"ABCDEF\")\n```\n\n### Example Operations\n\nThe `NumberBase` class supports all common arithmetic operations like addition, subtraction, multiplication, and more, while retaining the base of the original number.\n\n```python\n# Define a number in a custom hexadecimal-like base\nnum = NumberBase(3453, digits + \"ABCDEF\")\n\n# Print the representation of the number in the custom base\nprint(repr(num)) # Output: [bn]: D7D\n\n# Adding 1 to the number while retaining the base\nresult = num + 1\nprint(repr(result)) # Output: [bn]: D7E\n```\n\n*See [example.ipynb](./example.ipynb) for more examples*\n\n### Custom Bases\n\nYou can define custom bases by passing an iterable that represents the symbols for that base:\n\n```python\n# Binary number (Base 2)\nbinary_num = NumberBase(25, [0, 1])\nprint(binary_num) # Output: binary representation of 25\nprint(binary_num + 1) # Output: binary representation of 26\n```\n\n### Enum-Based Bases\n\nYou can also use the provided `Bases` enum to initialize `NumberBase` instances with predefined bases:\n\n```python\nfrom enum import Enum\n\nclass Bases(Enum):\n DECIMAL = \"0123456789\"\n BINARY = \"01\"\n HEXADECIMAL = \"0123456789ABCDEF\"\n\nhex_num = NumberBase(255, Bases.HEXADECIMAL)\nprint(hex_num) # Output: FF (in hexadecimal)\n```\n\n## Class Details\n\n### `NumberBase` Class\n\n- **Attributes:**\n - `base`: The length of the base map (number of symbols in the base).\n - `base_map`: A tuple of symbols representing the base.\n - `null`: The symbol representing zero in the base.\n\n- **Methods:**\n - `__new__(cls, x: int, base_map: Union[Iterable[object], Bases], null: object = None)`: Creates the integer instance.\n - `__init__(self, x: int, base_map: Union[Iterable[object], Bases], null: object = None)`: Initializes the instance with the specified base and null value.\n - `__add__`, `__sub__`, `__mul__`, etc.: Arithmetic operations that preserve the base of the `NumberBase` instance.\n - `__repr__()`: Returns a custom string representation of the number in its base.\n\n### Base Operations\n\nThe `NumberBase` class implements most arithmetic and bitwise operations (`+`, `-`, `*`, `/`, `//`, `%`, `&`, `|`, `^`, `<<`, `>>`) while ensuring that the base is preserved. Operations between two `NumberBase` instances or between a `NumberBase` and a regular integer are supported.\n\nFor instance, adding an integer to a `NumberBase` object returns a new `NumberBase` object with the result converted back to the original base.\n\n### Immutability\n\nOnce a `NumberBase` instance is initialized, certain attributes (`base`, `base_map`, `null`) cannot be modified or deleted. Attempts to do so will raise an `AttributeError`.\n\n```python\nnum = NumberBase(10, Bases.DECIMAL)\nnum.base = 2 # Raises AttributeError: The 'base' attribute is immutable\n```\n\n### String Representation\n\nThe `__str__()` and `__repr__()` methods provide custom representations of `NumberBase` objects. The `__str__()` method returns the number as a string in its respective base, while `__repr__()` prefixes the output with `[bn]:`.\n\n```python\nprint(str(num)) # Example output: D7D\nprint(repr(num)) # Example output: [bn]: D7D\n```\n\n## Future Enhancements\n\n- **Support for fractional numbers:** Extend `NumberBase` to handle floating-point numbers.\n- **Custom formatting options:** Allow customization of the `repr` and `str` outputs to support different formatting conventions.\n\n## Conclusion\n\nThe `NumberBase` class offers a flexible way to work with integers in various bases while preserving the base across arithmetic operations. This can be especially useful for tasks involving custom numeral systems or base conversions in Python.\n\n*Licensed under MIT.*",
"bugtrack_url": null,
"license": null,
"summary": "A module representing numbers in arbitrary bases, extending the built-in `int` type.",
"version": "1.0",
"project_urls": {
"Homepage": "https://github.com/jmtalec/NumberBase",
"Issues": "https://github.com/jmtalec/NumberBase/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c1b7792242c182f2f86a899359f3d1ef3b1b07f25e668a099ceb5f34e0ff816a",
"md5": "406c8bc9f7d3ed9e1f4d440940c27aa2",
"sha256": "d90e5682db383b05dc990a57097b89a29604fe6ac317da08c15ce444e76a5afb"
},
"downloads": -1,
"filename": "cbnumber-1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "406c8bc9f7d3ed9e1f4d440940c27aa2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6808,
"upload_time": "2024-09-05T14:12:25",
"upload_time_iso_8601": "2024-09-05T14:12:25.688370Z",
"url": "https://files.pythonhosted.org/packages/c1/b7/792242c182f2f86a899359f3d1ef3b1b07f25e668a099ceb5f34e0ff816a/cbnumber-1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cacd4739c250092e737fb774b9f91cd1169ebf072485f4c07d6e736f492e0e1a",
"md5": "ad7c738fa1263131aa13ecca846173e2",
"sha256": "3691faddab9d1b9d0506e898b7bfcf27f32abb5953b03dc9e5399b7e9d4fb3d7"
},
"downloads": -1,
"filename": "cbnumber-1.0.tar.gz",
"has_sig": false,
"md5_digest": "ad7c738fa1263131aa13ecca846173e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8261,
"upload_time": "2024-09-05T14:12:26",
"upload_time_iso_8601": "2024-09-05T14:12:26.903669Z",
"url": "https://files.pythonhosted.org/packages/ca/cd/4739c250092e737fb774b9f91cd1169ebf072485f4c07d6e736f492e0e1a/cbnumber-1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 14:12:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jmtalec",
"github_project": "NumberBase",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cbnumber"
}
