...

There are also uses of format-date() which can format dates to be appropriate for alternate calendars, such as the Nepali or Amharic calendars. More detail details can be found at Alternate Calendar Formats for CommCare AndroidDate and Calendar Display.

Logic and Math

+

• Behavior: Simple 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.

...

• Behavior:  Evaluates a value against a regular expression and returns true if the value matches that regular expression.

• Return: true or false

• Arguments:  There are two arguments, the value to be validated and the regular expression as a string. 

• Syntax: regex(value, regular_expression)

• Example:  This is useful when doing complex validation against some value.  For example, to validate that a string contains only numbers, you can use regex(/data/my_question, "^[0-9]+$").   You can test and develop other regular expressions using httphttps://www.regexr.com/.  Also see the Advanced Validation Conditions pagehttps://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2285240323/Validation+Conditions#Advanced-Validation-Conditions.

uuid()

• Behavior:  Calculates a random hexadecimal (0-9, a-f) identifier of 32 characters long.  There are 16^32 = 3.4*10^38 possibilities for this kind of identifier.  The statistical chance that these values are not unique is extremely low, so we call it a unique identifier.  
  https://en.wikipedia.org/wiki/Universally_unique_identifier

• Return: The unique id.  

• Arguments:  none!

• Syntax: uuid().  Omitting the argument results in a 32 digit unique identifier.

• Examples: uuid() could return 24235c71-09bf-40e8-87d2-00767efd7a14 or 4498b8a9-0af4-4413-994a-ad44e166f073

uuid(argument)

• Behavior:  Calculates a random alphanumeric (0-9, A-Z) identifier of a particular length.  The longer the length, this more likely it is that this random number is unique across the project.  If the argument is 3, then there are 36^3 = 4.7*10^4 possibilities.  This is a large number of possibilities, but not large enough to ensure that there is not a duplicate.  If the argument is 32, there will be 36^32 = 6.3*10^49 possibilities, which is statistically very unlikely to produce a duplicate.  Note that uuid() with an argument is not a traditionally-defined UUID as described here; : https://en.wikipedia.org/wiki/Universally_unique_identifier.

• Return: The random id.  

• Arguments:  The length of the random id

• Syntax: uuid(length).

• Examples: uuid(4) could return WZV4 or 5J43.  uuid(32) could return 4KV5JRAUM48YS9SP2SWX2G94UEAJBHXQ or N9HTXSZPJI0H8GQS2SBW88V881CJEN1I.

coalesce

• Behavior:  Useful for choosing which of two values to return.  Will return the non-null/empty value.  If both are not null, will return the first argument.  

• Return: One of the values

• Arguments:  The two values to be coalesced

• Syntax: coalesce(value_1, value_2).  

• Example:  This is useful if you want to use a default value when referring to a question which may or may not have been answered.  Ex. coalesce(/data/my_question, "my default value"). 

• Note: Since CommCare version 2.31, coalesce accepts more than 2 arguments, returning the first non-null argument.

...

• Behavior:  Performs a checklist computation, calculating if at least some number or a maximum number of items are answered a particular way.  

• Return: True or false depending on the checklist (if number of true items is between the minimum and maximum specified).  

• Arguments:  

  • The first argument is a numeric value expressing the minimum number of factors required.  If -1, no minimum is applicable

  • The second argument is a numeric value expressing the maximum number of allowed factors.  If -1, no maximum is applicable

  • arguments 3 through the end are the individual factors, each treated as a boolean.  

• Syntax: checklist(min_num, max_num, checklist_item_1, checklist_item_2, ...)  

• Example:  You may want to check that the mother has at least 2 out of 4 high risk symptoms.  Ex. checklist(2, -1, /data/high_risk_condition_1 = "yes", /data/high_risk_condition_2 = "yes", /data/high_risk_condition_3 = "yes", /data/high_risk_condition_4 = "yes")

...

• Behavior:  Raises a number to an exponent, bⁿ 

• Return: The value of the the first argument, raised to the power of the second argument

• Arguments: 
  

  • The first argument is a numeric value

  • The second argument is the numeric exponent to which the first argument should be raised. It can be a negative value.

    • NOTE: Due to technical restrictions the Exponent can only be an integer (non-decimal) value on Java Phones (Nokia, etc.). Decimal values can be used elsewhere.

• Syntax: pow(value, exponent)

• Example:  pow(2.5, 2)

• Since: The pow function is available on CommCare 2.9 and later.

...

• Behavior: Performs the tangent operation

• Return: The tangent of the value

• Arguments: The value whose tangent you want to calculate

• Syntax: tan(number)

• Example: tan(.5)

String Functions

...

concat

• Behavior:  Joins multiple strings together.  The arguments can either reference a question or be a directly type string.  

• Return: Joined string

• Arguments:  Multiple arguments (as many as needed) that represent the strings to be joined in order.  

• Syntax: concat(text1, text2, text3, ...)

• Example: concat("Full name: ", /data/first_name, " ", /data/last_name) 

...

• Behavior: Takes a message string, a Base64-encoded secret key and an algorithm name and returns a Base64 encoded encrypted message. The only algorithm currently implemented is AES encryption in the GCM mode.

• Return: A Base64 encoded sequence of bytes, structured as follows:

  • Byte 0: the length of the initialization vector (IV_LEN)

  • Bytes 1 to IV_LEN: the initialization vector, which is needed for AES decryption

  • Bytes IV_LEN+1 to end: the encrypted message bytes

• Arguments: A message string, a Base64-encoded secret key, which should be 256 bits (32 bytes) for AES, and an algorithm name string, which should currently always be 'AES'.

• Syntax: encrypt-string(message, key, algorithm)

• Example: encrypt-string('abcdef', 'Vx1ZqYO06xSiYRoJNAqPtjXGAbjRS/lKqMukkoD0vEc=', 'AES') -> "DAqlxpaPUrTPsCnQ2yVoVM6xf7YqvN1LNA7jdp34NAb25yI="

• Since: This function is available in CommCare 2.51 and later.Click here for an example.

substring-before

• Behavior: Takes two strings, a base string and a query string and returns the substring of the base string that precedes 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-before(full_string, substring)

• Example: substring-before('hello_there', '_there'). In conjunction with string-length, this can calculate the index of the 1st occurrence of a query string: string-length(substring-before(base_string, query_string))+1

• Since: This function is available on CommCare 2.31 and later

...

• Behavior: Takes a json string and a string property name and returns the value of that property from the json string.

• Return: A string value for the property name passed in 

• Arguments: A string (stringified json object), a string property name

• Syntax: json-property(json_string, property_name)

• Example: json-property('{"full":"New Canada St., 3855 Brienz, Switzerland","geopoint":"46.748107 8.0473685","zipcode":"3855","postcode":"3855","city":"Brienz","region":"Bern","state_long":"Bern","state_short":"CH-BE","country":"Switzerland","country_short":"ch","street":"New Canada St."}', 'city') -> "Brienz"

• Since: This function is available in CommCare 2.51 and later.

...

• Behavior: 2 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

...