{"id":2025,"library":"fixedint","title":"Fixed-Width Integers","description":"The `fixedint` library provides simple fixed-width integers in Python, allowing for both signed and unsigned types with configurable bit widths. It offers arithmetic and bitwise operations that mimic low-level hardware integer behavior, including silent wrap-around on overflow/underflow. The current version is 0.2.0, and it has a stable but low-cadence release cycle.","status":"active","version":"0.2.0","language":"python","source_language":"en","source_url":"https://github.com/nneonneo/fixedint","tags":["fixed-width","integer","low-level","bitwise","hardware","overflow"],"install":[{"cmd":"pip install fixedint","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"UInt16","correct":"from fixedint import UInt16"},{"symbol":"Int32","correct":"from fixedint import Int32"},{"note":"Commonly used types like UInt8, UInt16, Int32, Int64 are directly available.","symbol":"UInt64","correct":"from fixedint import UInt64"}],"quickstart":{"code":"from fixedint import UInt16, Int32\n\n# Unsigned 16-bit integer\nx = UInt16(65535)\nprint(f\"UInt16 max value: {x}\")\n\n# Signed 32-bit integer\ny = Int32(-1)\nprint(f\"Int32 value: {y}\")\n\n# Arithmetic operations (demonstrates wrap-around on overflow)\na = UInt16(65530)\nb = UInt16(10)\nc = a + b # This will overflow UInt16 (65530 + 10 = 65540)\nprint(f\"65530 + 10 = {c} (wraps around)\") # Expected: 4\n\n# Bitwise operations\ng = UInt16(0b1010)\nh = UInt16(0b0101)\ni = g | h\nprint(f\"0b1010 | 0b0101 = {i}\") # Expected: 0b1111 (15)\n\ntry:\n    # Instantiation with out-of-range value raises ValueError\n    j = UInt16(70000)\nexcept ValueError as e:\n    print(f\"Error creating UInt16 with too large value: {e}\")","lang":"python","description":"This example demonstrates how to import and instantiate `UInt16` and `Int32` fixed-width integers, perform basic arithmetic and bitwise operations, and shows the overflow behavior and error handling for out-of-range initial values."},"warnings":[{"fix":"Be explicit about desired behavior: understand the wrapping, or implement custom overflow checks if error-raising is preferred. The result is always within the type's defined bit width.","message":"Arithmetic operations (addition, subtraction, multiplication) on `fixedint` types silently wrap around on overflow or underflow, behaving like modulo arithmetic. This is by design but differs significantly from Python's default arbitrary-precision integer behavior.","severity":"gotcha","affected_versions":"All versions (0.1.x, 0.2.x)"},{"fix":"Explicitly cast or convert one of the operands to match the other type, or perform operations with standard Python integers before assigning the result to a `fixedint` type. For example, `UInt16(val1) + UInt16(val2)`.","message":"Attempting arithmetic operations between different `fixedint` types (e.g., `UInt16` and `Int32`) will raise a `TypeError`. Types must match for direct arithmetic.","severity":"gotcha","affected_versions":"All versions (0.1.x, 0.2.x)"},{"fix":"Ensure the initial value fits within the range of the chosen fixed-width integer type. For example, a `UInt16` cannot be initialized with a value greater than 65535 or less than 0.","message":"Initializing a `fixedint` type with a Python integer value that exceeds its defined bit width (or signed/unsigned range) will raise a `ValueError`.","severity":"gotcha","affected_versions":"All versions (0.1.x, 0.2.x)"}],"env_vars":null,"search_vec":"'0.2.0':52 'allow':16 'arithmet':29 'around':45 'behavior':40 'bit':25 'bitwis':31,71 'cadenc':61 'configur':24 'current':49 'cycl':63 'fix':2,11,65 'fixed-width':1,10,64 'fixedint':6 'hardwar':38,72 'includ':41 'integ':4,13,39,67 'level':37,70 'librari':7 'low':36,60,69 'low-cad':59 'low-level':35,68 'mimic':34 'offer':28 'oper':32 'overflow':73 'overflow/underflow':47 'provid':8 'python':15 'releas':62 'sign':19 'silent':42 'simpl':9 'stabl':57 'type':22 'unsign':21 'version':50 'width':3,12,26,66 'wrap':44 'wrap-around':43","created_at":"2026-04-09T18:40:18.492661+00:00","updated_at":"2026-04-16T15:02:22.038789+00:00","problems":[{"fix":"Install the library using pip: `pip install fixedint`","cause":"The `fixedint` library is not installed in the Python environment or the Python interpreter cannot find the installed package.","error":"ModuleNotFoundError: No module named 'fixedint'"},{"fix":"Ensure the correct class names are used, matching the library's exposed types (e.g., `from fixedint import UInt32` or `from fixedint import FixedInt`). Refer to the `fixedint` documentation for available types.","cause":"This error typically occurs when trying to import a class or function from the `fixedint` module with an incorrect name or casing, or if the specific class is not directly exposed for import (e.g., trying to import a dynamically generated type without using the factory function if applicable, though for fixedint, common types are directly importable like UInt32).","error":"ImportError: cannot import name 'FixedInt' from 'fixedint'"},{"fix":"Explicitly cast operands to compatible types where necessary, or be aware of operations that return standard Python types instead of `FixedInt`. For example, `UInt32(my_fixed_int + some_int)` or handle the `int`/`float` result accordingly.","cause":"This error arises when attempting to perform arithmetic operations between a `FixedInt` instance and a standard Python `int` (or another incompatible type) in a way that the `fixedint` library does not implicitly handle or when the operation results in a standard Python `int` or `float` where a `FixedInt` was expected, leading to subsequent type-sensitive operations failing. The library documentation notes that some operations like true division return a `float`, and `divmod` returns `plain int`s.","error":"TypeError: unsupported operand type(s) for +: 'FixedInt' and 'int'"},{"fix":"Consult the `fixedint` library's documentation to confirm available methods and attributes for `FixedInt` instances. Ensure you are not trying to use methods specific to Python's built-in `int` that `FixedInt` does not implement.","cause":"Users encounter this error when attempting to call a method or access an attribute on a `FixedInt` object that does not exist or is not part of its API, potentially confusing its behavior with that of a standard Python `int` or another custom class.","error":"AttributeError: 'FixedInt' object has no attribute 'some_method'"},{"fix":"Be mindful of the bit width and signed/unsigned nature of your `FixedInt` types. Before critical arithmetic operations, you can check if the value will exceed the range using comparison with `FixedInt.min_value` and `FixedInt.max_value` (if provided by the library, or calculate based on bit width) to handle potential overflow/underflow explicitly, or design your logic to correctly account for the wrap-around behavior.","cause":"This is a common logical problem rather than a Python exception. It occurs when arithmetic operations on `FixedInt` instances exceed their defined bit width (e.g., 8, 16, 32, 64 bits), leading to silent wrap-around (truncation) rather than an explicit error. This results in an unexpected numerical value, mimicking low-level hardware integer behavior, which can be a source of hard-to-debug logical errors if not anticipated.","error":"fixedint unexpected value overflow"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/nneonneo/fixedint","docs":null,"changelog":null,"pypi":"https://pypi.org/project/fixedint/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}