============================================================

                 Pico-8 Binary Functions Set

                                             PRGM ver. 1.1.1
Created by A-zu-ra                         MANUAL ver. 1.1.2

============================================================

This function set includes functions that will:
  - Convert a given integer into a 16-item table of
    binary values
  - Read a portion of the generated 16-item table
  - Insert a given table into another table at any position
  - Converts a given table of binary values into an integer

Through these functions, you can essentially use one integer
to serve multiple purposes. This document will not only
cover how the functions work, but also how to apply them in
the context of Pico-8's persistent data.

Included with this function set is a brief test program
showcasing all of the functions in action.

    INT COUNT increments once a frame in both whole number
    and decimal and is a base for all of the functions in
    the test.

    BIN START is the START variable of binread.
    BIN RANGE is the RANGE variable of binread.

    BIN TO INT tests reconversion of binary back to integer.
    BIN TO DEC tests reconversion of binary back to decimal.
    B2I + B2D is the values of BIN TO INT and BIN TO DEC
    as a single value.

    RANGE B2I is the integer value of binread.
    INSERT B2I is the integer value of binread inserted into
    another table via binins.
    RANGE B2D and INSERT B2D work the same as RANGE B2I and
    INSERT B2I, but for the decimal subset.

The bottom of the function test contains the RAW BINARY of
the integer, as well as the range of binread and starting
point of binins visualized. In the test code is a section
that has EDIT THESE BELOW VALUES! and EDIT THESE ABOVE
VALUES!, so feel free to experiment with the values to get
a better feel of how things go together.

------------------------------------------------------------

