Utils class

The Utils class contains various useful utility functions. More...

The T/HIS JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

_example
$example
ABC_example

Class functions

Ascii85Decode(encoded[string])
Ascii85Encode(data[ArrayBuffer], length (optional)[integer])
Build()
CallPromiseHandlers()
CheckinLicense(feature[string])
CheckoutLicense(feature[string])
GarbageCollect()
HTMLBrowser()
HiResTimer()
PdfReader()
SHA256(filename[string])
SHA512(filename[string])
TimerResolution()
UUID()
Version()

Detailed Description

The Utils class is used to provide various useful functions.

Details of functions

Ascii85Decode(encoded[string]) [static]

Description

Decodes an ASCII85 encoded string. See Utils.Ascii85Encode() for details on the method.

Arguments

encoded (string)

An ASCII85 encoded string

Returns

ArrayBuffer object

Return type

ArrayBuffer

Example

To decode an ASCII85 encoded string:

var decoded = Utils.Ascii85Decode(encoded);

Ascii85Encode(data[ArrayBuffer], length (optional)[integer]) [static]

Description

Encodes an ASCII85 encoded string. This enables binary data to be represented by ASCII characters using five ASCII characters to represent four bytes of binary data (making the encoded size 1/4 larger than the original). By doing this binary data can be stored in JavaScript strings. Note that the method used by THIS to encode and decode strings differs from the standard ASCII85 encoding as that uses the ASCII characters ", ' and \ which cannot be used in JavaScript strings as they have special meanings. The method in THIS uses
0-84 are !-u (ASCII codes 33-117) (i.e. 33 is added to it) with the following exceptions
v is used instead of " (ASCII code 118 instead of 34)
w is used instead of ' (ASCII code 119 instead of 39)
x is used instead of \ (ASCII code 120 instead of 92)
If all five digits are 0 they are represented by a single character z instead of !!!!!

Arguments

data (ArrayBuffer)

ArrayBuffer containing the data

length (optional) (integer)

Length of data in array buffer to encode. If omitted the whole array buffer will be encoded

Returns

string

Return type

String

Example

To encode ArrayBuffer data:

var encoded = Utils.Ascii85Encode(data);

Build() [static]

Description

Returns the build number

Arguments

No arguments

Returns

integer

Return type

Number

Example

To get the current build number

var build = Utils.Build();

CallPromiseHandlers() [static]

Description

Manually call any promise handlers/callbacks in the job queue

Arguments

No arguments

Returns

no return value

Example

To run any queued promise handlers/callbacks:

Utils.CallPromiseHandlers();

CheckinLicense(feature[string]) [static]

Description

Checks a license for a feature back in

Arguments

feature (string)

feature to check license back in for

Returns

no return value

Example

To check in a license for "EXAMPLE":

Utils.CheckinLicense("EXAMPLE");

CheckoutLicense(feature[string]) [static]

Description

Checks out a license for a feature

Arguments

feature (string)

feature to check license for

Returns

true if license available, false if not

Return type

Boolean

Example

To checkout a license for "EXAMPLE":

var got = Utils.CheckoutLicense("EXAMPLE");
if (got == false) Exit();

GarbageCollect() [static]

Description

Forces garbage collection to be done. This should not normally need to be called but in exceptional circumstances it can be called to ensure that garbage collection is done to return memory.

Arguments

No arguments

Returns

no return value

Example

To force garbage collection to be done:

Utils.GarbageCollect();

HTMLBrowser() [static]

Description

Returns the path to the default HTML browser

Arguments

No arguments

Returns

string of the path

Return type

String

Example

To get path to the default HTML browser

var path = Utils.HTMLBrowser();

HiResTimer() [static]

Description

A high resolution timer that can be used to time how long things take. The first time this is called the timer will start and return 0. Subsequent calls will return the time in nanoseconds since the first call. Note that the timer will almost certainly not have 1 nanosecond precision but, depending on the platform, should should have a resolution of at least 1 microsecond. The resolution can be found by using Utils.TimerResolution()

Arguments

No arguments

Returns

number

Return type

number

Example

To time how long something takes to nanosecond precision:

var start = Utils.HiResTimer();
do something that takes some time...
var end = Utils.HiResTimer();
Message("it took " + (end-start) + "nanoseconds");

PdfReader() [static]

Description

Returns the path to the executable of the default pdf reader

Arguments

No arguments

Returns

string of the path

Return type

String

Example

To get path to the default pdf reader

var path = Utils.PdfReader();

SHA256(filename[string]) [static]

Description

Create a SHA-256 hash for a file

Arguments

filename (string)

File to calculate the hash for

Returns

string

Return type

String

Example

To generate the hash for file "example.txt":

var sha256 = Utils.SHA256("example.txt");

SHA512(filename[string]) [static]

Description

Create a SHA-512 hash for a file

Arguments

filename (string)

File to calculate the hash for

Returns

string

Return type

String

Example

To generate the hash for file "example.txt":

var sha512 = Utils.SHA512("example.txt");

TimerResolution() [static]

Description

Returns the resolution (precision) of the Utils.HiResTimer() timer in nanoseconds

Arguments

No arguments

Returns

number

Return type

number

Example

To find the resolution of the timer in nanoseconds:

var resolution = Utils.TimerResolution();

UUID() [static]

Description

Create an UUID (Universally Unique Identifier)

Arguments

No arguments

Returns

string

Return type

String

Example

To generate an UUID:

var uuid = Utils.UUID();

Version() [static]

Description

Returns the version number

Arguments

No arguments

Returns

real

Return type

Number

Example

To get the current version number

var version = Utils.Version();