StringExt

Description

This library extends string capabilities. Includes useful tools for parsing strings, formatting data, and converting to/from string to other data formats.

Functions

lstrip()

The lstrip() function strips a set of characters from the left side of a string. It takes two inputs, the address of the string to be stripped, pStringVar, and the address of a string containing the characters to be stripped, pChars. If pChars is 0, then the function defaults to stripping white space characters. The function returns the number of characters copied. Please note that this function modifies the input string.

Parameters

Example

stringVar :=	' String Contents ';
pStringVar := ADR(stringVar);
pChars := 0;

NumCharsCopied :=	lstrip( pStringVar, pChars );

After this function call, stringVar will be ‘String Contents ‘, and NumCharsCopied will be 16.

rstrip()

Similar to lstrip(), the rstrip() function strips a set of characters from the right side of a string. It takes two inputs, the address of the string to be stripped, pStringVar, and the address of a string containing the characters to be stripped, pChars. If pChars is 0, then the function defaults to stripping white space characters. The function returns the number of characters copied. Please note that this function modifies the input string.

Parameters

Example

stringVar :=	' String Contents ';
pStringVar := ADR(stringVar);
pChars := 0;

NumCharsCopied :=	rstrip( pStringVar, pChars );

After this function call, stringVar will be ’ String Contents’, and NumCharsCopied will be 16.

atoui()

The atoui() function converts a string into a UDINT value. This allows conversion of numbers higher than the DINT limit, which is not possible using the standard atoi() function. It takes the address of the string to be converted as input and returns the UDINT value.

Parameters

Example

stringVar :=	'3280439123';
pStringVar := ADR(stringVar):

UdintVar :=	atoui( ADR(stringVar) );

After this function call, stringVar will be unchanged and UdintVar will be 3,280,439,123.

uitoa()

The uitoa() function writes a UDINT value to a string. This allows conversion of numbers higher than the DINT limit, which is not possible using the standard itoa() function. It takes two inputs, the UDINT value to be written to a string, and the address of the string to write to. It returns the number of characters written to the string. Please note that this function modifies the input string.

Parameters

Example

UdintVar :=	3280439123;
stringVar := '';
pStringVar := ADR(stringVar);

NumCharsWritten :=	uitoa( UdintVar, pStringVar );

After this function call, stringVar will be ‘3280439123’ and NumCharsWritten will be 10.

ByteToHexString()

The ByteToHexString() function converts a number of consecutive bytes into a hexadecimal code string. This can be useful for displaying memory addresses or handling hash values, for example. It takes three inputs, the starting address of the bytes to be converted, the number of bytes to be converted, and the address of the string to write to. It is important to note that the string will contain two characters for each byte to be converted. The function returns the number of characters written to the string. Please note that this function modifies the input string.

Parameters

Example

UsintArray[0] :=	16#A3;
UsintArray[1] :=	16#7D;
UsintArray[2] :=	16#3B;
UsintArray[3] :=	16#0F;
UsintArray[4] :=	16#C4;
NumOfBytes 	:= 5;
pUsintArray := ADR(UsintArray);
pStringVar	:= ADR(StringVar);

NumCharsWritten :=	ByteToHexString( pUsintArray, NumOfBytes, pStringVar );

After this function call, StringVar will be ‘a37d3b0fc4’, and NumCharsWritten will be 10. Please note that this function will only write lower case letters.

HexStringToDINT()

The HexStringToDINT() function converts a string of hexadecimal string to long integer value. It takes one input, the address of the hexadecimal string. The function returns a long integer value. Please note that this function WILL NOT modify the input string.

Parameters

Example

HexStr := 'a37d3b0fc4';
pHexStr := ADR(HexStr);

longInt :=  HexStringToDINT( pHexStr );

After the function call, HexStr wil be unmodified, and longInt will be 43886251972.

GenerateTimestamp()

The GenerateTimestamp() function generates a timestamp string from a DATE_AND_TIME variable. The format of the string is “YYYY-MM-DD HH:MM:SS”. It takes three inputs, the DATE_AND_TIME variable to be converted, the address of the timestamp string variable, and the size of the timestamp string variable, not including the null byte. The function returns the number of characters written to the string. Please note that this function modifies the input string.

Parameters

Example

DTGetTime_0.enable:=	1;
DTGetTime_0();

