@iotile/iotile-common/dist/types/utilities.d.ts

Common utilities for IoTile Packages and Applications

/**
 * @ngdoc object
 * @name Utilities
 *
 * @description
 * The utilities namespace contains common routines that are used in other modules
 * including delays and generic parsing functions.
 */
/**
 * @ngdoc object
 * @name Utilities.function:endsWith
 * @description
 * Check if a string ends with another string
 *
 *
 * @param {string} str The input string
 * @param {string} suffix The suffix to check
 * @returns {bool} Whether the string ends with the suffix
 */
export declare function endsWith(str: string, suffix: string): boolean;
/**
 * @ngdoc object
 * @name Utilities.function:startsWith
 * @description
 * Check if a string ends with another string
 *
 *
 * @param {string} str The input string
 * @param {string} prefix The prefix to check
 * @returns {bool} Whether the string ends with the suffix
 */
export declare function startsWith(str: string, prefix: string): boolean;
export declare function joinPath(path1: string, path2: string): string;
export declare function guid(): string;
/**
 * @ngdoc object
 * @name Utilities.function:delay
 * @description
 * Delay for a fixed number of milliseconds
 *
 * This function wraps setTimeout in a promise API that can be
 * used with async/await.
 *
 * @param {number} delayMS - The number of milliseconds to wait
 * @returns {Promise} A promise that is fullfilled after delayMS milliseconds
 */
export declare function delay(delayMS: number): Promise<void>;
/**
 * @ngdoc object
 * @name Utilities.function:deviceIDToSlug
 * @description
 * Convert a numeric deviceID to an IOTile cloud device slug
 *
 * This function converts a device id like 0x20 to a string slug of
 * the form:
 * d--XXXX-XXXX-XXXX-XXXX
 *
 * The slug always has the hex string in lowercase.
 *
 * @param {number} deviceID - The device ID to convert into a slug
 * @returns {string} The corresponding device slug
 */
export declare function deviceIDToSlug(deviceID: number): string;
/**
 * @ngdoc object
 * @name Utilities.function:createStreamerSlug
 * @description
 * Convert a numeric deviceID and streamer index to an IOTile cloud streamer slug
 *
 * This function converts a device id like 0x20 and streamer 0 to a string slug of
 * the form:
 * t--XXXX-XXXX-XXXX-XXXX--YYYY
 *
 * The slug always has the hex string in lowercase.  The device id is converted
 * into the XXXX portion and the streamer is converted to the YYYY portion.
 *
 * @param {number} deviceID - The device ID to convert into a slug
 * @param {number} streamer - The streamer index to convert into a slug
 * @returns {string} The corresponding streamer slug
 */
export declare function createStreamerSlug(deviceID: number, streamer: number): string;
/**
 * @ngdoc object
 * @name Utilities.function:numberToHexString
 * @description
 * Convert a number to lowercase hex string
 *
 * This function takes a number like 0x16 and returns
 * the string '16'.  It would also take 0xAF and return
 * 'af'.  It will pad the number out to a fixed length
 * using the second length parameter.
 *
 * The slug always has the hex string in lowercase.
 *
 * @param {number} inputNumber - The number to convert to a hex string
 * @param {number} length - The number of hex digits to pad out to.
 * @returns {string} The correspond lowercase hex string
 */
export declare function numberToHexString(inputNumber: number, length: number): string;
/**
 * @ngdoc object
 * @name Utilities.function:mapStreamName
 * @description
 * Convert a string description of an IOTile variable into a number
 *
 * This function converts string like 'output 1' into 16 bit integers
 * like 0x5001.
 *
 * @param {string} streamName - The string name of the variable that you want to convert
 * @returns {number} The numerical stream identifier
 */
export declare function mapStreamName(streamName: string): number;
/**
 * @ngdoc object
 * @name Utilities.function:convertVariableLengthFormatCode
 * @description
 * Convert the variable length byte array format code ('V') into a fixed length
 * format code ('#s') based on the size of the provided buffer and whether or not this
 * is for packing (buffer is the last argument to pack) or unpacking (buffer is the entire
 * response).
 *
 * ## See Also
 * {@link Utilities.function:packArrayBuffer Utilities.packArrayBuffer}
 *
 * {@link Utilities.function:unpackArrayBuffer Utilities.unpackArrayBuffer}
 *
 * @param {string} fmt - The format code to convert
 * @param {ArrayBuffer} buffer - Either the variable length arg to pack or the response buffer
 * @param {boolean} pack - Whether this is for packing (true) or unpacking (false)
 *
 * @returns {string} - The converted format code
 */
