IRISList

"intersystems-iris". IRISList

A class that provides an interface to interact with IRIS $LIST data.

Constructor

# new IRISList(listopt, optionsopt)

Parameters:
Name Type Attributes Description
list module:"intersystems-iris".IRISList | Buffer <optional>

a list to initialize the object from. If Buffer provided it needs to be formatted as a $LIST. (Note: If IRISList provided options are ignored and the object's properties are honored)
options Object <optional>

options regarding the IRISList format

Properties
Name Type Attributes Default Description
locale string <optional>
 'utf-16'

indicates the locale used to store and/or interpret strings stored in the list (Supported locales follow the Node.js locale name convensions described in the util.TextDecoder class). Default valu applied for null.

⚠ Warning: If a locale is not supported an error is thrown either during the construction of the IRISList OR after the first add of a non-ascii string (for example a string of the locale requested.)
isUnicode boolean <optional>
 true

marks the list as unicode or non unicode. Can be used instead of locale when list is unicode. When used along with locale, the two parameters need to be in sync. Default value applied for null.

Note: When only locale is provided the default value is ignored and isUnicode is equal to the evaluation of the expression local == 'utf-16'.
compactDouble boolean <optional>
 false

indicates whether the list should try to compress double values. Default value applied for null.
Properties
Name Type Description
locale string

the locale used to interpret the stings stored in the list
isUnicode boolean

true if locale is utf-16
compactDouble boolean

true if doubles stored in the list are compressed
Throws:

  • Fails if list provided but it is not of $LIST format

  • Fails if locale provided is not supported (any locale supported by the IRIS server is a supported locale)

  • Fails if locale and isUnicode parameters are not in sync

Methods

# add(value) → {module:"intersystems-iris".IRISList}

Adds a data element at the end of the list.

Parameters:
Name Type Description
value any

the value of the list element to be added
Throws:

  • If insufficient number of arguments (at least 1)

  • If argument is a list with compact double enabled but the current list does not allow compact double

Returns:

the current IRISList object

Type
module:"intersystems-iris".IRISList

# clear() → {module:"intersystems-iris".IRISList}

Clears all data elements from the list.

Returns:

the current IRISList object

Type
module:"intersystems-iris".IRISList

# count() → {number}

Returns the number of data elements in the list.

Returns:

the number of elements

Type
number

# equals(otherList) → {boolean}

Compares a list to the current list, return true if they are equal.

Parameters:
Name Type Description
otherList module:"intersystems-iris".IRISList

the list to compare the current list to
Returns:

true if equal

Type
boolean

# get(index) → {any}

Gets the list element at the specified index. If the element value is expected to be a list then use getList instead. Returns a string of length 0 if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of position (number|bigint|string|Buffer|Decimal|null)

Type
any

# getBigInt(index) → {bigint|null}

Gets the list element at the specified index as an integer number. Returns 0n if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as an integer number.

Type
bigint | null

# getBoolean(index) → {boolean|null}

Gets the list element at the specified index as a boolean. Returns false if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as a boolean.

Type
boolean | null

# getBuffer() → {Buffer}

Returns a Buffer that contains the $LIST format of all the data elements in the list.

Returns:

the entire contents of the current list.

Type
Buffer

# getBytes(index) → {Buffer|null}

Gets the list element at the specified index as a Buffer. Returns an empty Buffer if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as a Buffer.

Type
Buffer | null

# getDecimal(index) → {external:"decimal.js".Decimal|null}

Gets the list element at the specified index as a Decimal. Returns Decimal(0) if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as a Decimal.

Type
external:"decimal.js".Decimal | null

# getIRISList(index) → {module:"intersystems-iris".IRISList}

Gets the list element at the specified index as an IRISList. If element not in a list format it will throw. Returns empty list if element is an empty string. Alias of getList

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as an IRISList

Type
module:"intersystems-iris".IRISList

# getList(index) → {module:"intersystems-iris".IRISList}

Gets the list element at the specified index as an IRISList. If element not in a list format it will throw. Returns empty list if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as an IRISList

Type
module:"intersystems-iris".IRISList

# getNumber(index) → {number|null}

Gets the list element at the specified index as a number. Returns 0 if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as a number.

Type
number | null

# getString(index) → {string|null}

Gets the list element at the specified index as a string. Returns string of length 0 if element is an empty string.

Parameters:
Name Type Description
index number

the position of the element to retrieve. Should be >= 1.
Throws:

  • If index out of bounds

  • If index is invalid

  • If insufficient number of arguments (at least 1)

Returns:

the element of the position as a string.

Type
string | null

# remove(index) → {module:"intersystems-iris".IRISList}

Removes the list element at the specified index from the list.

Parameters:
Name Type Description
index number

the element position to retrieve. Should be >= 1.
Throws:

  • If insufficient number of arguments (at least 1)

  • If index is invalid

Returns:

the current IRISList object

Type
module:"intersystems-iris".IRISList

# set(index, value) → {module:"intersystems-iris".IRISList}

Changes the data element at the specified index to a new value. If the index is beyond the length of the IRISList, IRISList will be first expanded to that many elements, padded with null elements.

Parameters:
Name Type Description
index number

the element position to set. Should be >= 1.
value any

the element value
Throws:

  • If index is invalid

  • If insufficient number of arguments (at least 2)

Returns:

the current IRISList object

Type
module:"intersystems-iris".IRISList

# size() → {number}

Returns the total size (number of bytes) of the list.

Returns:

the size of the list in bytes

Type
number

# toString() → {string}

Returns a string containing the formatted list value

Returns:

the string representation of the list

Type
string