String Functions

String functions format alphanumeric data for display and for communications between the In-Sight vision system and a remote device.

Note:
  • Index parameters are zero-based. In other words, the first character of a string has an index of 0, the second character has an index of 1, and so on.
  • Text strings that are one character wider than the cell width are sometimes clipped. Increasing the column width or adding a space character to the string will display the entire string.

Function

Description

Code(Text)

Returns the integer value corresponding to the ASCII code for the first character in a string.

ClosedCode Example

If cell A2 contains the alphanumeric string, "ABC123", then the function Code(A2) returns 65.000, the ASCII code for "A".

Concatenate(Arg1, [Arg2, Arg3, ...])

Returns the concatenation of multiple alphanumeric text strings. Numeric arguments are automatically converted to text.

Note: The In-Sight 2000-110/120/120C vision sensor is only capable of returning Pass/Fail data as Output data, and the return value is converted to 0 or 1.

ClosedConcatenate Example

If cell A2 contains the alphanumeric string "A1B1", cell A3 contains the alphanumeric string "C1D2", and cell A4 contains the floating-point number 4.556, then the function Concatenate(A2,A3,A4) returns "A1B1C1D24.556"
Encrypt(Key, Value, Output Format)

Encrypts result data and returns an encrypted string. For more information, see Encrypt.

Exact(Text1, Text2)

Returns 1 if Text1 and Text2 are identical, else 0.

Note: Exact is case-sensitive.

ClosedExact Examples

  • If cell A2 contains the string, "ABC123", and cell A3 contains the string, "ABC1234", then Exact(A2,A3) returns 0.000.
  • If cell A2 contains the string, "VISION", and cell A3 contains the string, "VISION", then Exact(A2,A3) returns 1.000.

Find(FindText, SrcText, [StartChar])

Returns the indexed position of the string Text1 contained in the string Text2. The search for Text1 starts at the optionally-specified StartChar position within Text2.

Note: Find is case-sensitive.

ClosedFind Examples

If cell A2 contains the string "123" and cell A3 contains the string "ABC123", then Find(A2,A3,2) returns the (zero-based) Index value 3.000.

 

The function Find(A2,A3,4) returns -1.000, because the entire string "123" cannot be found in the string "ABC123" if the search begins at Index 4.

FormatString(Format-string, [Text or Value, ...])

Returns a text string constructed using a "C" library standard Format-string.

Tip: The FormatString function supports most Format-string parameters. Use the FormatString dialog to automatically configure the parameters within In-Sight Explorer. For more information, see Format String Dialog.
Note:
  • Manually editing the FormatString function is not recommended.
  • The In-Sight 2000-110, 2000-120, 2000-120C vision sensors are only capable of returning Pass/Fail data as Output data, and the return value is converted to 0 or 1.

Left(Text, NumChars)

Returns the leftmost number of characters (NumChars) from a Text string.

ClosedLeft Example

If cell A2 contains the alphanumeric string, "ABC123", then the function Left(A2,2) returns the string "AB".

Len(Text)

Returns the number of characters (bytes) in a Text string.

ClosedLen Example

If cell A2 contains the alphanumeric string, "ABC123", then the function Len(A2) returns the integer value 6.000.

Lower(Text)

Returns Text converted to lowercase.

ClosedLower Example

If cell A2 contains the alphanumeric string, "ABC123", then the function Lower(A2) returns the string "abc123".

Mid(Text, StartChar, NumChars)

Returns the Text starting from the indexed StartChar position in the alphanumeric string, for as many characters as specified by NumChars.

ClosedMid Example

If cell A2 contains the alphanumeric string, "ABC123", then the function Mid(A2,2,2) returns the string "C1".

Replace(SrcText, StartChar, NumChars, NewText)

Returns SrcText, modified by NewText at the indexed position StartChar.

ClosedReplace Example

If cell A2 contains the alphanumeric string, "ABC123", and cell A3 contains the string "123", then Replace(A2,0,3,A3) returns the string "123123".

Right(Text, NumChars)

Returns the rightmost number of characters (NumChars) from a Text string.

ClosedRight Example

If cell A2 contains the string, "ABC123", then Right(A2,2) returns the string "23".

Strcspn(SrcText, CharList)

Returns the index of the first character in SrcText that is also contained in CharList. If no characters in SrcText are present in CharList, the function returns the length of SrcText.

Note: Strcspn is case-sensitive.

ClosedStrcspn Example

If cell A2 contains the string "BLUE", and cell A3 contains the characters "RED", then Strcspn(A2,A3) returns an index value of 3.000, because 'E' is the first character in CharList that is contained in the SrcText.

Stringf(Format-string, [Text or Value, ...])

Returns a text string constructed using a "C" library standard Format-string.

