feat(binary-utils): add NAVBinaryCountLeadingZeros function

- Implement function to count leading zeros in 32-bit values

Author: damienbutt

BinaryUtils/NAVFoundation.BinaryUtils.axi

@@ -366,4 +366,39 @@ define_function integer NAVBcdToBinary(char value) {
 }
 
 
+/**
+ * @function NAVBinaryCountLeadingZeros
+ * @public
+ * @description Counts the number of leading zero bits in a 32-bit integer.
+ *
+ * @param {long} value - The value to analyze
+ *
+ * @returns {integer} Number of leading zeros (0-32)
+ *
+ * @example
+ * stack_var long value
+ * stack_var integer leadingZeros
+ *
+ * value = $0000000F  // Binary: 00000000 00000000 00000000 00001111
+ * leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 28
+ *
+ * value = $80000000  // Binary: 10000000 00000000 00000000 00000000
+ * leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 0
+ *
+ * value = $00000000  // Binary: 00000000 00000000 00000000 00000000
+ * leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 32
+ */
+define_function integer NAVBinaryCountLeadingZeros(long value) {
+    stack_var integer count
+
+    count = 0
+
+    while (count < 32 && (value & (1 << (31 - count))) == 0) {
+        count = count + 1
+    }
+
+    return count
+}
+
+
 #END_IF // __NAV_FOUNDATION_BINARYUTILS__

BinaryUtils/README.md

@@ -30,12 +30,14 @@ Include the library in your NetLinx project:
 Rotates bits of a 32-bit value to the left by the specified count. Bits that are rotated off the left end appear at the right end.
 
 **Parameters:**
+
 - `value` (long): The value to rotate
 - `count` (long): Number of positions to rotate left
 
 **Returns:** (long) The rotated value
 
 **Example:**
+
 ```netlinx
 stack_var long original
 stack_var long rotated
@@ -54,6 +56,7 @@ rotated = NAVBinaryRotateLeft(original, 4)  // Binary: 00000000 00000000 0000000
 Alias for `NAVBinaryRotateLeft`. Rotates bits of a 32-bit value to the left.
 
 **Parameters:**
+
 - `value` (long): The value to rotate
 - `count` (long): Number of positions to rotate left
 
@@ -68,12 +71,14 @@ Alias for `NAVBinaryRotateLeft`. Rotates bits of a 32-bit value to the left.
 Rotates bits of a 32-bit value to the right by the specified count. Bits that are rotated off the right end appear at the left end.
 
 **Parameters:**
+
 - `value` (long): The value to rotate
 - `count` (long): Number of positions to rotate right
 
 **Returns:** (long) The rotated value
 
 **Example:**
+
 ```netlinx
 stack_var long original
 stack_var long rotated
@@ -92,6 +97,7 @@ rotated = NAVBinaryRotateRight(original, 4)  // Binary: 00000000 00000000 000000
 Alias for `NAVBinaryRotateRight`. Rotates bits of a 32-bit value to the right.
 
 **Parameters:**
+
 - `value` (long): The value to rotate
 - `count` (long): Number of positions to rotate right
 
@@ -108,12 +114,14 @@ Alias for `NAVBinaryRotateRight`. Rotates bits of a 32-bit value to the right.
 Extracts a single bit from a 32-bit value at the specified position.
 
 **Parameters:**
+
 - `value` (long): The value to extract a bit from
 - `bit` (long): The bit position to extract (0-31)
 
 **Returns:** (long) 1 if the specified bit is set, 0 otherwise
 
 **Example:**
