Skip to content

bitset.adoc

Latest commit

 

History

History
252 lines (188 loc) · 5.87 KB

bitset.adoc

File metadata and controls

252 lines (188 loc) · 5.87 KB
Raw

Bitset! datatype

Table of Contents

1. Abstract

A bitset! value is an array of bits that is used to store boolean values. Bitset indexing is zero based with 1 values representing true, and 0 values representing false.

Bitset! is a member of the following typesets: default!

2. Creation

Bitset! values can be created by using a make constructor, a to conversion, or by using the function charset.

3. Runtime creation

<bitset> ::= make bitset! <binary> | make bitset! <bitset-spec> | to bitset! <bitset-spec> | charset <bitset-spec>
<bitset-spec> ::= <integer> | <char> | <string> | [<bit-position>*] | [not <bit-position>*]
<bit-position> ::= <integer> | <char> | <string> | <char> - <char> | <integer> - <integer>

  • Make

    >> make bitset! 50    ; create an empty bitset with places for at least 50 bits
== make bitset! #{00000000000000}
    >> make bitset! #"A"   ; create a bitset with bit 65 set
== make bitset! #{000000000000000040}
    >> make bitset! "hi"   ; create a bitset with bits 104 and 105 set
== make bitset! #{00000000000000000000000000C0}
    >> make bitset! [120 "hello" #"A"]   ; create and set bits using different value representations
== make bitset! #{00000000000000004000000004890080}

    Using ranges:

    Ranges are defined using two char!, or integer! values, separated by a dash word.

    >> make bitset! [#"0" - #"9" #"a" - #"z"]   ; create a bitset using ranges of values
== make bitset! #{000000000000FFC0000000007FFFFFE0}

    Bitsets are auto-sized to fit the specification values provided. The size is rounded to the upper byte bound.

  • To

    Converting a value to a bitset value using to is equivalent to using make bitset!, with the exception that integer! values are not allowed.

>> to bitset! 42
*** Script Error: cannot MAKE/TO bitset! from: 42
*** Where: to
*** Stack:
>> to bitset! #"A"   ; a bitset with bit 65 set
== make bitset! #{000000000000000040}
>> to bitset! "hi"   ; a bitset with bits 104 and 105 set
== make bitset! #{00000000000000000000000000C0}
>> to bitset! [#"0" - #"9" #"a" - #"z"]   ; a bitset using ranges of values
== make bitset! #{000000000000FFC0000000007FFFFFE0}

  • Charset

    >> source charset
charset: func ["Shortcut for `make bitset!`"
    spec [block! integer! char! string!]
][
    make bitset! spec
]

    Charset is a shortcut for make bitset!, with the exception that binary! values are not allowed.

    >> charset #{2A}
*** Script Error: charset does not allow binary! for its spec argument
*** Where: charset
*** Stack: charset
    >> charset [120 "hello" #"A"]   ; create and set bits using different value representations
== make bitset! #{00000000000000004000000004890080}
    >> charset [#"0" - #"9" #"a" - #"z"]   ; create a bitset using ranges of values
== make bitset! #{000000000000FFC0000000007FFFFFE0}
Note

Values in the charset range specs must be listed in ascending order.

4. Complements

Complemented bitsets can be created by including the word not in a block spec.

charset [not "0123456789"]   ; all characters except digits
== make bitset! [not #{000000000000FFC0}]

The action! value complement can also be used to create complemented bitsets.

>> make bitset! 42
== make bitset! #{000000000000}

>> complement make bitset! 42
== make bitset! [not #{000000000000}]

Complement? can be used to check if a bitset has been complemented.

>> b: complement make bitset! 42
== make bitset! [not #{000000000000}]

>> complement? b
== true
Note
 In order to cope with the wide range of Unicode characters, bits outside of the bitsets are treated as virtual bits so they can be tested and set without errors. The bitset size will auto-expand according to the needs. This is still not enough to deal with big ranges such as a bitset for example, all Unicode characters except digits. For such cases, it is possible to define a complemented bitset that represents the complement range of the specified bits. This makes it possible to have large bitsets while using only a tiny memory portion.

5. Path notation

For reading and writing single bits, use path notation.

bs: charset [#"a" - #"z"]
bs/97     ; will return true
bs/40     ; will return false
bs/97: false
bs/97     ; will return false

6. Data Set operations

The following data set operations are possible with bitset values: difference, exclude, intersect, union

>> a: charset "abc"
== make bitset! #{00000000000000000000000070}

>> b: charset "ABC"
== make bitset! #{000000000000000070}
>> difference a b
== make bitset! #{00000000000000007000000070}
>> exclude a b
== make bitset! #{00000000000000000000000070}
>> intersect a b
== make bitset! #{00000000000000000000000000}

Using union, you can merge two bitsets together to form a new bitset.

digit: charset "0123456789"
lower: charset [#"a" - #"z"]
upper: charset [#"A" - #"Z"]

letters:  union lower upper
hexa:     union upper digit
alphanum: union letters digit

7. Comparisons

All comparators can be applied on bitset!: =, ==, <>, >, <, >=, <=, =?.

8. Testing values

Use bitset? to check if a value is of the bitset! datatype.

>> b: make bitset! 42
== make bitset! #{000000000000}

>> bitset? b
== true

Use type? to return the datatype of a given value.

>> type? b
== bitset!

9. Predefined words

9.1. Actions

and~, append, clear, complement, copy, find, insert, length?, negate, or~, pick, poke, remove, xor~

9.2. Functions

bitset?, charset, to-bitset

9.3. Natives

complement?, difference, exclude, intersect, union

9.4. Operators

and, or, xor