insert

Insert data onto the end of a variable.

Syntax

status = insert ( destination , source ) ;

Arguments

list destination

• Destination 'list' or 'str' variable.

list source

• Source data, any type.

Return Value

str status

• $ACKNOWLEDGE

  The data was inserted.

  The STATUS variable is set to $ACKNOWLEDGE

Exceptions

%ARGUMENT : Invalid arguments. Usage: status = insert ( destination , source ) ;

%IDENTIFIER : 'variable' argument is not a valid identifier, literal, or reference

%INVALID : The destination is not a list or str variable.

Description

The top-level source variable is appended to the end of the destination structure. The source variable becomes a member of the destination structure,and ceases to exist as a top-level variable.

The destination structure must be of type list or str .

Appending a variable into an empty list is equivalent to a direct assignment of the variable.

a = {} ;
append ( a, 1 ) ;
describe a ;
list 'a' = {
1
} ;

b = 1 ;
describe b ;
list 'b' = {
1
} ;

If you append a variable to a list, it ceases to be a top level variable. To recreate the variable, it the remove() or chop() function can bring it back.

a = { 1, 2.5, "abc" } ;
container = {} ;
append ( container, a ) ;
put exists a ;
0

a = remove container ;
put exists a ;
1

describe a ;
list 'a' = {
1,2.5,"abc"
} ;

Examples

To execute the example below, press or modify the example to try different variations.
list L = { int b = 2, int c = 3 }; /* L contains { 'b', 'c' } */ describe L ; int a = 1; insert ( L, a ); /* L contains ( 'a', 'b', 'c' } */ describe L ; int d = 4; append ( L, d ); /* L contains ( 'a', 'b', 'c', 'd' } */ describe L ;

Related Links

append , chop , remove , detach