String Functions

This section provided explanations and demos of the various string functions in Omnis Studio.

To view all of the string functions:

1. Press F9 to open the Catalog.
2. Click the Functions tab.
3. Click String in column one. All of the string functions are displayed in column two.
   
   If you hover or one of the string functions a tooltip tip appears providing you with the syntax and a short description of the function.

You can drag and drop any of the functions into your code. Omnis Studio conveniently copies the function and parameter names into your code.

If your are entering code in the code editor, you can drag and drop or double-click on any of the constants in the F9 Catalog. Omnis Studio will copy the constant to your code.

asc - ASCII

asc(String,CharNum)

Returns the ASCII value of a character in a string. The position of the character is specified by CharNum. The value returned is between 0 and 255, or -1 if number is less than 1 or greater than the length of string.

; asc(string,number)
Calculate Ascii as asc('Quantity',1)

cap - Capitalize

cap(String)

Returns the capitalized representation of a string. The first letter of each and every word in the string will capitalized, the rest of the letters of each work will be lower case.

; cap(String)
Calculate CapString as cap('gRaVeS, hutton, MONKS')

chk - Check

chk(string1,string2,string3)

Returns true or false depending on a character-by-character comparison of string1 with string2 and string3 using the ASCII value of each character for the basis of the comparison.

Firstly, each character of string2 is compared with the corresponding character of string1 to ensure that, for each character, string2<=string1. A character is said to be less than or greater than another character if its ASCII code is less than or greater than the ASCII code of the corresponding character.

Secondly and provided string2<=string1, each character of string1 is compared with the corresponding character of string3 to ensure that, for each character, string1<=string3.

If both conditions are true, that is string2<=string1 and string1<=string3 are both satisfied, the function returns true, otherwise it returns false.

; Is 'b' >= '' and <= 'c'?
Do chk('b','','c') Returns FlagOK ;; Returns true.

; Is 'B' >= 'B' and <= 'C'?
Do chk('B','B','C') Returns FlagOK ;; Returns true.

; Is 'SD04' >= 'AA00' and <= 'ZZ99'?
Do chk('SD04','AA00','ZZ99') Returns FlagOK ;; Returns true.

; Is 'SDA4' >= 'AA00' and <= 'ZZ99'?
Do chk('SDA4','AA00','ZZ99') Returns FlagOK ;; Returns false.

chr - Characters

chr(CSVAsciiNumbers)

Returns a string by converting ASCII codes to characters. Any argument with a value less than zero or greater than 255 is ignored.

Only normal printable characters should be stored in Character or National fields. Also, since Omnis uses the character with ASCII value 0 as the end of string marker, this means that if you use this character in any other way, the part of the string following the 0 value is ignored.

Control characters in the data file may also cause problems when trying to import or export data.

Records with index fields which contain characters with ASCII value 255 may not have the correct index order. It is safe, however, to have unprintable characters in the text for the Transmit text commands.

The lower ASCII values are non-visible characters. e.g. kCr=13, kTab=9, kLf=10

Click the Run Demo button in the StudioTips Browser window to view the ASCII characters from 1-255.

The following sample code is used to build the list for the demo.

; Define the list.
Do List.$define()
Do List.$cols.$add('asciivalue',kInteger,kLongint)
Do List.$cols.$add('character',kCharacter,kSimplechar,10)

; Loop through the ascii characters from 1 to 255 building the list.
For Counter from 1 to 255 step 1
   Do List.$add(Counter,chr(Counter))
End For

; The list can now be viewed in a string grid or data grid.

con - Concatenate

con(string1,string2[,string3]...)

Returns a string by concatenating two or more string values. con() has a limit of 100 parameters.

Calculate FirstNameA as "Jack"
Calculate FirstNameB as "Jill"
Calculate LastName as "Hill"
Calculate FullName as con(FirstNameA," and ",FirstNameB," ",LastName)
; Results in "Jack and Jill Hill"

Note the use of spaces in the above example.

The pick() function can be useful in combination with con() where you only want a character or string included if the value of another string is not empty.

Calculate FirstNameA as "Jack"
Calculate FirstNameB as ""
Calculate LastName as "Hill"
Calculate FullName as con(FirstNameA," and ",FirstNameB," ",LastName)
; Results in "Jack and Hill"

; The pick() function can be used to decide whether or not to include ' and '.
Calculate FullName as con(FirstNameA,pick(FirstNameB<>"",""," and "),FirstNameB," ",LastName)
; Results in "Jack Hill"

decstr - Decode String

decstr(String,Key)

Decodes a string which was previously encoded using the encstr() function. If the key is omitted, Omnis uses its default value for the key.

; Set the key.
Calculate Key as 'MySecretKey'

; Encode the string.
Calculate Encode as encstr('piano',Key)

; Decode the encoded string.
Calculate Decode as decstr(Encode,Key)

