List Data Type

The List data structure is designed for storing several related pieces of data in a comma delimited list. The data can all be of the same type or be of differing types, including a list inside of a list. Lists are analogous to lists or arrays in other programming languages.

Conditionals

Contains

The Contains conditional checks if the List has a value inside it matching the value of the conditional and if so, returns True.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dc.Out>TestVar1 = {$TestVar1}<br /></dc.Out>

<dcs.If Target="$TestVar1" Contains="lime">
  <dc.Out>TestVar1 contains "lime"</dc.Out>
</dcs.If>

Output:

TestVar1 = [ "car", "sun", "lime", "32" ]
TestVar1 contains "lime"

Operations

Set

The Set operation tried to parse text between the Set tags and assign the values to the List.

<dcs.Var Name="TestVar1" Type="List">
  <Set>
    "ready",
    "steady",
    "GO!",
    1000
  </Set>
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "ready", "steady", "GO!", 1000 ]

Update

The Update operation is similar to Set but will add on to an exising list and not clear out the values beforehand.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dcs.With Target="$TestVar1">
  <Update>
    "ready",
    "steady",
    "GO!",
    1000
  </Update>
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "car", "sun", "lime", "32", "ready", "steady", "GO!", 1000 ]

AddItem

The AddItem can be used to initialize a list with values but also be used to add values afterwards when used in conjuction with the With tag.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="Ready" />
  <AddItem Type="String" Value="Steady" />
  <AddItem Type="String" Value="GO!" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <AddItem Type="String" Value="Stop" />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "Ready", "Steady", "GO!" ]
TestVar1 is [ "Ready", "Steady", "GO!", "Stop" ]

AddAll

The AddAll operation takes another list, designated in the Value field, and add all of its items into the target List.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dcs.Var Name="TestVar2" Type="List">
  <AddItem Type="String" Value="Ready" />
  <AddItem Type="String" Value="Steady" />
  <AddItem Type="String" Value="GO!" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>
<dc.Out>TestVar2 is {$TestVar2}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <AddAll Value="$TestVar2" />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "car", "sun", "lime", "32" ]
TestVar2 is [ "Ready", "Steady", "GO!" ]
TestVar1 is [ "car", "sun", "lime", "32", "Ready", "Steady", "GO!" ]

RemoveItem

The RemoveItem operation removes a single item based on index. Index notation begins at 0, so to remove the second element of a list, you would use the index of 1 and so forth.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="Ready" />
  <AddItem Type="String" Value="Steady" />
  <AddItem Type="String" Value="GO!" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <RemoveItem Index="1" />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "Ready", "Steady", "GO!" ]
TestVar1 is [ "Ready", "GO!" ]

RemoveAll

The RemoveAll operation does the inverse of AddAll - it compares the exising values in a list against another list and removes any matches.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dcs.Var Name="TestVar2" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="lime" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>
<dc.Out>TestVar2 is {$TestVar2}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <RemoveAll Value="$TestVar2" />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "car", "sun", "lime", "32" ]
TestVar2 is [ "car", "lime" ]
TestVar1 is [ "sun", "32" ]

Clear

The Clear operation simply removes all values from the existing list.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="Ready" />
  <AddItem Type="String" Value="Steady" />
  <AddItem Type="String" Value="GO!" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <Clear />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "Ready", "Steady", "GO!" ]
TestVar1 is [ ]

Sort

The Sort operation can be used in a List with nested Record s inside. The operation compares all of the nested Records and sort them by the field indicated in the ByField attribute. There is an optional parameter Desc that is defaulted to false; setting this to true will sort by descending order versus ascending.

<dcs.Var Name="TestVar10" Type="List">
  <Set>
    <Record>
      <Field Name="Name" Type="String" Value="Bob" />
      <Field Name="Age" Type="Integer" Value="32" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Dave" />
      <Field Name="Age" Type="Integer" Value="47" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Sharla" />
      <Field Name="Age" Type="Integer" Value="29" />
    </Record>
</Set>
</dcs.Var>

<dc.Out>TestVar10 is {$TestVar10}<br /></dc.Out>

<dcs.With Target="$TestVar10">
  <Sort ByField="Age"/>
