diff --git a/README.md b/README.md index 4b005501..942c7597 100644 --- a/README.md +++ b/README.md @@ -21,14 +21,14 @@ News ---- **April 2024**: bitstring 4.2.0 released. -New in 4.2: +New in version 4.2: * Dropped support for Python 3.7. Minimum version is now 3.8. * A new `Dtype` class can be optionally used to specify types. * The `bitstring.options` object is now the preferred method for changing module options. * New `fromstring` method as another way to create bitstrings from formatted strings. * More types can now be pretty printed. -* A range of 8-bit, 6-bit and even 4-bit float formats added (beta): +* A range of 8-bit, 6-bit and even 4-bit floating point formats added (beta): * Performance improvements. See the [release notes](https://github.com/scott-griffiths/bitstring/blob/main/release_notes.txt) for details. Please let me know if you encounter any problems. diff --git a/doc/array.rst b/doc/array.rst index dc847990..9fe60181 100644 --- a/doc/array.rst +++ b/doc/array.rst @@ -343,7 +343,7 @@ The dtype of the resulting ``Array`` is calculated by applying these rules: **Rule 0**: For comparison operators (``<``, ``>=``, ``==``, ``!=`` etc.) the result is always an ``Array`` of dtype ``'bool'``. -For other operators, one of the two input ``Array`` dtypes is used as the ouput dtype by applying the remaining rules in order until a winner is found: +For other operators, one of the two input ``Array`` dtypes is used as the output dtype by applying the remaining rules in order until a winner is found: * **Rule 1**: Floating point types always win against integer types. * **Rule 2**: Signed integer types always win against unsigned integer types. diff --git a/doc/bits.rst b/doc/bits.rst index deb4d6cd..1606c23d 100644 --- a/doc/bits.rst +++ b/doc/bits.rst @@ -328,7 +328,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: str Property for the representation of the bitstring as a binary string. - Can be shortend to just ``b``. + Can be shortened to just ``b``. .. attribute:: Bits.bool :type: bool @@ -354,7 +354,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: str Property representing the hexadecimal value of the bitstring. - Can be shortend to just ``h``. + Can be shortened to just ``h``. If the bitstring is not a multiple of four bits long then getting its hex value will raise an :exc:`InterpretError`. :: @@ -366,7 +366,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: int Property for the signed two’s complement integer representation of the bitstring. - Can be shortend to just ``i``. + Can be shortened to just ``i``. .. attribute:: Bits.intbe :type: int @@ -395,7 +395,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: float Property for the floating point representation of the bitstring. - Can be shortend to just ``f``. + Can be shortened to just ``f``. The bitstring must be 16, 32 or 64 bits long to support the floating point interpretations, otherwise an :exc:`InterpretError` will be raised. @@ -427,7 +427,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: str Property for the octal representation of the bitstring. - Can be shortend to just ``o``. + Can be shortened to just ``o``. If the bitstring is not a multiple of three bits long then getting its octal value will raise a :exc:`InterpretError`. :: @@ -443,7 +443,7 @@ Note that the ``bin``, ``oct``, ``hex``, ``int``, ``uint`` and ``float`` propert :type: int Property for the unsigned base-2 integer representation of the bitstring. - Can be shortend to just ``u``. + Can be shortened to just ``u``. .. attribute:: Bits.uintbe :type: int diff --git a/doc/bitstream.rst b/doc/bitstream.rst index a12b0014..2a3ddd01 100644 --- a/doc/bitstream.rst +++ b/doc/bitstream.rst @@ -12,7 +12,7 @@ BitStream The ``pos`` will also used as a default for the :meth:`BitArray.overwrite` and :meth:`BitArray.insert` methods. -The bit position is modifed by methods that read bits, as described in :attr:`~ConstBitStream.pos`, but for the mutable ``BitStream`` it is also modified by other methods: +The bit position is modified by methods that read bits, as described in :attr:`~ConstBitStream.pos`, but for the mutable ``BitStream`` it is also modified by other methods: * If a methods extends the bitstring (``+=``, ``append``) the ``pos`` will move to the end of the bitstring. * If a method otherwise changes the length of the bitstring (``prepend``, ``insert``, sometimes ``replace``) the ``pos`` becomes invalid and will be reset to ``0``. diff --git a/doc/constbitstream.rst b/doc/constbitstream.rst index 55d08b8c..fec4ffdf 100644 --- a/doc/constbitstream.rst +++ b/doc/constbitstream.rst @@ -172,7 +172,7 @@ This position will be set to zero by default on construction, and will be modifi Using :meth:`~Bits.find` or :meth:`~Bits.rfind` will move ``pos`` to the start of the substring if it is found. -Note that the ``pos`` property isn’t considered a part of the bitstring's identity; this allows it to vary for immutable ``ConstBitStream`` objects and means that it doesn’t affect equality or hash values. +Note that the ``pos`` property isn’t considered a part of the bitstring's identity; this allows it to vary for immutable ``ConstBitStream`` objects and means that it doesn't affect equality or hash values. It also will be reset to zero if a bitstring is copied. diff --git a/doc/dtypes.rst b/doc/dtypes.rst index f0c93c01..3319dc93 100644 --- a/doc/dtypes.rst +++ b/doc/dtypes.rst @@ -15,7 +15,7 @@ The first parameter is a format token string that can optionally include a lengt If the first parameter doesn't include a length and one is appropriate, the `length` parameter can be used to specify the length of the dtype. The `scale` parameter can be used to specify a multiplicative scaling factor for the interpretation of the data. -This is primarily inteded for use with floating point formats of 8 bits or less, but can be used on other types. +This is primarily intended for use with floating point formats of 8 bits or less, but can be used on other types. In most situations the token string can be used instead of `Dtype` object when it is needed, and the `Dtype` will be constructed automatically, which is why the `Dtype` object is rarely used directly in this documentation. diff --git a/doc/exotic_floats.rst b/doc/exotic_floats.rst index 02d8c242..01dab66c 100644 --- a/doc/exotic_floats.rst +++ b/doc/exotic_floats.rst @@ -69,7 +69,7 @@ IEEE 8-bit Floating Point Types The 'binary8' formats are part of an ongoing IEEE standardisation process. -This implementation here is based on a publically available draft of the standard. +This implementation here is based on a publicly available draft of the standard. There are seven formats defined in the draft standard, but only two are supported here. If you'd like the other precisions supported then raise a feature request! diff --git a/doc/functions.rst b/doc/functions.rst index 2457056f..f52ade24 100644 --- a/doc/functions.rst +++ b/doc/functions.rst @@ -62,7 +62,9 @@ Note how you can use some tokens without sizes (such as ``bin`` and ``bits`` in If the size had been specified then a :exc:`ValueError` would be raised if the parameter given was the wrong length. Note also how bitstring literals can be used (the ``0b110`` in the bitstring returned by ``foo``) and these don't consume any of the items in ``*values``. -You can also include keyword, value pairs (or an equivalent dictionary) as the final parameter(s). The values are then packed according to the positions of the keywords in the format string. This is most easily explained with some examples. Firstly the format string needs to contain parameter names:: +You can also include keyword, value pairs (or an equivalent dictionary) as the final parameter(s). +The values are then packed according to the positions of the keywords in the format string. +This is most easily explained with some examples. Firstly the format string needs to contain parameter names:: format = 'hex32=start_code, uint12=width, uint12=height' diff --git a/doc/interpretation.rst b/doc/interpretation.rst index bb23c629..ec19fb72 100644 --- a/doc/interpretation.rst +++ b/doc/interpretation.rst @@ -3,11 +3,16 @@ Interpreting Bitstrings ======================= -Bitstrings don't know or care how they were created; they are just collections of bits. This means that you are quite free to interpret them in any way that makes sense. +Bitstrings don't know or care how they were created; they are just collections of bits. +This means that you are quite free to interpret them in any way that makes sense. -Several Python properties are used to create interpretations for the bitstring. These properties call private functions which will calculate and return the appropriate interpretation. These don’t change the bitstring in any way and it remains just a collection of bits. If you use the property again then the calculation will be repeated. +Several Python properties are used to create interpretations for the bitstring. +These properties call private functions which will calculate and return the appropriate interpretation. +These don’t change the bitstring in any way and it remains just a collection of bits. +If you use the property again then the calculation will be repeated. -Note that these properties can potentially be very expensive in terms of both computation and memory requirements. For example if you have initialised a bitstring from a 10 GiB file object and ask for its binary string representation then that string will be around 80 GiB in size! +Note that these properties can potentially be very expensive in terms of both computation and memory requirements. +For example if you have initialised a bitstring from a 10 GiB file object and ask for its binary string representation then that string will be around 80 GiB in size! If you're in an interactive session then the pretty-print method :meth:`~Bits.pp` can be useful as it will only convert the bitstring one chunk at a time for display. diff --git a/doc/introduction.rst b/doc/introduction.rst index 79f1909f..644941ba 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -64,7 +64,7 @@ For example:: Note that some types need a length to be specified, some don't need one, and others can infer the length from the value. -Another way to create a bitstring is via the ``pack`` function, which packs multiple values accoring to a given format. +Another way to create a bitstring is via the ``pack`` function, which packs multiple values according to a given format. See the entry on :func:`pack` for more information. .. _auto_init: @@ -198,7 +198,9 @@ From an integer >>> f.bin '1111111' -For initialisation with signed and unsigned binary integers (``int`` and ``uint`` respectively) the ``length`` parameter is mandatory, and must be large enough to contain the integer. So for example if ``length`` is 8 then ``uint`` can be in the range 0 to 255, while ``int`` can range from -128 to 127. Two's complement is used to represent negative numbers. +For initialisation with signed and unsigned binary integers (``int`` and ``uint`` respectively) the ``length`` parameter is mandatory, and must be large enough to contain the integer. +So for example if ``length`` is 8 then ``uint`` can be in the range 0 to 255, while ``int`` can range from -128 to 127. +Two's complement is used to represent negative numbers. The 'auto' initialiser can be used by giving the length in bits immediately after the ``int`` or ``uint`` token, followed by an equals sign then the value:: diff --git a/doc/quick_reference.rst b/doc/quick_reference.rst index 9963aa57..e1f35f50 100644 --- a/doc/quick_reference.rst +++ b/doc/quick_reference.rst @@ -273,7 +273,7 @@ Methods * :meth:`~Array.append` -- Append a single item to the end of the Array. * :meth:`~Array.astype` -- Cast the Array to a new dtype. * :meth:`~Array.byteswap` -- Change byte endianness of all items. -* :meth:`~Array.count` -- Count the number of occurences of a value. +* :meth:`~Array.count` -- Count the number of occurrences of a value. * :meth:`~Array.equals` -- Compare with another Array for exact equality. * :meth:`~Array.extend` -- Append multiple items to the end of the Array from an iterable. * :meth:`~Array.fromfile` -- Append items read from a file object. diff --git a/release_notes.txt b/release_notes.txt index 70db8f58..d34278fb 100644 --- a/release_notes.txt +++ b/release_notes.txt @@ -7,7 +7,7 @@ April 2024: version 4.2.0 ------------------------- This release contains a fairly large refactor of how different types are managed. This -shouldn't affect the end user, and the main noticable change should be the new Dtype +shouldn't affect the end user, and the main noticeable change should be the new Dtype class, which is optional to use. Support for 8-bit and smaller floats has been reworked and expanded. These are still @@ -101,7 +101,7 @@ A maintenance release, with some changes to the Array class which is still in 'b August 2023: version 4.1.0 released ----------------------------------- -This has turned into a suprisingly big release, with a major refactor and a brand new +This has turned into a surprisingly big release, with a major refactor and a brand new class (the first for 12 years!) There are also a couple of small possibly breaking changes detailed below, in particular 'auto' initialising bitstrings from integers is now disallowed. @@ -156,7 +156,7 @@ Other changes: >>> a.float8_143 16.0 -* Auto initialistion from ints has been removed and now raises a TypeError. Creating a +* Auto initialization from ints has been removed and now raises a TypeError. Creating a bitstring from an int still creates a zeroed bitstring of that length but ints won't be promoted to bitstrings as that has been a constant source of errors and confusion.