Versions Compared

Key

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

...

today

  • Return:  Returns the current date.
  • Arguments: None
  • Usage: today()
  • Example Usage: You may want to use this when comparing against a user entered date.  For example, you may want to check that entered EDD is in the future (/data/edd > today()).  

now

  • Return:  Returns the current date.and time
  • Arguments: None
  • Usage: now()
  • Example Usage: You may want to use this if you want to calculate the current date and time in a hidden value. When saved to a case, will only save the date portion without the time. If the time portion is important, convert to a number before saving to a case: double(now()). 

here

  • Return:  Returns the current GPS position (Android only)
  • Arguments: None
  • Usage: here()
  • Example Usage: Use this to get the current global position as a space separated string of [latitude longitude altitude accuracy] where the last two fields are measured in meters. This can be used in the case list with the distance() function below to, for example, sort your case list by cases that are nearest to your current position.
  • Note: This function can be used only in case list or case detail calculations. It cannot be used within a form.

Formatting/Conversion Functions

These functions help convert one value into a value of another type.  (ex. converting a string value into a date value).  

boolean

  • Behavior: When passed a number, will return true if the number is not zero.  Otherwise it will return false.   When passed a string, will return true if the string is non-empty.  
  • Return: Returns true or false based on the argument. 
  • Arguments:  The value to be converted
  • Syntax: boolean(value_to_convert)
  • Example:  You may have stored a value that is 1 or 0 into a boolean for other logic.  boolean(/data/my_question) or boolean(23)

boolean-from-string

  • BehaviorWill convert a string value of "1" or "true" to true.  Otherwise will return false.  
  • Return: Returns true or false based on the argument. 
  • Arguments:  The value to be converted
  • Syntax: boolean-from-string(value_to_convert)
  • Example:  boolean(/data/my_question) or boolean("1")

number

  • Return: Returns a number based on the passed in argument.  
  • Behavior: Will convert a string (ex. "34.3") into a number.  Will cause an error if the passed in argument is not a number (ex. "two").  
  • Arguments:  The value to be converted
  • Syntax: number(value_to_convert)
  • Example:  If your application has a string value that needs to be stored as number.  number(/data/my_string_number) or number("453")

int

  • Return: Returns a whole number based on the passed in argument.  
  • Behavior: Will convert a string (ex. "34.3") or a decimal value into an integer.  It will round down (ex. 34.8 will be evaluated to 34). 
  • Arguments:  The value to be converted
  • Syntax: int(value_to_convert)
  • Example:  int(45.6) or int("45.6") will return 45.  You can also directly reference another question - int(/data/my_question).  

double

  • Return: Returns a double number based on the passed in argument.
  • Behavior: Will convert a string (ex. \ "34.3\") or a integer value into a double.
  • Arguments:  The value to be converted
  • Syntax: double(value_to_convert)
  • Example: double(45) or double(\"45\") will return 45.0. You can also directly reference another question - double(/data/my_question).

string

  • Behavior: Will convert a value into an equivalent string.  
  • Return: Returns a string based on the passed in argument.  
  • Arguments:  The value to be converted
  • Syntax: string(value_to_convert)
  • Example:  If you need to combine some information into a single string (using concatenate for example), you may need to convert some of those values into a string first.  concat("You are ", string(/data/age_question), " years old").  

date

  • BehaviorWill convert a string or a number value into an equivalent date.  Will throw an error if the format of the string is wrong or an invalid date is passed.  
  • Return: Returns a date
  • Arguments:  The value to be converted (either a string in the format YYYY-MM-DD or a number).  
  • Syntax: date(value_to_convert)
  • Example:  If you have stored any date values in a case, they are actually stored as a string in the format YYYY-MM-DD.  You will need to convert them into a date prior to using that for date math or when formatting for display.  (ex. date(/data/case_edd)).  
  • Notes:
    • When working with dates prior to 1970 you should use date(floor(value_to_convert)) in order to avoid an issue where negative numbers are rounded incorrectly.

 

format-date

  • BehaviorWill change the format of a date for display 
  • Return: Returns a string conversion of the provided date.  
  • Arguments:  the date to be converted, and a string describing how it should be formatted.  The syntax for the display format string is below
    • ‘%Y’ = year
    • ‘%y’ = 2 digit year
    • ‘%m’ = 0-padded month
    • ‘%n’ = numeric month
    • '%B' = full text month (English) (January, February, etc.)
    • ‘%b’ = short text month (Jan, Feb, etc.)
    • ‘%d’ = 0-padded day of month
    • ‘%e’ = day of month
    • ‘%H’ = 0-padded hour (24 hour time)
    • ‘%h’ = hour (24 hour time)
    • ‘%M’ = 0-padded minutes
    • ‘%S’ = 0-padded second
    • ‘%3’ = 0-padded milliseconds
    • ‘%a’ = three-letter short text day (Sun, Mon, etc.)
    • '%A' = full text day (English) (Sunday, Monday, etc.)    Since: This format is available on CommCare 2.32 and later
    • '%w' = numeric day of the week (0 through 6, 0 is Sunday)  
  • Syntax: format-date(date_to_convert, display_format_string)
  • Example:  When you are displaying a date in the display text, its useful to format it in a manner that is readable for your end users (the default is YYYY-MM-DD).  Some examples
    • format-date(date(/data/my_date), "%e/%n/%y") will return a date that looks like D/M/YY
    • format-date(date(/data/my_date), "%a, %e %b %Y") will return a date that looks like Sun, 7 Apr 2012. 
    • format-date(now(), '%y/%n/%e - %H:%M:%S') will return the current date and time in the format YY/M/D - HH:MM:SS
    • format-date(now(), '%H:%M:%S') will return the current time in the format HH:MM:SS

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 can be found at Alternate Calendar Formats for CommCare Android.

Logic and Math

+

...