</dcs.With>

<dc.Out>TestVar10 is {$TestVar10}<br /></dc.Out>

Output:

TestVar10 is [ { "Age": 32, "Name": "Bob" } , { "Age": 47, "Name": "Dave" } , { "Age": 29, "Name": "Sharla" } ]
TestVar10 is [ { "Age": 29, "Name": "Sharla" } , { "Age": 32, "Name": "Bob" } , { "Age": 47, "Name": "Dave" } ]

When needing to sort by multiple fields sequentially, the following format can be used:

<dcs.Var Name="TestVar11" Type="List">
  <Set>
    <Record>
      <Field Name="Name" Type="String" Value="Bob" />
      <Field Name="Age" Type="Integer" Value="32" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Dave" />
      <Field Name="Age" Type="Integer" Value="47" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Sharla" />
      <Field Name="Age" Type="Integer" Value="29" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Steve" />
      <Field Name="Age" Type="Integer" Value="32" />
    </Record>
</Set>
</dcs.Var>

<dc.Out>TestVar11 is {$TestVar11}<br /></dc.Out>

<dcs.With Target="$TestVar11">
  <Sort>
    <Field Name="Age" />
    <Field Name="Name" />
  </Sort>
</dcs.With>

<dc.Out>TestVar11 is {$TestVar11}<br /></dc.Out>

Output:

TestVar10 is [ { "Age": 32, "Name": "Bob" } , { "Age": 47, "Name": "Dave" } , { "Age": 29, "Name": "Sharla" } , { "Age": 32, "Name": "Steve" } ]
TestVar10 is [ { "Age": 29, "Name": "Sharla" } , { "Age": 32, "Name": "Bob" } , { "Age": 32, "Name": "Steve" } , { "Age": 47, "Name": "Dave" } ]

Join

The Join operation condenses the target list into a single string, designated with the variable name found in the Result attribute. The default deliminator is a comma, but another deliminator can be assigned in the Delim variable.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <Join Result="TestVar2" Delim="-"/>
</dcs.With>

<dc.Out>TestVar2 is {$TestVar2}<br /></dc.Out>

Output:

TestVar1 is [ "car", "sun", "lime", "32" ]
TestVar2 is car-sun-lime-32

FieldToList

Similar to Sort , the FieldToList operation is designed to work with Records nested inside a List. The operation takes the data found inside each Record in the List found in the Field attribute and creates a new list with a name designated in the Result attribute.

<dcs.Var Name="TestVar10" Type="List">
  <Set>
    <Record>
      <Field Name="Name" Type="String" Value="Bob" />
      <Field Name="Age" Type="Integer" Value="32" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Dave" />
      <Field Name="Age" Type="Integer" Value="47" />
    </Record>
    <Record>
      <Field Name="Name" Type="String" Value="Sharla" />
      <Field Name="Age" Type="Integer" Value="29" />
    </Record>
  </Set>
</dcs.Var>

<dcs.With Target="$TestVar10">
  <FieldToList Field="Name" Result="TestF2LVar"/>
</dcs.With>

<dc.Out>TestVar10 is {$TestVar10}<br /></dc.Out>

<dc.Out>TestF2LVar is {$TestF2LVar}<br /></dc.Out>

Output:

TestVar10 is [ { "Age": 32, "Name": "Bob" } , { "Age": 47, "Name": "Dave" } , { "Age": 29, "Name": "Sharla" } ]
TestF2LVar is [ "Bob", "Dave", "Sharla" ]

Reverse

The Reverse operation simply reverses the order of the list elements.

<dcs.Var Name="TestVar1" Type="List">
  <AddItem Type="String" Value="car" />
  <AddItem Type="String" Value="sun" />
  <AddItem Type="String" Value="lime" />
  <AddItem Type="Integer" Value="32" />
</dcs.Var>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

<dcs.With Target="$TestVar1">
  <Reverse />
</dcs.With>

<dc.Out>TestVar1 is {$TestVar1}<br /></dc.Out>

Output:

TestVar1 is [ "car", "sun", "lime", "32" ]
TestVar1 is [ "32", "lime", "sun", "car" ]