String and ustring field conversions

Use the modify operator to perform the following modifications involving string and ustring fields:

Extract the length of a string.
Convert long strings to shorter strings by string extraction.

Convert strings to and from numeric values using lookup tables (see "String Conversions and Lookup Tables" ).

Conversion Specification	Description
`stringField`=string_trim [`character, direction, justify`] (`string`)	You can use this function to remove the characters used to pad variable-length strings when they are converted to fixed-length strings of greater length. By default, these characters are retained when the fixed-length string is then converted back to a variable-length string. The `character` argument is the character to remove. It defaults to NULL. The value of the `direction` and `justify` arguments can be either begin or end; `direction` defaults to end, and `justify` defaults to begin. `justify` has no affect when the target string has variable length. Examples: name:string = string_trim[NULL, begin](name) removes all leading ASCII NULL characters from the beginning of name and places the remaining characters in an output variable-length string with the same name. hue:string[10] = string_trim['Z', end, begin](color) removes all trailing Z characters from color, and left justifies the resulting hue fixed-length string.
`stringField`=substring(`string, starting_position, length`) `ustringField`=u_substring(`ustring, starting_position, length`)	Copies parts of `strings` and `ustrings` to shorter strings by string extraction. The `starting_position` specifies the starting location of the substring; `length` specifies the substring length. The arguments starting_position and length are uint16 types and must be positive (>= 0).
`stringField`=lookup_string_from_int16 [`tableDefinition`](`int16Field`) `ustringField`=lookup_ustring_from_int16 [`tableDefinition`](`int16Field`)	Converts numeric values to strings and ustrings by means of a lookup table.
`int16Field`=lookup_int16_from_string [`tableDefinition`](`stringField`) `int16Field`=lookup_int16_from_ustring [`tableDefinition`](`ustringField`)	Converts strings and ustrings to numeric values by means of a lookup table.
`uint32` = lookup_uint32_from_string [`tableDefinition`](`stringField`) `uint32` =lookup_uint32_from_ustring [`tableDefinition`](`ustringField`)
`stringField`= lookup_string_from_uint32 [`tableDefinition`](`uint32Field`) `ustringField`=lookup_ustring_from_uint32 [`tableDefinition`](`uint32Field`)	Converts numeric values to strings and ustrings by means of a lookup table.
`stringField` = string_from_ustring(`ustring`)	Converts ustrings to strings.
`ustringField` = ustring_from_string(`string`)	Converts strings to ustrings.
`decimalField` = decimal_from_string(`stringField`)	Converts strings to decimals.
`decimalField` = decimal_from_ustring(`ustringField`)	Converts ustrings to decimals.
`stringField` = string_from_decimal[fix_zero] [suppress_zero] (`decimalField`)	Converts decimals to strings. fix_zero causes a decimal field containing all zeros to be treated as a valid zero. suppress_zero specifies that the returned ustring value will have no leading or trailing zeros. Examples: 000.100 -> 0.1; 001.000 -> 1; -001.100 -> -1.1
`ustringField` = ustring_from_decimal[fix_zero] [suppress_zero] (`decimalField`)	Converts decimals to ustrings. See string_from_decimal above for a description of the fix_zero and suppress_zero arguments.
`dateField` = date_from_string [`date_format` \| `date_uformat`] (`stringField`) `dateField` = date_from_ustring [`date_format` \| `date_uformat`] (`ustringField`)	date from string or ustring Converts the string or ustring field to a date representation using the specified `date_format` or `date_uformat`. By default, the string format is yyyy-mm-dd. `date_format` and `date_uformat` are described in "date Formats".
`stringField` = string_from_date [`date_format` \| `date_uformat`] (`dateField`) `ustringField` = ustring_from_date [`date_format` \| `date_uformat`] (`dateField`)	strings and ustrings from date Converts the date to a string or ustring representation using the specified `date_format` or `date_uformat`. By default, the string format is yyyy-mm-dd. `date_format` and `date_uformat` are described in "date Formats" .
`int32Field`=string_length(`stringField`) `int32Field`=ustring_length(`ustringField`)	Returns an int32 containing the length of a string or ustring.
`stringField`=substring [`startPosition`,`len`] (`stringField`) `ustringField`=substring [`startPosition`,`len`] (`ustringField`)	Converts long strings/ustrings to shorter strings/ ustrings by string extraction. The `startPosition` specifies the starting location of the substring; `len` specifies the substring length. If `startPosition` is positive, it specifies the byte offset into the string from the beginning of the string. If `startPosition` is negative, it specifies the byte offset from the end of the string.
`stringField`=uppercase_string (`stringField`) `ustringField`=uppercase_ustring (`ustringField`)	Convert strings and ustrings to all uppercase. Non-alphabetic characters are ignored in the conversion.
`stringField`=lowercase_string (`stringField`) `ustringField`=lowercase_ustring (`ustringField`)	Convert stringsand ustrings to all lowercase. Non-alphabetic characters are ignored in the conversion.
`stringField` = string_from_time [`time_format` \| `time_uformat` ] (`timeField`) `ustringField` = ustring_from_time [`time_format` \| `time_uformat`] (`timeField`)	string and ustring from time Converts the time to a string or ustring representation using the specified `time_format` or `time_uformat`. The `time_format` options are described below.
`stringField` = string_from_timestamp [`timestamp_format` \| `timestamp_uformat`] (`tsField`) `ustringField` = ustring_from_timestamp [`timestamp_format` \| `timestamp_uformat`] (`tsField`)	strings and ustrings from timestamp Converts the timestamp to a string or ustring representation using the specified `timestamp_format` or `timestamp_uformat`. By default, the string format is %yyyy-%mm-%dd hh:mm:ss. The `timestamp_format` and `timestamp_uformat` options are described in "timestamp Formats" .
`tsField` = timestamp_from_string [`timestamp_format` \| `timestamp_uformat`] (`stringField`) `tsField` = timestamp_from_ustring [`timestamp_format` \| `timestamp_uformat`] (`usringField`)	timestamp from strings and ustrings Converts the string or ustring to a timestamp representation using the specified `timestamp_format` or `timestamp_uformat`. By default, the string format is yyyy-mm-dd hh:mm:ss. The `timestamp_format` and `timestamp_uformat` options are described "timestamp Formats" .
`timeField` = time_from_string `[time_format \| time_uformat`](`stringField`) `timeField` = time_from_ustring [`time_format` \| `time_uformat`] (`ustringField`)	string and ustring from time Converts the time to a string or ustring representation using the specified `time_format`. The `time_uformat` options are described below.

The following osh command converts a string field to lowercase:

osh "... | modify "lname=lowercase_string(lname)" | peek"

The diagram shows a modification that converts the name of aField to field1 and produces field2 from bField by extracting the first eight bytes of bField:

Shows the modify operator being used to convert a string to lowercase characters

The following osh command performs the substring extraction:

modify 'field1 = aField; field2 = substring[0,8](bField);'

The diagram shows the extraction of the string_length of aField. The length is included in the output as field1.

Shows the modify operator being used to extract the length of a string

The following osh commands extract the length of the string in aField and place it in field1 of the output:

$ modifyspec="field1 = string_length(aField); field2 = aField;"
$ osh " ... | modify '$modifySpec' |... "

Notice that a shell variable (modifySpec) has been defined containing the specifications passed to the operator.