11.1 append()

anyalue append
(
      anyvalue ListValue  input,
      anyvalue NewValue   input
  { , integer  Count := 1 input }
  { , enum     Dir   := dir_row input }
)

Parameters

anyvalue ListValue input

This parameter specifies the collection or string where a value shall be appended.

anyvalue NewValue input

This parameter defines the new value to be added. The value must match the value type of the collection.

integer Count := 1 input

This optional parameter defines the number of times a new value (respectively how many rows or columns) shall be appended. Values >= 0 are allowed, with no appending being performed for 0. By default, the new value is appended once.

enum Dir := dir_row input

For collections of data type matrix, this optional parameter controls whether new rows (dir_row) or new columns (dir_column) are added.

Return value

The function returns the modified collection respectively the modified string.

Particularities

• hash

  Since this collection data type does not have a defined index range, appending takes place after the last integer index. Thus a hash with an indexing of 1,2,3… is assumed. The last set index of data type integer is determined and then it is appended after it.

• matrix

  Appending to a matrix always happens by rows or columns. This is controlled by the Dir parameter. By default (dir_row) new rows are added. If dir_column is given, new columns are added.

• refvec

  Appending null objects is not allowed. If the object ID already exists, it is repositioned to the last position.

• string

  The new value is appended to the end of the string.

• Default Values

  To determine the index position for the new values, default values are also taken into account except for a hash collection.

Examples

• Multiple appending to a string

  print append("hi", " ho", 3);

  Output

  "hi ho ho ho"

• Multiple appending to a list collection

  variable list L := [4711, "cologne"];
  print append(L, true, 2);

  Output

  [4711,"cologne",true,true]

• Appending two rows to a matrix

  variable matrix M := [ [0,0]=>"?", [1,1]=>"a", [1,2]=>"b",
                         [2,2]=>"c", [3,1]=>"end" ];
  print append(M, "new", 2);

  Output

  [[1,1]=>"a",[1,2]=>"b",[2,1]=>"?",[2,2]=>"c",[3,1]=>"end",[3,2]=>"?",
  [4,1]=>"new",[4,2]=>"new",[5,1]=>"new",[5,2]=>"new"]

• Appending to a hash with mixed indexing

  variable hash H := [false=>.xleft, 31=>.width, 33=>.ytop, "x"=>1];
  print append(H, .height);

  Output

  [false=>.xleft,31=>.width,33=>.ytop,34=>.height,"x"=>1]

• Appending to a vector list

  variable vector[integer] V := [9, 8, 7];
  print append(V, 6);

  Output

  [9,8,7,6]

Availability

Since IDM version A.06.02.g

See also

Built-in function insert()