BitOps - GDScript library for Godot

Note: This library is currently work-in-progress, I am planning to add support for hexadecimal representations as well as signed values. It is primarily intended for use with integer values.

What is BitOps?

BitOps is a static library aimed at those who wish to delve into the world of binary using GDScript.

Why make BitOps?

Though Godot has features like bitwise operators (used in this library), it lacks the ability to easily manipulate things on a bit-by-bit basis. The only time Godot allows you to convert from bits to integers is with the File class. That requires loading in a file and reading it byte by byte.

BitOps is there to help fill in some of the gaps, allowing you to freely convert integers to binary and vice-versa. Additionally, it allows you to work with arrays of bits, giving you the flexibility to manipulate them however you like.

Perform logical operations (AND, NOT, OR, XOR), shift left or right, reverse, split, glue, slice, and more.

Details

Indexing is performed right to left, the first bit - bit 0 is the rightmost bit.

Convert between integers, arrays of bits, and strings of bits. You can add padding bits to ensure a desired size. For example, BitOps.string_to_bits("0110", 8) will produce [0,0,0,0,0,1,1,0].

Conversion is not limited to any fixed number of bits. Want to convert 13 bits to an integer? Go right ahead, simply call BitOps.bits_to_num(bit_array). Likewise, you can convert an integer directly to the minimum number of bits needed to represent it.

Integer	Bit array	Bit string
244 3	[1,1,1,1,0,1,0,0] [0,0,0,0,0,0,1,1] - [1,1] (minified)	"11110100" "00000011" - "11" (minified)

Many array-based operations such as:

• Setting bits of bit arrays to the specified value, either by providing a single index, multiple indices, or a range.
• Perform logical AND, OR, and XOR operations using pairs of bit arrays. Perform logical NOT on a bit array to flip it.
• Shifting bit arrays left or right a specified number of times.
• Reversing the order of a bit array.
• Splitting a bit array into a series of sub-arrays of the given length, this can be used to split a byte into nibbles for example. Simply call BitOps.get_nibbles(byte) or BitOps.get_chunks(byte, 4). Chunks of any size can be chosen, the most common ones have their own functions for convenience.
• Joining multiple bit arrays into a single contiguous array.
• 'Gluing' sets of n bits in an array, this can be used to combine a set of bytes into a 32-bit dword for example. Simply call BitOps.glue(bytes, 4), if you had an array of 8 bytes then you would end up with two dwords.
• Getting and/or setting the lowest or highest n bits in a bit array.
• Getting a slice of a bit array.
• Minifying a bit array so it contains the fewest needed bits, discarding all preceding 0 bits. Save space by converting it back to the desired size only when you need to.
• Creating bit arrays of any length, defaulting all values to 0 or 1. Call BitOps.create_buffer(n) or use one of several functions such as BitOps.create_byte().
• Generating an arbitrarily long random bit array.
• Pad a bit array to the desired minimum size by inserting 0s or 1s at the start or end.

Simple Examples:

Creating and manipulating a bit array
-----------------------------------------------
Create a bit array of 5 1s, giving us [1,1,1,1,1]
var arr = BitOps.create_buffer(5, 1)

Pad the buffer to be 8 bits long, adding 0s to the end, giving us [1,1,1,1,1,0,0,0]
arr= BitOps.pad(arr, 8, 0, true)

Set the highest 2 bits to be 0, giving us [0,0,1,1,1,0,0,0]
arr= BitOps.set_highest(arr, 2, 0)

Flip the entire bit array, giving us [1,1,0,0,0,1,1,1]
arr= BitOps.NOT(arr)

Convert the bit array to an integer, giving us 199
var num = BitOps.bits_to_num(arr)

Plans for the near-future:

Porting many of the bit array functions to work with bit strings, increasing the total number of functions