21.4 List Assignment

The list element assignment assigns the object object, which can be of any type, to the list entry at the position pos, which must be a positive integer, in the mutable (see Mutability and Copyability) list list. That means that accessing the pos-th element of the list list will return object after this assignment.

gap> l := [ 1, 2, 3 ];;
gap> l[1] := 3;; l;             # assign a new object
[ 3, 2, 3 ]
gap> l[2] := [ 4, 5, 6 ];; l;   # <object> may be of any type
[ 3, [ 4, 5, 6 ], 3 ]
gap> l[ l[1] ] := 10;; l;       # <index> may be an expression
[ 3, [ 4, 5, 6 ], 10 ]

If the index pos is larger than the length of the list list (see Length), the list is automatically enlarged to make room for the new element. Note that it is possible to generate lists with holes that way.

gap> l[4] := "another entry";; l; # <list> is enlarged
[ 3, [ 4, 5, 6 ], 10, "another entry" ]
gap> l[ 10 ] := 1;; l;            # now <list> has a hole
[ 3, [ 4, 5, 6 ], 10, "another entry",,,,,, 1 ]

The function Add (see Add) should be used if you want to add an element to the end of the list.

Note that assigning to a list changes the list, thus this list must be mutable (see Mutability and Copyability). See Identical Lists for subtleties of changing lists.

If list does not evaluate to a list, pos does not evaluate to a positive integer or object is a call to a function which does not return a value (for example Print) an error is signalled.

The sublist assignment assigns the object objects[1], which can be of any type, to the list list at the position poss[1], the object objects[2] to list[poss[2]], and so on. poss must be a dense list of positive integers, it need, however, not be sorted and may contain duplicate elements. objects must be a dense list and must have the same length as poss.

gap> l := [ 2, 3, 5, 7, 11, 13, 17, 19 ];;
gap> l{[1..4]} := [10..13];; l;
[ 10, 11, 12, 13, 11, 13, 17, 19 ]
gap> l{[1,7,1,10]} := [ 1, 2, 3, 4 ];; l;
[ 3, 11, 12, 13, 11, 13, 2, 19,, 4 ]

It is possible to nest such sublist assignments, as can be seen in the following example.

gap> m := [ [1,2,3], [4,5,6], [7,8,9], [10,11,12] ];;
gap> m{[1,2,3]}{[3,2]} := [ [11,12], [13,14], [15,16] ];; m;
[ [ 1, 12, 11 ], [ 4, 14, 13 ], [ 7, 16, 15 ], [ 10, 11, 12 ] ]

The exact behaviour is defined in the same way as for list extractions (see List Elements). Namely with each selector [pos] or {poss} we associate a level that is defined as the number of selectors of the form {poss} to its left in the same expression. For example

    l[pos1]{poss2}{poss3}[pos4]{poss5}[pos6]
level   0      0      1     1      1     2

Then a list assignment list[pos] := vals; of level level is computed as ListAssignment( list, pos, vals, level ), where ListAssignment is defined as follows. (Note that ListAssignment is not a GAP function.)

ListAssignment := function ( list, pos, vals, level )
 local i;
 if level = 0 then
  list[pos] := vals;
 else
  for i in [1..Length(list)] do
   ListAssignment( list[i], pos, vals[i], level-1 );
  od;
 fi;
end;

and a list assignment list{poss} := vals of level level is computed as ListAssignments( list, poss, vals, level ), where ListAssignments is defined as follows. (Note that ListAssignments is not a GAP function.)

ListAssignments := function ( list, poss, vals, level )
 local i;
 if level = 0 then
  list{poss} := vals;
 else
  for i in [1..Length(list)] do
   ListAssignments( list[i], poss, vals[i], level-1 );
  od;
 fi;
end;

This operation implements sublist assignment. For any list, the default method is to loop over the entries in the list poss, and to delegate to the element assignment operation. (For the somewhat strange variable name, cf. Basic Operations for Lists.)

adds the element obj to the end of the mutable list list, i.e., it is equivalent to the assignment list[ Length(list) + 1 ] := obj, see list element!assignment. Nothing is returned by Add, the function is only called for its side effect.

gap> l := [ 2, 3, 5 ];; Add( l, 7 ); l;
[ 2, 3, 5, 7 ]

adds the elements of the list list2 to the end of the mutable list list1, see sublist!assignment. list2 may contain holes, in which case the corresponding entries in list1 will be left unbound. Append returns nothing, it is only called for its side effect.

Note that Append changes its first argument, while Concatenation (see Concatenation) creates a new list and leaves its arguments unchanged.

gap> l := [ 2, 3, 5 ];; Append( l, [ 7, 11, 13 ] ); l;
[ 2, 3, 5, 7, 11, 13 ]
gap> Append( l, [ 17,, 23 ] ); l;
[ 2, 3, 5, 7, 11, 13, 17,, 23 ]

[Top] [Previous] [Up] [Next] [Index]