NumCharsWritten :=	GenerateTimestamp( DTGetTime_0.DT1, ADR(TimestampString), SIZEOF(TimestampString) - 1 );

After this function call, TimestampString will contain the current date and time, and NumCharsWritten will be 19.

GenerateTimestampMS()

The GenerateTimestampMS() function generates a timestamp string from a DTStructure. The format of the string is “YYYY-MM-DD HH:MM:SS.MMM”. It takes three inputs, the address of a DTStructure variable to be converted, the address of the timestamp string variable, and the size of the timestamp string variable, not including the null byte. The function returns the number of characters written to the string. Please note that this function modifies the input string.

Parameters

Example

// DTStructure DTS 
DTStructureGetTime_0.enable:=	1;
DTStructureGetTime_0.pDTStructure := ADR(DTS);
DTStructureGetTime_0();

NumCharsWritten :=	GenerateTimestamp( ADR(DTS), ADR(TimestampString), SIZEOF(TimestampString) - 1 );

After this function call, TimestampString will contain the current date and time, and NumCharsWritten will be 23.

GenerateTimestampMS_1()

The GenerateTimestampMS_1() function generates a timestamp string from a DTStructure. The format of the string is “YYYYMMDD_HHMMSS_SSS”. It takes three inputs, the address of a DTStructure variable to be converted, the address of the timestamp string variable, and the size of the timestamp string variable, not including the null byte. The function returns the number of characters written to the string. Please note that this function modifies the input string.

Parameters

Example

// DTStructure DTS
DTStructureGetTime_0.enable :=	1;
DTStructureGetTime_0.pDTStructure := ADR(DTS);
DTStructureGetTime_0();

NumCharsWritten :=	GenerateTimestampMS_1( ADR(DTS), ADR(TimestampString), SIZEOF(TimestampString) - 1 );

After this function call, TimestampString will contain the current date and time, and NumCharsWritten will be 23.

strncat4()

The strncat4() function generates a string from four input strings with ‘/’ in between. The function takes in six inputs, the destination for the combined strings, the four strings to be combined, and the max length of the destination should have. Please note that this function modifies the input string Dest and not other input strings.

Parameters

Example

Dest := '';
pDest := ADR(Dest);
Source1 := 'test1';
pSource1 := ADR(Source1);
Source2 := 'test2';
pSource2 := ADR(Source2);
Source3 := 'test3';
pSource3 := ADR(Source3);
Source4 := 'test4';
pSource4 := ADR(Source4);
MaxLength := 28;

NumCharWritten :=  strncat4(	pDest, pSource1, pSource2, pSource3, pSource4, MaxLength);

After this function call, Dest will contain ’test1/test2/test3/test4’, and NumCharsWritten will be 23. Please note if the strings contained more than 25 characters plus the 3 characters for the ‘/’, they would have been cut off at the limit.

ToUpper()

The ToUpper() function replaces all lower case characters in a string with uppercase characters. This function takes in one input string and returns 0 with completed. Please note that this function modifies the input string.

Parameters

Example

String := 'This string';
pSting := ADR(String);

ToUpper(pString);

After this function call, String will be ‘THIS STRING’.

ToLower()

The ToLower() function replaces all uppercase characters in a string with lowercase characters. This function takes in one input string and returns 0 with completed. Please note that this function modifies the input string.

Parameters

Example

String := 'This string';
pSting := ADR(String);
ToLower(pString);

After this function call, String will be ’this string’.

Timestamp_TO_DT()

The function Timestamp_TO_DT(); is used to convert a string generated by generateTimeStamp and revert it back into a DATE_AND_TIME variable. This function has two inputs one is a string input and other is a DATE_AND_TIME variable.

Parameters

Example

Timestamp := '2019-04-25 12:42:16';

Timestamp_TO_DT( ADR(DT), ADR(TimeStamp));

After this function call, TimeStamp will not be changed and DT will be 2019-04-25 12:42:16 with a data type of DATE_AMD_TIME.

appendArrayIndex()

Appends [Value] onto end of string. Used as a quick method to append array indexes to messages. Returns address of string modified.

Parameters

Example

testStr := 'Motor';
motorIndex := 1;

testStrAddress := appendArrayIndex(motorIndex, ADR(testStr));

After this function call, testStr will contain ‘Motor[1]’.

SplitFileName()

