Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • BehaviorSimple addition between two values
  • Return: Returns the sum of the two values
  • Arguments:  Two numbers
  • Syntax: x + y.
  • Example: '5 + 7' returns 12.  Many common uses.

-

  • BehaviorSimple subtraction between two values
  • Return: Returns the difference of the two values
  • Arguments:  Two numbers
  • Syntax: x - y.
  • Example: '3 - 12' returns -9.  Many common uses.

*

  • BehaviorSimple multiplication between two values
  • Return: Returns the product of the two values
  • Arguments:  Two numbers
  • Syntax: x * y.
  • Example: '6 * 6' returns 36.  Many common uses.

div

  • BehaviorSimple division between two values
  • Return: Returns the quotient of the two values
  • Arguments:  Two numbers
  • Syntax: x div y.
  • Example: '15 div 2' returns 7.5.  Many common uses.

not

  • BehaviorWill evaluate to true if the argument is false.  Otherwise will return false. 
  • Return: Returns a boolean value (true or false)
  • Arguments:  The value to be converted
  • Syntax: not(value_to_convert)
  • Example:  In some situations its easier to write the display or validation condition for when something shouldn't be shown.  You can then pass this to the not function which will reverse it, allowing it to be used as a display condition.  For example, not(/data/is_pregnant = "yes" and /data/has_young_children = "yes")

mod

  • Behaviorx mod y, gives remainder when x is divided by y 
  • Return: Returns a number which is the remainder on dividing the two numbers
  • Arguments:  two numbers (divisor and divident)
  • Syntax: x mod y.
  • Example:  '15 mod 4' returns 3; '6 mod 2' returns 0, and so on. Common use case, checking if a number is exactly divisible by another or not. eg, even number check, x mod 2 = 0 
  • Limitation:  Note that mod does not work correctly for negative arguments.  '-1 mod 12' should return 11, but returns -1.  To avoid this limitation, add multiples of the second argument to the first to ensure it's never negative 'x + ay mod y' (11 mod 12 = 11).  

if

  • Behavior Can be used to test a condition and return one value if it is true and another if that condition is false.  Behaves like the Excel if function.  
  • Return: Will return either the value of the true or false branch.
  • Arguments:  The condition, the true value and the false value.  
  • Syntax: if(condition_to_test, value_if_true, value_if_false)
  • Example:  This function is very useful for complex logic.  Ex. if(/data/mother_is_pregnant = "yes" and /data/mother_age > 40, "High Risk Mother", "Normal Mother").  If you need more complex logic (if a, do this, otherwise if b, do this, otherwise do c), you can nest if statements.  Ex. if(data/mother_is_pregnant = "yes", "Is Pregnant", if(/data/mother_has_young_children = "yes", "Newborn Child Care", "Not Tracked"))

cond

  • BehaviorTakes a set of test/expression pairs along with a default expression. The test conditions are evaluated in sequence and once one returns to true, 'cond' evaluates and returns the value of the corresponding expression and doesn't evaluate any of the other tests or expressions. If none of the test conditions evaluate to true, the default expression is returned.
  • Return: Will return the value corresponding to one of the expression or the default expression.
  • Arguments:  Any number of test condition & expression pairs along with a default expression.  
  • Syntax: cond(first_condition, value_if_first_true, second_condition, value_if_second_true, ..., default_value)
  • Example:  This function is useful for avoiding nested if-statements. Instead of writing if(data/mother_is_pregnant = "yes", "Is Pregnant", if(/data/mother_has_young_children = "yes", "Newborn Child Care", "Not Tracked")) you can write cond(data/mother_is_pregnant = "yes", "Is Pregnant", /data/mother_has_young_children = "yes", "Newborn Child Care", "Not Tracked")
  • Since: This function is available on CommCare 2.31 and later

random

  • Return:  Returns a random number between 0.0 (inclusive) and 1.0 (exclusive). For instance: 0.738  
  • Arguments: None
  • Usage: random()
  • Example Usage: When you need to generate a random number.  For example, to generate a number between 5 and 23, you can use (random()*(23 - 5)) + 5.  This will be something like 12.43334.  You can convert that to a whole number by using int((random()*(23 - 5)) + 5).  You can also reference questions instead of directly typing numbers.  Ex. int(random()*(/data/high_num - /data/low_num) + /data/low_num).  

count

  • Behavior Counts the number of items in a group (ex. a repeat group)
  • Return: Will return a number of items in the group. 
  • Arguments:  The group of items to be counted.
  • Syntax: count(/data/group)
  • Example:  This is useful if you have repeats in your form that allow the end user to choose the number of items.  You may want to calculate how many items were chosen and store them in a hidden value. Ex. count(data/repeat_group)
  •   

sum

  • Behavior Sum the items in a group (ex. a question in a repeat group)
  • Return: Will return the sum of all items.  
  • Arguments:  The group of questions to be summed.
  • Syntax: sum(question_group_to_be_summed)
  • Example:  This is useful if you have a repeat and need to add up the values entered for one of the questions. Ex.  sum(/data/my_repeat_group/some_number_question).  

...

  • BehaviorTakes two strings, a base string and a query string and returns the substring of the base string that follows the first occurrence of the query string, or the empty string if the base string does not contain the query string 
  • Return: A substring of the first argument
  • Arguments: A base string and a query string.
  • Syntax: substring-after(full_string, substring)
  • Example: substring-after('hello_there', 'hello_') -> "there"
  • Since: This function is available on CommCare 2.31 and later

Multi-Select Helper Functions

