String Operations

HALCON offers several string operations to modify, select, and combine strings. Furthermore, some operations allow you to convert numbers (real and integer) to strings.

Table 1: String operations

Operation	Meaning	HALCON operator
v$s	convert v using specification s	tuple_string
v1 + v2	concatenate v1 and v2	tuple_add
strchr(s1,s2)	search character s2 in s1	tuple_strchr
strstr(s1,s2)	search substring s2 in s1	tuple_strstr
strrchr(s1,s2)	search character s2 in s1 (reverse)	tuple_strrchr
strrstr(s1,s2)	search substring s2 in s1 (reverse)	tuple_strrstr
strlen(s)	length of string	tuple_strlen
str_firstn(s,i)	cut the first characters of s up to position i	tuple_str_first_n
str_lastn(s,i)	cut the characters of s from position i	tuple_str_last_n
str_replace(s1,s2,s3)	replace substrings of s1 matching s2 with s3	tuple_str_replace
s{i}	select character at position i; \(0 \leq\) i \(\leq\) strlen(s)\(-1\)	tuple_str_bit_select
s{i1:i2}	select substring from position i1 to position i2	tuple_substr
split(s1,s2)	split s1 in substrings at s2	tuple_split
join(s1,s2)	join substrings in s1 via separator in s2	tuple_join
regexp_match(s1,s2)	extract substrings of s1 matching the regular expression s2	tuple_regexp_match
regexp_replace(s1,s2,s3)	replace substrings of s1 matching the regular expression s2 with s3	tuple_regexp_replace
regexp_select(s1,s2)	select tuple elements from s1 matching the regular expression s2	tuple_regexp_select
regexp_test(s1,s2)	return how many tuple elements in s1 match the regular expression s2	tuple_regexp_test
s1 =~ s2	return how many tuple elements in s1 match the regular expression s2	tuple_regexp_test

$ (string conversion)

See also: tuple_string

$ converts numbers to strings or modifies strings. The operation has two operands:

1. The operand to the left of the $ is the number that has to be converted.
2. The operand to the right of the $ specifies the conversion.

It is comparable to the format string of the printf() function in the C programming language. This format string consists of the following four parts

<flags><field width>.<precision><conversion>

or as a regular expression:

