# Utility Functions Akenza provides utility functions which contain commonly used functionality for e.g. converting hex strings into a bit string and vice-versa. These functions are useful in device types if the uplink payload is hex or base64 encoded or even a bit string representation. ## Bit Utility Functions Bit utility functions provide already implemented logic to convert and manipulate bit represenations to numbers or hexadecimal strings and vice-versa. ### Hex to Bits **Usage** `Bits.hexToBits(hex: string): string` **Examples** `Bits.hexToBits('DEADBEEF')` -> `'11011110101011011011111011101111'` `Bits.hexToBits('0xaa')` -> `'10101010'` **Details** This function converts a hex string to a bit string in big endian format. The hex string can be prefixed with `0x` but it is not required. Throws an error if the hex string does not contain valid hexadecimal characters (`0-9a-fA-F`). ### Bits to Hex **Usage** `Bits.bitsToHex(bits: string): string` **Examples** `Bits.bitsToHex('11011110101011011011111011101111')` -> `'DEADBEEF'` `Bits.bitsToHex('10101010')` -> `'AA'` **Details** This function converts a bit string into a hex string. The resulting hex string does not contain the prefix `0x`. The bit representation has to be in big endian format. Otherwise the results will differ. Throws an error if the bit string is invalid (it may only consist of 1s and 0s). ### Base64 to Bits **Usage** `Bits.base64ToBits(base64: string): string` **Examples** `Bits.base64ToBits('Zm9vIA==')` -> `'01100110011011110110111100100000'` `Bits.base64ToBits('YmFy')` -> `'011000100110000101110010'` **Details** This function converts a base64 encoded string into a bit string. Throws an error if the provided bas64 string is invalid. [More info about valid base64 characters](https://base64.guru/learn/base64-characters). ### Bits to Base64 **Usage** `Bits.bitsToBase64(bits: string): string` **Examples** `Bits.bitsToBase64('01100110011011110110111100100000')` -> `'Zm9vIA=='` `Bits.bitsToBase64('011000100110000101110010')` -> `'YmFy'` **Details** This function converts a bit string into a base64 encoded string. Throws an error if the provided bit string could not successfully be converted to base 64 e.g. the resulting string will contain invalid base64 characters. [More info about valid base64 characters](https://base64.guru/learn/base64-characters). ### Bits to Signed Integer **Usage** `Bits.bitsToSigned(bits: string): number` **Examples:** `Bits.bitsToSigned('1001')` -> `-7` `Bits.bitsToSigned('0110')` -> `6` **Details** This function converts a bit string representation of an unsigned integer into an integer. The bit string representation has to be in big endian format. Otherwise the results will differ. Throws an error if the bit string is invalid (it may only consist of 1s and 0s). ### Bits to Unsigned Integer **Usage** `Bits.bitsToUnsigned(bits: string): number` **Examples:** `Bits.bitsToUnsigned('1001')` -> `9` `Bits.bitsToUnsigned('0110')` -> `6` **Details** This function converts a bit string representation of a signed integer into an integer. The bit string representation has to be in big endian format. Otherwise the results will differ. Throws an error if the bit string is invalid (it may only consist of 1s and 0s). ### Number to Bits **Usage** `Bits.numberToBits(value: number, cutOff?: number): string` The function can be invoked with one or two arguments. The second argument is optional and can either be null or left out completely. If the resulting bit string representation would be smaller than the specified cut off amount, the full bit string representation will be returned, without padding `0`s to make up the difference. **Examples:** `Bits.numberToBits(123)` -> '`1111011'` `Bits.numberToBits(123, 4)` -> '`1011'` `Bits.numberToBits(123, 16)` -> '`1111011'` **Details** This function converts a number into an unsigned bit-string representation. If the `cutOff` argument is specified, the resulting string is cut off after the specified amount of bits starting at the LSB. As the resulting bit string is a big endian representation of the number, the cut off point starts from the right hand end of the string up until the specified cut off amount. Throws an error if an invalid number was provided either for the first or second argument (if present). ## Hex Utility Functions Hex utility functions provide already implemented logic to convert and manipulate hex representations to numbers or byte arrays and vice-versa. ### Hex to Bytes **Usage** `Hex.hexToBytes(hex: string): number[]` **Examples** `Hex.hexToBytes('DEADBEEF')` -> `[222, 173, 190, 239]` `Hex.hexToBytes('0xf00ba8')` -> `[240, 11, 168]` **Details** This function converts a hex string into a JS byte array. JS bytes are unsigned integers ranging from `0 - 255`. The hex string can be prefixed with `0x` but it is not required. Throws an error if the hex string does not contain valid hexadecimal characters (`0-9a-fA-F`). ### Bytes to Hex **Usage** `Hex.bytesToHex(bytes: number[]): string` **Examples** `Hex.bytesToHex([222, 173, 190, 239])` -> `'DEADBEEF'` `Hex.bytesToHex([240, 11, 168])` -> `'F00BA8'` **Details** This function converst an array of JS bytes (numbers from `0 - 255`) to a hex string. Throws an error if the bytes array contains values below 0 or above 255. ### Hex Little Endian to Big Endian Number **Usage** `Hex.hexLittleEndianToBigEndian(hex: string, signed: boolean): number` **Examples:** `Hex.hexLittleEndianToBigEndian('AA', false)` -> `170` `Hex.hexLittleEndianToBigEndian('0xaa', true)` -> `-86` **Details** This function converts the hex string in little endian forma to a big endian number. The `signed` param is used to indicate whether the hex representation is a signed or unsigned little endian. The hex string can be prefixed with `0x` but it is not required. Throws an error if the hex string does not contain valid hexadecimal characters (`0-9a-fA-F`). Throws an error if the `signed` argument is not a valid boolean.