From 8a4d5dc57b14e7c947c25970bb4d4f4ef91450f4 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Thu, 26 Jun 2025 13:06:47 -0400 Subject: Add get_bit() method for Ints and Bytes --- api/api.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ api/bytes.md | 30 ++++++++++++++++++++++++++++ api/bytes.yaml | 30 ++++++++++++++++++++++++++++ api/integers.md | 30 ++++++++++++++++++++++++++++ api/integers.yaml | 36 ++++++++++++++++++++++++++++++++- 5 files changed, 185 insertions(+), 1 deletion(-) (limited to 'api') 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 @@ -401,6 +431,36 @@ n | `Int` | The integer to compute the factorial of. | - >> (10).factorial() = 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 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 @@ -89,6 +89,36 @@ n | `Int` | The integer to compute the factorial of. | - >> (10).factorial() = 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 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: > -- cgit v1.2.3