Groesz.org
/
bits
1
0
Fork 0
Code Issues 3 Pull Requests Releases 2 Wiki Activity

Improve doc; add Bit.set and unset methods

Browse Source
master
S Groesz 3 years ago
parent 1226400c2d
commit 97f7d58dd7
2 changed files with 235 additions and 33 deletions
Show Stats Download Patch File Download Diff File

250
src/bits.py
Unescape Escape View File

@ -1,33 +1,218 @@
# -*- coding: utf-8 -*-
"""
============================
Binary manipulation classes
============================
Provides classes that assist in managing, comparing, transforming and working
with binary data in general.
-----------------
Provided Classes
-----------------
Bit
===
The Bit is the smallest representation of binary data and represents True or
False. This class provides methods to perform binary comparisons and
conversions between different types that can be used to represent a single
binary value.
Byte
====
A Byte is the representation of 8 Bits. The Byte class provides methods to
compare a single binary Byte to other data types. The Class also provides
binary math functions and allows getting and setting the state of individual
Bits.
Bytes
=====
The Bytes class allows an arbitrary amount of binary data to be represented.
The Bytes class provides access to each byte using the Byte class, which
further allows all the methods to be used on the binary data provided by the
Byte and Bit classes. Bytes can be compared and converted between several
different data types.
"""
class Bit:
"""
Provide a flexible bit representation.
====
Bit
====
A single binary bit representation of True or False
A Bit object can be compared and converted to int, str, bool and other Bit
objects. The Bit class is backed by a single bool variable. This backing
bool object is converted as necessary to provide conversions and
comparisons with other data types. Keep this in mind as converting an
object to Bit and then attempting to convert back to the original object
may not yield the exact same value.
In the case of comparisons, the object being compared is cast as a Bit
object, and the two Bit objects are then compared with each other and the
result of the comparison is returned.
----------------
Type Conversion
----------------
The objects that can be converted to and from a Bit include *bool*, *int*,
*str* and other *Bit* objects.
Convert *bool* to *Bit*:
.. code-block:: python
/>/>/> a_bit = Bit(True)
/>/>/> a_bit
Bit(1)
/>/>/>
Convert *Bit* to *bool*:
.. code-block:: python
/>/>/> a_bool = bool(Bit(True))
/>/>/> a_bool
True
/>/>/> type(a_bool)
<class 'bool'>
/>/>/>
Convert *int* to *Bit*:
.. code-block:: python
/>/>/> unset_bit = Bit(0)
/>/>/> unset_bit
Bit(0)
/>/>/> set_bit = Bit(1)
/>/>/> set_bit
Bit(1)
/>/>/>
Convert *Bit* to *int*:
.. code-block:: python
/>/>/> my_int = int(Bit(1))
/>/>/> my_int
1
/>/>/> type(my_int)
<class 'int'>
/>/>/>
.. note:: The only values allowed for *int* are **0** and **1**
Convert *str* to *Bit*:
.. code-block:: python
/>/>/> unset_bit = Bit("0")
/>/>/> unset_bit
Bit(0)
/>/>/> set_bit = Bit("1")
/>/>/> set_bit
Bit(1)
/>/>/>
Convert *Bit* to *str*:
.. code-block: python
/>/>/> my_str = str(Bit(False))
/>/>/> my_str
'0'
/>/>/> type(my_str)
<class 'str'>
/>/>/>
.. note:: The only *str* characters allowed are a single **0** or **1**
------------
Comparisons
------------
A Bit object can be compared to any object which can be cast to a Bit
.. code-block: python
/>/>/> 0 == Bit(False) == Bit("0") == Bit(0) == False
True
/>/>/>
.. note:: Comparing an object with a value that cannot be cast to Bit will
return a ValueError.
-----------------
Rich Comparisons
-----------------
Bit objects also support "rich comparisons". For example:
.. code-block: python
/>/>/> Bit(False) < 1
True
/>/>/> Bit(True) <= 1
True
/>/>/> Bit(False) <= "1"
True
/>/>/> Bit(False) != True
True
/>/>/> Bit(True) >= False
False
/>/>/>
--------
Methods
--------
The action method `toggle` is provided for convenience.
.. code-block: python
/>/>/> Bit(False).toggle()
Bit(1)
/>/>/> Bit(True).toggle() == False
True
/>/>/> int(Bit(False).toggle())
1
/>/>/>
The `set` and `unset` methods are also provided to explicitely set the
value of Bit.
.. code-block: python
/>/>/> a_bit = Bit(0)
/>/>/> a_bit
Bit(0)
/>/>/> a_bit.set()
/>/>/> a_bit
Bit(1)
/>/>/> a_bit.unset()
/>/>/> a_bit
Bit(0)
/>/>/>
-----------
Properties
-----------
The `lie` property returns the opposite value of Bit as a *bool*. Unlike
the `toggle` method, `lie` does not change the value of the Bit.
Extended description of function.
.. code-block: python
Parameters
----------
var : bool | int | str | Bit
Any of the supported objects which can be converted to a Bit object.
bool: True or False
int: 0 = False, anything else = True
str: "0" = False, anything else = True
BIT: Bit = Bit
/>/>/> Bit(1).lie
False
/>/>/>
Returns
-------
Bit
A binary representation of True or False with additional useful
features.
"""
def __init__(self, var):
"""
var: Any supported type
Supported types: (bool, int, str, Bit)
bool: True or False
int: 0 = False, anything else = True
str: "0" = False, anything else = True
int: 0 = False, 1 = True
str: "0" = False, "1" = True
Bit: Bit = Bit
"""
if not isinstance(var, (bool, int, str, Bit)):
@ -45,25 +230,22 @@ class Bit:
self.__bit = var
def __str__(self):
"""
Return "0" or "1"
"""
"""Return '0' or '1'"""
return str(int(self.__bit))
def __int__(self):
"""Return 0 or 1"""
return int(self.__bit)
def __bool__(self):
"""Returns True or False"""
return self.__bit
def __repr__(self):
return f'{self.__class__.__name__}({int(self.__bit)})'
def __eq__(self, compare):
"""
compare (self) to any supported object
"""
# Massage compare to bool
"""compare (self) to any supported object"""
return bool(self) == bool(Bit(compare))
def __ne__(self, compare):
@ -85,22 +267,24 @@ class Bit:
return self.__bit
def __hash__(self):
"""
Not very useful, but provided nonetheless
"""
"""Not very useful, but provided nonetheless"""
return hash(self.__bit)
def toggle(self):
"""
(self) = Not (Self)
"""
"""Change the state of (self) to Not (self)"""
self.__bit = not self.__bit
def set(self):
"""Set Bit to True"""
self.__bit = True
def unset(self):
"""Set Bit to False"""
self.__bit = False
@property
def lie(self):
"""
Return the opposite of bit, without changing the state of (self)
"""
"""Return the opposite of bit, without changing the state of (self)"""
return not self.__bit

18
tests/test_bit.py
Unescape Escape View File

@ -64,6 +64,24 @@ class TestBit(TestCase):
var.toggle()
self.assertTrue(var, "Bit(False).toggle() == True")
def test_set(self):
"""Test the set() method"""
var = Bit(False)
var.set()
self.assertTrue(var, "Bit(False).set() == True")
var = Bit(True)
var.set()
self.assertTrue(var, "Bit(True).set() == True")
def test_unset(self):
"""Test the unset() method"""
var = Bit(True)
var.unset()
self.assertFalse(var, "Bit(True).unset() == False")
var = Bit(False)
var.unset()
self.assertFalse(var, "Bit(False).unset() == False")
def test_errors(self):
"""
Test that errors are raised for invalid values

Write Preview
Loading…
Cancel
Save