{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}