export declare function convertVariableLengthFormatCode(fmt: string, buffer: ArrayBuffer, pack: boolean): string;
/**
 * @ngdoc object
 * @name Utilities.function:toUint32
 * @description
 * Takes a number and returns the value as a Uint32
 * See: http://2ality.com/2012/02/js-integers.html
 * See also: https://stackoverflow.com/questions/22335853/hack-to-convert-javascript-number-to-uint32
 *
 * @param {number} num - The number to convert
 *
 * @returns {Uint32}
 */
export declare function toUint32(num: number): number;
/**
 * @ngdoc object
 * @name Utilities.function:stringToBuffer
 * @description
 * Takes a string and returns an ArrayBuffer containing each character's
 * char code value.
 *
 * @param {string} str - The string to convert
 *
 * @returns {ArrayBuffer}
 */
export declare function stringToBuffer(str: string): ArrayBuffer;
/**
 * @ngdoc object
 * @name Utilities.function:parseBufferFormatCode
 * @description
 * Parse a string format code describing the packing of a binary buffer
 * into an array of entries where each entry has a type code and a count
 * prefix. For example,
 *
 * "18sH" would turn into [{count: 18, code: 's'}, {count: 8, code: 'H'}]
 *
 * ## See Also
 * {@link Utilities.function:packArrayBuffer Utilities.packArrayBuffer}
 *
 * {@link Utilities.function:unpackArrayBuffer Utilities.unpackArrayBuffer}
 *
 * @param {string} fmt - The format we are trying to determine the size of
 * @returns {[FormatCode]} A list of the parsed format codes that were extracted
 *     from the input format string.
 */
export declare function parseBufferFormatCode(fmt: string): {
    count: number;
    code: string;
    size: number;
    argumentsConsumed: number;
}[];
/**
 * @ngdoc object
 * @name Utilities.function:padString
 * @description
 * Pad a string by appended a given character until it reaches a fixed length
 *
 * @param {string} input The string we are trying to pad.
 * @param {string} pad The padding character to add.
 * @param {number} length The length of the final string you want.
 * @returns {string} The correctgly padded string.
 */
export declare function padString(input: string, pad: string, length: number): string;
/**
 * @ngdoc object
 * @name Utilities.function:padArrayBuffer
 * @description
 * Pad a string by appending null bytes to meet a fixed length
 *
 * @param {ArrayBuffer} input The buffer we are trying to pad.
 * @param {number} length The length of the final buffer you want.
 * @returns {ArrayBuffer} The correctly padded ArrayBuffer.
 */
export declare function padArrayBuffer(input: ArrayBuffer, length: number): ArrayBuffer;
/**
 * @ngdoc object
 * @name Utilities.function:appendArrayBuffer
 * @description
 * Append one ArrayBuffer to the end of another.
 *
 * @param {ArrayBuffer} buffer1 The first ArrayBuffer.
 * @param {ArrayBuffer} buffer2 The second ArrayBuffer.
 * @returns {ArrayBuffer} The resulting combined ArrayBuffer.
 */
export declare function appendArrayBuffer(buffer1: ArrayBuffer, buffer2: ArrayBuffer): ArrayBuffer;
/**
 * @ngdoc object
 * @name Utilities.function:expectedBufferSize
 * @description
 * Determine how large a buffer is given its binary format string
 *
 * This function takes a string describing how fixed width integers are packed
 * into a binary ArrayBuffer and calculates how large the buffer would need to
 * be to contain that many integers of those sizes.  It also support packing
 * fixed length strings that must be prefixed with a number like 18s for an
 * exactly 18 character string.
 *
 * Alignment is not taken into account, so if you are trying to match the alignment
 * of a structure on, e.g. a 32 bit platform, you will need to insert alignment gaps as needed.
 *
 * ## See Also
 * {@link Utilities.function:packArrayBuffer Utilities.packArrayBuffer}
 *
 * {@link Utilities.function:unpackArrayBuffer Utilities.unpackArrayBuffer}
 *
 * @param {string} fmt - The format we are trying to determine the size of
 * @returns {number} The number of bytes required to store fmt
 */
