Add get_bit() method for Ints and Bytes

5 files changed, 185 insertions, 1 deletions

diff --git a/api/api.md b/api/api.md
index 464ec58a..9711ab44 100644
--- a/api/api.md
+++ b/api/api.md
@@ -210,6 +210,36 @@ text | `Text` | The string containing the boolean value.  | -
 ```
 
 # Byte
+## Byte.get_bit
+
+```tomo
+Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)
+```
+
+In the binary representation of a byte, check whether a given bit index is set to 1 or not.
+
+The bit index must be between 1-8 or a runtime error will be produced.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Byte` | The byte whose bits are being inspected.  | -
+bit_index | `Int` | The index of the bit to check (1-indexed, range 1-8).  | -
+
+**Return:** Whether or not the given bit index is set to 1 in the byte.
+
+
+**Example:**
+```tomo
+>> Byte(6).get_bit(1)
+= no
+>> Byte(6).get_bit(2)
+= yes
+>> Byte(6).get_bit(3)
+= yes
+>> Byte(6).get_bit(4)
+= no
+
+```
 ## Byte.hex
 
 ```tomo
@@ -402,6 +432,36 @@ n | `Int` | The integer to compute the factorial of.  | -
 = 3628800
 
 ```
+## Int.get_bit
+
+```tomo
+Int.get_bit : func(i: Int, bit_index: Int -> Bool)
+```
+
+In the binary representation of an integer, check whether a given bit index is set to 1 or not.
+
+For fixed-size integers, the bit index must be between 1 and the number of bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must be between 1 and `Int64.max`. Values outside this range will produce a runtime error.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Int` | The integer whose bits are being inspected.  | -
+bit_index | `Int` | The index of the bit to check (1-indexed).  | -
+
+**Return:** Whether or not the given bit index is set to 1 in the binary representation of the integer.
+
+
+**Example:**
+```tomo
+>> (6).get_bit(1)
+= no
+>> (6).get_bit(2)
+= yes
+>> (6).get_bit(3)
+= yes
+>> (6).get_bit(4)
+= no
+
+```
 ## Int.hex
 
 ```tomo
diff --git a/api/bytes.md b/api/bytes.md
index 598c92b7..908d78e2 100644
--- a/api/bytes.md
+++ b/api/bytes.md
@@ -3,6 +3,36 @@
 # Builtins
 
 # Byte
+## Byte.get_bit
+
+```tomo
+Byte.get_bit : func(i: Byte, bit_index: Int -> Bool)
+```
+
+In the binary representation of a byte, check whether a given bit index is set to 1 or not.
+
+The bit index must be between 1-8 or a runtime error will be produced.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Byte` | The byte whose bits are being inspected.  | -
+bit_index | `Int` | The index of the bit to check (1-indexed, range 1-8).  | -
+
+**Return:** Whether or not the given bit index is set to 1 in the byte.
+
+
+**Example:**
+```tomo
+>> Byte(6).get_bit(1)
+= no
+>> Byte(6).get_bit(2)
+= yes
+>> Byte(6).get_bit(3)
+= yes
+>> Byte(6).get_bit(4)
+= no
+
+```
 ## Byte.hex
 
 ```tomo
diff --git a/api/bytes.yaml b/api/bytes.yaml
index 52f48528..2785513d 100644
--- a/api/bytes.yaml
+++ b/api/bytes.yaml
@@ -1,3 +1,33 @@
+Byte.get_bit:
+  short: check whether a bit is set
+  description: >
+    In the binary representation of a byte, check whether a given bit index is
+    set to 1 or not.
+  note: >
+    The bit index must be between 1-8 or a runtime error will be produced.
+  return:
+    type: 'Bool'
+    description: >
+      Whether or not the given bit index is set to 1 in the byte.
+  args:
+    i:
+      type: 'Byte'
+      description: >
+        The byte whose bits are being inspected.
+    bit_index:
+      type: 'Int'
+      description: >
+        The index of the bit to check (1-indexed, range 1-8).
+  example: |
+    >> Byte(6).get_bit(1)
+    = no
+    >> Byte(6).get_bit(2)
+    = yes
+    >> Byte(6).get_bit(3)
+    = yes
+    >> Byte(6).get_bit(4)
+    = no
+
 Byte.hex:
   short: convert to hexidecimal
   description: >
diff --git a/api/integers.md b/api/integers.md
index 0865e93f..efb891bf 100644
--- a/api/integers.md
+++ b/api/integers.md
@@ -90,6 +90,36 @@ n | `Int` | The integer to compute the factorial of.  | -
 = 3628800
 
 ```
+## Int.get_bit
+
+```tomo
+Int.get_bit : func(i: Int, bit_index: Int -> Bool)
+```
+
+In the binary representation of an integer, check whether a given bit index is set to 1 or not.
+
+For fixed-size integers, the bit index must be between 1 and the number of bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must be between 1 and `Int64.max`. Values outside this range will produce a runtime error.
+
+Argument | Type | Description | Default
+---------|------|-------------|---------
+i | `Int` | The integer whose bits are being inspected.  | -
+bit_index | `Int` | The index of the bit to check (1-indexed).  | -
+
+**Return:** Whether or not the given bit index is set to 1 in the binary representation of the integer.
+
+
+**Example:**
+```tomo
+>> (6).get_bit(1)
+= no
+>> (6).get_bit(2)
+= yes
+>> (6).get_bit(3)
+= yes
+>> (6).get_bit(4)
+= no
+
+```
 ## Int.hex
 
 ```tomo
diff --git a/api/integers.yaml b/api/integers.yaml
index f927c75f..a91a21ce 100644
--- a/api/integers.yaml
+++ b/api/integers.yaml
@@ -81,7 +81,41 @@ Int.factorial:
   example: |
     >> (10).factorial()
     = 3628800
-    
+
+Int.get_bit:
+  short: check whether a bit is set
+  description: >
+    In the binary representation of an integer, check whether a given bit index
+    is set to 1 or not.
+  note: >
+    For fixed-size integers, the bit index must be between 1 and the number of
+    bits in that integer (i.e. 1-64 for `Int64`). For `Int`, the bit index must
+    be between 1 and `Int64.max`. Values outside this range will produce a
+    runtime error.
+  return:
+    type: 'Bool'
+    description: >
+      Whether or not the given bit index is set to 1 in the binary
+      representation of the integer.
+  args:
+    i:
+      type: 'Int'
+      description: >
+        The integer whose bits are being inspected.
+    bit_index:
+      type: 'Int'
+      description: >
+        The index of the bit to check (1-indexed).
+  example: |
+    >> (6).get_bit(1)
+    = no
+    >> (6).get_bit(2)
+    = yes
+    >> (6).get_bit(3)
+    = yes
+    >> (6).get_bit(4)
+    = no
+
 Int.hex:
   short: convert to hexidecimal
   description: >