inttobin(value, decimal)

    value     An integer within Pico-8's acceptable range
              (-32768 to 32767)
    decimal   A boolean that decides whether or not to pull
              from either whole number or decimal (0 or 1)

    RETURNS a table with 16 values of either 0 or 1

    This function takes an acceptable value that you give it
    and creates a 16-value table, each containing either a
    0 or a 1 in it. The following examples are formatted to
    be human readable; the order is reversed when the table
    is created (i.e. the first example below is, from the
    table's perspective, 0000100000000000).

    16        0000000000010000
    136       0000000010001000
    9570      0010010101100010
    -32768    1000000000000000
    -3530     1111001000110110

------------------------------------------------------------

binread(table, start, range)

    table     A table generated via inttobin
    start     The starting point to read from
              (remember, tables are 1-indexed)
    range     How many values from the starting point
              to read from

    RETURNS a table with a number of values
    specified in range

    This function takes a table that is generated from
    inttobin and extracts a user specified portion of it.
    This function requires two more additional values: the
    starting point (so you can choose from a different
    section of the table), and a range (so you can extract
    larger values).

    Since the table has the binary values in reverse order,
    the function will appear to go from right to left when
    imagining the ranges in a human readable order. The
    following examples will hopefully give a better visual
    of this.

    Assume that table is {1, 1, 0, 0, 1, 1, 0, 0,
    1, 1, 0, 0, 1, 1, 0, 0}.

    (table, 1, 1)                   S
                     0011001100110011   bintoint: 1
    (table, 1, 5)               E   S
                     0011001100110011   bintoint: 19
    (table, 4, 7)          E     S   
                     0011001100110011   bintoint: 102
    (table, 9, 4)        E  S   
                     0011001100110011   bintoint: 3

------------------------------------------------------------

binins(table, table2, start)

    table     The table you want to append values to
    table2    A table generated via inttobin or binread
    start     What point in the target table to start at

    RETURNS the target table with table2 appended to it,
    starting from the bit position specified by the user

    This function allows you to combine one table into
    another at any place. It's advised that you calculate
    the size of the table that you want to insert if you
    plan on using this function multiple times on one table.

    Much like the binread function, the function will appear
    to go from right to left when imagining the start point
    in a human readable order.

    Assume that the target table is empty.

    table2 = {1, 0, 0, 1} -- 1001
    (table, table2, 1)                   S
                          0000000000001001   bintoint: 9

    table2 = {1, 0, 1, 0, 1, 1} -- 110101
    (table, table2, 4)                S
                          0000000110101000   bintoint: 424

    table2 = {0, 1, 1, 0, 1} -- 10110
    (table, table2, 7)             S
                          0000010110000000   bintoint: 1408

    Remember to calculate your table sizes.

    table2 = {1, 0, 1, 1} -- 1101                YES
    table3 = {0, 1, 1} -- 110
    (table, table2, 3)            3    2
    (table, table3, 8)            S    S
                          0000001100110100   bintoint: 820
                          (Both tables added in with no
                           problems)

    Otherwise, calling the function again will overwrite
    those bits if the sizes conflict with the positioning.

    table2 = {1, 0, 1, 1} -- 1101                NO
    table3 = {0, 1, 1} -- 110
    (table, table2, 6)            3 2
    (table, table3, 8)            S S
                          0000001100100000   bintoint: 800
                          (Table 3 overwrites last two bits
                           of table 2)

------------------------------------------------------------

bintoint(table, decimal)

    table     A table generated via inttobin, binread, or
              binins
    decimal   A boolean that decides whether or not to write
              to either whole number or decimal (0 or 1)

    RETURNS an integer representation of the binary table

    This function will take a binary table that you give it
    and convert it back into an integer.

    0000000000001000    8
    0000000001000010    66
    0000101000101000    2600
    1000100100001000    -30456

------------------------------------------------------------

How to apply code in context with Pico-8 persistent data

-- Two 8-bit values (43 tokens)
c = {}
v = {6,6}
for i=1,#v do
 binins(c,binread(inttobin(v[i],0),1,8),((i-1)*8)+1)
end
f = bintoint(c,0)

(Throw f into persistent data via dset)

To adjust this for other equal bit values, replace B and
adjust the amount of items used in the v table:

for i=1,#v do
 binins(a,binread(inttobin(v[i]),1,B),((i-1)*B)+1)
end

         #v  B   Max     Leftover bits
16-bit   1   16  65535*  None left over
15-bit   1   15  32767   1 bit
14-bit   1   14  16383   2 bits
13-bit   1   13  8191    3 bits
12-bit   1   12  4095    4 bits
11-bit   1   11  2047    5 bits
10-bit   1   10  1023    6 bits
9-bit    1   9   511     7 bits
8-bit    2   8   255     None left over
7-bit    2   7   127     2 bits
6-bit    2   6   63      4 bits
5-bit    3   5   31      1 bit
4-bit    4   4   15      None left over
3-bit    5   3   7       1 bit
2-bit    8   2   3       None left over
1-bit    16  1   1       None left over

*Any number past 32767 will be represented as a negative
 value counting towards 0.

-- Different size bit values (47 tokens)
d = {}
s = {5,8}
v = {31,255}
c = 1
for i=1,#v do
 binins(d,binread(inttobin(v[i],0),1,8),c)
 c += s[i]
end
f = bintoint(d)

(Throw f into persistent data via dset)

To adjust this for other values and bit sizes, ensure that:
  - s and v have the same amount of items
  - the sum of all numbers in s is less than or equal to 16
  - the values in v are within the boundaries of the
    respective bit count specified in s

============================================================

Version History

PROGRAM                                          TKN    BYTE

    v1.1.1                                       161     418
        Optimized inttobin function.

    v1.1.0                                       171     435
        inttobin and bintoint can now read from and write
        to decimal.

    v1.0.0                                       136     377
        Initial release.

*Token and byte values based on the functions alone;
 they do not factor in the included function test.

MANUAL

    v1.1.2
        Modified examples for applying code in context with
        Pico-8 persistent data to work with PRGM v1.1.1.

    v1.1.1
        Changed version number system.

    v1.1.0
        Added explanation of additional test functions,
        as well as new decimal option for inttobin and
        bintoint.

    v1.0.2
        Removed mention of empty table generation in the
        function summary.

    v1.0.1
        Added bintoint readouts on binread and binins.

    v1.0.0
        Initial manual.