Skip to main content

Utilities

Latest Version: 2.0.0

This library provides a set of handy and compact functions for Squirrel programmers. It is not implemented as a class, but all of the functions are namespaced to utilities (via a table) to avoid clashes with your code’s existing functions.

You can view the library’s source code on GitHub. Click here to see information on other versions of this library.

To include this library in your project, add #require "utilities.lib.nut:2.0.0" to the top of your agent or device code.

Library Functions

utilities.hexStringToInteger(hexString)

This function evaluates the supplied hexadecimal string (eg. 0xFFA0) and returns the corresponding integer value.

Example

#require "Utilities.lib.nut:2.0.0"

server.log(utilities.hexStringToInteger("0xFFFE"));
// Displays '65534'

utilities.integerToHexString(integerValue)

This function converts the supplied integer to a hexadecimal string.

Example

server.log(utilities.integerToHexString(78692));
// Displays '0x13364'

utilities.rnd(max)

This function returns a random integer between 0 and max.

Example

// Roll for a strike on d100
local strikeSuccess = utilities.rnd(100);

utilities.frnd(max)

This function returns a random float between 0.0 and max.

Example

server.log(utilities.frnd(100));

utilities.numberFormatter(number, decimals, separator)

This function formats the supplied number to the number of decimal places specified by decimals.

Numbers greater than 999 are separated with the symbol string passed into separator, which defaults to ,. Pass in an empty string ("") if you don’t want a separator to be used.

Example

server.log(utilities.numberFormatter("2000.099999", 2, ","));
// Displays '2,000.10'

utilities.dayOfWeek(dayOfMonth, month, year)

This function returns the day of the week of the date passed into the dayOfMonth, month and year integer parameters. The month parameter should be in the range 0 (January) to 11 (December) as per Squirrel’s date() function. The year should be specified in four-digit form.

The returned integers lies in the range 0 to 6, where 0 is Sunday and 6 is Saturday.

Example

local days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
server.log("3 April 2011 was a " + days[utilities.dayOfWeek(3, 3, 2011)]);

utilities.isLeapYear(year)

The function returns true if the supplied year is a leap year, otherwise false. The year should be specified in four-digit form.

utilities.bstCheck()

This function returns true if the current date is within the British Summer Time (BST) period (last Sunday of March to last Sunday of October), otherwise false (GMT).

Example

if (utilities.bstCheck()) {
    server.log("The UK is observing British Summer Time");
} else {
    server.log("The UK is observing Greenwich Mean Time");
}

utilities.dstCheck()

This function returns true if the current date is within the North American Daylight Saving Time (DST) period (second Sunday in March to first Sunday in November).

Example

if (utilities.dstCheck() && !utilities.bstCheck()) {
    server.log("The Los Altos folks will be an hour earlier");
}

utilities.getNewUUID(callback)

This function generates a new UUID code.

Example

server.log(utilities.getNewUUID();
// Logs, for example, 52473CFA-ACB1-4978-831F-1B1A74A2E265

utilities.debugI2C(impI2Cbus)

This function logs all the devices (by 8-bit and 7-bit address) on the specified imp I²C bus. This function is only available to devices, not agents.

Example

utilities.debugI2C(hardware.i2c89);
// Displays 'Device at 8-bit address: 0xE0 (7-bit address: 0x70)'

utilities.impType(returnString)

This function returns the type of imp on which your code is running. The returnString parameter is a Boolean: pass in true to receive the imp type as a printable string, eg. "imp004m". If returnString is false (the default), the function returns an integer, eg. 1 for the imp001, 4 for the imp004m. This function is only available to devices, not agents.

Improvements, Bug Fixes and Suggestions

Please submit pull requests to the Develop branch.

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release
2.0.0 GitHub Fix UUID generation issues; change library's #require name to utilities.lib.nut

License

The Utilities class is licensed under the MIT License.