Version 0.5

Author: canbula

README.md

@@ -2,11 +2,12 @@
 
 ieee754 is a Python module which finds the IEEE-754 representation of a floating point number. You can specify a precision given in the list below or you can even use your own custom precision.
 <ul>
-<li>Half Precision (16 bit: 1 bit for sign + 5 bits for exponent + 10 bits for mantissa)</li>
-<li>Single Precision (32 bit: 1 bit for sign + 8 bits for exponent + 23 bits for mantissa)</li>
-<li>Double Precision (64 bit: 1 bit for sign + 11 bits for exponent + 52 bits for mantissa)</li>
-<li>Quadruple Precision (128 bit: 1 bit for sign + 15 bits for exponent + 112 bits for mantissa)</li>
-<li>Octuple Precision (256 bit: 1 bit for sign + 19 bits for exponent + 236 bits for mantissa)</li>
+    <li>Half Precision (16 bit: 1 bit for sign + 5 bits for exponent + 10 bits for mantissa)</li>
+    <li>Single Precision (32 bit: 1 bit for sign + 8 bits for exponent + 23 bits for mantissa)</li>
+    <li>Double Precision (64 bit: 1 bit for sign + 11 bits for exponent + 52 bits for mantissa)</li>
+    <li>Quadruple Precision (128 bit: 1 bit for sign + 15 bits for exponent + 112 bits for mantissa)</li>
+    <li>Octuple Precision (256 bit: 1 bit for sign + 19 bits for exponent + 236 bits for mantissa)</li>
+</ul>
 
 ## Prerequisites
 
@@ -20,9 +21,20 @@ $ pip install ieee754
 ```
 
 ## Using
+
 After installation, you can import ieee754 and use it in your projects.
 
+### Simplest Example
+
+The simplest example is to use the desired precision IEEE-754 representation of a floating point number. You can import the desired precision from ieee754 and use it like this. The available precisions are half, single, double, quadruple and octuple.
+```Python
+from ieee754 import double
+
+print(double(13.375))
+```
+
 ### Default Options
+
 Default precision is Double Precision and you can get the output by just calling the instance as a string.
 ```Python
 from ieee754 import IEEE754
@@ -40,6 +52,7 @@ print(a.json())
 ```
 
 ### Select a Precision
+
 You can use Half (p=0), Single (p=1), Double (p=2), Quadrupole (p=3) or Octuple precision (p=4).
 ```Python
 from ieee754 import IEEE754
@@ -50,6 +63,7 @@ for p in range(5):
 ```
 
 ### Use the Precision Name as an Interface
+
 You can use the precision name as an interface to get the IEEE-754 representation of a floating point number. With this method you can get the IEEE-754 representation of a floating point number without creating an instance.
 ```Python
 from ieee754 import half, single, double, quadruple, octuple
@@ -63,6 +77,7 @@ print(octuple(x))
 ```
 
 ### Using a Custom Precision
+
 You can force exponent, and mantissa size by using force_exponent and force_mantissa parameters to create your own custom precision.
 ```Python
 a = IEEE754(x, force_exponent=6, force_mantissa=12)

ieee754/IEEE754.py

@@ -2,6 +2,31 @@
 
 
 class IEEE754:
