Topic: DMD0167

Help File Version: 2.10.0.636

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 Hex/ASCII

     

  • 8 Hex/ASCII

     

  • 16 Hex/ASCII

     

  • 24 Hex/ASCII

     

  • 32 Hex/ASCII

 

  • 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