Text Manipulation

Concatenate

Purpose

To combine the values of several values in the value dictionary into a new value using a delimeter to combine the values.

Type Name

‘concatenate’

Definition Syntax

[field_1] | [field_2] | [field_3] : [delimiter] : [decimals]

where:

  • ‘field_1’ is the first field to use in the concatenation. This may represent either a constant value or a key mapping to a value in the value dictionary.
  • ‘field_2’ is the second field to use in the concatenation. This may represent either a constant value or a key mapping to a value in the value dictionary.
  • Etc. for more fields to concatenate
  • ‘delimiter’ is the character that should be used to delimits the values in the result. For example, use ‘|’ when the value is pipe-delimited.
  • ‘decimals’ is number of decimals to round any numerical values to before concatenation. This is an optional specification and must be numeric.
Important

Note that currently the values you supply for ‘delimiter’ and ’decimals must be character and number, respectively. These values will be parsed as literals and can not be keys mapping to values in the value dictionary. This constraint will be removed in future upgrades if requested by users.

Example

The definition : *urban_rural|pave_use|surf_material : _*

will give a result that concatenates the values in the value dictionary that maps to fields/keys ‘urban_rural’, ‘pave_use’ and ‘surf_material’ using an underscore character (‘_’) to combine the values. For example, if the value mapping to these three keys are ‘U’, ‘1’ and ‘1CHIP’ then the function will return the value ‘U_1_1CHIP’.

Comment

The value provided for ‘decimals’ is useful when you want to concatenate several numbers that were calculated by previous JFunctions. Since JCass uses double precision, these numbers may have many decimals which could result in a long and ugly return value. So for example, if we want to create a value that is a combination of surface age and VCI as a comment when applying treatments, we can use the following syntax:

age = |par_surf_age| vci = | par_vci : ;

If we presume that the values mapping to keys ‘par_surf_age’ and ‘par_vci’ are 7.65123465 and 78.5499011, respectively, the above function will return:

‘age = 7.65123465; vci = 78.5499011’

which is rather ugly. To make this more elegant, we simply modify our function definition to:

age = |par_surf_age| vci = | par_vci : ; 2

This instructs our function to round numeric values to 2 decimals, so that our result is now:

‘age = 7.65; vci = 78.55’

Important

You cannot use a colon (‘:’) as a delimiter when concatenating values.

Split and Select

Purpose

To split a value and select one of the splitted values based on its index.

Type Name

‘split_and_select’

Definition Syntax

[field_to_split] : [delimiter] : [index_to_retrieve] : [default_value]

where:

  • ‘field_to_split’ represents the delimited value to split. This could be either a constant value or a key mapping to a value in the value dictionary.
  • ‘delimiter’ is the character that delimits the values in ‘field_to_split]. For example, use’|’ when the value is pipe-delimited.
  • ‘index_to_retrieve’ is the 1-based index of the value to retrieve from the splitted values. This must be a number (see note below).
  • ‘default_value’ (optional) is the optional default value to return if the splitted values contain fewer elements than what is specified by ‘index_to_retrieve’. OMIT this parameter if you want to throw an error when there are fewer elements than what is specified by ‘index_to_retrieve’.
Important

Note that currently the values you supply for ‘delimiter’ and ‘index_to_retrieve’ must be character, number respectively. The value specified for ‘default_value’ can be either a number or text. These values will be parsed as literals and can not be keys mapping to values in the value dictionary. This constraint will be removed in future upgrades if requested by users.

Example

  1. Use ‘par_setup_code : , : 3’ to split the value matching key ‘par_setup_code’ in the value dictionary by comma and then return the 3rd value after splitting. Thus, if the value matching key ‘par_setup_code’ is ‘mary, sue, sam, joe’, then the function will return ‘sam’ (value at the third index after splitting by comma). In this case, since there is no value specified for ‘default_value’, an error will be thrown if the splitted data contains fewer than 3 elements.

  2. Use ‘par_code : | : 2’ to split the value matching key ‘par_code’ in the value dictionary by pipe symbol and then return the 2nd value after splitting. Thus, if the value matching key ‘par_code’ is ‘4|16|32’, then the function will return ‘16’ (value at the second index after splitting by pipe-symbol). In this case, since there is no value specified for ‘default_value’, an error will be thrown if the splitted data contains fewer than 3 elements.

  3. Use ‘par_code : | : 4 : -999’ to split the value matching key ‘par_code’ in the value dictionary by pipe symbol and then return the 4th value after splitting. Thus, if the value matching key ‘par_code’ is ‘4|16|32’, then the function will return the specified default ‘-999’ because there are only 3 values in the splitted list but you have specified to select element at index 4.

String Replace

Purpose

To replace parts of a string with blanks or other strings.

Type Name

‘string_replace’

Definition Syntax

[field_to_use] : [to_be_replaced] : [replace_with]

where:

  • ‘field_to_use’ represents the string in which to replace certain parts. This could be either a constant value or a key mapping to a value in the value dictionary.
  • ‘to_be_replaced’ is the character or sub-string to be replaced. This value must be a literal string and cannot be a key mapping to a value in the Value Dictionary.
  • ‘replace_with’ is the character or sub-string to replace the sub-string in ‘to_be_replaced’ with. This can be an empty string.
Important

The String-Replace JFunction is currently NOT case-sensitive.

Example

‘fam_surf_mat : seal : cs’

This setup code will cause the value mapping to key ‘fam_surf_mat’ to be modified by replacing any occurrence of ‘seal’ (not case sensitive) with ‘cs’. Thus if the value mapping to key ‘fam_surf_mat’ in the value dictionary is any one of the following:

‘rack_seal’, ‘bongo_SEAL’, ‘binkySeal’ or ‘seal_mat’ then these values will become:

‘rack_cs’, ‘bongo_cs’, ‘binkycs’ and ‘cs_mat’.