Separates file name from extension. It takes three inputs, the address of a string of a filename to be converted, the address of the Name to be filled, the address of the extension to be filled. It returns the length of the Name without the extension. Both the Name and Extension inputs are optional and can be left 0 if not needed.

Parameters

Example

FileName := 'TestFile.txt';
lengthOfName := SplitFileName(ADR(FileName),ADR(Name),ADR(Extension));

After this function call, Name will contain ‘TestFile’, Extension will contain ’txt’, and lengthOfName will be 8. FileName will remain unchanged.

stringlcpy()

Copy string pSrc to string pDst of size dSize. At most dSize minus one chars will be copied. Always null terminates (unless dSize == 0). Returns strlen(pSrc). If return value greater than or equal to dSize, truncation occurred.

Parameters

Example

char[10] myString;
length = stringlcpy(&myString,"This is a strcpy",sizeof(myString));

After this function call, myString will contain ‘This is a’, and length will be 16.

stringlcat()

Appends pSrc to string pDest of size dSize (unlike strncat, dSize is the full size of pDest, not space left). At most dSize minus one characters will be copied. Always null terminates (unless dSize <= strlen(pDst)). Returns strlen(pSrc) + MIN(dSize, strlen(initial pDst)). If return value is greater than or equal to dSize, truncation has occurred.

Parameters

Example

char[10] myString, tempString;
strcpy(myString, "This "); // strlen(myString) == 5
strcpy(tempString, "is a concat"); // strlen(tempString) == 11
length = stringlcat(&myString,&tempString,sizeof(myString));

After this function call, myString will contain ‘This is a’, tempString will contain ‘is a concat’, and length will be 16.

string2wstring()

Converts string pSrc to wide string pDest of size dSize. At most dSize minus one characters will be copied. Always null terminates. Returns strlen(pSrc). If return value is greater than or equal to dSize/2, truncation has occurred.

Parameters

Example

unsigned int myString[10];
char tempString[12];
strcpy(tempString, "is a string"); // strlen(tempString) == 11
length = string2wstring(&myString,&tempString,sizeof(myString));

After this function call, myString will contain ‘is a stri’, tempString will contain ‘is a string’, and length will be 11.

wstring2string()

Converts wide string pSrc to string pDest of size dSize. Any characters not support by a char type will be replaced with an STREXT_INVALID_CHAR. At most dSize minus one characters will be copied. Always null terminates. Returns strlen(pSrc). If return value is greater than or equal to dSize, truncation has occurred.

Parameters

Example

char myString[10];
unsigned int tempString[12];
brwstrcpy(tempString, u"is a string"); // brwstrlen(tempString) == 11
length = wstring2string(&myString,&tempString,sizeof(myString));

After this function call, myString will contain ‘is a stri’, tempString will contain ‘is a string’, and length will be 11.

char2wchar()

Converts char character to wide char return.

Parameters

Example

unsigned int wCharacter;
wCharacter = char2wchar('L');

After this function call, wCharacter will contain u’L’.

wchar2char()

Converts wide char character to char return. Any characters not support by a char type will be replaced with an STREXT_INVALID_CHAR.

Parameters

Example

char character;
character = wchar2char(u'L');

After this function call, wCharacter will contain ‘L’.

formatString()

Copies string with formatters from format into dest. Similar to sprintf.

Formatters:

• real: ‘%r’, ‘%f’
• string: ‘%s’
• boolean: ‘%b’
• integer: ‘%i’, ‘%d’

Parameters

Example

char destination[80];
char* source = "This is a real: %r and an int %i";
StrExtArgs_typ args = {};
args.r = 1.23;
args.i = 123;
unsigned long character = formatString(&destination, sizeof(destination), source, &args);

After this function call, character will be 35 and destination will be “This is a real: 1.23 and an int 123”.

StrExtArgs_typ

This structure contains an array of four booleans, integers, strings, and reals. These values can be used in the error string by adding a ‘%’ and the corresponding letter. The error string will be populated with the first member of the array and then will count up based on the error string.

stringfTime

Formats time from a DATE_AND_TIME type to a string using provided format. Function internally uses strftime.

Parameters

Formatters

stringpTime

Parses formatted time string into a DATE_AND_TIME.

Parameters

Formatters

Uses the same formatters specified in stringfTime. Some formatters are not fully supported by parser.