`singleitem`

Retrieves a single item from a list.

The singleitem expression can be useful when it is expected that a list contains only a single item, e.g. when filtering a list by criteria which should only pick out a single item from the list.

The singleitem expression specifies:

onEmpty
The behavior when the list is found to be empty:
- error
  A runtime error occurs (use this option if the list is not expected to be empty); or
- returnNull
  The value null is returned.
onMultiple
The behavior when the list is found to contain more than one item:
- error
  A runtime error occurs (use this option if the list is not expected to contain more than one item);
- returnNull
  The value null is returned;
- returnFirst
  The first item in the list is returned; or
- returnLast
  The last item in the list is returned.

To retrieve an item from a specific position in a list, see get in Useful List Operations.

<?xml version="1.0" encoding="UTF-8"?>
<RuleSet name="Example_singleitem"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation=
"http://www.curamsoftware.com/CreoleRulesSchema.xsd">
  <Class name="Person">

    <Attribute name="dateOfBirth">
      <type>
        <javaclass name="curam.util.type.Date"/>
      </type>
      <derivation>
        <specified/>
      </derivation>
    </Attribute>

    <Attribute name="children">
      <type>
        <javaclass name="List">
          <ruleclass name="Person"/>
        </javaclass>
      </type>
      <derivation>
        <specified/>
      </derivation>
    </Attribute>

    <!-- The first child born to this person -->
    <Attribute name="firstBornChild">
      <type>
        <ruleclass name="Person"/>
      </type>
      <derivation>
        <!-- get the first child, if any
             - if no children, return null -->
        <singleitem onEmpty="returnNull" onMultiple="returnFirst">
          <!-- sort the children in date-of-birth order -->
          <sort>
            <list alias="child">
              <reference attribute="children"/>
            </list>
            <sortorder>
              <sortitem direction="ascending">
                <reference attribute="dateOfBirth">
                  <current alias="child"/>
                </reference>
              </sortitem>
            </sortorder>
          </sort>

        </singleitem>
      </derivation>

    </Attribute>

    <!-- Retrieve the single household information record
         from external storage - there should always
         be exactly one - anything else is an error.  -->
    <Attribute name="householdInformation">
      <type>
        <ruleclass name="HouseholdInformation"/>
      </type>
      <derivation>
        <singleitem onEmpty="error" onMultiple="error">
          <readall ruleclass="HouseholdInformation"/>
        </singleitem>
      </derivation>
    </Attribute>

  </Class>

  <Class name="HouseholdInformation">

    <Attribute name="householdContainsDisabledPerson">
      <type>
        <javaclass name="Boolean"/>
      </type>
      <derivation>
        <specified/>
      </derivation>
    </Attribute>

  </Class>

</RuleSet>