Fundamentals: Strings

Strings are simply text; a sequence of printable and non-printable characters. Strings can contain numbers, however these are just printable representations of numbers; you cannot use them as inputs to functions that take Integer or Decimal parameters, nor can you use them with mathematical operators.

String variables can contain a maximum of 254 characters.

Strings must be surrounded by quotes. Example:

#S1="This is a String."

Strings are often used to display messages. Example:

INTEGER:#STATUS=0
			
IF(#STATUS = 0) THEN
	PAUSE[TX="Error: Status is O."]
ENDIF

When this macro is run, it will display a message box with the text: Error: Status is 0.

This example used a literal string; the text message was entered directly into the PAUSE command. Strings can also be passed to functions as variables. The following example has the same results as above, except the string is passed as a variable.

INTEGER:#STATUS=0
STRING:#EMSG = "Error: Status is 0."
			
IF(#STATUS = 0) THEN
	PAUSE[TX=#EMSG]
ENDIF

Notice that when you use literal strings the text must be quoted. However, when you pass the string data to the macro command, with a variable, the variable name is not quoted. Instead, it is preceded by a pound sign (#) which signifies it is a variable.

If you used quotes around the variable name, instead of getting the contents of the string variable output, you would get the variable name itself.

INTEGER:#STATUS=0
STRING:#EMSG = "Error: Status is 0."
			
IF(#STATUS = 0) THEN
	PAUSE[TX="#EMSG"]
ENDIF

In the above example, where the variable name is surrounded by quotes, the message box will contain: #EMSG. By placing quotes around the variable name you converted it from a string variable to literal text.

Multiple Line Strings

In the above examples, the string is displayed on a single line in the message box. It is possible to embed a new line command in the string which causes the message to be split into multiple lines.

PAUSE[TX="Line One\nLine Two"]

When run, this displays the following message box:

With the literal string, the \n (backslash, lowercase n) serves as a new line character. When this sequence is found, a new line is created and the remaining text is displayed on this second line. You can use several new line sequences in the same literal string. By default the PAUSE command displays four lines, however you can use the SR parameter to increase the number of displayed lines.

Escaping Special Characters

The new line sequence, above, is one example of escaping special characters. The backslash character "\" is a special character, it says the character that immediately follows it has special meaning.

For a new line, the character that immediately follows the backslash is "n". This "n" means add a new line.

Another special character is the quote character ("). Since quotes are used to delineate literal text strings, you cannot embed a quote into a string. Example:

#STR="Warning: "variable" not found."

This assignment will not work. A string is a series of characters surrounded by quotes. So, when the macro parser reads this line it sees a literal string: "Warning: ", followed by the letters "variable," and then another literal string " not found.".

If the message needs embedded quotes, then the quote must be escaped. The quote character is escaped by adding a backslash just before it. The following assignment will work:

#STR="Warning: \"variable\" not found."

If this string were output to a message box, it would look like: Warning: "variable" not found.

One other special character is the backslash itself. If the string requires a backslash character, the backslash itself must be escaped. Example:

#STR="This is a backslash: \\."

When output the string displays as: This is a backslash: \.

Using Quoted Paths

Operating system paths using backslash as the path separator must escape the backslash. Example:

FN="C:\\Program Files\\SmartCAM\\"

This is required because the backslash character (\) is a special character - see above.

Alternatively, paths can use the UNIX-style separators:

FN="C:/Program files/SmartCAM"

Building Strings

The simplest string to create is a straight string literal, where the entire string is assigned without any additional modification.

STRING:#S1="Hello World."

PAUSE[TX=#S1]

String Concatenation

Concatenation is joining two or more strings together to create a larger single string. SmartCAM supports a number of different methods for handling this.

CAT()

The CAT() macro function is a concatenation function. The macro function takes two string parameters, the two strings to join, and returns the joined string.

STRING:#S1
			
#S1=CAT("Hello ", "World.")
PAUSE[TX=#S1]

When run, the message box will contain the string: Hello World.

When concatenating strings, they will be added together without any other changes. This means if the message needs spaces between the joined strings, the spaces must be in one or the other string.

#S1=CAT("Hello","World.") will place "HelloWorld." into #S1. This happens because there is no space added to either of the two joined strings.

Concatenation Operator (+)

A modern alternative to the CAT() macro function is the concatenation operator. SmartCAM supports using the plus sign (+) to join two or more strings.

STRING:#S1="SmartCAM"
			
#S1 = #S1 + " Process" + " Modeling."
PAUSE[TX=#S1]

When run, #S1 contains and displays the text: SmartCAM Process Modeling.

String Length

It is sometimes required to find the length of an existing string. The MCL command STRLEN() will return an integer containing the string length for the supplied string parameter.

INTEGER:#ISTRLEN
			
#ISTRLEN=STRLEN("Hello World.")
PAUSE[TX="String contains " + ITOA(#ISTRLEN) + " characters."]

The PAUSE statement will display: String contains 12 characters.

Data Conversion

When developing and testing a macro, it is important to be able to output the contents of a variable in a message box to see what data it contains. Most of the time, the variable will be either an INTEGER or DECIMAL; however, the PAUSE[] macro command expects a STRING as the message to be displayed. This requires a way to convert numbers to strings.

Inversely, when working with external files which are often text files, it is important to be able to convert a string representation of a number into an actual number.

SmartCAM has functionality to help in either direction.

Number to String

There are several ways to convert numerical data into string data.

There are also special purpose macro functions that convert ASCII stings to either Decimal or Integer numbers.


STRTMP()

STRTMP() takes a string parameter and returns a string. The macro function will convert numeric variables into strings when they are prefaced with a percent (%) sign. This is the original method the SmartCAM macro language used for handling number to string conversion; it is no longer the recommended method. This function will be removed in a future release of SmartCAM.
Example:

DECIMAL:#D1=12.5
INTEGER:#I1=3

PAUSE[TX=STRTMP("#D1=%#D1 and #I1=%#I1")]

When run, the message box will contain the text: #D1=12.5 and #I1=3.

Note: STRTMP does not support array elements. If an array element needs to be converted to a string, use the FMT() or ITOA() commands.

By placing a "%" character just prior to the variable, for example "%#D1," STRTMP replaces the variable name with the actual contents of the variable. This can also be used to concatenate strings - although the concatenation operation is a better solution.

STRING:#S1="Hello"
STRING:#S2="World."

PAUSE[TX=STRTMP("%#S1 %#S2")]

When run, the message box contains: Hello World.


FMT()

FMT() takes two parameters, first the number to be converted to a string and second a formatting statement that controls how the number is formatted when it is converted. The function returns a string - the formatted number.

The formatting statement uses the same notation as the Numeric Format used in SmartCAM Machine Files. This format is well documented in the Numeric Formats topic within the Code Generation section of Learning SmartCAM.

DECIMAL:#D1=12.5
INTEGER:#I1=3
STRING:#S1

#S1= "#D1=" + FMT(#D1, "D3.4") + " and #I1=" + FMT(#I1, "T3.0")
PAUSE[TX=#S1]

When run, this macro will generate output identical to the previous STRTMP example. It will display: #D1=12.5 and #I1=3. Using the FMT function offers a capability that STRTMP does not have, the ability to change the format of the number when it is converted to a string.

DECIMAL:#D1=12.5
STRING:#S1

#S1= "#D1=" + FMT(#D1, "T3.4")
PAUSE[TX=#S1]

When run, the message string displays: #D1=12.5000. The format of the number was changed from a pure decimal format to a trailing zero format.


ITOA()

The FMT() function uses the built-in SmartCAM numeric formatter, which is designed to massage data for output to an NC control. It normally does not need to handle Integer values. Since there are no Integer format strings, a different method of converting an Integer to a string, for output, is used. This is the ITOA() macro function.

ITOA() stands for "Integer to ASCII." The function takes an Integer variable as its parameter and returns a STRING.

INTEGER:#I1=11
STRING:#S1

#S1="#I1=" + ITOA(#I1)
PAUSE[TX=#S1]

When run, the message string displays: #I1=11.

String to Number

There are two macro functions used to convert a string representation of a number to a string.

ATOI()

The ATOI() stands for "ASCII to Integer". The macro function takes a string as the parameter and returns in INTEGER.

ATOD()

The ATOD() stands for "ASCII to Decimal". The macro function takes a string as the parameter and returns in DECIMAL.

DECIMAL:#D1
INTEGER:#I1
STRING:#S1="3"

#D1=ATOD("12.5")
#I1=ATOI(#S1)

PAUSE[TX="#D1=" + FMT(#D1,"D3.4") + " and #I1=" + ITOA(#I1)]

When run, the message box will display: #D1=12.5 and #I1=3.

Related Topics

Branching and Looping

Functions and Commands

Macro Development Fundamentals Overview

SmartCAM Automation Overview