encstr - Encode String

encstr(String,Key)

Encodes the string using the key. If key is omitted, Omnis uses its default value. The return value of encstr() is a string that is difficult to decode without knowing the key. To decode the string, and return the original value, use the decstr() function.

; Set the key.
Calculate Key as 'MySecretKey'

; Encode the string.
Calculate Encode as encstr('piano',Key)

; Decode the encoded string.
Calculate Decode as decstr(Encode,Key)

For tougher encryption see the Blowfish External under the Externals subject.

isnumber - Is Number

isnumber(String)

Returns true if the specified string can be evaluated as a number, otherwise false is returned.

; isnumber(String)
Calculate bNumber as isnumber('5,678.45')
Calculate bNumber as isnumber('123QRJ')
Calculate bNumber as isnumber('123 45')

jst - Justify

jst()

is a function with many uses.

Search the F1 Help for jst to see all the different possibilities.

Listed below are just a few examples of some of things you can do with the jst() function.

; Today's date in the format: 'Saturday, 29th November 2010'
Calculate DateString as jst(#D,'D:w, d n y')
Calculate DateString as jst(#D,'D:y-M-D') ;; Return format YYYY-DD-MM

; Current time formated different ways.
Calculate TimeString as jst(#T,'T:h:N A') ;; Return format '2:07 PM'

Calculate TimeString as jst(#T,'T:H-N') ;; Return format '14-07'


; PcÊpads the part of the field not filled by the data to be filled by specified character.
Calculate LeftPadString as jst('abc','-5P*') ;; Returns '**abc'
Calculate RightPadString as jst('abc','10P~') ;; Returns '**abc'

Calculate ValueString as jst(Value,'A') ;; Returns 'NULL' when Value is null



Calculate TruncateString as jst('abcdef','4X') ;; Returns 'abcd'

left - Left

left(String,Length)

The left() function returns a substring of specified length, starting at the beginning of the specified string.

Calculate LeftString as left('The fox jumped',7)

len - Length

len(String)

Returns the length of a string, that is, number of characters.

Calculate Length as len('Hello World!')

low - Lowercase

code>low(String)

Returns the lower case representation of a string. Any non-alphabetic characters in the strings are unaffected by low().

Calculate String as low('Hello World!')

mid - Mid

mid(String,Position,Length)

Returns a substring of a specified length, starting at a specified position, from a larger string.

If Position is less than 1 it is taken as 1. If Position is greater than the length of the string, an empty string is returned.

If Length is not included, or is greater than the maximum length of any substring of string starting at position, the returned substring will be the remainder of string starting at Position.

natcmp - National Sort Compare

natcmp(Value1,Value2)

Returns the result of comparing two values using the national sort ordering. 0 if the strings are equal, 1 if Value1 > Value2, and -1 if Value 1 < Value2.

pos - Position

pos(Substring,String)

Returns the position of a substring within a larger string. The substring must be contained within string in its entirety for the returned value to be non-zero. Also, the comparison is case sensitive and only the first occurrence of substring is returned. Use the low() function for case-insenstitive comparisons.

Calculate Posn as pos('Mouse','Mickey Mouse') ;; Returns 8
Calculate Posn as pos('mouse','Mickey Mouse') ;; Returns 0 case sensitive.
Calculate Posn as pos('mouse',low('Mickey Mouse')) ;; Returns 8. Note use of low()

replace - Replace

replace(source-string, target-string, replacement-string)

Replaces the first occurrence of the target-string, within the source-string, with the replacement-string. The replace() function returns the new string containing the changes, if any.

Calculate String as 'Joe Smith'
Calculate NewString as replace(String,'Joe','John') ;; Returns 'John Smith'

replaceall - Replace All

replaceall(source-string, target-string, replacement-string)

Replaces all occurrences of the target-string, within the source-string, with the replacement-string. The replaceall() function returns the new string containing the changes, if any.

; To figure out the total width of a headed list from the $columnwidths.
Calculate ColWidths as '30,40,100,250'

; Replace the commas with + characters.
Calculate String as replaceall(ColWidths,",","+")

; Evaluate the string to calculate the total width.
Calculate TotalWidth as eval(String)

right - Right

right(string,length)

Returns a substring of specified length, starting from the end of the specified string.

Calculate String as "The Fox Jumped"
Calculate RightString as right(String,6) ;; Returns 'Jumped'

rpos - Right Position

rpos(Substring,String)

Returns the furthest right position of a substring within a larger string. The substring must be contained within string in its entirety for the returned value to be non-zero. Also, the comparison is case sensitive. Use the low() function to make the comparision case-insensitive.

Calculate String as "The fox jumped over the fence."

; Get the position of the last space in the string.
Calculate Posn as rpos(' ',String)

; Get the last word.
Calculate LastWord as mid(String,Posn+1)

strpbrk - String Pointer to Break

strpbrk(string1, string2)

Returns a substring of string1 from the point where any of the characters in string2 match string1.

Calculate String as "This is a test"
Calculate String as strpbrk(String,"absj") ;; returns "s a test"
Calculate String as strpbrk(String,"a") ;; returns "a test

strspn - String Span

strspn(string1, string2)

Returns the index of the first character in string1 that does not match any of the characters in the string2. The strspn() function computes the length of the maximum initial segment of the first string which consists entirely of characters in the second string. strspn() is case sensitive.

Calculate String as "This is a test"
Calculate Length as strspn(String,'aehit')
; Returns 1. "s" is missing, but the first letter "T" is upper case, so 1 is returned.

Calculate String as "This is a test"
Calculate Length as strspn(low(String),'aehit')
; Returns 4, the 's' character in 'This' Using the low() function on the string, makes the function case insensitive.

Calculate String as "This is a test"
Calculate Length as strspn(low(String),'aehist')
; Returns 5, the 'space' character.

Calculate String as "This is a test"
Calculate Length as strspn(low(String),' aehist')
; Returns 15. The length of 'This is a test' is 14. All characters match, so the index must be one greater than the length of the string.

; Using the low() function on the string, makes the function case insensitive. To test for an non-alpha character.

Calculate String as 'ABC3'
Calculate Length as strspn(low(String),'abcdefghijklmnopqrstuvwxyz')
; To test for an non-alphanumeric character.

Calculate String as 'ABC34%'
Calculate Length as strspn(low(String),'abcdefghijklmnopqrstuvwxyz0123456789')

strtok - String Tokenize

strtok('string1', string2)

Tokenizes string1, using string2 as the delimiter with which to tokenize. This function returns tokens which are a substring of string1 until any character in string2 matches a character in string1. When strtok() is called, the token found in string1 is removed, so that the function looks for the next token the next time it is called.

You must remember to enclose the string1 variable in quotes or the strtok() function will not work. e.g. 'String1'

The strtok() function is great for parsing strings!

; Parse a comma delimited string into a list.
Calculate CSVString as "fox,dog,cat,mouse"
Do List.$cols.$add('name',kCharacter,kSimplechar,1000)
While len(CSVString)
   
   Calculate SubString as strtok("CSVString",",")
   Do List.$add(SubString)
   
End While

; Parse a string from a text file with carriage returns into a list.
Calculate String as con("Line1",kCr,"Line2",kCr,"Line3")
Do List.$cols.$add('test',kCharacter,kSimplechar,100000)
While len(String)
   
   Calculate SubString as strtok("String",kCr)
   Do List.$add(SubString)
   
End While

style - Style

style(style-character[,value])

Inserts a style-character represented by an Omnis constant into a calculation. Depending on the style character, you can also specify a value, which itself can be a constant from the Text Escapes constants group. This function is particularly useful for formatting the columns of a headed list box field. You can insert an icon by specifying its ID, a center tab, right tab, left tab, a color value, or text property such as italic. For example, to format the columns in a headed list box you could use the following calculation:

con(Col1,style(kEscBmp,1756),kTab,Col2,style(kEscColor,kRed),kTab,Col3,style(kEscStyle,kItalic))

trim - Trim

trim(string[,leading=kTrue,trailing=kTrue,character=space_char])

Removes the specified leading and/or trailing character from the string. You specify the character to be removed in the character argument. If this is omitted the space character is removed from the string by default. The character can only be a single character.

; Remove leading and trailing spaces.
Calculate String as trim(" this is a string with leading and trailing spaces ")

; Remove leading and trailing commas.
Calculate String as trim(",fox,cat,mouse,",kTrue,kTrue,",")

; Remove trailing path delimiter.
Calculate String as trim(FolderPath,kFalse,kTrue,sys(9))

; Remove trailing carriage returns and spaces.
Calculate String as trim(trim(String,kFalse,kTrue,kCr))

upp - Uppercase

upp(string)

Returns the upper case representation of a string.

Calculate String as upp("Hello World!")

; String functions can be combined.
Calculate String as trim(upp(mid("Hello World! ",1,5)))

retAlphaNumeric

The following is a custom method which removes non-alphanumeric characters from an input string.

The method uses the strspn() function to find the first non-matching character in the string, and then con() and mid() to remove the non-matching character from the string.

Calculate String as pString
Calculate Length as len(String)
If Length
   
   Repeat
      
      Calculate IllegalCharPosn as strspn(String,"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_")
      If IllegalCharPosn>Length
         Break to end of loop
      End If
      
      Calculate String as con(mid(String,1,IllegalCharPosn-1),mid(String,IllegalCharPosn+1))
      Calculate Length as Length-1
      
   Until break
   
End If
Quit method String

StudioTips Documentation - Copyright 2006 Vencor Software