# JSDoc: Module: util

# Module: util

### Classes

Clock
Color
CountdownTimer
EventEmitter
MixinBuilder
MonotonicClock
PsychObject
Scheduler

### Mixins

ColorMixin

### Methods

#### (static) addInfoFromUrl(info)

Add info extracted from the URL to the given dictionary.

We exclude all URL parameters starting with a double underscore since those are reserved for client/server communication

##### Parameters:

Name | Type | Description
--- | --- | ---
`info` | Object | the dictionary

Source:
  - util/Util.js, line 765

#### (static) average(input) → {number}

Calculate the average of the elements in the input array. If 'input' is not an array, or if it is an empty array, then we return 0.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]

Source:
  - util/Util.js, line 1087

##### Returns:

the average of the elements in the array

Type
  number

#### (static) count(input, value)

Count the number of elements in the input array that match the given value.

Note: count is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

Source:
  - util/Util.js, line 1311

##### Returns:

the number of matching elements

#### (static) detectBrowser() → {string}

Detect the user's browser.

Note: since user agent is easily spoofed, we use a more sophisticated approach, as described here: https://stackoverflow.com/a/9851769

Source:
  - util/Util.js, line 135

##### Returns:

the detected browser, one of 'Opera', 'Firefox', 'Safari', 'IE', 'Edge', 'EdgeChromium', 'Chrome', 'unknown'

Type
  string

#### (static) extensionFromMimeType(mimeType) → {string}

