11.22 insert()

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

Parameters

anyvalue ListValue input

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

integer Pos input

In this parameter, the index position is defined before which the insertion occurs. Values >= 1 are permitted. For matrix collections, depending on the Dir parameter, Pos represents either a row position (dir_row) or a column position (dir_column).

integer Count := 1 input

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

enum Dir := dir_row input

This optional parameter defines the orientation of the index position, which is important for a matrix. The default value dir_row means that rows are inserted in the matrix. With dir_column columns are inserted.

anyvalue NewValue input

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

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, inserting takes place based on the integer indices. Thus a hash with an indexing of 1,2,3… is assumed. There are no limitations concerning the largest possible index position.

• matrix

  Inserting into a matrix always happens by rows or columns. This is controlled by the Dir parameter. By default (dir_row) new rows are inserted. If dir_column is given, new columns are inserted. This also means that the position refers to a row in the first case and to a column in the second.

• refvec

  Inserting null objects is not allowed. Multiple insertion is also not supported, since the same object ID may only be contained once. If the object ID already exists, it is repositioned.

• string

  Here the position refers to the character position in the string, i.e. the string is treated as an array of characters.

• Default Values

  In general it is useful to give a new value when inserting. If this is omitted, it depends on the collection type which values will be at the inserted positions. The collection types list, hash and matrix allow default values, so that the default values appear at the inserted positions when inserting without a new value.

Examples

• Multiple insertion of the string "X" into a list

  variable list L := ["a", "b", "c"];
  print insert(L, 1, 2, "X");

  Output

  ["X","X","a","b","c"]

• Appending a row to the end of a matrix

  variable matrix M := [ [0,0]=>"?", [1,1]=>"a1", [1,2]=>"b1",
                         [2,1]=>"a2", [2,2]=>"b2" ];
  M := insert(M, 3, "NEW");
  print M;

  Output

  [[1,1]=>"a1",[1,2]=>"b1",[2,1]=>"a2",[2,2]=>"b2",[3,1]=>"NEW",[3,2]=>"NEW"]

  Inserting a new 1^st column without value

  M := insert(M, 1, dir_column);
  print M;

  Output

  [[1,1]=>"?", [1,2]=>"a1",[1,3]=>"b1",[2,1]=>"?",[2,2]=>"a2",[2,3]=>"b2",
  [3,1]=>"?",[3,2]=>"NEW",[3,3]=>"NEW"]

• Inserting "ll" into a string

  print insert("heo", 3, 2, "l");

  Output

  "hello"

• Inserting into a hash with integer indexing

  variable hash H := [2=>.xleft, 33=>.ytop];
  H := insert(H, 10, .width);
  print H;

  Output

  [2=>.xleft,10=>.width,34=>.ytop]

• Inserting into a vector list

  variable vector[boolean] V := [true, true];
  print insert(V, 2, 3, false);

  Output

  [true,false,false,false,true]

• Inserting an already existing refvec item at another position

  variable refvec R := [PbApply, PbCancel, PbRevert];
  print insert(R, 1, PbRevert);

  Output

  [pushbutton D.PbRevert,pushbutton D.PbApply,pushbutton D.PbCancel]

Availability

Since IDM version A.06.02.g

See also

Built-in functions append(), delete()