_insert

#insert

###Insert data onto the end of a variable.

Syntax

status = insert ( destination,source ) ;

Arguments

1. list destination

Destination 'list' or 'str' variable.

2. list source

Source data, any type.

Return Value

str status

• $ACKNOWLEDGE : The data was inserted.

The STATUS variable is set to $ACKNOWLEDGE

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

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