Return the file extension corresponding to an audio mime type. If the provided mimeType is not a string (e.g. null, undefined, an array) or unknown, then '.dat' is returned, instead of throwing an exception.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mimeType` | string | the MIME type, e.g. 'audio/webm;codecs=opus'

Source:
  - util/Util.js, line 1419

##### Returns:

the corresponding file extension, e.g. '.webm'

Type
  string

#### (static) flattenArray(array) → {Array.<Object>}

Recursively flatten an array of arrays.

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array of arrays

Source:
  - util/Util.js, line 862

##### Returns:

the flatten array

Type
  Array.<Object>

#### (static) getDownloadSpeed(psychoJS, nbDownloadsopt) → {number}

Get an estimate of the download speed, by repeatedly downloading an image file from a distant server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`psychoJS` | PsychoJS |  |  | the instance of PsychoJS
`nbDownloads` | number | <optional> | 1 | the number of image downloads over which to average the download speed

Source:
  - util/Util.js, line 1460

##### Returns:

the download speed, in megabits per second

Type
  number

#### (static) getErrorStack() → {string}

Get the error stack of the calling, exception-throwing function.

Source:
  - util/Util.js, line 80

##### Returns:

the error stack as a string

Type
  string

#### (static) getPositionFromObject(object, units) → {Array.<number>}

Get the position of the object, in pixel units

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object
`units` | string | the units

Source:
  - util/Util.js, line 381

##### Returns:

the position of the object, in pixel units

Type
  Array.<number>

#### (static) getRequestError(jqXHR, textStatus, errorThrown)

Get the most informative error from the server response from a jquery server request.

##### Parameters:

Name | Type | Description
--- | --- | ---
`jqXHR` |  |
`textStatus` |  |
`errorThrown` |  |

Source:
  - util/Util.js, line 688

#### (static) getUrlParameters() → {URLSearchParams}

Get the URL parameters.

Source:
  - util/Util.js, line 739

##### Returns:

the iterable URLSearchParams

Type
  URLSearchParams

##### Example

    const urlParameters = util.getUrlParameters();
    for (const [key, value] of urlParameters)
      console.log(key + ' = ' + value);

#### (static) index(input, value)

Get the index in the input array of the first element that matches the given value.

Note: index is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

Source:
  - util/Util.js, line 1376

##### Throws:

if the input array does not contain any matching element

##### Returns:

the index of the first element that matches the value

#### (static) isEmpty(x) → {boolean}

Test if x is an 'empty' value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`x` | Object | the value to test

Source:
  - util/Util.js, line 104

##### Returns:

true if x is one of the following: undefined, [], [undefined]

Type
  boolean

#### (static) isInt(obj) → {boolean}

Test whether an object is either an integer or the string representation of an integer.

This is adapted from: https://stackoverflow.com/a/14794066

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

Source:
  - util/Util.js, line 718

##### Returns:

whether or not the object is an integer or the string representation of an integer

Type
  boolean

#### (static) isNumeric(input) → {boolean}

Check whether a value looks like a number

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | * | Some value

Source:
  - util/Util.js, line 291

##### Returns:

Whether or not the value can be converted into a number

Type
  boolean

#### (static) IsPointInsidePolygon(point, vertices) → {boolean}

Check whether a point lies within a polygon

We are using the algorithm described here: https://wrf.ecse.rpi.edu//Research/Short_Notes/pnpoly.html

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Array.<number> | the point
`vertices` | Object | the vertices defining the polygon

Source:
  - util/Util.js, line 305

##### Returns:

whether or not the point lies within the polygon

Type
  boolean

#### (static) makeUuid() → {string}

Get a Universally Unique Identifier (RFC4122 version 4)

See details here: https://www.ietf.org/rfc/rfc4122.txt

Source:
  - util/Util.js, line 62

##### Returns:

the uuid

Type
  string

#### (static) offerDataForDownload(filename, data, type)

Offer data as download in the browser.

##### Parameters:

Name | Type | Description
--- | --- | ---
`filename` | string | the name of the file to be downloaded
`data` | * | the data
`type` | string | the MIME type of the data, e.g. 'text/csv' or 'application/json'

Source:
  - util/Util.js, line 929

#### (static) promiseToTupple(promise) → {Array.<Object>}

Convert the resulting value of a promise into a tupple.

##### Parameters:

Name | Type | Description
--- | --- | ---
`promise` | Promise | the promise

Source:
  - util/Util.js, line 45

##### Returns:

the resulting value in the format [error, return data] where error is null if there was no error

Type
  Array.<Object>

#### (static) randchoice(array, randomNumberGeneratoropt) → {Array.<Object>}

Pick a random value from an array, uses `util.shuffle` to shuffle the array and returns the last value.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

Source:
  - util/Util.js, line 361

##### Returns:

a chosen value from the array

Type
  Array.<Object>

#### (static) randint(minopt, max) → {number}

Generates random integers a-la NumPy's in the "half-open" interval [min, max). In other words, from min inclusive to max exclusive. When max is undefined, as is the case by default, results are chosen from [0, min). An error is thrown if max is less than min.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`min` | number | <optional> | 0 | lowest integer to be drawn, or highest plus one if max is undefined (default)
`max` | number |  |  | one above the largest integer to be drawn

Source:
  - util/Util.js, line 1006

##### Returns:

a random integer in the requested range (signed)

Type
  number

#### (static) range(startopt, stop, stepopt) → {Array.<Number>}

Create a sequence of integers. The sequence is such that the integer at index i is: start + step * i, with i >= 0 and start + step * i < stop

Note: this is a JavaScript implement of the Python range function, which explains the unusual management of arguments.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`start` | Number | <optional> | 0 | the value of start
`stop` | Number |  |  | the value of stop
`step` | Number | <optional> | 1 | the value of step

Source:
  - util/Util.js, line 1159

##### Returns:

the range as an array of numbers

Type
  Array.<Number>

#### (static) round(input, places) → {number}

Round to a certain number of decimal places. This is the Crib Sheet provided solution, but please note that as of 2020 the most popular SO answer is different.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | number | the number to be rounded
`places` | number | the max number of decimals desired

Source:
  - util/Util.js, line 1039
See:
  - Stack Overflow

##### Returns:

input rounded to the specified number of decimal places at most

Type
  number

#### (static) selectFromArray(array, selection) → {Object|Array.<Object>}

Select values from an array.

'selection' can be a single integer, an array of indices, or a string to be parsed, e.g.:

- 5
- [1,2,3,10]
- '1,5,10'
- '1:2:5'
- '5:'
- '-5:-2, 9, 11:5:22'

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array
`selection` | number | Array.<number> | string | the selection

Source:
  - util/Util.js, line 794

##### Returns:

the array of selected items

Type
  Object | Array.<Object>

#### (static) shuffle(array, randomNumberGeneratoropt) → {Array.<Object>}

Shuffle an array in place using the Fisher-Yastes's modern algorithm

See details here: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

Source:
  - util/Util.js, line 336

##### Returns:

the shuffled array

Type
  Array.<Object>

#### (static) sliceArray(array, fromopt, toopt, stepopt) → {Array.<Object>}

Slice an array.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`array` | Array.<Object> |  |  | the input array
`from` | number | <optional> | NaN | the start of the slice
`to` | number | <optional> | NaN | the end of the slice
`step` | number | <optional> | NaN | the step of the slice

Source:
  - util/Util.js, line 883

##### Returns:

the array slice

Type
  Array.<Object>

#### (static) sort(input) → {array}

Sort the elements of the input array, in increasing alphabetical or numerical order.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers or of strings

Source:
  - util/Util.js, line 1113

##### Throws:

if 'input' is not an array, or if its elements are not consistent in types, or if they are not all either numbers or strings

##### Returns:

the sorted array

Type
  array

#### (static) sum(input, start) → {number}

Calculate the sum of the elements in the input array. If 'input' is not an array, then we return start.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]
`start` | number | value added to the sum of numbers (a la Python)

Source:
  - util/Util.js, line 1057

##### Returns:

the sum of the elements in the array + start

Type
  number

#### (static) to_height(pos, posUnit, win) → {Array.<number>}

Convert the position to height units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

Source:
  - util/Util.js, line 505

##### Returns:

the position in height units

Type
  Array.<number>

#### (static) to_norm(pos, posUnit, win) → {Array.<number>}

Convert the position to norm units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

Source:
  - util/Util.js, line 473

##### Returns:

the position in norm units

Type
  Array.<number>

#### (static) to_pixiPoint(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Convert a position to a PIXI Point.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | false | whether or not to round the PIXI Point coordinates.

Source:
  - util/Pixi.js, line 13

##### Returns:

the position as a PIXI Point

Type
  Array.<number>

#### (static) to_px(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Convert the position to pixel units.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | false | whether or not to round the position coordinates.

Source:
  - util/Util.js, line 424

##### Returns:

the position in pixel units

Type
  Array.<number>

#### (static) to_unit(pos, posUnit, win, targetUnit) → {Array.<number>}

Convert the position to given units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window
`targetUnit` | string | the target units

Source:
  - util/Util.js, line 579

##### Returns:

the position in target units

Type
  Array.<number>

#### (static) to_win(pos, posUnit, win) → {Array.<number>}

Convert the position to window units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

Source:
  - util/Util.js, line 541

##### Returns:

the position in window units

Type
  Array.<number>

#### (static) toNumerical(obj) → {number|Array.<number>}

Convert obj to its numerical form.

- number -> number, e.g. 2 -> 2
- [number] -> [number], e.g. [1,2,3] -> [1,2,3]
- numeral string -> number, e.g. "8" -> 8
- [number | numeral string] -> [number], e.g. [1, 2, "3"] -> [1,2,3]

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

Source:
  - util/Util.js, line 214

##### Returns:

the numerical form of the input object

Type
  number | Array.<number>

#### (static) toString(object) → {string}

Convert an object to its string representation, taking care of symbols.

Note: if the object is not already a string, we JSON stringify it and detect circularity.

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object

Source:
  - util/Util.js, line 618

##### Returns:

a string representation of the object or 'Object (circular)'

Type
  string

#### (static) turnSquareBracketsIntoArrays(input, max) → {array}

Convert a string representing a JSON array, e.g. "[1, 2]" into an array, e.g. ["1","2"]. This approach overcomes the built-in JSON parsing limitations when it comes to eg. floats missing the naught prefix, and is able to process several arrays, e.g. "[1,2][3,4]".

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | string | string potentially containing JSON arrays
`max` | string | how many matches to return, unwrap resulting array if less than two

Source:
  - util/Util.js, line 957

##### Returns:

an array if arrays were found, undefined otherwise

Type
  array