`g_lst(G;S;O;X)`

Returns a list value for each group, in the specified order. (Available as of version 15.21)

Function type

Vector only

Syntax

g_lst(G;S;O;X)

Input

Argument	Type	Description
`G`	any	A space- or comma-separated list of column names Rows are in the same group if their values for all of the columns listed in `G` are the same. If `G` is omitted, all rows are considered to be in the same group. If any of the columns listed in `G` contain N/A, the N/A value is considered a valid grouping value.
`S`	integer	The name of a column in which every row evaluates to a 1 or 0, which determines whether or not that row is selected to be included in the calculation If `S` is omitted, all rows will be considered by the function (subject to any prior row selections). If any of the values in `S` are neither 1 nor 0, an error is returned.
`O`	integer	A space- or comma-separated list of column names that determine the row order within a particular group If `O` is omitted, the order is the current display order of the table. If any of the values in `O` are N/A, an error is returned.
`X`	any simple type	A column name

Return Value

For every row in each group defined by G and ordered by O (and for those rows where S=1, if specified), g_lst returns a list value for each group specified by G for the column listed in X.

If no rows have valid (non-N/A) values for X, the result is N/A.

Note: An empty string is not considered to be an N/A for the purposes of g_ functions.

Sample Usage

<base table="pub.doc.samples.ref.func.g_func_time_series_sample_usage"/>
<willbe name="g_lst_1" value="g_lst(state;include;order;value)"/>
<willbe name="g_lst_2" value="g_lst(state city;include;order;value)"/>

Example

In the following example, we use r_mappkg(C;S;X) to create a package out of each row of table data in pub.demo.retail.item. Then, we use g_lst(G;S;O;X) to return a list of items grouped by transaction ID. Finally, we convert that list of records (objects) into JSON format.

First, we create a record column and use r_mappkg(C;S;X) to create a package value for each row in the table:

<willbe name="record" value="r_mappkg(;;rcv_)"/>

Then, we create a group column and use g_lst(G;S;O;X) to create a list out of the package in the record column, grouped by transid:

<willbe name="group" value="g_lst(transid;;;record)"/>

Since each value for a transaction ID will be the same, we can select only the first record of each transaction ID, as follows:

<sel value="g_first1(transid;;)"/>

Then, we can use enjson(V;O) to convert the list in the group column into JSON:

<willbe name="json" value="enjson(group;)"/>

And let's display only those columns of interest to us:

<colord cols="transid,json"/>

If you display the full details of the json column, you will see the complete list of records for each transaction ID in JSON format. In the case of transaction ID 535, there are three records, formatted in JSON.