Main Help → GENerel Reference → Expressions

Expressions

You can use expressions to make calculations. Furthermore, any argument to a command can be an expression.

Expressions

An expression combines any number of numbers, strings, variables, GEDCOM Expressions, and functions with operators. An expression evaluates to a numeric or string value. The general, recursive definition of an expression is

[EXPRESSION] = [sign] [ATOMIC] [op] [ATOMIC] [op] [ATOMIC] ... [op] [ATOMIC]

where

• [sign] is an optional leading sign of + or -
• [op] are operators that determine how the [ATOMIC]'s are combined. The options are:
  • + for addition
  • - for subtraction
  • * for multiplication
  • / for division
  • ^ for raising to a power
  • & for string concatenation
  When there are multiple operators, the operations are combined with the usual operator precedence of ^ followed by * and / followed by + and -. When there are multiple operators of the same precedence, they are evaluated left to right.
• [ATOMIC] are the elements that are combined. The possible atomics are:
  • An unsigned number (23, 2.234, 3e2, 4.56e-3, ...)
  • A variable (such as #varname, #x[2], #z[#i][#j], etc.) and the value of the variable is used. The variable must have been previously defined.
  • A GEDCOM Expression beginning in an "@" sign that evaluates to some text extracted from the genealogy data.
  • Text in quotes ("some text") and the value is the text after the quotes are removed.
  • Unquoted text and the value is all the text between the operators after all spaces have been removed. If the resulting text is one of the following case-sensitive keywords, it will be replaced with special characters:
    • return - inserts a line-ending return character
    • tab - inserts a tab.
    • quote - inserts a double-quote character (")
    • pi - inserts numerical value of π
    To have the value equal to one of these keywords or include spaces, the [ATOMIC]'s text must be quoted.
  • Another expression in parenthesis or ([EXPRESSION]) and the value of the [ATOMIC] is the value of the included expression.
  • A function of an expression (such as sin([EXPRESSION])) and the value of the [ATOMIC] is the value of the function applied to the value of the expression. The possible useful functions when formatting genealogy are:
    • local() - look up a localized string in the list of strings for the current language in the browser style using the provided key. If the string is not found, return the key itself.
    • string() - the same as local(), but, if the string is not found, return empty string.
    • length() - number of characters in a string.
    • words() - number of words in a string.
    • firstWord() - first word in a string.
    • lastWord() - last word in a string.
    • removeFirstWord() - string with first word removed.
    • removeLastWord() - string with last word removed.
    • upperCase() - convert string to upper case.
    • lowerCase() - convert string to lower case.
    • titleCase() - convert to string with capitalized words.
    • trim() - remove leading and trailing whitespace from a string.
    • rjust(string,num) - return string with leading spaces to right justify it in string length num. If string is too long truncate to first num characters.
    • val(ref) - the value of the variable referenced by ref. Returns "_nav_" (for "not a variable") rather than an error if ref does not refer to a defined variable.
    • soundex() - convert any string to its SoundEx code, which is code used in genealogy to compare names and places by their sound.
    • dateformat() - convert any valid date to the user-preferred date style (selected in GEDitCOM II date settings).
    • dateyear() - convert any valid date to just the year (or years) of the date.
    • exectime() - execution time elapsed since start of an Internal Script (prior to 3.5/1.0, a argument was required, e.g., exectime(0)).
    • chars(c1,c2,target) - returns characters c1 to c2 (inclusive) of target (the first character is character 1). Either c1 or c2 can be <=0 to indicate character number relative to end of the string (e.g., 0 is last character, -1 is next to last, etc.) (since 3.5/1.0, see below for older versions).
    • word(w1,target) - returns word w1 of target. If w1<=0, it specifies word number relative to end of the string (e.g., 0 is last word, -1 is next to last, etc.) (since 3.5/1.0, see below for older versions).
    • offset(s1,c1,target) - returns offset of string s1 in target at or after character c1 (the first character is character 1) or returns 0 if string s1 is not found. The search is case insensitive (since 3.5/1.0, see below for older versions).
    • replace(s1,s2,target) - returns string where all occurrences of string s1 in target are replaced with string s2 (since 3.5/1.0, see below for older versions).
    • round(num,digits) - returns number rounded to the provided number of digits past the decimal point (since 3.5/1.0, see below for older versions).
    • hexchar(string) - converts a hexadecimal string (e.g., "2a4f", case insensitive) into a one-character string. If the hexadecimal string contains "e", it must be quoted to avoid conversion to a number (e.g., use hexchar("25e6") instead of hexchar(25e6) because later will convert the function argument to number 25000000). Note that you can insert unicode characters into strings using the MacOS text panel. This function is useful for inserting non-printing or special characters.
    • cond(test,iftrue,iffalse) - if test is an integer not equal to 0 or a string equal to "true" (case insensitive), return iftrue, otherwise return iffalse.
    • ord(number) - converts to ordinal number ("first", "second", "third", etc.). Numbers greater than 13 get number appended ordinal ("14th", "21st", "33rd". etc.).
    • card(number) - converts to cardinal number ("zero", "one", "two", etc.). Negative numbers and numbers 10 or higher get just the number.
    • alpha(number) - converts to lower case letter ("a", "b", "c", etc.). Zero and numbers greater than 26 or less than -26 get just the number.
    • roman(number) - converts to upper case Roman Number ("I", "IV", "MMMXXIV", etc.). Zero and numbers greater than 4999 or less than -4999 get just the number.
    • int() - integer part
    • mod(x,y) - returns x mod y or remainder after integer divide x/y
    • sgn(x) - -1 for x<0, 0 for x=0, and +1 for x>0
    • sign() - 1 if argument is positive or 0 if it is negative or zero
    • rand() - random number between 0 and the argument
  • Prior to version 3.5/1.0, string functions were limited to a single argument. As a result, commands that needed multiple arguments had to combine them into a single string. The deprecated versions still work, but are only needed if you want internal scripts or browser styles by be compatible for versions before 3.5/1.0:
    • chars(string) - same as chars(c1,c2,target) where string argument concatenates c1, c2, and target separated by backslashes into a single string c1\c2\target (e.g., "2\6\"&#var). If omitted, c1 defaults to 1 and c2 defaults to length of target.
    • word(string) - same as word(w1,target) where string argument concatenates w1 and target separated by a backslash into a single string w1\target (e.g., "5\"&#var).
    • offset(string) - same as offset(s1,c1,target) where string argument concatenates s1, c1, and target separated by backslashes into a single string s1\c1\target (e.g., #sarg&"\3\"&#var). c1 can be omitted to find s1 any place in string. Note that this function fails if s1 contains back slashes. Use the multiargument method instead or for versions older than 3.5/1.0 use the offset scripting command.
    • replace(string) - same as replace(s1,s2,target) where string argument concatenates s1, s2, and target separated by backslashes into a single string s1\s2\target (e.g., #arg1&"\text\"&#var). s2 may be omitted to delete all occurrences of string s1. Note that this function fails if s1 or s2 contain back slashes. Use the multiargument method instead or for versions older than 3.5/1.0 use the replace scripting command.
    • round(sting) - same as round(num,digits) where string argument should concatonates numeric value and an integer separated by a space. For example, if #nmbr=34.6745 and #digits=2 use round(#nmbr&" "&#digits).
  • The following functions are available and do mathematical calculations. They are usually not useful when formatting genealogy data:
    • sin() - sine of argument in radians
    • cos() - cosine of argument in radians
    • tan() - tangent of argument in radians
    • asin() - inverse sine with result in radians
    • acos() - inverse cosine with result in radians
    • atan() - inverse tangent with result in radians
    • exp() - exponential
    • log() - natural log
    • log10() - log base 10
    • sqrt() - square root
    • abs() - absolute value
    • sinh() - hyperbolic sine
    • cosh() - hyperbolic cosine
    • tanh() - hyperbolic tangent
    • erf() - the error function of the argument
    • erfc() - complementary error function of the argument