Topic: DMD0167
String Functions Overview
Strings are predefined containers that are used to store bytes of data. The primary usage of the String data type is to provide the underlying storage mechanism for data that is received from, or sent to communication ports.
String Lengths
There are two length values associated with a String that you need to be concerned with when dealing with the Strings, The first is the maximum length of the String, and the second is the number of bytes of data currently stored in that String.
The maximum length of the String is determined when the String is initially created and that length cannot be changed at runtime. This value determines the maximum number of bytes of data that the String can contain. (for more information on creating Strings, refer to the Memory Configuration help topic. For example, the maximum length of the system-defined Short Strings is 64 bytes, and the maximum length of the system-defined Long Strings is 256 bytes. The maximum length of any String is available through the <stringname>.maxlen variable.
The number of bytes that are currently stored in a String at any given time is available through the <stringname>.length variable. The number of bytes of data that a String can store at any time is 0 up to the value in the <stringname>.maxlenfield of that String.
Unlike a C/C++ string, Strings in a Do-more CPU are NOT null-terminated, if a String needs a null terminator it will have to be manually added and accounted for in the .length value.
String Errors
If any String instruction attempts to store more data in a String than that String can hold, the instruction will store as many of the bytes of data in the String as it can hold, and generate a 'Buffer Overflow' warning which will be seen on the Do-more Designer status bar in yellow, and it will be logged in the System Information's Event Log.
String Literals
Many of the String instructions can process either Strings or string literals. String literals are zero or more characters enclosed in double quotes, as in "hello", and may include both simple escape sequences (such as $T for the tab character) and hexadecimal data (such as $AA).
Data View formats for Strings
When using the Data View to see the contents of Strings, there are four display options available to you. Which of the display options you use will largely depend on the type of data in String, that is, whether the data in the String is ASCII text or simple byte data or a combination of the two.
ASCII - This is the default display option for a String.
-
printable ASCII characters are displayed as expected
-
non-printable ASCII characters are displayed as a decimal point
Quoted
-
printable ASCII characters are displayed as expected
-
non-printable ASCII characters are displayed as "$" and the two-digit hex value
Hexadecimal
-
each byte of the String is displayed as a two-digit hexadecimal value
-
a space is displayed between each value and an extra space after each fourth value
Hexadecimal/ASCII bytes are displayed in groups of:
-
4, 8, 16, 24 or 32 Columns of hexadecimal data with 4, 8, 16, 24 or 32 Columns of ASCII text respectively
String Instructions:
The instructions that operate on Strings are listed below. Notice the instructions are organized into five groups:
Instructions that modify ASCII text stored in a String whether generating, searching, extracting, or modifying the text
STRCASE - Convert String to UPPER / Lower Case - convert the characters in a String to all upper or lower case
STRCLEAR - Clear Strings - will remove the contents from the specified string or range of Strings
STRCMP - String Compare - compare two Strings, or compare one String with some ASCII text
STRCOPY - Copy String - copy one String to another String or to a Range of Strings
STRCOPYR - Copy a Range of Strings - copy one ranges of Strings to another Range of Strings
STRDELETE - Delete Substring - delete characters from a String
STRINSERT - Insert Substring - insert characters into a String
STRPRINT - Print to String - send ASCII data to another String
STRSUB - Get Sub-String - extract the ASCII data from a portion of a String
STRTRIM - Trim Whitespace - remove leading and trailing whitespace characters from a String
STRTRUNC - Set String Length - set the length of a String to a fixed value
Instructions that compare the text stored in a String
STRCMP - String Compare - compare two Strings, or compare one String with some ASCII text
STRFIND - Find within String - search within a String for another String, or search within a String for some ASCII text
String Instructions that convert ASCII text to their numeric equivalent values
STR2INT - Convert String to Integer - convert ASCII data to an integer
STR2REAL - Convert String to Real - convert ASCII data to a Real (floating point) number
String Instructions that send and receive data from such as serial ports or a UDP packet on an Ethernet port
STREAMIN - Stream In Data from Device - retrieve data from the specified Stream Device and place that data in a String or a numeric data block
STREAMOUT - Stream Out Data to Device - send the data contained in a String or a numeric data block to the specified Stream Device
PACKETIN - Input Data from Packet Device - retrieve data from a Packet Device (UDP Connection) and place that data in a String or a numeric data block
PACKETOUT - Output Data to Packet Device - send the data contained in a String or a numeric data block to Packet Device (UDP Connection)
Instructions that operate on simple byte data stored in a String
STRGETB - Get Bytes Out of a String - copy bytes of data from a String to memory in the CPU
STRPUTB - Put Bytes Into a String - copy bytes of data from CPU memory to a String
CHECKSUM - Checksum Algorithm - compute a checksum on the bytes of data in a String
Other Instructions that operate on Strings
ISCLEAR - Is Structure Cleared - can determine if a String is clear (empty and initialized)
MEMCLEAR - Clear Memory Range - can clear Strings (make them empty and initialized)
MEMCOPY - Copy Memory Range - can copy a single String or a range of Strings
Related Topics:
String Functions Overview
String Scripting Language Reference