Name: combine

Type: command

Syntax: combine <arrayName> {using | by | with} <primaryDelimiter> [and <secondaryDelimiter>]

Syntax: combine <arrayName> {using | by | with} <primaryDelimiter> as set

Syntax: combine <arrayName> {using | by | with} {row | column}

Summary:
Transforms an <array> into a list.

Introduced: 1.1

OS: mac, windows, linux, ios, android, html5

Platforms: desktop, server, mobile

Example:
combine myArray using comma

Example:
combine myArray by row

Example:
local tArray
put "apple" into tArray[1]
put "banana" into tArray[2]
combine tArray using return and ":"

## RESULT tArray
## 1:apple
## 2:banana

Parameters:
primaryDelimiter:
A character or expression that resolves to a character.

secondaryDelimiter:
A character or expression that resolves to a character.

arrayName (array): An array variable.

Description:
Use the <combine> command to display an <array> in a field or to process
an <array> using string operators, functions, and chunk expressions.

The <combine> command combines the <element|elements> of the <array> into a single
variable. After the command is finished executing, the variable
specified by <arrayName> is no longer an <array>.

If the first form of the command is used, the <element|elements> of the original
<array> are separated by the <primaryDelimiter>. For example, if the
<primaryDelimiter> is return, the content of each <element> of the
original <array> appears on a separate line.

If you specify a <secondaryDelimiter>, the <key> corresponding to each
<element> is added to the <element|element's> content, separated from the content by
the <secondaryDelimiter>. For example, if the <primaryDelimiter> is
return and the <secondaryDelimiter> is tab, each line of the resulting
variable contains an <element|element's> <key>, a tab character, and the <element|element's>
content. If you don't specify a <secondaryDelimiter>, then the <key|keys> are
lost in the transformation.

If you use the `as set` form the <combine> command rebuilds the list using
the delimiter passed; the values of the <array> are ignored.

> *Note:* The order of the elements is based on case-sensitive
> lexicographical sorting of the array's keys.  The ordering is
> equivalent to:
>
>     local tKeys
>     put the keys of tArray into tKeys
>     set the caseSensitive to true
>     sort tKeys text ascending

If the second form of the <combine> command is used, the elements of the
original <array> are considered to be either columns or rows, separated by
the <columnDelimiter> or <rowDelimiter> property respectively.

Combining an <array> by row converts the <array> into a table with rows 
separated by the <rowDelimiter>. Each row in the resulting string is 
the contents of the corresponding <key> in the <array>.

Combining an <array> by column converts the <array> into a table
with columns separated by the <columnDelimiter> <property>. Each column of
the resulting string is the contents of the corresponding <key> in the
<array>.

>*Note:*  The combine by row and combine by column forms can only be
> used with numerically <key|keyed> arrays

Changes:
The combine by row / column form was added in 2.8.1

References: [] (keyword), array (glossary), columnDelimiter (property), 
element (glossary), extents (function), intersect (command), key (glossary), 
keys (function), rowDelimiter (property), sort (command), split (command), 
union (command), using (keyword)

Tags: arrays
