listWhich

The listWhich function iterates over a list and a logical statement. Each iteration evaluates the logical statement with a list substitution. listWhich returns either the first iteration that evaluates to true, or optionally all iterations that evaluate to true. The values returned can be an ID, text, or other list related data.

Syntax

The listWhich function accepts three inputs:

• a list name with optional inclusion/exclusions,
• a logical condition with iterators, and
• the data element to return.

Additionally, [ square brackets ] may be placed around a listWhich function in order to return all items in a comma-separated string, rather than just one.

Basic syntax

The syntax examples below use listWhich to return a single or multiple items, and show how to use listWhich to include or exclude options.

# Basic format, returning a single item
listWhich(LISTNAME; Logical statement with [id]; Item returned)

# Inclusion, returning a single item
listWhich(LISTNAME [List IDs to include]; Logical statement with [id]; Item returned)

# Exclusion, returning a single item
listWhich(LISTNAME -[List IDs to exclude]; Logical statement with [id]; Item returned)

# Returning multiple items by adding square brackets around the syntax
[listWhich(LISTNAME; Logical statement with [id]; Item returned)]

Advanced syntax

There are a few scenarios with list functions which require the Survey Programmer (SP) to explicitly state the list name along with the element [id] reference to help the system differentiate the list data. In these instances, the list name is prefixed to the [id] reference, separated by a colon. As with the regular element [id] reference, we also wrap this construction in square braces, e.g., '[LISTNAME:id]', to pull the option data through.

One common instance where this occurs is any time two or more lists are invoked in the list function, e.g.,'listWhich(LIST1, LIST2; ...)'. This often happens in a hidden variable using cvalue. Here, all list names will be prefixed to their list 'id' reference. See the section Using multiple lists below for more information.

# Using two different lists, allowing the logical condition to contain two axes of data, and the item returned to have two iterative substitutions
listWhich(LISTA, LISTB; Logical statement with [LISTA:id] [LISTB:id] iterators; Item returned using same style of iterator reference)

Examples

Skip and autocode

In this example, a sum-to-100% table is auto-coded if only one brand is selected. The target field ID is determined using Perl concatenation and listWhich. The conditions to trigger the setvalue widget and display the table are each controlled by a Boolean statement containing listCount.

If only one brand in Q5 was designated "Used in the last 12 months, primary supplier" (option 4), that brand will be auto-coded as Q6R and assigned a value of '100' since clearly 100% of the IT department's spending was on that brand. If option 4 was chosen for more than one brand, then Q6 will be displayed to the respondent, and the percent spending for each brand can be inputted.

See demo See code Restart demo

Using multiple lists

In this example, the respondent is asked to rank different suppliers on a 10 point scale in a question that repeats for different material types. All material-supplier combinations ranked 8 or higher are coded into a closed-ended variable, RATED8, which uses the crosslist TYPES_BY_SUPPLIERS. Since the block iterations will likely return multiple responses rated 8 or higher, we have applied [ square brackets ] surrounding the listWhich function and its description so it can return all matching responses.

Please scroll to see the full code.

See demo See code Restart demo

Using multiple lists continued

The following example asks respondents to indicate in which region of the country they live. Then, based on their response, they are asked about restaurants in their region. (McDonald's appears in all regions.)

The crosslist RESTXPANEL is introduced to be used in quotas — see RESTQTA_%%ID%% — where each quota collects up to five restaurants the respondent has eaten at or bought "take out" in the past 12 months. (This allows quota-capping options that are intersections of restaurant and panel.)

Finally, we introduce listWhich to use three different lists to find all the restaurants that were selected in the various quotas' intersections. The variable REST_WGHT uses cvalue to look through all three lists used (PANELS, REGIONS, and RESTLIST), using the IDs from each list to create a full logical expression:

cvalue: [listWhich(RESTLIST,PANELS,REGIONS; anyChecked($QRESTQTA_[REGIONS:id],'[RESTLIST:id]_[PANELS:id]'); [RESTLIST:id])]

The cvalue will "return" a collection of answers that will effectively be like a making multiple selections in a checkbox question with the restaurants in RESTLIST. Looking at RESTQTA_%%ID%% for each region (which, remember, uses a crosslist of RESTLIST and PANELS), we look for checked intersections and use listWhich to derive the restaurant ID from each. 

Please scroll to see the full code.

See demo See code Restart demo