+
 ```netlinx
 stack_var long value
 stack_var long bitValue
@@ -128,18 +136,59 @@ bitValue = NAVBinaryGetBit(value, 2)  // Returns 1 (third bit from right)
 
 ---
 
+#### `NAVBinaryCountLeadingZeros(long value)`
+
+Counts the number of leading zero bits in a 32-bit integer. This is useful for determining the position of the most significant bit or calculating the number of bits required to represent a value.
+
+**Parameters:**
+
+- `value` (long): The value to analyze
+
+**Returns:** (integer) Number of leading zeros (0-32)
+
+**Example:**
+
+```netlinx
+stack_var long value
+stack_var integer leadingZeros
+
+value = $0000000F  // Binary: 00000000 00000000 00000000 00001111
+leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 28
+
+value = $80000000  // Binary: 10000000 00000000 00000000 00000000
+leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 0
+
+value = $00000000  // Binary: 00000000 00000000 00000000 00000000
+leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 32
+
+value = $00FF0000  // Binary: 00000000 11111111 00000000 00000000
+leadingZeros = NAVBinaryCountLeadingZeros(value)  // Returns 8
+```
+
+**Use Cases:**
+
+- Determining bit width requirements for variable-length encoding
+- Finding the position of the most significant bit
+- Calculating logarithm base 2 (floor)
+- Implementing priority encoders
+- Optimizing compression algorithms
+
+---
+
 ### Binary Representation Functions
 
 #### `NAVByteToBitArray(char value)`
 
 Converts a byte to an array of individual bit values. Each bit is represented as a numeric value (0 or 1) in the returned array.
 
 **Parameters:**
+
 - `value` (char): The byte value to convert
 
 **Returns:** (char[8]) Array of 8 bit values (0 or 1)
 
 **Example:**
+
 ```netlinx
 stack_var char value
 stack_var char result[8]
@@ -150,6 +199,7 @@ result = NAVByteToBitArray(value)
 ```
 
 **Use Cases:**
+
 - Analyzing individual bits of protocol bytes
 - Implementing custom bit-level protocols
 - Debugging binary data structures
@@ -161,11 +211,13 @@ result = NAVByteToBitArray(value)
 Converts a byte to its binary representation as an 8-character string.
 
 **Parameters:**
+
 - `value` (char): The byte value to convert
 
 **Returns:** (char[8]) Binary representation as an 8-character string
 
 **Example:**
+
 ```netlinx
 stack_var char value
 stack_var char result[8]
@@ -176,6 +228,7 @@ result = NAVByteToBinaryString(value)
 ```
 
 **Use Cases:**
+
 - Debugging and logging binary data
 - Display binary values in user interfaces
 - Protocol analysis and troubleshooting
@@ -191,11 +244,13 @@ BCD (Binary Coded Decimal) is a binary encoding where each decimal digit (0-9) i
 Converts a binary integer to BCD (Binary Coded Decimal) format using the double-dabble algorithm.
 
 **Parameters:**
+
 - `value` (integer): The binary integer to convert (0-9999)
 
 **Returns:** (long) BCD representation of the value
 
 **Example:**
+
 ```netlinx
 stack_var integer decimal
 stack_var long bcd
@@ -208,6 +263,7 @@ bcd = NAVBinaryToBcd(decimal)  // Returns $1234 (BCD format)
 ```
 
 **Use Cases:**
+
 - Sending decimal values to hardware that expects BCD encoding
 - Implementing BCD-based protocols
 - Interfacing with seven-segment displays
@@ -221,11 +277,13 @@ bcd = NAVBinaryToBcd(decimal)  // Returns $1234 (BCD format)
 Converts a BCD (Binary Coded Decimal) byte to its binary integer value. Each nibble (4 bits) of the input represents a decimal digit (0-9).
 
 **Parameters:**
+
 - `value` (char): The BCD-encoded byte to convert (0x00-0x99)
 
 **Returns:** (integer) Binary integer representation (0-99)
 
 **Example:**
+
 ```netlinx
 stack_var char bcdValue
 stack_var integer decimal