+    """
+    IEEE 754 Floating Point Representation
+    https://en.wikipedia.org/wiki/IEEE_754
+
+    Author: Bora Canbula
+    Email: bora.canbula@cbu.edu.tr
+    Link: https://github.com/canbula/ieee754
+
+    Parameters
+    ----------
+    number : str
+        Floating point number to be converted.
+    precision : int, optional
+        Precision of the number, by default 2
+    force_exponent : int, optional
+        Force the exponent bits, by default None
+    force_mantissa : int, optional
+        Force the mantissa bits, by default None
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+    """
+
     def __init__(
         self,
         number: str = "0.0",
@@ -166,26 +191,173 @@ def __repr__(self) -> str:
 
 
 def half(x: str) -> IEEE754:
+    """
+    IEEE 754 Half Precision Representation
+
+    Parameters
+    ----------
+    x : str
+        Floating point number to be converted.
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+
+    Examples
+    --------
+    >>> half(13.375)
+    0 10010 1010110000
+
+    >>> half(13.375).hex()
+    4AB0
+
+    >>> half(13.375).json()
+    {'exponent-bits': 5, 'mantissa-bits': 10, 'bias': 15, 'sign': '0', 'exponent': '10010', 'mantissa': '1010110000', 'binary': '1101011', 'binary_output': '1101.011', 'hex': '4AB0', 'up scaled number': 107, 'scale': 3, 'number': 13.375}
+
+    Project
+    -------
+    https://github.com/canbula/ieee754
+    """
     return IEEE754(x, 0)
 
 
 def single(x: str) -> IEEE754:
+    """
+    IEEE 754 Single Precision Representation
+
+    Parameters
+    ----------
+    x : str
+        Floating point number to be converted.
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+
+    Examples
+    --------
+    >>> single(13.375)
+    0 10000010 10101100000000000000000
+
+    >>> single(13.375).hex()
+    41560000
+
+    >>> single(13.375).json()
+    {'exponent-bits': 8, 'mantissa-bits': 23, 'bias': 127, 'sign': '0', 'exponent': '10000010', 'mantissa': '10101100000000000000000', 'binary': '1101011', 'binary_output': '1101.011', 'hex': '41560000', 'up scaled number': 107, 'scale': 3, 'number': 13.375}
+
+    Project
+    -------
+    https://github.com/canbula/ieee754
+    """
     return IEEE754(x, 1)
 
 
 def double(x: str) -> IEEE754:
+    """
+    IEEE 754 Double Precision Representation
+
+    Parameters
+    ----------
+    x : str
+        Floating point number to be converted.
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+
+    Examples
+    --------
+    >>> double(13.375)
+    0 10000000010 1010110000000000000000000000000000000000000000000000
+
+    >>> double(13.375).hex()
+    402AC00000000000
+
+    >>> double(13.375).json()
+    {'exponent-bits': 11, 'mantissa-bits': 52, 'bias': 1023, 'sign': '0', 'exponent': '10000000010', 'mantissa': '1010110000000000000000000000000000000000000000000000', 'binary': '1101011', 'binary_output': '1101.011', 'hex': '402AC00000000000', 'up scaled number': 107, 'scale': 3, 'number': 13.375}
+
+    Project
+    -------
+    https://github.com/canbula/ieee754
+    """
     return IEEE754(x, 2)
 
 
 def quadruple(x: str) -> IEEE754:
+    """
+    IEEE 754 Quadruple Precision Representation
+
+    Parameters
+    ----------
+    x : str
+        Floating point number to be converted.
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+
+    Examples
+    --------
+    >>> quadruple(13.375)
+    0 100000000000010 1010110000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+
+    >>> quadruple(13.375).hex()
+    4002AC00000000000000000000000000
+
+    >>> quadruple(13.375).json()
+    {'exponent-bits': 15, 'mantissa-bits': 112, 'bias': 16383, 'sign': '0', 'exponent': '100000000000010', 'mantissa': '1010110000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000', 'binary': '1101011', 'binary_output': '1101.011', 'hex': '4002AC00000000000000000000000000', 'up scaled number': 107, 'scale': 3, 'number': 13.375}
+
+    Project
+    -------
+    https://github.com/canbula/ieee754
+    """
     return IEEE754(x, 3)
 
 
 def octuple(x: str) -> IEEE754:
+    """
+    IEEE 754 Octuple Precision Representation
+
+    Parameters
+    ----------
+    x : str
+        Floating point number to be converted.
+
+    Returns
+    -------
+    IEEE754
+        IEEE 754 representation of the number
+
+    Examples
+    --------
+    >>> octuple(13.375)
+    0 1000000000000000010 10101100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+
+    >>> octuple(13.375).hex()
+    40002AC000000000000000000000000000000000000000000000000000000000
+
+    >>> octuple(13.375).json()
+    {'exponent-bits': 19, 'mantissa-bits': 236, 'bias': 262143, 'sign': '0', 'exponent': '1000000000000000010', 'mantissa': '10101100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000', 'binary': '1101011', 'binary_output': '1101.011', 'hex': '40002AC000000000000000000000000000000000000000000000000000000000', 'up scaled number': 107, 'scale': 3, 'number': 13.375}
+
+    Project
+    -------
+    https://github.com/canbula/ieee754
+    """
     return IEEE754(x, 4)
 
 
 if __name__ == "__main__":
+    # you can call the precision functions by using their names
+    x = 13.375
+    print(half(x))
+    print(single(x))
+    print(double(x))
+    print(quadruple(x))
+    print(octuple(x))
     # with default options (Double Precision)
     x = 13.375
     a = IEEE754(x)
@@ -199,16 +371,9 @@ def octuple(x: str) -> IEEE754:
     for p in range(5):
         a = IEEE754(x, p)
         print("x = %f | b = %s | h = %s" % (13.375, a, a.hex()))
+        print(a.json())
     # or you can use your own custom precision
     a = IEEE754(x, force_exponent=6, force_mantissa=12)
     print(f"{a}")
     # you can get more details with json
     print(a.json())
-
-    # you can also call the precision functions
-    x = 13.375
-    print(half(x))
-    print(single(x))
-    print(double(x))
-    print(quadruple(x))
-    print(octuple(x))

setup.py

@@ -1,15 +1,20 @@
 from distutils.core import setup
 
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
 setup(
     name="ieee754",
     packages=["ieee754"],
-    version="0.4",
+    version="0.5",
     license="MIT",
     description="A Python module which converts floating points numbers into IEEE-754 representation.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
     author="Bora Canbula",
     author_email="bora.canbula@cbu.edu.tr",
     url="https://github.com/canbula/ieee754",
-    download_url="https://github.com/canbula/ieee754/archive/refs/tags/v_04.tar.gz",
+    download_url="https://github.com/canbula/ieee754/archive/refs/tags/v_05.tar.gz",
     keywords=[
         "IEEE-754",
         "precisions",