[-+ #]?([0-9]+)?(\.[0-9]*)?[doxXfeEgGsb]?

This roughly translates to zero or more of the characters in the first bracket pair, followed by zero or more digits, optionally followed by a dot, which may be followed by digits followed by a conversion character from the last bracket pair.

Some conversion examples might show it best:

Input	Output
23 $ '10.2f'	'     23.00'
23 $ '-10.2f'	'23.00     '
4 $ '.7f'	'4.0000000'
1234.56789 $ '+10.3f'	' +1234.568'
255 $ 'x'	'ff'
255 $ 'X'	'FF'
0xff $ '.5d'	'00255'
'total' $ '10s'	'     total'
'total' $ '-10s'	'total     '
'total' $ '10.3'	'       tot'

flags

Zero or more flags, in any order, which modify the meaning of the conversion specification. Flags can consist of the following characters:

-

The result of the conversion is left justified within the field.

+

The result of a signed conversion always begins with a sign, + or -.

(Space)

If the first character of a signed conversion is not a sign, a space character is prefixed to the result.

#

The value is to be converted to an “alternate form”. For d and s conversions, this flag has no effect. For o conversion, it increases the precision to force the first digit of the result to be a zero. For x or X conversion, a non-zero result has 0x or 0X prefixed to it. For e, E, f, g, and G conversions, the result always contains a radix character, even if no digits follow the radix character. For g and G conversions, trailing zeros are not removed from the result, contrary to usual behavior.

width

An optional string of decimal digits to specify a minimum field width. For an output field, if the converted value has fewer characters than the field width, it is padded on the left (or right, if the left-adjustment flag - has been given) to the field width.

precision

For integer conversions, the precision specifies the minimum number of digits to appear (the field is padded with leading zeros).
For the e and f conversions, it specifies the number of digits to appear after the radix character.
For the g conversion, it specifies the maximum number of significant digits.
For a string conversion, it specifies the maximum number of characters to be printed.
The precision takes the form of a period . followed by a decimal digit string. A null digit string is treated as a zero.

conversion

A conversion character indicates the type of conversion to be applied:

d, o, x, X

The integer argument is printed in signed decimal (d), unsigned octal (o), or unsigned hexadecimal notation (x and X).
The x conversion uses the numbers and lower-case letters 0123456789abcdef, and the X conversion uses the numbers and upper-case letters 0123456789ABCDEF.
The precision component of the argument specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits than the specified minimum, it is expanded with leading zeroes.
The default precision is 1. The result of converting a zero value with a precision of 0 is no characters.

f

The floating-point number argument is printed in decimal notation in the style
[-] ddd.ddd
where the number of digits after the radix character, ., is equal to the precision specification. If the precision is omitted from the argument, six digits are produced; if the precision is explicitly 0, no radix appears.

e,E

The floating-point-number argument is printed in the style
[-]d.ddde+dd
where there is one digit before the radix character, and the number of digits after it is equal to the precision. When the precision is missing, six digits are produced; if the precision is 0, no radix appears. The E conversion character produces a number with E introducing the exponent instead of e. The exponent always contains at least two digits. However, if the value to be printed requires an exponent greater than two digits, additional exponent digits are printed as necessary.

g, G

The floating-point-number argument is printed in style f or e (or in style E in the case of a G conversion character), with the precision specifying the number of significant digits. The style used depends on the value converted; style e is used only if the exponent resulting from the conversion is less than −4 or greater than or equal to the precision. Trailing zeros are removed from the result. A radix character appears only if it is followed by a digit.

s

The argument is taken to be a string, and characters from the string are printed until the end of the string or the number of characters indicated by the precision specification of the argument is reached. If the precision is omitted from the argument, it is interpreted as infinite and all characters up to the end of the string are printed.

A nonexistent or insufficient field width never causes truncation of a field. If the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

Examples for the string conversion can be found in the program string.hdev.

+ (string concatenation)

See also: tuple_add

The string concatenation (+) can be applied in combination with strings or all numerical types. If necessary, the operands are first transformed into strings (according to their standard representation). At least one of the operands has to be already a string, enabling the operator to act as a string concatenator.

Example

In the following example, a file name 'Name5.tiff' is generated. For this purpose, two string constants ('Name' and '.tiff') and an integer value (the loop-index i) are concatenated:

for i := 1 to 5 by 1
  read_image (Image, 'Name'+i+'.tiff')
endfor

strchr, strrchr

See also: tuple_strchr, tuple_strrchr

strchr(s1,s2) returns the index of the first (and strrchr(s1,s2) of the last) occurrence of one of the characters in s2 in string s1, or -1 if none of the characters occur in the string. s1 can be a single string or a tuple of strings.

strstr, strrstr

See also: tuple_strstr, tuple_strrstr

strstr(s1,s2) returns the index of the first (and strrstr(s1,s2) of the last) occurrence of string s2 in string s1, or -1 if s2 does not occur in the string. s1 can be a single string or a tuple of strings.

strlen

See also: tuple_strlen

strlen(s) returns the number of characters in s.

str_firstn

See also: tuple_str_first_n

str_firstn(s,t) returns the characters from the beginning of string s up to position t.

str_lastn

See also: tuple_str_last_n

str_lastn(s,t) returns the character from position t of string s to the end.

str_replace

See also: tuple_str_replace

str_replace(s1,s2,s3) replaces all substrings of s1 that match s2 with s3.

{}

See also: tuple_str_bit_select, tuple_substr

s{i} selects a single character (specified by index position) from s. The index ranges from zero to the length of the string minus 1. The result of the operator is a string of length one.

s{i1:i2} returns all characters from the first specified index position (i1) up to the second specified position (i2) in s as a string. The index ranges from zero to the length of the string minus 1.

split

See also: tuple_split

split(s1,s2) divides the string s1 into single substrings. The string is split at those positions where it contains a character from s2.

Example

The result of

split('/usr/image:/usr/proj/image',':')

consists of the two strings

['/usr/image','/usr/proj/image']

join

See also: tuple_join

join(s1,s2) joins the substrings in s1. The separator in s2 is placed between the substrings.

Example

The result of

join(['/usr/image', '/usr/proj/image'], [':', ';'])

consists of the two strings

['/usr/image:/usr/proj/image', '/usr/image;/usr/proj/image']

Regular Expressions

HDevelopEVO provides string functions that use Perl-compatible regular expressions. Detailed information about them can be found in the Reference Manual in the descriptions of the corresponding operators, which have the same name but start with tuple_. In particular, in the description of tuple_regexp_match you find further information about the used syntax, a list of possible options, and a link to suitable literature about regular expressions.

regexp_match

See also: tuple_regexp_match

regexp_match(s1,s2) searches for elements of the tuple s1 that match the regular expression s2. It returns a tuple with the same size as the input tuple.¹ The resulting tuple contains the matching results for each tuple element of the input tuple. For a successful match, the matching substring is returned. Otherwise, an empty string is returned.

regexp_replace

See also: tuple_regexp_replace

regexp_replace(s1,s2,s3) replaces substrings in s1 that match the regular expression s2 with the string given in s3. By default, only the first matching substring of each element in s1 is replaced. To replace all occurrences, the option 'replace_all' has to be set in s2; see tuple_regexp_replace.

Example

assign(regexp_replace(List, '\\.jpg$', '.png'), List)

This substitutes file names that look like JPEG images with PNG images.

regexp_select

See also: tuple_regexp_select

regexp_select(s1,s2) returns only the elements of the tuple s1 that match the regular expression s2. In contrast to regexp_match, the original tuple elements instead of the matching substrings are returned. Tuple elements that do not match the regular expression are discarded.

Example

assign(regexp_select(List, '\\.jpg$'), Selection)

This sets Selection to all the strings from List that look like file names of JPEG images.

The backslash character has to be escaped to be preserved.

regexp_test

See also: tuple_regexp_test

regexp_test(s1,s2) returns the number of elements of the tuple s1 that match the regular expression s2. Additionally, a short-hand notation of the operator is available, which is convenient in conditional expressions:

s1 =~ s2

---

1. Exceptions exist when working with capturing groups; see the description of tuple_regexp_match in the Reference Manual for details. ↩