export declare function expectedBufferSize(fmt: string): number;
export declare function expectedArraySize(fmt: string): number;
/**
 * @ngdoc object
 * @name Utilities.function:packArrayBuffer
 * @description
 * Pack a series of arguments into an ArrayBuffer using a format string
 *
 * This function is a javascript equivalent of the python struct.pack function.
 * It takes a format string consisting of the letters l, L, B and H and a variable
 * list of numeric arguments.  There must be exactly as many arguments as letters
 * in the format string.  The format string is used to convert each argument into
 * a little endian binary representation of the number which is serialized into
 * an ArrayBuffer.  The resulting ArrayBuffer is returned.
 *
 * The meaning of each format code is:
 * - B: An 8 bit wide unsigned integer
 * - H: A 16 bit wide unsigned integer
 * - L: A 32 bit wide unsigned integer
 * - l: A 32 bit wide signed integer
 * - #s: A fixed length string with length given by the number preceding s, e.g. 5s for a 5
 *   character string.  If the string argument is shorter than what is specified, it is padded
 *   with null characters.
 *   UPDATE: As of v0.2 '#s' may also represent an ArrayBuffer with a bytelength given by the
 *   number preceding 's'. If the bytelength of the ArrayBuffer argument is shorter than what
 *   is specified, the ArrayBuffer will NOT be padded and an error will be thrown.
 * - V: A variable length byte array. This must come as the last format code
 *
 * ## Exceptions
 * - **{@link type:ArgumentError} If there is an unknown format string code or the string
 *   does not match the number or type of arguments received.
 *
 * @param {string} fmt The format string specifying the size of each argument
 * @param {number[]} arguments A variable list of numberic arguments that are packed to
 * 							   create the resulting ArrayBuffer according to fmt.
 * @returns {ArrayBuffer} The packed resulting binary array buffer
 */
export declare function packArrayBuffer(fmt: string, ...args: any[]): ArrayBuffer;
/**
 * @ngdoc object
 * @name Utilities.function:unpackArrayBuffer
 * @description
 * Unpack an ArrayBuffer into a list of numeric values using a format string
 *
 * This function is a javascript equivalent of the python struct.unpack function.
 * It takes a format string consisting of the letters l, L, B and H and a single ArrayBuffer.
 * The format string is used to decode the ArrayBuffer into a list of numbers assuming
 * that those numbers are encoded into fixed width integers in little endian format in
 * the ArrayBuffer.
 *
 * The meaning of each format code is:
 * - B: An 8 bit wide unsigned integer
 * - H: A 16 bit wide unsigned integer
 * - L: A 32 bit wide unsigned integer
 * - l: A 32 bit wide signed integer
 * - [#]x: one or more padding bytes
 * - #s: A fixed length string.  # should be a decimal number, e.g. 5s or 18s
 * - V: A variable length byte array. This must come as the last format code.
 *   NOTE: Data upacked from a 'V' code will be returned as a string.
 *
 * ## Exceptions
 * - **{@link type:ArgumentError} If there is an unknown format string code or the string
 *   does not match the data contained inside the ArrayBuffer.
 *
 * @param {string} fmt The format string specifying the size of each argument
 * @param {ArrayBuffer} buffer The packed ArrayBuffer that should be decoded using fmt
 * @returns {number[]} A list of numbers decoded from the buffer using fmt
 */
export declare function unpackArrayBuffer(fmt: string, buffer: ArrayBuffer | SharedArrayBuffer): any[];
/**
 * @ngdoc object
 * @name Utilities.function:copyArrayBuffer
 * @description
 * Copy an ArrayBuffer into another one like memcpy
 *
 * This function is a javascript translation of memcpy. It takes a source and destination
 * ArrayBuffer, an offset into both and a length of bytes to copy.  In slicing syntax,
 * this function does the following:
 *
 * dest[destOffset:destOffset+length] = src[srcOffset:srcOffset+length]
 *
 * * ## Exceptions
 * - **{@link type:InsufficientSpaceError InsufficentSpaceError}:** If there is not space in the destination buffer
 *   to hold the copied data. This function will not expand the size of the destination buffer, so it must already be allocated
 *   with enough space for the copied data.
 *
 * @param {ArrayBuffer} dest The destination buffer that we should copy into.  There must be enough
 *   space in dest to hold what you are copying.  This function will not allocate
 *   more space for you.
 * @param {ArrayBuffer} src  The source buffer to copy from
 * @param {number} srcOffset The offset in src to start copying from, 0 would mean copy from the beginning
 * @param {number} destOffset The offset in dest to start copying into, 0 would mean to copy to the beginning
 *   of dest.
 * @param {number} length The number of bytes to copy from src into dest.
 * @throws {InsufficientSpaceError} If there is not space in the destination buffer to hold the copied data.
 */
export declare function copyArrayBuffer(dest: ArrayBuffer, src: ArrayBuffer | SharedArrayBuffer, srcOffset: number, destOffset: number, length: number): void;
/**
 * @ngdoc object
 * @name Utilities.object:base64ToArrayBuffer
 * @description
 * Decode a Base 64 encoded string into an ArrayBuffer
 *
 * @param {string} encodedString The base 64 encoded string
 * @returns {ArrayBuffer} The decoded ArrayBuffer
 */
export declare function base64ToArrayBuffer(encodedString: string): ArrayBuffer;
/**
 * @ngdoc object
 * @name Utilities.object:arrayBufferToBase64
 * @description
 * Encode an ArrayBuffer to a Base 64 encoded string
 *
 * @param {ArrayBuffer} buffer The ArrayBuffer
 * @returns {ArrayBuffer} The Base 64 encoded string
 */
export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;