List

Namespace

ZCore

FUNCTION_BLOCK ABSTRACT List

Lists are a standard feature of a lot of programming languages. They are meant for storing values in a specific order and have mechanismns to append, insert and remove items at specific index. Structured Text (ST) doesn't come with built-in feature like that.

This function block is an abstraction of the core methods that can be used to realize custom lists in Structured Text and is a building block to realize lists that can contain all kinds of primitives or types (e.g. see implementation for the DINT primitive type) as well as arbitrary datatype. The implementation uses a logic buffer to store the actual index of items that are added to the list. The Actual implementation also utilize a data buffer which the logic buffer references to. The logic buffer makes it cheap (performance-wise) to remove and insert items at an arbitrary index.

Note

List assumes that ìndex=0 contains an actual, read and writeable instance for both the logic buffer and (in an actual implementation) and the data buffer)

Constructor

FB_init

METHOD FB_init (
 [input] bInitRetains : BOOL,
 [input] bInCopyCode : BOOL,
 [input] bufferSize : DINT,
 [input] logicBuffer : POINTER TO DINT)

The constructs is used to set up the logic buffer the the list, the List has to be initalized as shown in the example below, i.e. the zeroth index of the array that is passed to the function block has to be indexable.

logicBuffer_ : ARRAY[0..100] OF <Type>;
list_ : List<Type>(100, ADR(logicBuffer_));

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

bufferSize DINT := 0

logicBuffer POINTER TO DINT

must be an array in the form ARRAY[0..#Items]

Methods

AppendIndex

METHOD PROTECTED AppendIndex () : DINT

This method adds an item to the logic buffer and returns the index that should be used for the data buffer to store the just added item. It has to be called by an implementation of this function block in order to add an actual object to the list, i.e.

Append := AppendIndex();
IF Append >= 0 THEN
  _pDataBuffer[Append] := value;
END_IF

The method returns -1 if no available index is found - in that case consider to increase the buffersize of the List.

Returns

DINT

Clear

METHOD Clear ()

This method can be used to clear the list such that access with the "normal" getter methods will not work anymore. The method has a very low overhead, since it doesn't actually remove any data, but clears the logic buffer such that data can't be indexed to anymore.

Index

METHOD Index (
 [input] idx : DINT) : DINT

This method returns the actual databuffer index for the x-th item in the list. If no item has been removed or inserted the logic buffer index and data buffer index are the same. However, if items are inserted these indices may differ.

Inputs

idx DINT

starting from idx=0 for the first element

Returns

DINT

InsertIndex

METHOD PROTECTED InsertIndex (
 [input] idx : DINT) : DINT

This method inserts an item at a specific index of the list. It is very fast as data is not copied, but only the logic buffer is updated.

The method return -1 if no available index is found - in that case consider to increase the buffersize of the List.

Inputs

idx DINT

starting from idx=0 for the first element

Returns

DINT

IsEmpty

METHOD IsEmpty () : BOOL

This method returns if the List is empty (i.e. there is not a single item in the List)

Returns

BOOL

IsFull

METHOD IsFull () : BOOL

This method returns TRUE if the internal buffer has been completely filled and hence, there is not enough space for any further item before any old one gets removed by using RemoveAt.

Returns

BOOL

NextIndex

METHOD PROTECTED NextIndex () : DINT

This method returns the next available index in the logic buffer. This is not necessarily the same index as the next free index of the data buffer.

Returns

DINT

RemoveAt

METHOD RemoveAt (
 [input] idx : DINT) : DINT

This method removes an item at a specific index of the list. It is very fast as data is not deleted, but only the logic buffer is updated.

The method return -1 if no available index is found - in that case consider to increase the buffersize of the List.

Inputs

idx DINT

starting from idx=0 for the first element

Returns

DINT

Size

METHOD Size () : DINT

returns the number of items in the list. Keep in mind that when iterating over the list with a FOR-LOOP that indices in the list start with 0 and a FOR-LOOP in Structured Text from 0 TO 0 actually executes 1 iteration. Hence the method should be used in the following way.

FOR i:=0 TO list_.Size()-1
DO
  logicBufferIndex = Index(0);
END_FOR

Returns

DINT