GetStateCounts - chart function
The GetStateCounts() chart function is used to calculate the total number of unique values matching the specified selection states.
With GetStateCounts() , you can combine the calculations from the following functions into a single function call: GetSelectedCount(), GetNotSelectedCount(), GetAlternativeCount(), GetPossibleCount(), and GetExcludedCount(). The count of selected excluded values is also available to add to the calculation. You can specify whether each function calculation adds or subtracts from the returned total.
Syntax:
GetStateCounts (field_name, state_name [, state_type1,...state_typeN])
Return data type: integer
Argument | Description |
---|---|
field_name | The field for which you are calculating the selection state. A non-existing field name results in a null outcome. |
state_name | The name of the alternate state. If the argument is empty ('') or null, the inherited alternate state is used. Use $ to explicitly use the default state. A named (non-empty) state name that doesn't match an existing state results in a null outcome. |
state_type |
A list of one or more state types for the field value. These state types will be aggregated into a count. A state type is specified using a key. Enter each key with single quotation marks. When this argument is omitted, the function returns a string with all available state counts for the field, in the same order as the enumeration. For a list of states you can use, see the table below. |
State types are referenced using specific keys. You can use the numeric or textual version of the key. Combine more than one key in the same expression to further customize the result. You can subtract the state count from the total, rather than adding it. To do this, use the textual key and prefix the state type with a minus symbol (-).
The state type, and if applicable, the minus symbol, need to be enclosed in a set of single quotation marks.
Field state type | Description | Numeric key | Textual key |
---|---|---|---|
Selected | Includes selected values in the calculation. For the equivalent function, see GetSelectedCount - chart function. | 1 | S |
Optional | Includes optional (not selected, but possible to select) values in the calculation. For the equivalent function, see GetPossibleCount - chart function. | 2 | O |
Deselected |
Includes not-selected values in the calculation. This state type is only available when the field is in and-mode. This state type returns the same calculation that the GetNotSelectedCount() function returns, assuming the include_excluded argument in that function is set to the default value of False. For more information about GetNotSelectedCount(), see GetNotSelectedCount - chart function. |
3 | D |
Alternative | Includes alternative values in the calculation. For the equivalent function, see GetAlternativeCount - chart function. | 4 | A |
Excluded | Includes excluded (not selected) values in the calculation. For the equivalent function, see GetExcludedCount - chart function. | 5 | X |
Selected excluded | Includes selected excluded values in the calculation. | 6 | XS |
When to use it
With GetStateCounts(), you can calculate a custom selection state. The function allows you to consolidate multiple function calls into a single function call, simplifying the process of writing your expression.
For example, you might need to calculate the total number of excluded, alternative, and selected excluded values for a field. You can use GetStateCounts() to calculate this total.
Examples | Results |
---|---|
=GetStateCounts(ProductName, Null(), 'S') | Returns the selected count for ProductName, in the inherited alternate state. |
=GetStateCounts(ProductName, '', 'X', 'A', 'XS') | Returns the total count of excluded, selected excluded, and alternative values for ProductName. The inherited alternate state is used. |
=GetStateCounts(ProductName, '', 'S', 'XS') | Returns the total count of user selections for ProductName, in the inherited state. |
Given that the ProductName field is in and-mode. =GetStateCounts(ProductName, '', 'D', '-O') |
Returns the number of not-selected values, subtracted by the number of possible values, for ProductName. The inherited alternate state is used. |
=GetStateCounts(ProductName, '', 'X', , 'A', 'XS') | Returns the total count of excluded, selected excluded, and alternative values for ProductName. The inherited alternate state is used. |
=GetStateCounts(ProductName, '$', 'O') | Returns the possible count for ProductName, in the default alternate state. |
=GetStateCounts(ProductName, 'StateA', 'S') | Returns the selected count of ProductName, in the alternate state named StateA. |