.. include:: ../../global.rst .. _`bitset type`: Bitset Type =========== Bitsets are arrays of bits. They were originally introduced to provide testable state for :ref:`SRFI-14 ` char-sets: "is this code point *Lowercase*?" Reader Form ----------- The reader form for bitsets is :samp:`#B\\{ {size} [{bits} ...] }`. :samp:`{size}` indicates the absolute size of the bitset with indexing starting at 0. Referencing a bit beyond this range is an error. All bits are initially cleared. :samp:`{bits}` defines the bits that are initially set (or clear) with a sequence of 1s and 0s in blocks of up to 8 bits. The first 0 or 1 sets the first bit, the second 0 or 1 the second bit etc.. The next block of eight bits starts at the ninth bit and continues. Setting the n\ :sup:`th` bit in a large bitset should not involve explicitly indicating that all the previous bits were 0 so :samp:`{bits}` can take the form :samp:`{offset}:{bits}` where :samp:`{offset}` is a hexadecimal number and is a multiple of 8. Intervening blocks are skipped. Subsequent :samp:`{bits}` continue with the next block. Whole blocks of bits can be set with the form :samp:`{first}-{last}` where :samp:`{first}` and :samp:`{last}` are hexadecimal numbers (and multiples of 8) representing the first block of all 1s through to the last block inclusive. To set a single block use :samp:`{first}-{first}`. By way of example: * ``#B{ 32 001 }`` is much like hexadecimal 0x0004 * ``#B{ 32 8:1 }`` is much like hexadecimal 0x0100 * ``#B{ 32 1 10-18 }`` is much like hexadecimal 0xFF01 * ``#B{ 32 01 10-10 00000001 }`` is much like hexadecimal 0x8F02 * ``#B{ 65536 30-30 11000000 01111110 60:01111110 }`` is the bitset of Unicode's *ASCII_Hex_Digit* Property in Plane 0, this it, bits 0x30-0x39, 0x41-0x46 and 0x61-0x66. * try typing ``SRFI-14/char-set:lower-case`` at the :lname:`Idio` prompt to see a richer example Bitset Predicates ----------------- .. _`bitset?`: .. idio:function:: bitset? o test if `o` is an bitset :param o: object to test :return: ``#t`` if `o` is an bitset, ``#f`` otherwise Bitset Constructors ------------------- .. _`make-bitset`: .. idio:function:: make-bitset size create an bitset with a size of `size` :param size: initial bitset size :type size: integer :rtype: bitset Bitset Attributes ----------------- .. _`bitset-size`: .. idio:function:: bitset-size bs return the size of bitset `bs` :rtype: integer .. _`bitset-set!`: .. idio:function:: bitset-set! bs bit set bit `bit` in bitset `bs` :param bs: bitset :type bs: bitset :param bit: bit :type bit: unicode or integer :return: ``#`` .. _`bitset-clear!`: .. idio:function:: bitset-clear! bs bit clear bit `bit` in bitset `bs` :param bs: bitset :type bs: bitset :param bit: bit :type bit: unicode or integer :return: ``#`` .. _`bitset-ref`: .. idio:function:: bitset-ref bs bit get bit `bit` in bitset `bs` :param bs: bitset :type bs: bitset :param bit: bit :type bit: unicode or integer :rtype: ``#`` Bitset Functions ---------------- .. _`copy-bitset`: .. idio:function:: copy-bitset bs copy the bitset :param args: bitset to be copied :type args: bitset :rtype: bitset .. _`merge-bitset`: .. idio:function:: merge-bitset [bs ...] merge the bitsets :param args: bitsets to be merged :type args: list :rtype: bitset or ``#n`` if no bitsets supplied .. _`and-bitset`: .. idio:function:: and-bitset [bs ...] logical AND the bitsets :param args: bitsets to be operated on :type args: list :rtype: bitset or ``#n`` if no bitsets supplied .. _`ior-bitset`: .. idio:function:: ior-bitset [bs ...] logical Inclusive OR the bitsets :param args: bitsets to be operated on :type args: list :rtype: bitset or ``#n`` if no bitsets supplied .. _`xor-bitset`: .. idio:function:: xor-bitset [bs ...] logical eXclusive OR the bitsets :param args: bitsets to be operated on :type args: list :rtype: bitset or ``#n`` if no bitsets supplied .. _`not-bitset`: .. idio:function:: not-bitset bs logical complement of the bitset :param args: bitset to be operated on :type args: bitset :rtype: bitset .. _`subtract-bitset`: .. idio:function:: subtract-bitset [bs ...] subtract the bitsets :param args: bitsets to be operated on :type args: list :rtype: bitset or ``#n`` if no bitsets supplied .. _`equal-bitset?`: .. idio:function:: equal-bitset? [bs ...] are the bitsets equal :param args: bitsets to be operated on :type args: list :rtype: bitset or ``#f`` if no bitsets supplied .. _`bitset-for-each-set`: .. idio:function:: bitset-for-each-set bs f invoke `f` on each bit in bitset `bs` that is set :param bs: bitset to be operated on :type bs: bitset :param f: function to invoke on each set bit :type f: function of 1 arg :rtype: ``#`` The argument to `f` will be the index of the bit .. _`fold-bitset`: .. idio:function:: fold-bitset bs f v invoke `f` on each bit in bitset `bs` that is set accumulating the result in `v` :param bs: bitset to be operated on :type bs: bitset :param f: function to invoke on each set bit :type f: function of 2 args :param v: accumulated value :type v: any :return: the accumulated value :rtype: any For each set bit, the arguments to `f` will be the index of the bit and `v` and `v` is subsequently set to the result of `f`. .. include:: ../../commit.rst