2.6 Methods for Arrays of User-defined Attributes

The methods :clear(), :delete(), :exchange(), :insert() and :move() are used for non-associative arrays of user-defined attributes and will be described in more detail here.

2.6.1 :clear()

This method deletes the contents of elements in fields (indexed, non-associative, user-defined attributes).

In contrast to the :delete() method, :clear() only deletes the contents of the items. The items themselves remain as empty items, which will have the default value if available. Thus :clear() will not reduce the number of items.

Particularity

The :clear() method can also be used to delete all items of an associative array. In this case, neither the Start nor the Count parameter may be specified. Therefore, :clear() cannot be used to delete single items from an associative array. Additionally, not only the contents but the elements themselves are deleted in this case. Thus, the number of elements afterwards will be 0.

Definition

boolean :clear
(
      attribute Attr input
  { , integer Start input }
  { , integer Count input }
)

Parameters

attribute Attr input

This parameter defines the user-defined attribute on which the method should be applied.

integer Start input

This parameter defines the position from which the contents of the items should be deleted.

The value range for Start is 0 … .count[Attr], i.e. the default value can also be deleted.

If neither Start nor Count is specified, the contents of all elements are deleted.

integer Count input

This optional parameter defines the number of items whose contents are to be deleted.

If neither Start nor Count is specified, the contents of all elements are deleted.

If Start is specified, the default value of Count is 1.

Return value

The method returns true if the contents of the items could be deleted.

If an error has occurred when deleting the contents, the method will return a fail.

2.6.2 :delete()

This method deletes items from arrays (indexed user-defined attributes).

Unlike the :clear() method, :delete() completely deletes the elements, i.e. the number of elements is reduced.

Definition

boolean :delete
(
      attribute Attr input,
      anyvalue Position input
  { , integer Count := 1 input }
)

Parameters

attribute Attr input

This parameter defines the user-defined attribute on which the method should be applied.

anyvalue Position input

In this parameter the index of the first item to be deleted is passed. For non-associative arrays Position has to be of the data type integer, for associative arrays it has to be of the data type the associative array is indexed with.

The value range for Position with non-associative fields is 0 … .count[Attr], i.e. the default value can also be deleted. If the default value is deleted, the value of the first item after the deleted items becomes the default value.

integer Count := 1 input

This optional parameter defines the number of items that are deleted. If the parameter is not specified, 1 is taken as default.

Count cannot be used with associative arrays, only 1 item can be deleted at once.

Return value

The method returns true if the rows or columns could be deleted.

If an error has occurred when deleting, the method will return a fail.

2.6.3 :exchange()

This method exchanges two items of an array (indexed, non-associative, user-defined attribute).

Definition

boolean :exchange
(
  attribute Attr input,
  integer Position1 input,
  integer Position2 input
)

Parameters

attribute Attr input

This parameter defines the user-defined attribute on which the method should be applied.

integer Position1 input
integer Position2 input

In these parameters the indices of the two items to be exchanged with each other are passed.

The value range for both parameters is 0 … .count[Attr], i.e. the default value can also be exchanged with the value of another item.

Return value

The method returns true if the items could be exchanged.

If an error has occurred when exchanging, the method will return a fail.

2.6.4 :insert()

This method inserts new items into arrays (indexed, non-associative, user-defined attributes). The newly inserted items are empty or have the default value if available.

Definition

boolean :insert
(
      attribute Attr input,
      integer Position input
  { , integer Count := 1 input }
)

Parameters

attribute Attr input

This parameter defines the user-defined attribute on which the method should be applied.

integer Position input

In this parameter the index where the new elements should be inserted is passed. If its value is 0, the elements are appended to the end.

integer Count := 1 input

This optional parameter defines the number of items that are inserted. If the parameter is not specified, 1 is taken as default.

Return value

The method returns true if the items could be inserted.

If an error has occurred when inserting, the method will return a fail.

2.6.5 :move()

This method moves items of an array (indexed, non-associative, user-defined attribute) to another position in the array.

Definition

void :move
(
  attribute Attr input,
  integer Position input,
  integer Target input,
  integer Count input
)

Parameters

attribute Attr input

This parameter defines the user-defined attribute on which the method should be applied.

integer Position input

This parameter specifies the index of the first item to be moved.

integer Target input

This parameter determines where the items should be moved to.

integer Count input

This parameter defines how many items are moved.

Return value

None.