X++ container runtime functions

This article describes the container run-time functions.

These functions manipulate the contents of containers.

conDel

Removes the specified number of elements from a container.

Syntax

container conDel(container container, int start, int number)

Parameters

Parameter	Description
container	The container to remove elements from.
start	The one-based position at which to start removing elements.
number	The number of elements to delete.

Return value

A new container that doesn't include the removed elements.

Example

static void conDelExample(Args _args)
{
    container c = ["Hello world", 1, 3.14];
        // Deletes the first two items from the container.
        c = conDel(c, 1, 2);
}

conFind

Locates the first occurrence of an element or a sequence of elements in a container.

Syntax

int conFind (container container, anytype element,... )

Parameters

Parameter	Description
container	The container to search.
element	One or more elements to search for, separated by commas.

Remarks

If several elements are specified in the sequence, they must be separated by commas and specified in the correct sequence. The elements can be of any data type.

Return value

0 if the item was not found; otherwise, the sequence number of the item.

Example

static void conFindExample(Args _args)
{
    container c = ["item1", "item2", "item3"];
    int i;
    int j;
    i = conFind(c, "item2");
    j = conFind(c, "item4");
    print "Position of 'item2' in container is " + int2Str(i);
    print "Position of 'item4' in container is " + int2Str(j);
}

conIns

Inserts one or more elements into a container.

Syntax

container conIns (container container, int start, anytype element, ... )

Parameters

Parameter	Description
container	The container to insert elements into.
start	The position to insert elements at.
element	One or more elements to insert, separated by commas.

Return value

A new container that contains the inserted elements.

Remarks

The first element of the container is specified by the number 1. To insert after the n element, the start parameter should be n+1. You can also use the += operator to add values of any type to a container. For example, to create a container that contains the squared values of the first 10 loop iterations, use the following code.

int i;
container c;

for (i = 1; i < = 10; i++)
{
    c += i*i;
}

Example

static void conInsExample(Args _arg)
{
    container c;
    int i;

    c = conIns(c,1,"item1");
    c = conIns(c,2,"item2");
    for (i = 1 ; i <= conLen(c) ; i++)
    {
        // Prints the content of a container.
        print conPeek(c, i);
    }
}

conLen

Retrieves the number of elements in a container.

Syntax

int conLen(container container)

Parameters

Parameter	Description
container	The container to count the number of elements in.

Return value

The number of elements in the container.

Example

static void conLenExample(Args _arg)
{
    container c;
    int i;

    c = conins(["item1", "item2"], 1);
    for (i = 1 ; i <= conLen(c) ; i++)
    {
            print conPeek(c, i);
    }
}

conNull

Retrieves an empty container.

container conNull()

Remarks

Use this function to explicitly dispose of the contents of a container.

Return value

An empty container.

Example

static void conNullExample(Args _arg)
{
    container c = ["item1", "item2", "item3"];

    print "Size of container is " + int2str(conLen(c));
    // Set the container to null.
    c = conNull();
    print "Size of container after conNull() is " + int2Str(conLen(c));
}

conPeek

Retrieves a specific element from a container and converts it into another data type, if conversion is required.

Syntax

anytype conPeek(container container, int number)

Parameters

Parameter	Description
container	The container to return an element from.
number	The position of the element to return. Specify 1 to get the first element. An invalid position number, such as -3, 0, or a number that is higher than the length of the container, might cause unpredictable errors.

Return value

The element in the container at the position that is specified by the number parameter. The conPeek function automatically converts the peeked item into the expected return type. Strings can automatically be converted into integers and real numbers, and integers and real numbers can be converted into strings.

Example

static void main(Args _args)
{
    container cnI, cnJ;
    int i, j;
    anytype aty;
    info("container cnI ...");
    cnI = ["itemBlue", "itemYellow"];
    for (i=1; i <= conLen(cnI); i++)
    {
        aty = conPeek(cnI, i);
        info(int2str(i) + " :  " + aty);
    }

    info("container cnJ ...");
    cnJ = conIns(cnI, 2, "ItemInserted");
    for (j=1; j <= conLen(cnJ); j++)
    {
        aty = conPeek(cnJ, j);
        info(int2str(j) + " :  " + aty);
    }
}
/***  Output pasted from InfoLog ...
Message (10:20:03 am)
container cnI ...
1 :  itemBlue
2 :  itemYellow
container cnJ ...
1 :  itemBlue
2 :  ItemInserted
3 :  itemYellow
***/

conPoke

Modifies a container by replacing one or more of the existing elements.

Syntax

container conPoke(container container, int start, anytype element, ...)

Parameters

Parameter	Description
container	The container to modify.
start	The position of the first element to replace.
element	One or more elements to replace, separated by commas.

Return value

A new container that includes the new elements.

Remarks

The first element of the container is specified by the number 1.

Example

static void conPokeExample(Args _arg)
{
    container c1 = ["item1", "item2", "item3"];
    container c2;
    int i;
    void conPrint(container c)
    {
        for (i = 1 ; i <= conLen(c) ; i++)
        {
            print conPeek(c, i);
        }
    }

    conPrint(c1);
    c2 = conPoke(c1, 2, "PokedItem");
    print "";
    conPrint(c2);
}