g_enum(G;S;O;X)

Returns the enumeration of unique values across one or more columns within a given group.

Function type

Vector only

Syntax

g_enum(G;S;O;X)
t_enum(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 space- or comma-separated list of column names

If more than one column is specified, the function enumerates the unique combination of values across all of the columns specified.

Return Value

For every row in each group defined by G (and for those rows where S=1, if specified), g_enum returns an integer value corresponding to the enumeration of that row. Each unique value in X is assigned a number, beginning with 1 and increasing by 1 each time a new unique value is encountered. Repeated values are assigned the same number. The order of the values is determined by the values in O; if O is omitted, the order is the current display order of the table.

For those rows where S=0, the result is 0.

Sample Usage

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

Example

Let's take a look at g_enum(G;S;O;X) in action. We'll use the Store Master table (pub.demo.retail.store) to demonstrate the use of this function. When we open the table, it looks something like this:

For demonstration purposes, let's hide some of the columns that will not be relevant to this example using <colord:
<colord hide="addr,city,state,zip,sqft"/>

So now our table looks like this:

Let's say we want to enumerate all of the unique divisions for all of the stores in our table. Since we want to do the enumeration for the entire table, we'll omit the G parameter. We'll omit the S parameter since we want all of the rows to be considered by the function and not just a subset, and we'll omit the O parameter since we're not particularly concerned about the ordering for this example. For the X parameter, we'll specify the sdiv column since we want to enumerate the unique divisions.

Let's create a computed column for the enumeration:
<willbe name="enum_div" value="g_enum(;;;sdiv)"/>

This will give us a column that looks like the following:

We can see that the two rows where the division is 5 have been enumerated with the value 1, and the one row with division 6 has been given the value 2.

If we do the enumeration on the type column instead:
<willbe name="enum_type" value="g_enum(;;;type)"/>

We get the following results:

Now we see that the row with type "SHOPPING CENTER" has been given the enumerated value 1, and the two rows with type "STAND ALONE" have the value 2.

You can specify multiple columns for X in g_enum(G;S;O;X), so we could specify both the sdiv and type columns:
<willbe name="enum_div_type" value="g_enum(;;;sdiv type)"/>

Now we see that each unique combination of sdiv and type has been given a unique enumeration.

Additional Information

  • The t_ version of this function defaults the G argument and omits the S argument. The default for G is set at table load time based on the organization of the table.