Version dev

# Arrays and Maps

The speedata Publisher supports arrays and maps as native data structures. This allows ordered lists and key-value mappings to be used directly in XPath expressions — without the detour of dynamically generated variable names.

The constructors (`[...]`, `array { ... }`, `map { ... }`) and the lookup operator (`?`) can be used directly. To use functions like `array:size()`, `map:keys()` etc., the corresponding namespaces must be declared in the root element:

    <Layout xmlns="urn:speedata.de:2009/publisher/en"
        xmlns:sd="urn:speedata:2009/publisher/functions/en"
        xmlns:array="http://www.w3.org/2005/xpath-functions/array"
        xmlns:map="http://www.w3.org/2005/xpath-functions/map">

The prefixes `array` and `map` can be chosen freely, but the namespace URIs must be exactly as shown.

## Arrays

An array is an ordered collection of values. Each element (“member”) can be any XPath value — numbers, strings, or even other arrays and maps.

### Creating arrays

Square brackets — each expression becomes a member:

    <SetVariable variable="colors" select="['red', 'green', 'blue']"/>
    <SetVariable variable="numbers" select="[10, 20, 30]"/>
    <SetVariable variable="empty" select="[]"/>

Curly constructor — a sequence is split into individual members:

    <SetVariable variable="one_to_five" select="array { 1 to 5 }"/>

The result is an array with five members: 1, 2, 3, 4, 5.

### Accessing array elements

The lookup operator `?` accesses a member by index (1-based):

    <Value select="$colors?1"/>   <!-- returns: red -->
    <Value select="$colors?3"/>   <!-- returns: blue -->

The wildcard `?*` returns all members as a flat sequence:

    <Value select="string-join($colors?*, ', ')"/>
    <!-- returns: red, green, blue -->

### Array functions

All array functions are in the `array:` namespace. Arrays are immutable – functions like `array:put()` or `array:append()` return a new array, the original remains unchanged.

`array:size(<array>)`
  Number of members. `array:size([1, 2, 3])` returns `3`.
`array:get(<array>, <position>)`
  Return the member at the given position. `array:get(['a', 'b', 'c'], 2)` returns `b`.
`array:append(<array>, <value>)`
  New array with appended member. `array:append([1, 2], 3)` returns `[1, 2, 3]`.
`array:put(<array>, <position>, <value>)`
  New array with replaced member at the given position.
`array:remove(<array>, <position>)`
  New array without the member at the given position.
`array:subarray(<array>, <start>[, <length>])`
  Sub-array starting at the given position.
`array:join(<array-sequence>)`
  Concatenate a sequence of arrays into a single array.
`array:flatten(<array>)`
  Recursively flatten nested arrays into a flat sequence. `array:flatten([1, [2, 3]])` returns the sequence `1, 2, 3`.

## Maps

A map is a collection of key-value pairs. Keys are atomic values (typically strings or numbers), values can be anything.

### Creating maps

    <SetVariable variable="prices"
        select="map { 'apple': 1.50, 'pear': 2.30, 'cherry': 4.90 }"/>
    <SetVariable variable="empty" select="map {}"/>

Keys and values are separated by `:`, entries by `,`.

### Accessing map entries

The lookup operator `?` accesses entries by key name:

    <Value select="$prices?apple"/>   <!-- returns: 1.5 -->
    <Value select="$prices?cherry"/>  <!-- returns: 4.9 -->

The wildcard `?*` returns all values:

    <Value select="count($prices?*)"/>  <!-- returns: 3 -->

### Map functions

All map functions are in the `map:` namespace and return new maps.

`map:size(<map>)`
  Number of entries. `map:size(map { 'a': 1, 'b': 2 })` returns `2`.
`map:keys(<map>)`
  Return the keys as a sequence.
`map:get(<map>, <key>)`
  Return the value for the key. Empty sequence if the key does not exist.
`map:contains(<map>, <key>)`
  `true()` if the key exists.
`map:put(<map>, <key>, <value>)`
  New map with inserted or replaced entry.
`map:remove(<map>, <key>)`
  New map without the entry.
`map:merge(<map-sequence>)`
  Merge a sequence of maps. For duplicate keys, the last value wins.
`map:entry(<key>, <value>)`
  Create a map with a single entry.

## Practical examples

### Product catalog with prices

    <SetVariable variable="prices" select="map {
        'SKU-001': 29.95,
        'SKU-002': 79.00,
        'SKU-003': 149.90
    }"/>

    <Record element="product">
        <PlaceObject>
            <Textblock>
                <Paragraph>
                    <Value select="@name || ': ' || $prices?(@sku) || ' EUR'"/>
                </Paragraph>
            </Textblock>
        </PlaceObject>
    </Record>

### Color mapping

    <SetVariable variable="colors" select="map {
        'error': 'red',
        'warning': 'yellow',
        'ok': 'green'
    }"/>

    <Value select="$colors?($status)"/>

### Building a collection

Since arrays and maps are immutable, collections are built incrementally:

    <SetVariable variable="entries" select="[]"/>

    <SetVariable variable="entries"
        select="array:append($entries, 'First entry')"/>
    <SetVariable variable="entries"
        select="array:append($entries, 'Second entry')"/>

#### On this page