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

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

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

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

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

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

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);
}