Numeric Array Datatypes

Numeric Array Datatypes

All integer array types share the NumericArray template, giving them an identical API. The types covered by this guide are:

SINTARRAY · USINTARRAY · INTARRAY · UINTARRAY · DINTARRAY · UDINTARRAY · LINTARRAY · ULINTARRAY

from ethernetip_emulator.server.device import actions

# Tag definition
("O_Passed", actions.type.UINTARRAY([0, 0, 0, 0]))
("O_Scores", actions.type.SINTARRAY([-1, 2, -3, 4]))

Slot Convention

Numeric array operations treat 0 as an empty slot and any non-zero value as an occupied slot. This convention is used by append, prepend, pop, insert, remove, count, is_full, and is_empty.

Core Read / Write

get_val(name, key?)

Returns the full array or a sub-range as a list[int].

Parameter	Type	Default	Description
name	str	—	Tag name.
key	slice | None	full array	Sub-range to read.

actions.uintarray.get_val("O_Passed")               # → [5, 0, 12, 0]
actions.uintarray.get_val("O_Passed", slice(0, 2))  # → [5, 0]

set_val(name, value, key?)

Writes a list of integers to the array or a sub-range.

Parameter	Type	Default	Description
name	str	—	Tag name.
value	list[int]	—	Values to write.
key	slice | None	full array	Sub-range to write.

actions.uintarray.set_val("O_Passed", [5, 0, 12, 0])
actions.uintarray.set_val("O_Passed", [99], slice(2, 3))  # write only index 2

Inspection

size(name)

Returns the total number of elements, or 0 if the tag does not exist.

actions.uintarray.size("O_Passed")   # → 4

count(name, key?)

Returns the number of non-zero elements.

# [5, 0, 12, 0]
actions.uintarray.count("O_Passed")   # → 2

is_full(name, key?)

Returns True if every element is non-zero.

actions.uintarray.is_full("O_Passed")   # → False

is_empty(name, key?)

Returns True if every element is 0.

actions.uintarray.is_empty("O_Passed")   # → False

find(name, value, key?)

Returns the zero-based index of the first element equal to value, or None if not found.

# [5, 0, 12, 0]
actions.uintarray.find("O_Passed", 12)   # → 2
actions.uintarray.find("O_Passed", 99)   # → None

List Operations

append(name, value, key?)

Writes value into the first 0 slot (scanning left to right). Returns True on success, False if no empty slot is available.

# [5, 0, 12, 0]
actions.uintarray.append("O_Passed", 7)   # → True
# [5, 7, 12, 0]

prepend(name, value, key?)

Writes value into the last 0 slot (scanning right to left). Returns True on success, False if no empty slot is available.

# [5, 7, 12, 0]
actions.uintarray.prepend("O_Passed", 3)   # → True
# [5, 7, 12, 3]

pop(name, key?)

Clears (sets to 0) the last non-zero element and returns its value. Returns None if all elements are 0.

# [5, 7, 12, 3]
actions.uintarray.pop("O_Passed")   # → 3
# [5, 7, 12, 0]

insert(name, index, value, key?)

Inserts value at index, shifting all subsequent elements one position to the right. The last element is lost if the array is full. Returns False if there is no room (last element is non-zero), True on success.

# [5, 7, 12, 0]
actions.uintarray.insert("O_Passed", 1, 99)   # → True
# [5, 99, 7, 12]

remove(name, index, key?)

Removes the element at index, shifting subsequent elements one position to the left. The last element is set to 0. Returns the removed value, or None if the element at index was already 0.

# [5, 99, 7, 12]
actions.uintarray.remove("O_Passed", 1)   # → 99
# [5, 7, 12, 0]

Bulk Mutations

clear(name, key?)

Sets all elements (or a sub-range) to 0.

actions.uintarray.clear("O_Passed")
# [0, 0, 0, 0]

Listening for Changes

on_change defaults to the full array slice when no key is provided. Use a specific key to subscribe to individual elements.

# Fires when any element in the array is written
@actions.uintarray.on_change("O_Passed")
def any_changed(attr, key, value):
    print(f"Array updated: {actions.uintarray.get_val('O_Passed')}")

# Fires only when index 0 is written
@actions.uintarray.on_change("O_Passed", key=slice(0, 1))
def slot_0_changed(attr, key, value):
    print(f"Slot 0 is now {value[0]}")

See the Working with Actions for full documentation on key and defer.

Method Reference

Method	Description
get_val(name, key?)	Read the full array or a sub-range as list[int]
set_val(name, value, key?)	Write a list of integers to the array or a sub-range
size(name)	Return the total number of elements
count(name, key?)	Count non-zero elements
is_full(name, key?)	True if all elements are non-zero
is_empty(name, key?)	True if all elements are 0
find(name, value, key?)	Return the index of the first matching element
append(name, value, key?)	Write into the first 0 slot
prepend(name, value, key?)	Write into the last 0 slot
pop(name, key?)	Clear and return the last non-zero element
insert(name, index, value, key?)	Insert at index, shifting right
remove(name, index, key?)	Remove at index, shifting left
clear(name, key?)	Set all elements to 0
on_change(name, callback?, key?, defer?)	Register a change listener