These functions are useful for working with a multi-select question. Multi-select questions store what is selected as a space-separated list of items. These functions will operate over that space separated list.  

selected

  • Behavior Checks to see if a value was selected from a multiselect question. You cannot just do /data/my_question = "my_value_1" - this will fail if both "my_value_1" and "my_value_2" were selected.  
  • Return: True if that particular value was selected.  Otherwise false.  
  • Arguments:  Two arguments, the multi-select question and the value to check.  
  • Syntax: selected(my_question, value_to_check)
  • Example:  selected(/data/my_multi_select_question, "my_value_4").  

count-selected

  • Behavior Counts the number of items selected in a multi-selected.
  • Return: Returns the number of items selected. 
  • Arguments:  The multi-select question  (or a space-separated list of items).
  • Syntax: count-selected(my_question)
  • Example:  You may want to check that at least three items were chosen in a multi-select question.  Ex. count-selected(/data/my_question) >= 3

selected-at

  • Return Returns the nth selected item.  
  • Arguments:  The multi-select question (or a space-separated list of items) and the number of selected item.  Note: The number is zero-indexed.  This means that to choose the first item, you need to enter 0, the second item, 1, etc.
  • Syntax: selected-at(my_question, number)
  • Example:  To return the 3rd selected item, you can use selected-at(/data/my_question, 2).

Sequence Functions

Sequence functions provide limited support for manipulating data which are either a space separated list of items (like the output of a checkbox question) or a "nodeset" reference (such as a query into the casedb, or a reference questions inside of a Repeat Group). These functions require a good understanding of the underlying data model and form and should be tested carefully. 

count

  • Behavior Counts the number of items in a group (ex. a repeat group)
  • Return: Will return a number of items in the group. 
  • Arguments:  The group of items to be counted.
  • Syntax: count(/data/group)
  • Example:  This is useful if you have repeats in your form that allow the end user to choose the number of items.  You may want to calculate how many items were chosen and store them in a hidden value. Ex. count(data/repeat_group)

distinct-values

  • BehaviorTakes a group of values (ex. a question in a repeat group) and returns a group of values which contains only one instance of each unique value in the input group. 
  • Return A group of values where no two values are the same. The order of the returned values is not guaranteed
  • Arguments:  Either a group of values, a reference to a group of values, or a string containing a space separated list of values. 
  • Syntax: distinct-values(input_sequence)
  • Examples :
    • join(" ", distinct-values("a a b b c c c")) → "a b c"
    • count(distinct-values(/data/myrepeat/myquestion)) → Number of unique responses to 'myquestion'
  • Since: This function is available on CommCare 2.41 and later

sort

  • BehaviorTakes 1 string, which should be a space-separated string representing a list of strings, and an optional boolean value indicating the desired sort direction, and returns the sorted list
  • Return: A string representing a sorted, space-separated list
  • Arguments: A string representing a space-separated list, and an optional boolean argument indicating direction (true() is ascending, false() is descending, default is ascending)
  • Syntax: sort("a b c d", true())
  • Examples: 
    • sort("4 2 1 5 3 2") --> "1 2 2 3 4 5"
    • sort("4 2 1 5 3 2", true()) --> "1 2 2 3 4 5"
    • sort("4 2 1 5 3 2", false()) --> "5 4 3 2 2 1"
  • Since: This function is available on CommCare 2.38 and later

sort-by

  • Behavior2 strings, each of which should be a space-separated string representing a list of strings, and an optional boolean value indicating the desired sort direction, and returns the result of sorting the 1st list by the 2nd list.
  • Return: A string representing a sorted, space-separated list
  • Arguments: 2 strings representing space-separated lists, and an optional boolean argument indicating direction (true() is ascending, false() is descending, default is ascending)
  • Syntax: sort-by("a b c d", "3 2 4 1", true())
  • Examples: 
    • sort-by("apple banana chip dog egg flea", "4 2 1 5 3 2") --> "chip banana flea egg apple dog" 
    • sort-by("apple banana chip dog egg flea", "4 2 1 5 3 2", false()) --> "dog apple egg flea banana chip" 
  • Since: This function is available on CommCare 2.38 and later

Multi-Select Helper Functions

These functions are useful for working with a multi-select question. Multi-select questions store what is selected as a space-separated list of items. These functions will operate over that space separated list.  

selected

  • Behavior Checks to see if a value was selected from a multiselect question. You cannot just do /data/my_question = "my_value_1" - this will fail if both "my_value_1" and "my_value_2" were selected.  
  • Return: True if that particular value was selected.  Otherwise false.  
  • Arguments:  Two arguments, the multi-select question and the value to check.  
  • Syntax: selected(my_question, value_to_check)
  • Example:  selected(/data/my_multi_select_question, "my_value_4").  

count-selected

  • Behavior Counts the number of items selected in a multi-selected.
  • Return: Returns the number of items selected. 
  • Arguments:  The multi-select question  (or a space-separated list of items).
  • Syntax: count-selected(my_question)
  • Example:  You may want to check that at least three items were chosen in a multi-select question.  Ex. count-selected(/data/my_question) >= 3

selected-at

  • Return Returns the nth selected item.  
  • Arguments:  The multi-select question (or a space-separated list of items) and the number of selected item.  Note: The number is zero-indexed.  This means that to choose the first item, you need to enter 0, the second item, 1, etc.
  • Syntax: selected-at(my_question, number)
  • Example:  To return the 3rd selected item, you can use selected-at(/data/my_question, 2).