Tip: The FormatString function supports most Format-string parameters; use the FormatString dialog to automatically configure the parameters within In-Sight Explorer. For more information, see Format String Dialog.
Note:
  • The In-Sight 2000-110/120/120C vision sensor is only capable of returning Pass/Fail data as Output data, and the return value is converted to 0 or 1.
  • The format-string must be enclosed in quotes (").
  • The format-string parameters are case-sensitive.
  • When using the Stringf function, the backslash "\" is used to indicate a format control character follows. If a backslash is not followed by a control character ("n", "r", or "t") then the backslash is ignored. To display a single backslash, two backslashes must be entered (Example:  Stringf("C:\\InSight2\\") = "C:\InSight2\").
  • Non-printable/control code ASCII characters will be displayed as either a symbol or "garbage" text.

Available Format-string parameters are:

%c

Returns the ASCII character corresponding to an integer Value. When supplied with an alphanumeric text string, returns the first character.

ClosedStringf %c Example

If cell A2 contains the integer value 65.000, then Stringf("%c",A2) returns the character "A", which is the character corresponding to ASCII code 65. The function Stringf("Value = %c",A2) returns the string "Value = A".

If cell A2 contains the string "123ABC", then Stringf("%c",A2) returns the character "1".

%d

Returns a string containing an integer Value.

ClosedStringf %d Examples

If cell A2 contains the floating point value 123.456, then Stringf("%d",A2) returns the numeric string "123". The function Stringf("Value = %d",A2) returns the alphanumeric string "Value = 123".

If cell A2 contains the string "ABC123", then Stringf("%d",A2) returns the numeric string "65", the ASCII code for the character "A".

%e

Returns a string containing a Scientific Notation Value. The number of decimal places may be specified by inserting a decimal point (.) and a number between the % and e parameters.

ClosedStringf %e Examples

If cell A2 contains the floating point value 123.456, then Stringf("%e",A2) returns the numeric string "1.234560e+02". The function Stringf("%.1e",A2) returns the numeric string "1.2e+02", because only one number after the decimal point is specified.

%f

Returns a string containing a floating point Value. The number of decimal places may be specified by inserting a decimal point (.) and a number between the % and f parameters.

ClosedStringf %f Examples

If cell A2 contains the floating point value 123.456, then Stringf("%f",A2) returns the numeric string "123.456001". The function Stringf("%.1f",A2) returns the numeric string "123.5", because only one number after the decimal point is specified.

%H

Returns a string containing the specific Host Name of the In-Sight sensor. For more information, see Network Settings Dialog.

ClosedStringf %H Example

If a cell contains the function Stringf("Host Name: %H") on an In-Sight sensor with the host name "is3k010203", the function returns the alphanumeric string "Host Name: is3k010203".

%I

Returns a string containing the specific IP Address of the In-Sight sensor.

ClosedStringf %I Example

If a cell contains the function Stringf("IP Address: %I") on an In-Sight sensor with the IP Address "198.232.26.1", the function returns the alphanumeric string "IP Address: 198.232.26.1".

%M

Returns a string containing the specific Media Access Control (MAC) address of the In-Sight sensor. The MAC address is a hardware address that identifies a specific node of a network. Every In-Sight vision system has a unique MAC address assigned to it, which cannot be changed. For example, 00-d0-24-01-02-03. To locate the MAC address of an In-Sight vision system, look at the serial number label affixed to the vision system. Alternately, you can open the About In-Sight Explorer dialog. For more information, see About In-Sight Explorer Dialog.

ClosedStringf %M Example

If a cell contains the function Stringf("MAC Address: %M") on an In-Sight sensor with the MAC Address "00-d0-24-01-02-03", the function returns the alphanumeric string "MAC Address: 00:d0:24:01:02:03".

%N

Returns a string containing the specific serial number of the In-Sight sensor.

ClosedStringf %N Example

If a cell contains the function Stringf("Serial Number: %N") on an In-Sight sensor with the serial number "Z01020304", the function returns the alphanumeric string "Serial Number: Z01020304".

%o

Returns a string containing the octal value for an integer, or the first character in an alphanumeric string.

ClosedStringf %o Examples

If cell A2 contains the integer value 123.000, then Stringf("%o",A2) returns the numeric string "173", the octal value for the integer 123. If cell A2 contains the string "ABC123" then Stringf("%o",A2) returns the numeric string "101", the octal value for the character "A".

%s

Returns a string with alphanumeric characters appended.

ClosedStringf %s Examples

If cell A2 contains the string "ABC", then Stringf("%s123",A2) returns the alphanumeric string "ABC123". If cell A2 contains the numeric string "123", then Stringf("%s.450",A2) returns the numeric string "123.450".

%T

Returns a string with the specific model type of the In-Sight sensor.

ClosedStringf %T Example

If a cell contains the function Stringf("Model Type: %T") on an In-Sight 5400 sensor, the function returns the alphanumeric string "Model Type: 5400".

%u

Returns a string containing an unsigned integer Value.

ClosedStringf %u Examples

If cell A2 contains the floating point value 123.456, then Stringf("%u",A2) returns the numeric string "123". The function Stringf("Value = %u",A2) returns the alphanumeric string "Value = 123".

If cell A2 contains the string "ABC123", then Stringf("%u",A2) returns the numeric string "65", the ASCII code for the character "A".

%V

Returns a string containing the specific firmware version of the In-Sight sensor.

ClosedStringf %V Example

If a cell contains the function Stringf("Firmware Version: %V") on an In-Sight sensor running firmware version 3.40.01, the function returns the alphanumeric string "Firmware Version: 3.40.01 (475)".

%x or %X

Returns a string containing the hexadecimal value for an integer value, or the first character in an alphanumeric string.

ClosedStringf %x Examples

If cell A2 contains the integer value 123.000, then Stringf("%x",A2) returns the string "7b", the hex value for the integer 123. If cell A2 contains the string "ABC123", then Stringf("%x",A2) returns the numeric string "41", the hex value for the character "A".

The following Format-string parameters are used primarily for text formatting. For example, formatting the text of an email message in the WriteSMTP function:

\x##

Inserts the ASCII character specified by a hexadecimal number ## into the text.

ClosedStringf \x## Example

If cell A2 contains Stringf("\x02123\x1bABC\x03456"), then the cell will display: ("<STX>123<ESC>ABC<ETX>456").

\n

Inserts a line feed into the text. This parameter is usually used in conjunction with \r (carriage return).

\r

Inserts a carriage return into the text. This parameter is usually used in conjunction with \n (line feed).

\t

Inserts a tab into the text.

Strspn(SrcText, CharList)

Returns the index of the first character in SrcText that is not contained in CharList. If all characters in SrcText are also in CharList, the function returns the length of SrcText.

Note: Strspn is case-sensitive.

ClosedStrspn Example

If cell A2 contains the string "RED", and cell A3 contains the characters "GREEN", then Strspn(A2,A3) returns an index value (zero-based) of 2.000, because 'D' is the first character in CharList that is not contained in SrcText.

Strtol(IntegerText)

Converts numeric characters (decimal, hexadecimal  and octal) at the beginning of an alphanumeric string into an integer. Hexadecimal characters must begin with "0x"; octal characters must begin with "0".

ClosedStrtol Examples

Decimal: If cell A2 contains the text string "123ABC", then the function Strtol(A2) returns the integer value 123.000.

 

Hexadecimal: If cell A2 contains the text string "0x123", Strtol(A2) returns the integer value 291.000.

 

"0x12AB" = 4,779.000, since "A" and "B" are hexadecimal characters.

"0x12GB"  = 18.000, since "G" is not a hexadecimal character.

 

Octal: If cell A2 contains the text string "0123ABC", Strtol(A2) returns the integer value 83.000.

Substitute(SrcText, OldText, NewText, [Instance])

Returns a text string constructed by substituting NewText for each occurrence of OldText in SrcText. If an optional Instance index is specified, then only that instance of the text will be replaced.

ClosedSubstitute Example

If cell A2 contains the text string "ABC123123", cell A3 contains the string "123", and cell A4 contains the string "abc", then Substitute(A2,A3,A4,1) replaces the second instance of "123" in SrcText and returns the string "ABC123abc".

Token(Text, Delimiter, Instance)

Returns the text located at the specified Instance index (occurrence) of a delimited string. The Delimiter must be enclosed in quotes (") in the function.

ClosedToken Example

If cell A2 contains the comma delimited string "A,B,C,1,2,3" then Token(A2,",",2) returns "C" because C is at index 2 in the text.

Trim(Text)

Returns Text stripped of leading and trailing spaces, leaving only a single space between words (if any). All control characters (Carriage Return, Line Feed, etc.) are also stripped.

ClosedTrim Example

If cell A2 contains the string " ABC   123 ", then Trim(A2) returns the string "ABC 123".

Upper(Text)

Returns Text converted to uppercase.

ClosedUpper Example

If cell A2 contains the alphanumeric string, "abc123", then the function Upper(A2) returns the string "ABC123".

Value(NumericText)

Returns the floating point value of NumericText. Subsequent non-numeric characters are ignored.

ClosedValue Example

If cell A2 contains the numeric string "123.4", then the function Value(A2) returns the floating point value 123.400.

Note:

An In-Sight cell allows you to enter up to 7-digit numeric value. If the Value function references a numeric text that has more than 8 digits, the value may not be exact due to the limitations of the floating point data type. For example:

A2 = '68456668

A3 = Value(A2)

In this case, the function returns 68456672.000.