@@ -238,6 +296,7 @@ decimal = NAVBcdToBinary(bcdValue)  // Returns 99
 ```
 
 **Use Cases:**
+
 - Reading BCD-encoded data from hardware (RTCs, displays, etc.)
 - Parsing BCD protocol responses
 - Converting BCD values for display or calculation
@@ -305,21 +364,23 @@ NAVErrorLog(NAV_LOG_LEVEL_DEBUG, "'Received byte: ',binaryStr")
 
 If you're updating from an older version of NAVFoundation.BinaryUtils, the following function names have changed:
 
-| Old Function Name | New Function Name | Notes |
-|------------------|-------------------|-------|
-| `NAVCharToDecimalBinaryString()` | `NAVByteToBitArray()` | Returns numeric bit array instead of string |
-| `NAVCharToAsciiBinaryString()` | `NAVByteToBinaryString()` | Returns ASCII string (behavior unchanged) |
-| `NAVDecimalToBinary()` | `NAVBinaryToBcd()` | Corrected naming to reflect BCD conversion |
+| Old Function Name                | New Function Name         | Notes                                       |
+| -------------------------------- | ------------------------- | ------------------------------------------- |
+| `NAVCharToDecimalBinaryString()` | `NAVByteToBitArray()`     | Returns numeric bit array instead of string |
+| `NAVCharToAsciiBinaryString()`   | `NAVByteToBinaryString()` | Returns ASCII string (behavior unchanged)   |
+| `NAVDecimalToBinary()`           | `NAVBinaryToBcd()`        | Corrected naming to reflect BCD conversion  |
 
 **New function:**
+
 - `NAVBcdToBinary()` - Reverse BCD conversion for reading hardware values
 
 **Migration steps:**
+
 1. Search your codebase for the old function names
 2. Replace with the new names according to the table above
 3. For BCD operations, verify you're using the correct direction:
-   - Use `NAVBinaryToBcd()` when sending to hardware
-   - Use `NAVBcdToBinary()` when reading from hardware
+    - Use `NAVBinaryToBcd()` when sending to hardware
+    - Use `NAVBcdToBinary()` when reading from hardware
 
 ## Dependencies
 

__tests__/NAVFoundation-Tests.apw

@@ -761,12 +761,12 @@
                 <Comments></Comments>
             </File>
         </System>
-        <System IsActive="false" Platform="Netlinx" Transport="Serial" TransportEx="TCPIP">
+        <System IsActive="true" Platform="Netlinx" Transport="Serial" TransportEx="TCPIP">
             <Identifier>BinaryUtils</Identifier>
             <SysID>0</SysID>
             <TransTCPIP>0.0.0.0</TransTCPIP>
             <TransSerial>COM1,115200,8,None,1,None</TransSerial>
-            <TransTCPIPEx>192.168.10.37|1319|1|NX-2200|ZGFtaWVu|QXZtYWNoMW5lcyE3MjQ5</TransTCPIPEx>
+            <TransTCPIPEx>192.168.10.38|1319|1|NX-1200|ZGFtaWVu|QXZtYWNoMW5lcyE3MjQ5</TransTCPIPEx>
             <TransSerialEx>COM1|38400|8|None|1|None||</TransSerialEx>
             <TransUSBEx>|||||</TransUSBEx>
             <TransVNMEx>10.0.0.1|1|&lt;Default&gt;</TransVNMEx>
@@ -942,7 +942,7 @@
                 <Comments></Comments>
             </File>
         </System>
-        <System IsActive="true" Platform="Netlinx" Transport="Serial" TransportEx="TCPIP">
+        <System IsActive="false" Platform="Netlinx" Transport="Serial" TransportEx="TCPIP">
             <Identifier>SocketUtils</Identifier>
             <SysID>0</SysID>
             <TransTCPIP>0.0.0.0</TransTCPIP>

__tests__/include/binary-utils/NAVBinaryCountLeadingZeros.axi

@@ -0,0 +1,50 @@
+PROGRAM_NAME='NAVBinaryCountLeadingZeros'
+
+#include 'NAVFoundation.Core.axi'
+#include 'NAVFoundation.Testing.axi'
+
+DEFINE_CONSTANT
+
+// Test data: [value, expected]
+constant long BINARY_COUNT_LEADING_ZEROS_TESTS[][2] = {
+    { $00000000, 32 },      // Test 1: Zero value - all 32 bits are zero
+    { $80000000, 0 },       // Test 2: MSB set - no leading zeros
+    { $40000000, 1 },       // Test 3: Second MSB set - 1 leading zero
+    { $20000000, 2 },       // Test 4: Third MSB set - 2 leading zeros
+    { $FFFFFFFF, 0 },       // Test 5: All bits set - no leading zeros
+    { $00000001, 31 },      // Test 6: Only LSB set - 31 leading zeros
+    { $0000FFFF, 16 },      // Test 7: Lower 16 bits set - 16 leading zeros
+    { $000000FF, 24 },      // Test 8: Lower 8 bits set - 24 leading zeros
+    { $00008000, 16 },      // Test 9: Bit 15 set - 16 leading zeros
+    { $00000080, 24 },      // Test 10: Bit 7 set - 24 leading zeros
+    { $0000000F, 28 },      // Test 11: Lower 4 bits set - 28 leading zeros
+    { $00FF0000, 8 },       // Test 12: Bits 23-16 set - 8 leading zeros
+    { $FF000000, 0 },       // Test 13: Upper byte set - no leading zeros
+    { $AAAAAAAA, 0 },       // Test 14: Alternating bits (MSB set) - no leading zeros
+    { $55555555, 1 },       // Test 15: Alternating bits (MSB clear) - 1 leading zero
+    { $01000000, 7 },       // Test 16: Bit 24 set - 7 leading zeros
+    { $00001000, 19 },      // Test 17: Bit 12 set - 19 leading zeros
+    { $0010000F, 11 },      // Test 18: Bit 20 and lower 4 bits - 11 leading zeros
+    { $00000002, 30 },      // Test 19: Bit 1 set - 30 leading zeros
+    { $10000000, 3 }        // Test 20: Bit 28 set - 3 leading zeros
+}
+
+define_function TestNAVBinaryCountLeadingZeros() {
+    stack_var integer x
+
+    NAVLog("'***************** NAVBinaryCountLeadingZeros *****************'")
+
+    for (x = 1; x <= length_array(BINARY_COUNT_LEADING_ZEROS_TESTS); x++) {
+        stack_var integer result
+
+        result = NAVBinaryCountLeadingZeros(type_cast(BINARY_COUNT_LEADING_ZEROS_TESTS[x][1]))
+
+        if (!NAVAssertIntegerEqual('Should count leading zeros correctly', BINARY_COUNT_LEADING_ZEROS_TESTS[x][2], result)) {
+            NAVLogTestFailed(x, itoa(BINARY_COUNT_LEADING_ZEROS_TESTS[x][2]), itoa(result))
+            continue
+        }
+
+        NAVLogTestPassed(x)
+    }
+}
+

__tests__/include/binary-utils/binary-utils.axi

@@ -7,7 +7,7 @@
 #DEFINE TESTING_NAVBYTETOBINARYSTRING
 #DEFINE TESTING_NAVBCDTOBINARY
 #DEFINE TESTING_NAVBINARYTOBCD
-
+#DEFINE TESTING_NAVBINARYCOUNTLEADINGZEROS
 #include 'NAVFoundation.Core.axi'
 #include 'NAVFoundation.BinaryUtils.axi'
 #include 'NAVFoundation.Assert.axi'
@@ -50,6 +50,10 @@
 #include 'NAVBinaryToBcd.axi'
 #END_IF
 
+#IF_DEFINED TESTING_NAVBINARYCOUNTLEADINGZEROS
+#include 'NAVBinaryCountLeadingZeros.axi'
+#END_IF
+
 define_function RunBinaryUtilsTests() {
     #IF_DEFINED TESTING_NAVBINARYROTATELEFT
     TestNAVBinaryRotateLeft()
@@ -86,4 +90,8 @@ define_function RunBinaryUtilsTests() {
     #IF_DEFINED TESTING_NAVBINARYTOBCD
     TestNAVBinaryToBcd()
     #END_IF
+
+    #IF_DEFINED TESTING_NAVBINARYCOUNTLEADINGZEROS
+    TestNAVBinaryCountLeadingZeros()
+    #END_IF
 }