diff --git a/CHANGE_LOG b/CHANGE_LOG index 573b9bc3..5ba205a0 100644 --- a/CHANGE_LOG +++ b/CHANGE_LOG @@ -1,5 +1,8 @@ -2023-12-XX 2.9.0: +2023-12-17 2.9.0: ------------------- + * deprecate support for Python 2 - Python 2.7 support will be removed + in bitarray version 3.0, + see [roadmap](https://github.com/ilanschnell/bitarray#roadmap) * `bitarray(n)` for integer initializer `n` will always return a bitarray of length `n` with all items initialized to `0`, see #212 * allow sub-bitarray in `.count()`, #212 @@ -7,8 +10,6 @@ * `.find()` and `.index()`: add keyword argument `right` for rightmost index * `.itersearch()`: add start and stop argument, and keyword argument `right` (for descending order - starting with rightmost match) - * deprecate support for Python 2 - Python 2 support will be removed in - bitarray version 3.0 * deprecate `util.rindex()` (will be removed in 3.0 release), use `.index(..., right=True)` instead * deprecate `util.make_endian()` (will be removed in 3.0 release), diff --git a/README.rst b/README.rst index 5a48f861..a8a2d36a 100644 --- a/README.rst +++ b/README.rst @@ -78,7 +78,7 @@ Once you have installed the package, you may want to test it: $ python -c 'import bitarray; bitarray.test()' bitarray is installed in: /Users/ilan/bitarray/bitarray - bitarray version: 2.8.5 + bitarray version: 2.9.0 sys.version: 3.11.0 (main, Oct 25 2022) [Clang 14.0.4] sys.prefix: /Users/ilan/Mini3/envs/py311 pointer size: 64 bit @@ -427,11 +427,13 @@ and can therefore be used as a dictionary key: Reference ========= -bitarray version: 2.8.5 -- `change log `__ +bitarray version: 2.9.0 -- `change log `__ In the following, ``item`` and ``value`` are usually a single bit - an integer 0 or 1. +Also, ``sub_bitarray`` refers to either a bitarray, or an ``item``. + The bitarray object: -------------------- @@ -442,7 +444,7 @@ The bitarray object: The initializer may be of the following types: ``int``: Create a bitarray of given integer length. The initial values are - uninitialized. + all ``0``. ``str``: Create bitarray from a string of ``0`` and ``1``. @@ -511,13 +513,20 @@ bitarray methods: Return a copy of the bitarray. -``count(value=1, start=0, stop=, step=1, /)`` -> int - Count number of occurrences of ``value`` in the bitarray. +``count(value=1, start=0, stop=, step=1, /)`` -> int + Number of occurrences of ``value`` bitarray within ``[start:stop:step]``. + Optional arguments ``start``, ``stop`` and ``step`` are interpreted in + slice notation, meaning ``a.count(value, start, stop, step)`` equals + ``a[start:stop:step].count(value)``. + The ``value`` may also be a sub-bitarray. In this case non-overlapping + occurrences are counted within ``[start:stop]`` (``step`` must be 1). New in version 1.1.0: optional start and stop arguments. New in version 2.3.7: optional step argument. + New in version 2.9: add non-overlapping sub-bitarray count. + ``decode(code, /)`` -> list Given a prefix code (a dict mapping symbols to bitarrays, or ``decodetree`` @@ -545,13 +554,15 @@ bitarray methods: a multiple of 8, and return the number of bits added [0..7]. -``find(sub_bitarray, start=0, stop=, /)`` -> int - Return lowest index where sub_bitarray is found, such that sub_bitarray - is contained within ``[start:stop]``. +``find(sub_bitarray, start=0, stop=, /, right=False)`` -> int + Return lowest (or rightmost when ``right=True``) index where sub_bitarray + is found, such that sub_bitarray is contained within ``[start:stop]``. Return -1 when sub_bitarray is not found. New in version 2.1. + New in version 2.9: add optional keyword argument ``right``. + ``frombytes(bytes, /)`` Extend bitarray with raw bytes from a bytes-like object. @@ -569,11 +580,13 @@ bitarray methods: is still read and appended). -``index(sub_bitarray, start=0, stop=, /)`` -> int - Return lowest index where sub_bitarray is found, such that sub_bitarray - is contained within ``[start:stop]``. +``index(sub_bitarray, start=0, stop=, /, right=False)`` -> int + Return lowest (or rightmost when ``right=True``) index where sub_bitarray + is found, such that sub_bitarray is contained within ``[start:stop]``. Raises ``ValueError`` when the sub_bitarray is not present. + New in version 2.9: add optional keyword argument ``right``. + ``insert(index, value, /)`` Insert ``value`` into bitarray before ``index``. @@ -592,9 +605,14 @@ bitarray methods: the symbols. -``itersearch(sub_bitarray, /)`` -> iterator - Searches for given sub_bitarray in self, and return an iterator over - the start positions where sub_bitarray matches self. +``itersearch(sub_bitarray, start=0, stop=, /, right=False)`` -> iterator + Return iterator over indices where sub_bitarray is found, such that + sub_bitarray is contained within ``[start:stop]``. + The indices are iterated in ascending order (from lowest to highest), + unless ``right=True``, which will iterate in descending oder (starting with + rightmost match). + + New in version 2.9: optional start and stop arguments - add optional keyword argument ``right``. ``pack(bytes, /)`` @@ -730,6 +748,13 @@ This sub-module was added in version 1.2. endianness, which may be 'big', 'little'. +``ones(length, /, endian=None)`` -> bitarray + Create a bitarray of length, with all values 1, and optional + endianness, which may be 'big', 'little'. + + New in version 2.9. + + ``urandom(length, /, endian=None)`` -> bitarray Return a bitarray of ``length`` random bits (uses ``os.urandom``). @@ -755,13 +780,19 @@ This sub-module was added in version 1.2. New in version 1.3. + New in version 2.9: deprecated - use ``bitarray()``. -``rindex(bitarray, value=1, start=0, stop=, /)`` -> int - Return rightmost (highest) index of ``value`` in bitarray. - Raises ``ValueError`` if value is not present. + +``rindex(bitarray, sub_bitarray=1, start=0, stop=, /)`` -> int + Return rightmost (highest) index where sub_bitarray (or item - defaults + to 1) is found in bitarray (``a``), such that sub_bitarray is contained + within ``a[start:stop]``. + Raises ``ValueError`` when the sub_bitarray is not present. New in version 2.3.0: optional start and stop arguments. + New in version 2.9: deprecated - use ``.index(..., right=1)``. + ``strip(bitarray, /, mode='right')`` -> bitarray Return a new bitarray with zeros stripped from left, right or both ends. diff --git a/doc/changelog.rst b/doc/changelog.rst index d51c1587..28900638 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -1,6 +1,24 @@ Change log ========== +**2.9.0** (2023-12-17): + +* deprecate support for Python 2 - Python 2.7 support will be removed + in bitarray version 3.0, + see `roadmap `__ +* ``bitarray(n)`` for integer initializer ``n`` will always return a bitarray + of length ``n`` with all items initialized to ``0``, see `#212 `__ +* allow sub-bitarray in ``.count()``, `#212 `__ +* add ``util.ones()`` +* ``.find()`` and ``.index()``: add keyword argument ``right`` for rightmost index +* ``.itersearch()``: add start and stop argument, and keyword + argument ``right`` (for descending order - starting with rightmost match) +* deprecate ``util.rindex()`` (will be removed in 3.0 release), + use ``.index(..., right=True)`` instead +* deprecate ``util.make_endian()`` (will be removed in 3.0 release), + use ``bitarray(..., endian=...)`` instead + + **2.8.5** (2023-12-09): * speedup unaligned copies by always using word shifts (in combination diff --git a/doc/reference.rst b/doc/reference.rst index fd51bc6a..46068a09 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -1,11 +1,13 @@ Reference ========= -bitarray version: 2.8.5 -- `change log `__ +bitarray version: 2.9.0 -- `change log `__ In the following, ``item`` and ``value`` are usually a single bit - an integer 0 or 1. +Also, ``sub_bitarray`` refers to either a bitarray, or an ``item``. + The bitarray object: -------------------- @@ -16,7 +18,7 @@ The bitarray object: The initializer may be of the following types: ``int``: Create a bitarray of given integer length. The initial values are - uninitialized. + all ``0``. ``str``: Create bitarray from a string of ``0`` and ``1``. @@ -85,13 +87,20 @@ bitarray methods: Return a copy of the bitarray. -``count(value=1, start=0, stop=, step=1, /)`` -> int - Count number of occurrences of ``value`` in the bitarray. +``count(value=1, start=0, stop=, step=1, /)`` -> int + Number of occurrences of ``value`` bitarray within ``[start:stop:step]``. + Optional arguments ``start``, ``stop`` and ``step`` are interpreted in + slice notation, meaning ``a.count(value, start, stop, step)`` equals + ``a[start:stop:step].count(value)``. + The ``value`` may also be a sub-bitarray. In this case non-overlapping + occurrences are counted within ``[start:stop]`` (``step`` must be 1). New in version 1.1.0: optional start and stop arguments. New in version 2.3.7: optional step argument. + New in version 2.9: add non-overlapping sub-bitarray count. + ``decode(code, /)`` -> list Given a prefix code (a dict mapping symbols to bitarrays, or ``decodetree`` @@ -119,13 +128,15 @@ bitarray methods: a multiple of 8, and return the number of bits added [0..7]. -``find(sub_bitarray, start=0, stop=, /)`` -> int - Return lowest index where sub_bitarray is found, such that sub_bitarray - is contained within ``[start:stop]``. +``find(sub_bitarray, start=0, stop=, /, right=False)`` -> int + Return lowest (or rightmost when ``right=True``) index where sub_bitarray + is found, such that sub_bitarray is contained within ``[start:stop]``. Return -1 when sub_bitarray is not found. New in version 2.1. + New in version 2.9: add optional keyword argument ``right``. + ``frombytes(bytes, /)`` Extend bitarray with raw bytes from a bytes-like object. @@ -143,11 +154,13 @@ bitarray methods: is still read and appended). -``index(sub_bitarray, start=0, stop=, /)`` -> int - Return lowest index where sub_bitarray is found, such that sub_bitarray - is contained within ``[start:stop]``. +``index(sub_bitarray, start=0, stop=, /, right=False)`` -> int + Return lowest (or rightmost when ``right=True``) index where sub_bitarray + is found, such that sub_bitarray is contained within ``[start:stop]``. Raises ``ValueError`` when the sub_bitarray is not present. + New in version 2.9: add optional keyword argument ``right``. + ``insert(index, value, /)`` Insert ``value`` into bitarray before ``index``. @@ -166,9 +179,14 @@ bitarray methods: the symbols. -``itersearch(sub_bitarray, /)`` -> iterator - Searches for given sub_bitarray in self, and return an iterator over - the start positions where sub_bitarray matches self. +``itersearch(sub_bitarray, start=0, stop=, /, right=False)`` -> iterator + Return iterator over indices where sub_bitarray is found, such that + sub_bitarray is contained within ``[start:stop]``. + The indices are iterated in ascending order (from lowest to highest), + unless ``right=True``, which will iterate in descending oder (starting with + rightmost match). + + New in version 2.9: optional start and stop arguments - add optional keyword argument ``right``. ``pack(bytes, /)`` @@ -304,6 +322,13 @@ This sub-module was added in version 1.2. endianness, which may be 'big', 'little'. +``ones(length, /, endian=None)`` -> bitarray + Create a bitarray of length, with all values 1, and optional + endianness, which may be 'big', 'little'. + + New in version 2.9. + + ``urandom(length, /, endian=None)`` -> bitarray Return a bitarray of ``length`` random bits (uses ``os.urandom``). @@ -329,13 +354,19 @@ This sub-module was added in version 1.2. New in version 1.3. + New in version 2.9: deprecated - use ``bitarray()``. -``rindex(bitarray, value=1, start=0, stop=, /)`` -> int - Return rightmost (highest) index of ``value`` in bitarray. - Raises ``ValueError`` if value is not present. + +``rindex(bitarray, sub_bitarray=1, start=0, stop=, /)`` -> int + Return rightmost (highest) index where sub_bitarray (or item - defaults + to 1) is found in bitarray (``a``), such that sub_bitarray is contained + within ``a[start:stop]``. + Raises ``ValueError`` when the sub_bitarray is not present. New in version 2.3.0: optional start and stop arguments. + New in version 2.9: deprecated - use ``.index(..., right=1)``. + ``strip(bitarray, /, mode='right')`` -> bitarray Return a new bitarray with zeros stripped from left, right or both ends. diff --git a/setup.py b/setup.py index 58287a9b..3af5a0b6 100644 --- a/setup.py +++ b/setup.py @@ -5,10 +5,10 @@ if sys.version_info[0] == 2: print("""\ -************************************************************************** -* Python 2 support of bitarray is deprecated (as of bitarray version 2.9) -* and will be removed in bitarray version 3.0. -************************************************************************** +**************************************************************************** +* Python 2 support of bitarray is deprecated (as of bitarray version 2.9) +* and will be removed in bitarray version 3.0. +**************************************************************************** """) if "test" in sys.argv: diff --git a/update_doc.py b/update_doc.py index f98ce9ed..0a2b4ae0 100644 --- a/update_doc.py +++ b/update_doc.py @@ -163,7 +163,7 @@ def write_reference(fo): In the following, ``item`` and ``value`` are usually a single bit - an integer 0 or 1. -Also, ``sub_bitarray`` refers to either a bitarray, or an item. +Also, ``sub_bitarray`` refers to either a bitarray, or an ``item``. The bitarray object: