You can declare StringTheory objects in your code by simply doing;
str StringTheory
Overriding or deriving StringTheory methods is not usually necessary.
Symbols | Meaning |
---|---|
^ |
Caret matches the beginning of the string or the beginning of a line within the string. For example: ^chapter matches a string that starts with chapter. |
$ |
Dollar sign is similar to the caret, but it matches only at the end of a string or the end of a line within the string. For example: p$ matches a string that ends with a p. |
. |
Period (.) matches any single character except a new line. For example: .P matches any single character followed by a P as long as P is not the first character on a line. Similar to + and ?. |
[...] |
This is called a character set. It matches any one of the characters that are enclosed in the square brackets. For example: [MVX] matches any one of the characters M, V, or X in a string. Ranges of characters are indicated by using a hyphen between the beginning and ending characters, and enclosing the whole thing in brackets. For example:[0-9] matches any digit. To match -, write it as ---, which is a range containing only -. You may also give - as the first or last character in the set. To match ^, put it anywhere except as the first character of a set. To match a ], make it the first character in the set. For example: []d^]matches either ], d or ^. |
[^...] |
This is a complemented character set. The first character after the [ must be a ^. It matches any characters except those in the square brackets (or newline). For example: [^0-9] matches any character that is not a digit. |
| |
Vertical bar is the alternation operator and it is used to specify alternatives. For example: ^P|[0-9]matches any string that matches either ^P or [0-9]. This means it matches any string that contains a digit or starts with P. The alternation applies to the largest possible regular expressions on either side. No spaces are allowed between strings and the alternation operator. |
{...} |
Brackets are used for grouping in regular expressions as in arithmetic. They can be used to concatenate regular expressions containing the alternation operator, |. |
* |
Asterisk means that the preceding regular expression is to be repeated as many times as possible to find a match. For example: ph* applies the * symbol to the preceding h and looks for matches to one p followed by any number of h's. This will also match just p if no h's are present. The * repeats the smallest possible preceding expression (use parentheses if you wish to repeat a larger expression). It finds as many repetitions as possible. For example: (c[ad][ad]*r x) matches a string of the form (car x), (cdr x), (cadr x), and so on. |
+ |
Plus sign is similar to *, but the preceding expression must be matched at least once. This means that: wh+y would match "why" and "whhy" but not "wy," whereas wh*y would match all three of these strings. This is a simpler way of writing the last * example: (c[ad]+r x) |
? |
Question mark is similar to *, but the preceding expression can be matched once or not at all. For example: fe?d will match fed and fd, but nothing else. |
\ |
Backslash is used to suppress the special meaning of a character when matching. For example: \$ matches the character $. |
Check out general product CompilerErrors.
String (@S) | |
---|---|
@S[length] | Length is considered to be optional. If omitted the passed
string is returned as-is. Length is not limited to 255 as it is by the Clarion FORMAT command. Length can be 0 - ie @S0 is a valid picture, returning a blank string when formatted. |
Pattern (@P / @K) | |
Use a > character in place of a < character. | Three important facts conspire to cause a common programming
error. a) In the pattern # and < are used to represent required and optional digits. b) The picture to this parameter is passed as a string. c) In Clarion, putting << into a string results in the compiler changing this to < Put together, this means that the picture @p<<<<p, when passed as a string actually represents 2, not 4, digits. To help avoid this error the DeformatPattern command supports the use of the > character in place of the < character in the pattern. The two characters have exactly the same meaning. |
Date (@D) | |
Add a M to the end of any Date picture | This indicates that the raw data is in Unix Epoch Datetime (milliseconds) (aka JavaScript) format rather than Clarion Long format. |
Add a U to the end of any Date picture | This indicates that the raw data is in Unix Epoch Datetime (seconds) format rather than Clarion Long format. |
Add a L to the end of any date picture | This indicates that if the value is zero, then the current local date will be used in the format. (Useful in conjunction with @U formats) |
Add a T to the end of any date picture | This indicates that if the value is zero, then the current UTC date will be used in the format. (Useful in conjunction with @U formats) |
Alternate Separator ! | Setting the separator in the picture to ! indicates that no separator should be used. In other words @D10! is the same as @D12. |
@D91 | New Date Picture - yyyy/Www - where ww is the ISO 8601 Week Number |
@D92 | New Date Picture - Www/yyyy - where ww is the ISO 8601 Week Number |
@D93 | New Date Picture - yyyy/Www/d - where ww is the ISO 8601 Week Number and d is the day number. |
Time (@T) | |
Add a M to the end of any Time picture | This indicates that the raw data is in Unix Epoch Datetime (milliseconds) (aka JavaScript) format rather than Clarion Long (centiseconds) format. |
Add a U to the end of any Time picture | This indicates that the raw data is in Unix Epoch Datetime (seconds) format rather than Clarion Long (centiseconds) format. |
Add a L to the end of any Time picture | This indicates that if the value is zero, then the current local time will be used in the format. (Useful in conjunction with @U formats) |
Add a T to the end of any Time picture | This indicates that if the value is zero, then the current UTC time will be used in the format. (Useful in conjunction with @U formats) |
Add a Z to the end of any Time picture. | This indicates that the value should be rounded up by 1
hundredth of a second. In other words FormatValue(360000,'@T1Z ') returns 1:00 instead of 0:59:59:99. This simplifies the display of "round numbers" and makes time-math easier. Is especially useful where the time is a "duration" rather than a "time of day". |
@T1, @T2, @T4, @T5, @T91 support values greater than 24 hours. | The standard Clarion format command allows for a maximum time of 23:59:59. This works for time-of-day, but is less suitable for time-duration. The StringFormat class allows for any time up to (plus or minus) 2 billion hours for these time pictures. A REAL data type is supported (in addition to the traditional LONG) to support very large time values. |
NumberPart | Because some time pictures allow for numbers greater than 23
hours, it's possible that these times could be very large. For
example Accumulated-Time-Worked by a large department for a year
might be thousands, or hundreds of thousands of hours. Thus the
"hours" part of this time requires its own format string. This
is achieve by concatenating a Numeric picture to the Time
picture. For example; @T1@N6 In this case the time will be displayed as hh,hhh:mm - the @n6 part is applied to the Hours part of the time. |
@T91 | New Time Picture. hh:mm:ss:cc |
@T92 | New Time Picture. hh:mm:ss:cc xm |
@T93 | New Time Picture. hh:mm:ss.mmm |
@T94 | New Time Picture. hh:mm:ss.mmm xm |
The Clarion FORMAT command does
not include a space between the time, and the AM
or PM. However using capitals, and no space, is considered poor layout by today's standards. By default the FormatClass separates the time from the am or pm with a space, and am or pm is in lower case. |
|
TimeHours Pictures (@H) | |
Time pictures display time as hours, minutes and seconds.
Number pictures display a numeric value. TimeHours pictures behave exactly as Number pictures, except that the value is divided by 360000 (1 standard Clarion hour). In other words TimeHours pictures display Clarion Time, but as a Decimal Number. So 2 and a half hours is 2.5 rather than 2:30. All the format options for Numeric pictures are supported - and the behavior is exactly as for numeric pictures, but the value returned has been divided by 360000. |
|
Unix Date & Time Pictures (@U) | |
@Un[S][M][D][T][@d][@t] | Takes in a Unix Epoch Datetime value (or Clarion Date
/ Time value) and returns a date/time stamp of the form dateTtime.
n is the picture number (1 or 2) [S] is an optional separator character. If omitted the default is T. Use an underscore to separate the date and time with a space character. [M] indicates the value is in Milliseconds rather than seconds. If M is included then the separator character [S] MUST be included. [D] indicates the value is a Clarion Date rather than seconds. If D is included then the separator character [S] MUST be included. The output will treat the time part as 0. [T] indicates the value is a Clarion Time rather than seconds. If T is included then the separator character [S] MUST be included. The output will treat the date part as 0. The @d part of the picture refers to the picture for the date part, the @t part of the picture refers to the time part. If @d is omitted then @D010 (yyyy/mm/dd) is used. If @t is omitted then @T04 (hh:mm:ss) is used. @U1 -- The separator has a space before and after it @U2 -- The separator has no spaces before or after it @U3 -- There is no separator @U1_ - The separator is a space character @U1x - The separator is a x character - where x is any character (except underscore or a digit) Examples : @U1 1970/01/01 T 00:00:00 @U2 1970/01/01T00:00:00 @U2_ 1970/01/01 00:00:00 @u1@d06 01/01/1970 T 00:00:00 @u1@d6@t1 1/01/1970 T 0:00 |
HEX Pictures (@X) | |
@Xn[S][Bm] | Takes in a value, and displays it as a raw hexadecimal or
binary format. X displays ABCDEF values in Capital letters. x displays abcdef in lower case letters. n is the number of string characters to display per line, before a line break. For example @X4 _would display as 00 00 00 00 00 00 00 00 Set n to 0 to indicate no line breaks. [S] is an optional separator character. If omitted the default is no separator. Use an underscore to separate with a space character. [Bm] specifies the base of the numbers to display. So to display as Binary is B2, Octal is B8, Decimal is B10 and Hexadecimal is B16. m can be any number in the range of 2 to 36. If omitted the default value is 16 (Hexadecimal). @X8_ - The separator is a space character @X8x - The separator is a x character - where x is any character (except underscore) |
Abbreviate | Truncate a string, searching for a natural break point if possible. |
AddBOM | Add a byte-order-mark (BOM) to the front of the string (usually right before saving to disk.) |
AdjustLength | Adjust the length of the string. |
After | Returns the rest of the string after a delimiter. |
AfterLast | Returns the rest of the string after the last instance of a delimiter. |
AfterNth | Returns the rest of the string after the nth instance of a delimiter. |
All | Returns the current string, repeated until the returned value is a specific length. |
Append | Append a value to the end of the string |
AppendBinary | Append a (long / short / byte) to the end of the string, but as binary characters. |
Ascii85Decode, Ascii85Encode | See Base85Decode and Base85Encode. |
AsnDecode | Take a ASN.1 Encoded value and split it into the component parts. |
AsnEncode | Take a string value, and encode it according to ASN.1 rules. |
AsnEncodeNumber | Take a number and encode it according to ASN.1 rules. |
Before | Returns the section of the string before a delimiter. |
BeforeLast | Returns the section of the string before the last instance of a delimiter. |
BeforeNth | Returns the section of the string before the nth instance of a delimiter. |
Between | Returns the string between the passed delimiters if it exists. Also see FindBetween which returns the start and end positions and allows multiple strings to be located and returned between the same delimiters . |
Base32Decode | Decode a string that is encoded using Base32 |
Base32Encode | Encode the string using Base32 encoding method |
Base64Decode | Decode a string that is encoded using Base64 |
Base64Encode | Encode the string using Base64 encoding method |
Base85Decode |
Decode a string that is encoded using Base85 / ASCII85 |
Base85Encode |
Encode the string using Base85 / ASCII85 encoding method |
Capitalize | Capitalizes the first letter in one or more words in the string. |
ChangeBase | Treat the string as a number, change the base of the number. |
Chars | Returns the number of Characters in the string (not the number of bytes). Works for strings in ANSI, Utf-8 or Utf-16 encodings. |
CharToDecEntity | Converts all the characters (in a range) to the form &#nn; |
CleanFileName | Cleans and returns a file name with any invalid characters replaced. |
Clip | Clips the string (removed trailing whitespace) |
ClipLength | Get the length of the string, ignoring trailing spaces |
ColorToHex | Converts a color stored in any format to a hex string (which can be used in CSS, HTML etc.). |
ColorToLong | Converts a color stored in any format to a standard Clarion long color. |
ContainsA | Returns true if the string contains at least one character from a matching alphabet. |
ContainsADigit | Returns True if the string contains at least one digit character ('0' to '9') |
ContainsByte | Returns true if the string contains a specific ASCII Byte. |
ContainsChar | Returns true if the string contains a specific character. |
ConvertAnsiToOem | Applies the Clarion ConvertAnsiToOem function to the string. |
ConvertOemToAnsi | Applies the Clarion ConvertOemToAnsi function to the string. |
ConvertTabs | Expand tabs to the next tab point, using spaces. |
Count | Returns the number of times that the Search Value appears in the current string |
CountWords | Returns the number of words in the string. Also see WordStart and WordEnd. |
Crop | Removes part of the string from either the front, or rear, or both, of the string |
DecEntityToChar | Converts the for &#nnn; into a character. |
DeformatValue |
Returns a deformatted value. |
EndsWith | Checks to see if the string ends with a substring. |
Equals | Compares one StringTheory object with another StringTheory object. |
ErrorTrap | Called if an OS error occurs |
ExtensionOnly | Splits the extension part out of a file name. |
FileNameOnly | Splits the file name part out of a fully qualified path name |
FindBetween | Finds and returns a string between the passed start and end delimiters and returns the start and end position of the string found. |
FindBetweenPosition | Same as FindBetween, but does not return the Substring. |
FindByte | Fast brute force find a single byte value |
FindChar | Fast brute force find a single character |
FindChars | Fast brute force find for a substring |
FindEndOfString | Finds the end of a null-terminated string. |
FindLast | Find the last instance of a substring in a string. |
FindMatch | Find a regular-expression string in the object. Returns the string found, and the position of the string in the object |
FindMatchPosition | The same as FindMatch, but does not return the found string (for performance reasons). |
FindNth | Finds the nth instance of a substring in a string. |
FindWord | Retrieve the word at the specified position from the string, and returns the position of the word as well. |
FlexPolylineDecode | Decode a string containing a Flexible Polyline Encoding |
Flush | Flushes a disk-write-cache to the disk. See Streaming to a Disk file (Write-Caching) |
FormatHTML | Format text according to HTML indenting and line ending rules. |
FormatMessage | Interprets the windows API error code |
FormatValue | Returns a formatted value. |
Free | Clears the string and returns all the memory used by the string |
FromBlob | Retrieves the data from the passed BLOB and stores it. |
GetAddress | Return the current address of the string in memory. |
GetCodePageFromCharset | Given a Clarion Charset select a code page to match. |
GetValue | Returns the current value of the string |
GetValuePtr | Returns a pointer to the current value of the string. |
GetWord | See Word. |
GuidDecode | Remove hyphens and brackets, and hex-decode a string. |
GuidEncode | Hex encode, and add hyphens, to a 16 character binary string. |
HtmlEntityToDec | Converts the form ´ into a character |
HostOnly | See UrlHostOnly. |
Insert | Inserts a passed string into the stored string at the specified position |
Instring | Search for a string in a sub string |
IsAll | Returns true if the string only contains specific characters. |
IsAllDigits | Returns True if the string contains only digit characters ('0' to '9') |
IsAllLower | Returns true if value contains ONLY lower case letters (a through z). Any other characters will return false. |
IsAllUpper | Returns true if value contains ONLY upper case letters (A through Z). Any other characters will return false. |
IsAscii | Returns true if the string is blank, or only contains characters from <0> to <127>. |
IsLower | Returns true if value contains no upper case letters - the value would be unchanged by doing LOWER on it |
IsTime | Returns true if the string looks like a formatted time value. |
IsUpper | Returns true if value contains no lower case letters - the value would be unchanged by doing UPPER on it |
IsValidUtf8 | Returns true if the string is valid utf-8, false if it is not. |
Join | See Split, Manipulate and Join Strings |
JsonDecode | Converts a string that was encoded for transport in JSON format. |
JsonEncode | Encodes a string into JSON format, suitable for adding to a JSON packet. |
KeepChars | Removes all non-specified characters from the string. |
Left | Returns the non-space characters from the left of the string. |
Length | The current length of the string |
LineEndings | Change <13,10> to <13> or <10> or vice versa. |
LoadFile | Load a file off the disk into the string |
LongDivision | Divide any length string by a number. |
Lower | Change all the characters in the string to be lower case |
MakeGuid | Create a random string suitable for a unique identifier. |
MakeGuid4 | Make a binary Guid value, to conform to RFC 4122, version 4. |
Match | find the position of a regular expre |
MatchBrackets | Find the matching end bracket in a string. |
MD5 | Generates the MD5 Hash of a string |
MergeXML | Merge a new XML node into an existing XML document. |
Normalize | Normalizes a string reducing it to a form suitable for comparisons. |
NoStream | Ceases Streaming, without Flushing. See Streaming to a Disk file (Write-Caching) |
PathOnly | Gets the path part of a fully qualified file name |
PeekRAM | Debugging method to view the raw content of a variable. |
Prepend | Adds a sub string to the front of the string |
Quote | Adds the specified "quotes" to the stored (wraps the string in the passed quotes). |
Random | Fills the string with random characters |
Remove | Remove some text from the string. |
RemoveAttributes | Removes the attributes from an HTML tag. |
RemoveChars | Removes all specified characters from the string. |
RemoveFromPosition | Removes a number of characters from a position in the string. |
RemoveHTML | Removes all HTML markup, leaving just the text. |
RemoveXMLPrefixes | Removes all prefixes from inside xml tags. |
Replace | Replaces one, or more, instances of the search string with a new value |
ReplaceBetween | Replaces one, or more, instances of the search string with a new value, if it's between known left and right strings. |
ReplaceLast | Replaces the last instance of a substring in a string. |
ReplaceNth | Replace the nth instance of a substring in a string. |
ReplaceSingleChars | Replaces several possible single characters, with several other possible single characters. |
Reverse | Reverses the contents of the string so the first byte is last and so on. |
Right | Returns the non-space characters from the right of the string. |
SaveFile | Saves the current string to disk |
SeedRandom | Reseeds the random number generator. |
SerializeGroup | Converts a group to a (something) delimited string. |
SerializeQueue | Converts a Queue to a (something) delimited string. |
SetAfter | Alters the string to text after a specific search value. |
SetAfterLast | Alters the string to text after the last instance of a specific search value. |
SetAfterNth | Alters the string to text after the nth instance of a specific search value. |
SetAll | Repeats the contents of the current string, until the string is a specific length. |
SetBefore | Alters the string to text before a specific search value. |
SetBeforeLast | Alters the string to text before the last instance of a specific search value. |
SetBeforeNth | Alters the string to text before the nth instance of a specific search value. |
SetBetween | Injects text into the string, or replaces text already in the string, between two boundaries. |
SetDeformatValue | Sets the contents of the object to a Deformatted value. |
SetEncodingFromBOM | After loading a file, sets the encoding property based the Byte-Order-Mark (if one exists.) Optionally removes the BOM. |
SetFormatValue, | Sets the contents of the object to a formatted value. |
SetLeft | Removes leading spaces, and possibly limits the length of the string. |
SetLength | Sets the length of the string |
SetRight | Adds leading spaces so the string is the specified length, but has no trailing spaces. |
SetValue | Assigns a new value to the current string |
SetValueByAddress | Copies memory into the current string. |
SetValueByCstringAddress | set the contents of the object from ram, where the string is null terminated. either <0> or <0,0> or <0,0,0,0> depending on encoding. |
SetSlice | Sets the value of a substring within the stored string |
Slice | Returns a substring of the current string |
Sort | Sorts the contents of a string. |
Split | See Split, Manipulate and Join Strings |
Squeeze | Removes additional white space from between words in the string (word will be separated by only a single space after calling squeeze). |
Start | Reset all properties back to the default to reuse the object. |
StartsWith | Checks to see if the string starts with a substring. |
Stream | Starts a disk stream. See Streaming to a Disk file (Write-Caching) |
Sub | Returns a substring of the current string |
Str | Returns the current string and optionally stores the passed value. |
Swap | Swaps one object with another. |
Tail | Remove characters from the end of the string. |
ToAnsi | Converts the current Unicode (UTF-8 or UTF-16) string to ANSI |
ToCString | Creates a CString and copies in the current string value |
ToBlob | Saves the data stored by the StringTheory object in the passed BLOB. |
Top | Removes characters from the front of the string. |
ToUnicode | Converts the current ANSI string to Unicode (either UTF-8 or UTF-16) |
Trace | Sends a string to the DebugView program for logging |
Trim | Removes whitespace from the start and the end of the string |
UnQuote | Removes quotation marks (or the specified values) from the start and end of the string. |
Upper | Converts all the lower case characters to upper case |
UrlEncode | Method URL (percent) encodes the passed string |
UrlDecode | Methods decodes the passed URL (percent) encoded string. |
UrlFileOnly | Extracts the Filename part of a URL |
UrlHostOnly | Extracts the Host part of a URL |
UrlParameter | Returns the value of a single parameter from a URL. |
UrlParametersOnly | Extracts the Parameters part of a URL |
UrlPathOnly | Extracts the Path part of a URL |
UrlPortOnly | Extracts the Port part of a URL |
UrlProtocolOnly | Extracts the Protocol part of a URL |
Word | Retrieve the word at the specified position from the string. |
WordEnd | Returns the end position of the next word in the string given a start position to begin searching from. |
WordStart | Returns the start of the next word in the string given a starting position to being search from. |
WrapText | performs word wrapping to wrap the text to a fixed width by breaking lines as close the the specified width as possible. Lines are only broken on white space (tabs and spaces). The default wrap width is 80 characters. |
XMLDecode | Decodes a string that was encoded for transport in XML format. |
XMLEncode | Encodes a string into XML format, suitable for adding to an XML packet. |
ZeroXDecode | Decodes a string stored as a hex-encoded-byte-array. |
ZeroXEncode | Encodes a string as a hex-encoded-byte-array, consistent with C, JavaScript etc languages. |
Split, manipulate and Join strings | |
Split | Splits the string into parts based on the specified delimiters |
SplitBetween | Splits the string into parts based on a left and right substring. |
SplitByMatch | Splits the string into parts, based on a regular expression. |
SplitEvery | Splits the string into substrings of the specified length. |
SplitIntoWords | Splits the string into a queue of words. |
Join | Creates a string from the separate lines (where the lines are made by Split) |
AddLine | Adds a line to the line queue, at a specific position. |
DeleteLine | Deletes a line from the line queue. |
FreeLines | Frees the Queue populated by the Split method |
GetLine | Gets a specific line after a call to the Split method |
GetLines | Gets a group of lines after the call to the Split method. |
InLine | Searches the lines for a specific substring |
Records | Returns the number of records after a call to the Split method |
RemoveLines | Remove empty lines, or lines which only contain specific characters. |
SetLine | Sets the Value of a specific line in the queue |
Sort | Sorts the lines alphabetically |
Filter | Remove some lines, based on the presence, or absence, of a string on that line. |
Formatting and Deformatting | |
FormatTime | Formats a number (Clarion standard time) into a String |
DeformatTime | Formats a string into a number (Clarion Standard Time) |
FormatHTML | Format text according to HTML indenting and line ending rules. |
Base Conversion, Hexadecimal encoding and Byte Ordering | |
ToHex | Converts the stored string to a hex string - each bytes is converted to two characters representing the hexadecimal equivalent. |
FromHex | Converts a string that is encoded as a hex string back to the original value. |
DecToBase | Converts a decimal number to a number using the specified base (such as Hexadecimal - base 16) |
BaseToDec | Converts the passed number stored in a string to a decimal |
ByteToHex | Returns a string that contains the hexadecimal equivalent of the passed byte |
LongToHex | Converts a long of 4 bytes to hex. Returns a string that contains the hex of each byte in big endian order (the most significant byte first) |
StringToHex | Returns a string that contains the hexadecimal equivalent of each byte in the passed string (which is treated as binary data). |
HexToString | Decodes the passed hex string and returns a pointer to a new string that contains the unencoded data. |
BigEndian | Returns a big endian long when passed a little endian one |
LittleEndian | Returns a little endian long when passed a big endian one |
SwitchEndian | Switches between big endian and little endian (returns a little endian long when passed a big endian one and vice versa). |
ReverseByteOrder | Reverse the byte order of the stored string (the entire string is reversed). |
Unicode Encoding, Conversion and Handling | |
ToAnsi | Converts the current Unicode (UTF-8 or UTF-16) string to ANSI |
ToUnicode | Converts the current ANSI string to Unicode (either UTF-8 or UTF-16) |
AnsiToUtf16 | Converts the pass ANSI string to UTF-16 encoded Unicode |
Utf16ToAnsi | Converts the passed UTF-16 encoded Unicode string to ANSI |
Utf8To16 | Converts UTF-8 to UTF-16 |
Utf16To8 | Converts UTF-16 to UTF-8 |
Utf16ToUtf8Char | Converts a Utf-16 (2 byte) character to a (1 to 3 byte long) Utf-8 character |
Utf8ToAnsi | Converts the passed UTF-8 encoded Unicode string to ANSI |
AnsiToUtf8 | Converts the passed ANSI string to UTF-8 encoded Unicode |
DecodeHexInline | Converts text encoded with \x or \u in an ANSI string into the appropriate character |
BigEndian | Makes sure the string (if utf-16) is in BigEndian form. |
LittleEndian | Makes sure the string (if utf-16) is in LittleEndian form. |
Other Encodings | |
Base64Decode | Decode a string that is encoded using Base64 |
Base64Encode | Encode the string using Base64 encoding method |
Base85Decode | Decode a string that is encoded using Base85 / ASCII85 |
Base85Encode | Encode the string using Base85 / ASCII85 encoding method |
EncodedWordDecode | Decodes the string if it's encoded in "Encoded Word" format. |
EncodedWordEncode | Encodes the string to "Encoded Word" format. |
ToHex | Converts the stored string to a hex string - each bytes is converted to two characters representing the hexadecimal equivalent. |
FromHex | Converts a string that is encoded as a hex string back to the original value. |
HtmlEntityToDec | Converts HTML Entity names to Unicode Decimal encoding. |
JsonDecode | Decodes a string that was encoded for transport in JSON format. |
JsonEncode | Encodes a string into JSON format, suitable for adding to a JSON packet. |
QuotedPrintableEncode | Encodes the string to QuotedPrintable Format. |
QuotedPrintableDecode | Decodes the string from QuotedPrintable format. |
UrlEncode | Method URL (percent) encodes the passed string |
UrlDecode | Methods decodes the passed URL (percent) encoded string. |
XMLDecode | Decodes a string that was encoded for transport in XML format. |
XMLEncode | Encodes a string into XML format, suitable for adding to an XML packet. |
Binary Data handling and storage | |
FromBytes | Converts a value stored as binary within a string back into the native data type (for example retrieving a Long value from a String). Prevents any automatic type conversion and retrieves the actual binary value stored in a string for the following types: byte, short, ushort, long, ulong, sreal, real, decimal, cstring, string |
ToBytes | Stores the passed value in a string as binary. Does not do any type conversion - the data is stored as a sequence of bytes with the same values as in the original. Support the following types: byte, short, ushort, long, ulong, sreal, real, decimal, cstring, string |
GetBytes | Retrieves a binary value stored in the StringTheory object. |
SetBytes | Stores a binary value in the StringTheory object. |
Compression and Decompression | |
Gzip | Compress the string to the .gz (gzip) format using the external zlibwapi.dll. |
Gunzip | Decompress the string from the .gz (gzip) format using the external zlibwapi.dll |
NOTE: To make use of the GZIP and GUNZIP methods, you must copy the ZLIBWAPI.DLL into your application folder. |
Parameter | Description |
---|---|
pPos | The desired length of the string. |
pRangeLeft | The number of characters to examine, left of the desired position. |
pRangeright | The number of characters to examine, right of the desired position. If the pPos value is an upper-bound then set this parameter to 0. |
Parameter | Description |
---|---|
Encoding | the encoding to use. Valid values are st:EncodeUtf8 or st:EncodeUtf16. If omitted then the current encoding (as set in the encoding property) is used. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after the last instance of this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after the last instance of this string (not including this string). |
Occurrence | The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end. |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
Length (optional) |
The length of the resultant string. If the parameter is
omitted then a length of 255 is used. If the current string is empty then a space-padding-string of Length is returned. If the current string is longer than Length then the first Length characters are returned. If Length is not a multiple of the current string length, then the result will be truncated to Length characters. |
Parameter | Description |
---|---|
newValue | The value to append to the string |
pOptions | This can be one of several options. st:NoClip - The NewValue is not clipped before being added to the object. st:Clip - The NewValue is clipped before it is appended st:NoBlanks - If the NewValue is blank, then the pSep parameter is not added to the string. st:Clip + st:NoBlanks- the string is clipped, and the separator is not added if NewValue is blank. st:Lines - the Lines Queue from the pStr is added to the lines for this object. (Lines are added after the existing lines.) Note: Only text data should be clipped. Clipping binary data is not recommended. |
pStr | Another StringTheory object. If this form of the method is used then the contents of pStr will be appended to the current object. |
pSep | If the string already contains text, then the optional Separator is added between the existing text, and the new text. If the string is currently blank then the separator is ignored. The separator is not clipped (thus allowing for space separators) so care should be taken with the string being passed. |
Parameter | Description |
---|---|
Value | The value (in number form) to append to the string |
Length | The number of bytes to append to the string. Use 1 for a byte, 2 for a short, or 4 (the default) for a long. |
Parameter | Description |
---|---|
pLen | The amount to adjust the length of the string by. This value can be positive or negative. |
Parameter | Description |
---|---|
pPos | The position in the current string to extract from. Only the first ASN value found, starting at this position is extracted. This field is altered to point at the first character after the extracted value. |
rAsnValue | The raw data in the Value part of the encoding. |
rAsnType | A string, length 1 or more, to contain the TYPE of the
field extracted. the type returned is always 1 character long.
Some common types are declared in the Stringtheory.Inc
file, however this list is not exhaustive. For example; st:ASN_BOOLEAN Equate('<01h>') st:ASN_INTEGER Equate('<02h>') st:ASN_BITSTRING Equate('<03h>') st:ASN_OCTETSTRING Equate('<04h>') This parameter is optional and can be omitted if the type is not required. |
Parameter | Description |
---|---|
pType | The ASN Type to use. This is a String 1. Some basic types are declared in StringTheory.Inc, however other type values may also be used depending on the program creating or consuming the type. |
pValue | An optional parameter. If this parameter is omitted then the current string in the object will be used. Strings of zero length are allowed in ASN. |
Parameter | Description |
---|---|
pType | The ASN Type to use. This is a String 1. Some basic types
are declared in StringTheory.Inc,
however other type values may also be used depending on the
program creating or consuming the type. A number of the types
are numeric, for example; st:ASN_BOOLEAN Equate('<01h>') st:ASN_INTEGER Equate('<02h>') st:ASN_ENUMERATED Equate('<00Ah>') |
pValue | The number to encode. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text before this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text before the last instance of this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
SearchValue | Searches for the nth instance this string in the current string, and returns all the text before the last instance of this string (not including this string). |
Occurrence | The nth occurrence of the SearchValue to look for. If the value is positive the search is from the start, if negative then backwards from the end. |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
Parameter | Description |
---|---|
Left | The left hand delimiter. If this is blank, and Start is 0, then the start of the string is used. If this is blank, and the Start parameter is set then text from the start position is returned (if the Right boundary is found). |
Right | The right hand delimiter. If this is blank then the end of the string is used. |
Start [optional] | If this is specified then the search for the delimiter starts at this position in the string. Defaults to the start of the string. |
End [optional] | If this is specified then the search ends at this position in the string (delimiters after this are ignored). Defaults to the length (end) of the string. |
NoCase [optional] | If this is set then the delimiter search is case insensitive, otherwise it is case sensitive. |
Exclusive [optional] | If this is set to true (the default) then the delimiters are not included in the returned string. If it is set to false then they are included in the returned string. |
Parameter | Description |
---|---|
pOptions | st:noCase: Upper and Lower case
are treated the same st:detectAlphabet: use this if you do not know the alphabet - it will try to work it out based on first 1000 chars (or less if not that much data). If an alphabet is passed in, then that will be tested first. If that fails the default alphabet will be used. If that fails the ExtendedHex alphabet (0123456789ABCDEFGHIJKLMNOPQRSTUV=) will be used. If st:detectAlphabet is set then st:noCase is implied (whether it is set or not). If st:Tolerant is used then characters not in the alphabet will be discarded before decoding. If the result is not a multiple of 8 characters, then padding is automatically added to make up the missing characters before decoding commences. If st:Tolerant is not used, then only whitespace (CR,LF,Tab,Space) will be removed. The remaining characters must all be part of the alphabet. |
pAlphabet | A string containing the alphabet to use. If omitted the
default alphabet is 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=' The alphabet MUST be 33 characters long, consisting of the 32 char alphabet, and the padding character (usually =). If a 32 char alpabet is passed in, the padding char is set to =. If an alphabet length of a different length is used, the method will return st:notok. the padding character may not be one of the alphabet characters. Alphabets may not contain formatting characters (CR, LF, Tab, Space) |
Parameter | Description |
---|---|
pOptions | This parameter allows for a number of options which affect
the outcome. These options can be added together if multiple
options are required. st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length. st:NoPadding : Usually base32 output is padded with = characters to be a multiple of 8 bytes. If this option is on that padding is removed. |
pAlphabet | The alphabet to use. If not passed, the default alphabet (ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=) is used. |
Parameter | Description |
---|---|
pOptions | This parameter allows for a number of options which affect
the outcome. These options can be added together if multiple
options are required. st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length. st:URLSafe : If this option is used then an alternate base64 alphabet is used. This output is suitable for use in a URL or HTTP header. If this option is set then st:nowrap is also set. This alphabet replaces + with - and / with _. st:NoPadding : Usually base64 output is padded with = characters to be a multiple of 3 bytes. If this option is on that padding is removed. |
Parameter | Description |
---|---|
pOptions | This parameter allows for a number of options which affect
the outcome. These options can be added together if multiple
options are required. st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length. st:Adobe85 : If this option is used then the encoding uses the Adobe variant. The Adobe variant is bounded by <~ and ~>. |
Parameter | Description |
---|---|
pCount | The maximum number of words to Check. (Not this is NOT the maximum number of words to Change.) Defaults to 1 - ie only the first word in the string will be Capitalized. Set it to 0 to capitalize all words. |
pStartPos | The position in the string to begin. Defaults to the start of the string. |
pEndPos | The position in the string to end. Defaults to the end of the string. |
pCharList | The list of characters which specify the end of a word. The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' |
Parameter | Description |
---|---|
pBaseFrom | The base of the current string. Use 10 for decimal, 16 for Hexadecimal and so on. Valid values are in the range 2 through 36. |
pBaseTo | The base to change 10. Use 10 for decimal, 16 for Hexadecimal and so on. Valid values are in the range 2 through 36. |
Parameter | Description |
---|---|
pEncoding | Possible values are st:EncodeANSI, st:EncodeUft8, st:EncodeUtf16. If omitted then the current value in the st.Encoding property is used |
pStr | The string to count the characters for. If omitted then the current value of the object is used. |
Parameter | Description |
---|---|
pFrom | The character value to encode from. Must be from 0 to 255. Defaults to 128. |
pTo | The character value to encode from. Must be from 0 to 255. Defaults to 255. |
Parameter | Description |
---|---|
fileName | The file name to create a clean version of. If omitted then the current value is used. |
replaceChar | Optional parameter for the replacement character. Defaults to an underscore. |
Parameter | Description |
---|---|
pAlphabet | Defines the white-space characters to be clipped from the end of the string. If omitted then only space characters are clipped. |
Parameter | Description |
---|---|
pColor | A color in either long, hex, csl or name format. |
Example |
---|
Str StringTheory color Long code color = str.ColorToLong(color:red) color = str.ColorToLong('red') color = str.ColorToLong('#F00') color = str.ColorToLong('#FF0000') color = str.ColorToLong(color:MenuBar) color = str.ColorToLong('rgb(255,0,0)') color = str.ColorToLong('(255,0,0)') color = str.ColorToLong('255,0,0') |
Parameter | Description |
---|---|
pColor | A color in either Clarion (Long), or Web (#hex) format, or standard color name, or Comma-Separated-List (rgb(r,g,b)) format |
addhash [optional] | If this is set to True then the hexadecimal string starts with a hash character. Primarily for compatibility with web (HTML, CSS etc.) colors. For example 0 (black) would produce '#000000'. Default value is false. |
Example |
---|
col long hCol string(7) St StringTheory code col = color:red hCol = St.ColorToHex(col) ! hCol contains 'ff0000' hCol = St.ColorToHex(col, true) ! hCol contains '#ff0000' |
Parameter | Description |
---|---|
Alphabet | A list of individual characters. If the string contains any of the characters in this list, then true is returned. |
TestString (optional) | The string to test. If omitted the current string value of the object is used. |
Clip (Optional) | If true (the default) then the alphabet string is clipped when doing the text. If you want to test for a space, and the space is not the last character, then you can leave this as true. In the case where you are testing only for spaces then use .ContainsA(' ', ,false) |
Parameter | Description |
---|---|
pByte | A single byte value to test in the string. |
TestString (optional) | The string to test. If omitted the current string value of the object is used. If the testString is passed, then it is not clipped, so trailing spaces will count as "containing a space". |
Parameter | Description |
---|---|
Char | A single character to test. this character is case sensitive. |
TestString (optional) | The string to test. If omitted the current string value of the object is used. If the testing is passed, then it is not clipped, so trailing spaces will count as "containing a space". |
Parameter | Description |
---|---|
pTabSize | The tab boundary. Defaults to every 8 characters. |
pLineEnding (optional) | The characters that indicate the end of a line. Defaults to CRLF - ie ('<13,10>'). |
Parameter | Description |
---|---|
searchValue | The value to search the string for. |
pStep [optional] | The number of characters to step through the string for each search. This parameters is optional and defaults to 1. |
pStart [optional] | Position in the string to start the search at. Defaults to 1 (the start of the string). If value < 1 then is treated as 1. |
pEnd [optional] | Position in the string to end searching at. This parameter is optional, the default of 0 searches to the end of the string. |
noCase [optional] | If this is set to non zero then the search is case insensitive, otherwise a case sensitive search is done (the default behaviour). |
softClip [optional] | By default (with softClip set to True) the method will return a count of all matching strings that start within the passed range, even if the string overlaps the passed pEnd parameter. To include on strings that are completely within the pStart to pEnd range the softClip parameter can be passed as False. |
Overlap [optional] | If true then the test is moved forward 1 character when a match is found. If false then the test is moved forward by the length of the substring when a match is found. For example, if overlap is true then AA is found 3 times in AAAA. If it is false then it's found twice in AAAA. |
Example |
---|
|
Parameter | Description |
---|---|
Long startPos [optional] | The start position to begin counting words from. Defaults to the start of the string |
Long TextType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character.) |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?()*/+=<>:' when the TextType parameter is set to ST:HTML. (no & char) |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Parameter | Description |
---|---|
start | The position to start the crop at (the first character to be included in the cropped string). If the start parameter is omitted then it defaults to the start of the string (the string will only be cropped at the end). |
end | The position to end the crop at (the last character to be included in the cropped string). If the end parameter is omitted then it defaults to the end of the string (the string will only be cropped at the front). |
Example |
---|
st StringTheory code st.SetValue('123456789') st.Crop(4, 7) ! Crop the string from the forth to the seventh characters Messsage(st.GetValue()) ! Will display: 4567 |
Parameter | Description |
---|---|
pValue | The string to deformat. If not passed then the current contents of the object are used. |
pPicture | The picture that hints how the string is formatted. Supports Extended Pictures. With some formats the picture acts as a hint only, and another picture may be used if it is a better fit. For example a time value (hh:mm:ss) will be deformatted as @t4 even if the picture passed is @t1. |
st StringTheory code st.SetValue('12/31/2022')See Also
x = st.DeformatValue('@d1')
Parameter | Description |
---|---|
Sub | The sub string to check for. If this string is empty then the method returns true. |
Case | Set this to false if the test is case insensitive. The default value is true, meaning the test is case sensitive. |
Clip | If this is true (the default) then the Sub string is clipped before comparing to the stored string. If set to false then any trailing spaces in the Sub parameter will need to match trailing spaces in the string. |
st StringTheory code st.SetValue('123456789') x = st.EndsWith('89') ! x is true at this point x = st.EndsWith('') ! x is true at this point x = st.EndsWith('8') ! x is false at this pointSee Also
Parameter | Description |
---|---|
pOtherValue | The StringTheory object, or string, to compare this object
to. If this parameter is a string then the string is assumed to be ANSI, and the default option includes clipping. |
pOptions (optional) |
Contains flags describing the depth of the comparison. ST:Clip : Only when a String form is used - clips the string before comparing ST:SimpleCompare : The strings are compared byte for byte regardless of encoding. ST:UnicodeCompare : The strings are first converted to a common type before comparing them. The original strings are not altered. st:NoCaseCompare : The strings are compared in a case insensitive way. (Some unicode comparisons are incomplete at this time.) |
Parameter | Description |
---|---|
Charset - optional | The Charset to use. The charset may be any character set registered with IANA. For example iso-8859-1. If omitted then the ASCII charset (iso-8859-1) will be used. |
Encoding - optional | One of st:QuotedPrintable or st:Base64. If the parameter is omitted, or invalid then st:QuotedPrintable is used. |
Parameter | Description |
---|---|
FileName | If a Filename is passed into the method, then the Extension of that filename is returned. If the parameter is not passed then the contents of the string is treated as a filename, and the extension of that is returned. |
Parameter | Description |
---|---|
FileName | If a Filename is passed into the method, then the name of that file is returned. If the parameter is not passed then the contents of the string is treated as a filename, and only the file name of that is returned. |
IncludeExtension (optional) | If omitted, or True, then the filename returned will include the extension part of the name. If the parameter is set to False then the name without the extension is returned. |
Example |
---|
st stringtheory s string(255) code s = command(0) s = st.FileNameOnly(s) |
Parameter | Description |
---|---|
Left | The left hand delimiter. If this is blank then the start of the string is used. |
Right | The right hand delimiter. If this is blank then the end of the string is used. |
Start | The search for the delimiter starts at this position in the string. If less than or equal to zero this defaults to the start of the string. When the method returns this is set to the start position of the returned string. |
End | The search ends at this position in the string (delimiters after this are ignored). Defaults to the length (end) of the string if the passed value is less than or equal to zero. On return this is set to the end position of the returned string. |
NoCase [optional] | If this is set then the delimiter search is case insensitive, otherwise it is case sensitive. |
Exclusive [optional] | If this is set to true (the default) then the delimiters are not included in the returned string. If it is set to false then they are included in the returned string. |
Example |
---|
limit = 0 !
set to zero for end of string
pStart = 0 ! set to zero or one for start of string loop pEnd = limit betweenVal = st.FindBetween('[[', ']]', pStart, pEnd) if pStart = 0 break else ! do something with the returned betweenVal end ! Reset pStart for next iteration. If not doing pExclusive then pStart = pEnd + 1 pStart = pEnd + len(pRight) + 1 end |
Parameter | Description |
---|---|
pSearchValue | The byte to search for. |
pStart [optional] | The position to start searching at. Defaults to the start of the string. |
pEnd [optional] | The position to end searching. Defaults to the end of the string. |
pText [optional] | The string to search. If omitted the object value is searched. |
Parameter | Description |
---|---|
pSearchValue | The character to search for. If this string contains multiple characters then the search is only done on the first character - the other characters in the SearchValue are ignored. |
pStart [optional] | The position to start searching at. Defaults to the start of the string. |
pEnd [optional] | The position to end searching. Defaults to the end of the string. |
pText [optional] | The string to search. If omitted the object value is searched. |
Parameter | Description |
---|---|
pSearchValue | The substring to search for. |
pStart [optional] | The position to start searching at. Defaults to the start of the string. |
pEnd [optional] | The position to end searching. Defaults to the end of the string. |
pText [optional] | The string to search. |
Parameter | Description |
---|---|
pEncoding | One of st:EncodeAnsi, st:EncodeUtf8 or st:EncodeUtf16. For ANSI and UTF-8 encodings a single null character is needed to end the string. If the UTF-16 encoding is used, then two null characters are needed to end the string. |
pStringAddress | The start of the memory block to start searching |
pMaxLength | The maximum length to look for. The default is 255. This prevents searches from exceeding possible string limits. |
Parameter | Description |
---|---|
pSearchValue | The sub string value to look for. |
pStart | The position in the current value to begin searching from. If this parameter is omitted then the search starts at the beginning of the current value. |
pEnd | The position in the current value to stop searching. If this parameter is omitted then the search ends at the end of the current value. |
pNoCase | If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive. |
Parameter | Description |
---|---|
pRegEx | The characters to search for. This string can contain a regular expression. |
pStart | The position to start searching at. Defaults to the start of the string. The start position of the found string is returned here. If the searched-for string is not found then this value changes to 0. |
pEnd | The position to end searching. Defaults to the end of the string. The end position of the found string. If the searched-for string is not found then this value changes to 0. |
pMode | Supported modes are; Match:simple, Match:regular. Match:wildcard and Match:SoundEx are not supported. |
pNoCase | Set this to true (st:nocase) to do a case insensitive match. |
Parameter | Description |
---|---|
pSearchValue | The characters to search for. |
pOccurrence | The nth instance of the characters to search for. If this value is positive then it searches from the start, if negative it searches from the end. |
pStart | The position to start searching at. Defaults to the start of the string. The start position of the found string is returned here. If the searched-for string is not found then this value changes to 0. |
pEnd | The position to end searching. Defaults to the end of the string. The end position of the found string. If the searched-for string is not found then this value changes to 0. |
pNoCase | Set this to true (st:nocase) to do a case insensitive match. |
Parameter | Description |
---|---|
pStr | Typically used with a very large string. If passed this will be written to the disk file, after flushing the current cache. |
Parameter | Description |
---|---|
long WordNumber | The number (position) of the word in the string to return. For example given the string "Hello World", a WordNumber of 2 would return "World". |
long startPos [optional] | The position to start searching for the word at. |
long TextType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character.) |
Start | A long which will be populated with the position of the first character of the word in the string |
End | A loA long which will be populated with the position of the last character of the word in the string |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML. |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Parameter | Description |
---|---|
pValue | The value to format. If not passed then the current contents of the object are used. |
pPicture | The picture that determines how the string is formatted. Supports Extended Pictures. |
st StringTheory
code
s = st.FormatValue(81087,'@d1')
See AlsoParameter | Description |
---|---|
*blob blobField | The BLOB to retrieve the data from. |
Example |
---|
ss
StringTheory blobContents string code s.FromBlob(MailData.Text) ! Store the data blobContents = s.GetValue() ! Get the stored data |
Parameter | Description |
---|---|
Lines | If set to True then FreeLines is also called. If set to false (the default) then the Lines queue is unaltered. |
Force | If set to false (the default) then existing memory owned by the object is not disposed. In other words the string is cleared, but the memory is held. If set to true then the memory is disposed. |
Parameter | Description |
---|---|
PSrc | A string that contains the binary value to be retrieved. |
pVal | The variable to store the binary value into |
pOffset | The offset index into the string for where to get the value from. If omitted then then the default position is the first character in the string. |
Example |
---|
a Long s String(10) code s = 'AAAABBBB' str.FromBytes(s,a) ! a = 1094795585 = 041414141h str.FromBytes(s,a,5) ! a = 1111638594 = 042424242h |
Parameter | Description |
---|---|
pDest | The variable to receive the value from the StringTheory object. |
pOffset | The offset in the Object string to get the value from. |
Parameter | Description |
---|---|
pVal | The variable to receive the value stored in the StringTheory object |
pType | A string that contains the Clarion type for the passed parameter: 'BYTE', 'SHORT', 'USHORT', 'LONG', 'ULONG', 'REAL' etc. |
Parameter | Description |
---|---|
long pCharSet | The Clarion font charset . If omitted then the current system{prop:charset} is used. Makes a reasonable guess as to what charset the program is currently using. |
Parameter | Description |
---|---|
pStart | Allows for an offset into the current string value. In other words returns a pointer to a string, where the string starts not from the beginning of the string, but from somewhere in the string. Default value is 0. |
pEnd | Allows for an early-end of the current string value. In other words allows passing of "part of the string" to another function which takes a *string as input. Default value is the end of the current object. |
Parameter | Description |
---|---|
long WordNumber | The number (position) of the word in the string to return. For example given the string "Hello World", a WordNumber of 2 would return "World". If the word number is negative, then the search counts words from the end of the string. For example, given the string "This is the end" a word number of -2 would return "the". |
llong startPos [optional] | The position to start searching for the word at. |
long TextType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character.) |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML. |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Parameter | Description |
---|---|
long pOptions | By default the method will encode the string using Hex encoding, and hypens. The hypens can be suppressed using st:NoHypens. If curly brackets are desired, then these can be added using st:brackets. these two options can be added together. |
Parameter | Description |
---|---|
long pOffset | By default the string is assumed to contain a compressed value. If the string is partially uncompressed (the "header" part) and then compressed (the "body" part) then this allows you to specify the starting point of the decompression. Specifically the pOffset value is the number of uncompressed bytes at the start of the string. |
Parameter | Description |
---|---|
long pLevel | This is a value from 0 to 9 where 1 is the fastest, and 9 is the most compressed. If set to 0 no compression takes place. If omitted the default value for this parameter is 5. |
Example |
---|
str.LoadFile('whatever.txt') str.Gzip() str.SaveFile('whatever.txt.gz') |
Parameter | Description |
---|---|
Start | Start position to insert at. If the Start parameter is less than or equal to 1, then the new value is prepended to the front of the string. If it is higher than the current length of the string then the current string is padded with spaces so that the new value can be added at the specified position. |
insertValue | The string to insert at the specified position. This value is not clipped, so clip if necessary. |
Parameter | Description |
---|---|
SearchValue | The sub string value to look for. |
Step | The number of characters stepped in the current value, if a
match is not made. Unlike the Clarion INSTRING function (which
defaults to the length of the sub string), this value defaults
to 1 if omitted. This number can be < 0. If <0 then the search is performed backwards from the End to the Start. Note that even if this value < 0 then Start remains the "left" position in the string to search, Start and End do not switch place in the parameter list. If step=0 then only value at the Start position is checked. |
Start | The position in the current value to begin searching from. If this parameter is omitted then the search starts at the beginning of the current value. |
End | The position in the current value to stop searching. If this parameter is omitted then the search ends at the end of the current value. |
NoCase | If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive. |
WholeWord | If this parameter is set to not zero, then only sub strings which form a Whole Word will be returned. A whole word is defined as any sequence not immediately followed, or preceded by an alpha-numeric character (A through Z, a through z and 0 through 9). |
Parameter | Description |
---|---|
Alphabet | The list of characters to test against the string. |
TestString | The string to test. If omitted the current string value of the object is used. |
Clip | If true (the default) then the Alphabet is clipped before being used in the test. If you do want to include a space character in the alphabet then make sure it's either not the last character, or this parameter is set to false. |
Parameter | Description |
---|---|
Value (optional) | If a value is passed to the method, then it will do the detection on this value. If not, the contents of the object value will be tested. |
Parameter | Description |
---|---|
Options (optional) | Default is none. If set to st:xml then the < character is encoded as \u003c. This allows the JSON string to be included in XML without creating an unexpected opening tag. |
Parameter | Description |
---|---|
Alphabet | Only characters specified in this string will be preserved. This string is case sensitive. |
pReplacementChar | If this parameter exists then any chars not in the alphabet are not removed, but replaced with this character. This parameter is only a single character long - any additional characters are ignored. |
Parameter | Description |
---|---|
Length (optional) |
The Length of the string to return. If omitted, or zero, the
current length of the string is used. If the Length is set to less than the current string length then the string is cropped to fit. |
What (optional) | Determines what leading characters are removed. Possible
options for this parameter are; st:Spaces (This is the default value if the parameter is omitted.) st:Tabs st:cr st:lf st:zeros These options can be added together. For example to remove leading spaces and leading tabs you can use st.left( ,st:spaces + st:tabs) To remove all leading spaces, tabs, carriage returns and linefeeds use st.left( ,st:spaces + st:tabs + st:cr + st:lf) |
Pad (optional) | Allows you to specify the character to use as the padding character if the length required is greater than the current string. If omitted then the default pad character is a space. |
Parameter | Description |
---|---|
Endings (optional) |
The format desired for the text. Valid options are st:None, st:Windows, st:Mac, st:Unix and st:web. If this parameter is omitted then st:Windows is used. |
pFrom | If the source document is known to be HTML, and conversion of <br> etc is desired then set this parameter to st:web. |
Parameter | Description |
---|---|
FileName | The name of the file to load from disk. |
Offset [optional] | The offset into the file to begin reading. For example if this is set to 10, then the read will commence with the 11th character. If the value is larger than the file then Errortrap is called, and the current value in the object is cleared. If this value is less than zero, then the read is measured from the end of the file. For example, if this value is -10 then the last 10 characters in the file will be read. |
Length [optional] | The maximum number of bytes to load. If this number is greater than the data (left) in the file then the available data is read. |
RemoveBOM [optional] | Default value is false. If set to true, and the file contains a Byte-Order-Mark (BOM) as the first 2 or 3 bytes, then the BOM will be removed when the file is loaded. Regardless of whether this parameter is true or false, the .encoding property will be set if a BOM exists. |
Example |
---|
|
Parameter | Description |
---|---|
pDivisor | The integer value to divide the string by. |
pRemainder | A long to hold the remainder after the division is complete. |
pBase | The base of the number in the string. Valid values are 2 through 36. If this base is invalid then then method will terminate with a return value of str |
Example |
---|
st stringtheory r long code st.SetValue('184694349FB2A2C700000000532BC82B') st.LongDivision(10,r,16) ! st now contains '26d7538765ea9e0b33333333b8460d1' ! r contains 1 |
Parameter | Description |
---|---|
Quote (optional) | A character to identify the start of Quoted Text. Quoted Text will not be lowered by this method. If this parameter is omitted then all the text in the string is lowered. |
QuoteEnd (optional) | The character to use as the end of Quoted Text. If omitted, and the Quote parameter is not omitted, then the same quote character will be used to delineate the start and end of text. |
Example |
---|
st stringtheory code st.SetValue('This is a "TEST" of the LOWER method') st.lower('"') ! st now contains 'this is a "TEST" of the lower method' |
Parameter | Description |
---|---|
pOptions | If set to st:format then the returned value is not binary, but already passed through GuidEncode. Options for GuidEncode can be used here as well. |
Parameter | Description |
---|---|
pRegEx | The regular expression to search for. |
pStart | The start position to start searching in the string. Defaults to the start of the current object. |
pEnd | The end position to stop searching in the string. Defaults to the end of the current object. |
pMode | Supported modes are; Match:simple, Match:regular. Match:wildcard and Match:SoundEx are not supported. |
pNoCase | Set this to true (st:nocase) to do a case insensitive match. |
Example |
---|
Parameter | Description |
---|---|
LeftBracket | A string, indicating the left bracket of the search. For example, ( or < or { and so on. |
RightBracket | A string indicating the right bracket in the search. |
Start | The position to start in the string. The first instance of the LeftBracket after the start marks the beginning of the search. If omitted the search starts at the beginning of the string. |
Parameter | Description |
---|---|
pFormat (optional) | Determines the format of the result. Possible options are st:EncNone, st:EncHex or st:EncBase64. If omitted this parameter defaults to st:EncHex. |
pStr (optional) | If passed, then the MD5 is calculated on the passed string, not the current string contents. If ot passed then the contents of the object are used to calculate the hash. |
pLength (optional) | If the pStr parameter is passed, then the length of the data to hash must be passed as well. |
Example 1 |
---|
|
Example 2 |
---|
st.SetValue(myValue)
! Store the value to create
a hash of |
Parameter | Description |
---|---|
New | The block of new xml code to inject into the current document. |
Where | Indicates the position where the new node must be placed. Valid options are st:First and st:Last |
Parameter | Description |
---|---|
Form | The string can be normalized to one of four forms. Valid
values here are; st:NFC, st:NFD, st:NFKC and st:NFKD. If omitted defaults to st:NFKD. |
Preserve Encoding | If omitted defaults to true. If true then if the string is
encoded as utf-8, then it will remain as utf-8 when this
method completes. If it is false, and the current encoding is
utf-8 then the encoding of the string will change to utf-16. If the current encoding is ANSI then the method immediately returns without any change to the string (regardless of this parameter setting.) |
Parameter | Description |
---|---|
FileName | If a Filename is passed into the method, then the Path part of that filename is returned. If the parameter is not passed then the contents of the string is treated as a filename, and the path part of that is returned. |
Example |
---|
st stringtheory s string(255) code s = command(0) s = st.PathOnly(s) ! c:\program\bob |
Parameter | Description |
---|---|
pResult | Optional. If omitted the output is sent to Debugview. If passed then the result is placed into the passed object. |
pAdr | The address of the memory (or variable) to be peeked at. If the second form of the method is used (ie this parameter is not passed) or this value is 0, then the current contents of the StringTheory object are peeked. |
pLen | The length of memory to Peek. |
pFormat | One of st:Decimal or st:Hex. Determines the number format of the value being output. |
Parameter | Description |
---|---|
newValue | The value to prepend to the string |
pOptions | This can be one of several options. st:NoClip - The new value is not clipped before the NewValue is prepended. st:Clip - The NewValue value is clipped before the NewValue is prepended to the string. st:NoBlanks - If the NewValue is blank, then the pSep parameter is not prepended to the string. st:Clip + st:NoBlanks- the new value is not clipped, and the separator is not added if NewValue is blank. st:Lines - the Lines Queue from the pStr is added to the lines for this object. (Lines are added before the existing lines.) Note: Only text data should be clipped. Clipping binary data is not recommended. |
pStr | Another StringTheory object. If this form of the method is used then the contents of pStr will be prepended to the current object. |
pSep | If the string already contains text, then the optional Separator is added between the existing text, and the new text. If the string is currently blank then the separator is ignored. The separator is not clipped (thus allowing for space separators) so care should be taken with the string being passed. |
Parameter | Description |
---|---|
pQuoteStart | Optional character to use as the opening quotation mark. Defaults to a double quote ("). |
pQuoteEnd | Optional character to use as the closing quotation mark. Defaults to pQuoteStart. |
Example |
---|
st.Quote() ! Wrap the string in double quotes |
Example |
---|
st.SetValue('If you believe that
truth=beauty, then surely mathematics is the most beautiful
branch of philosophy.') st.QuotedPrintableEncode() ! object now contains If you believe that truth=3Dbeauty, then surely mathematics is the most bea= utiful branch of philosophy. |
Example |
---|
st.SetValue('If you believe that
truth=3Dbeauty, then surely mathematics is the most
bea=<13,10>utiful branch of philosophy.') st.QuotedPrintableDecode() ! object now contains If you believe that truth=beauty, then surely mathematics is the most beautiful branch of philosophy. |
Parameter | Description |
---|---|
Length [optional] | The length of the random string to return. If omitted the default string length is 16 characters. |
Flags [optional] | Determines the alphabet that can be used. Can be one or more
of the following; st:Binary - Includes characters from chr(0) to chr(255). The Alphabet parameter, and other flags, are ignored. st:AlmostBinary - Includes characters from chr(1) to chr(255). The Alphabet parameter, and other flags, are ignored. st:Alphabet - Use only the Alphabet parameter st:Upper - Includes Uppercase letters from A to Z in the alphabet. st:Lower - Includes lowercase letter from a to z in the alphabet. st:Number - Includes decimal digits from 0 to 9 in the alphabet st:Hex - Includes A to F and 0 to 9 in the alphabet. (Only works if st:Upper, st:Lower and st:Number are all excluded from the flags) st:space - Include a space character in the alphabet. st:DNA - Includes the uppercase characters GCAT. (Ignored if st:Upper is set). st:AlphaFirst - Regardless of the other bit settings, the first character must be an uppercase letter, A through Z. |
Alphabet [optional] | In addition to the alphabet created by the Flags settings,
add the following specific characters as well. Note that if
you want to include a space in your alphabet, then it must not
be the last character in the alphabet as this parameter is
clipped before usage. If both the Alphabet and Flags parameters are omitted then the default alphabet is st:Upper. This parameter is not used if the Flags includes st:Binary or st:AlmostBinary |
Parameter | DDescription |
---|---|
pLeft | The start delimiter of the text to remove. Note that this parameter is not clipped by the method, so you may want to call clip yourself. |
pRight | The end delimiter of the text to remove. If this parameter is omitted then the text in pLeft is removed. Note that this parameter is not clipped by the method, so you may want to call clip yourself. |
pNoCase | If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive. |
pContentsOnly | Only the text between the delimiters, not including the delimiters, is removed. The default is false, meaning that the delimiters are removed as well as the contained text. |
pCount | The number of occurrences to remove. If set to 0 (the default) then all instances of the text are removed. |
EExample |
---|
htmlString = <td class="tabledata"
align="left" ' | & 'colspan="2" valign="middle" id="td_11">' | & 'Hello World</td>' st.SetValue(htmlString) st.Remove('<td','>') st.Remove('</td>') Message(st.GetValue()) |
Parameter | Description |
---|---|
pTag | The tag to replace attributes for. This should just be the actual tag name, without any angle brackets or attributes. |
pCount (optional) | Limits the number of tags to search for, and remove attributes from. If 0, or omitted, then there is no limit. |
EExample |
---|
|
Parameter | Description |
---|---|
Alphabet | All characters specified in this string will be removed. |
Parameter | Description |
---|---|
pPosition | The position to remove the characters from. |
pLength | The number of characters to remove from the position. |
Parameter | Description |
---|---|
oldValue | The value to search for. |
newValue | The replacement value. |
count [optional] | If the Count parameter is set, then the method will terminate after Count instances of OldValue have been found, and replaced. |
Start [optional] | Position to start searching from. Defaults to 1 (the start of the string) |
End [optional] | Position to stop search the string at. Defaults to 0 (which will search to the end of the string). |
NoCase [optional] | If the NoCase parameter is true (1) then a case-insensitive search will be done. The default is 0 (case sensitive). |
Recursive [optional] | If Recursive is set to True then a recursive find and replace is performed (after replacement the new replacement text is searched again in case it contains the text being replaced). This is not frequently used and can reduce performance significantly. |
Example |
---|
|
Parameter | Description |
---|---|
pLeft | The left edge of the string to search. |
pRight | The right edge of the string to search. If omitted the same text as pLeft is used. |
pOldValue | The value to search for. If this value is blank then the replacement value is inserted immediately after the pLeft string. |
pNewValue | The replacement value. |
pCount [optional] | If the Count parameter is set, then the method will terminate after Count instances of OldValue have been found, and replaced. |
pStart [optional] | Position to start searching from. Defaults to 1 (the start of the string) |
pEnd [optional] | Position to stop search the string at. Defaults to 0 (which will search to the end of the string). |
pNoCase [optional] | If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive). |
pReplaceAll | If this is set to st:replaceAll then the pOldValue is ignored, and all the text between the pLeft and pRight is replaced with the pNewValue. |
Example |
---|
|
Parameter | Description |
---|---|
pLeft | The left edge of the string to search. |
pRight | The right edge of the string to search. If omitted the same text as pLeft is used. |
pOldValue | The value to search for. This value may not be blank. |
pNewValue | The replacement value. |
pCount [optional] | If the Count parameter is set, then the method will terminate after Count instances of OldValue have been found, and replaced. |
pStart [optional] | Position to start searching from. Defaults to 1 (the start of the string) |
pEnd [optional] | Position to stop search the string at. Defaults to 0 (which will search to the end of the string). |
pNoCase [optional] | If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive). |
Example |
---|
|
Parameter | Description |
---|---|
pOldValue | The value to search for. This value may not be blank. |
pNewValue | The replacement value. |
pStart [optional] | Position to start searching from. Defaults to 1 (the start of the string) |
pEnd [optional] | Position to stop search the string at. Defaults to 0 (which will search to the end of the string). |
pNoCase [optional] | If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive). |
Parameter | Description |
---|---|
pOldValue | The value to search for. This value may not be blank. |
pNewValue | The replacement value. |
pOccurrence | The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end. |
pStart [optional] | Position to start searching from. Defaults to 1 (the start of the string) |
pEnd [optional] | Position to stop search the string at. Defaults to 0 (which will search to the end of the string). |
pNoCase [optional] | If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive). |
Parameter | Description |
---|---|
OldChars | A string containing the characters to replace. |
NewChars | A string containing the characters to replace the OldChars with. Each character is replaced individually from the matching old character to the new character in the same position. The length of OldChars and NewChars must be the same. If they are not the method returns st:error, and no replacements take place. |
OnceOnly | If this is set to False (the
default) then the method behaves the same as multiple calls to
Replace. In other words the first
character in OldChars is
replaced by the first character in Newchars.
Then the second character in OldChars is
replaced by the second character in Newchars
EVEN IF the characters was already replaced by the
first character. However if this property is set to true then each character in the string can only be altered once. Once a character has been changed once it won't be changed again. |
Parameter | Description |
---|---|
pString (optional) |
If a string is passed then the passed string is reversed and
returned. If no string is passed then the current contents of the object are reversed and nothing is returned. If a parameter is passed then the current value in the object is unaltered. |
Parameter | Description |
---|---|
Length (optional) |
The Length of the string to return. If omitted, or zero, the
current length of the string is used. If the Length is set to less than the current string length then the string is cropped to fit. |
What (optional) | Determines which trailing characters are removed. Possible
options for this parameter are; st:Spaces (This is the default value if the parameter is omitted.) st:Tabs ! remove <9> st:cr ! remove <13> st:lf ! remove <10> st:zeros ! remove <48> These options can be added together. For example to remove trailing spaces and trailing tabs you can use st.Right( ,st:spaces + st:tabs) To remove all trailing spaces, tabs, carriage returns and linefeeds use st.Right( ,st:spaces + st:tabs + st:cr + st:lf) |
Pad (optional) | Allows you to specify the character to use as the padding character if the length required is greater than the current string. If omitted then the default pad character is a space. |
Parameter | Description |
---|---|
fileName | The name of the file to save to. |
newValue [optional] | If the second form of the method is called and a newValue is passed, then the newValue string is saved to disk rather than the contents of the StringTheory object. |
appendFlag | If a non zero value is passed then the file is appended to rather than overwritten. This parameter is optional if the first form is called, but required if the second form is called. |
dataLen [optional] | The length of the data to write. If omitted or zero then the entire newValue is written. |
Parameter | Description |
---|---|
pGroup | The group structure to serialize. |
pBoundary [optional] |
The boundary string (one or more characters) which appear
between the fields. For example, in a pipe-separated string
this would be a | character. If omitted this parameter
defaults to a comma (,). This field can contain multiple boundaries (as an I separated list) so that nested groups in the structure can be separated with a different boundary. For example ',I*I^'. If this field is a StringTheory object, instead of a string, then the StringTheory object should be pre-split using whatever character for the boundary separator is preferred. In this way I can be used as a separator if desired. |
pQuoteStart [optional] |
A start-quote string to surround fields which may contain the boundary character(s). If omitted then no boundary character is used. |
pQuoteEnd [optional] |
An end-quote string to surround fields which may contain the boundary character(s). If omitted the start-boundary string is used. |
pLevel [optional] |
The separator level to use as the first separator. Default value is 1. |
pFree [optional] |
Default value is true. If true, then the current value of the object is cleared before the serialize is done. If false then the serialized group is added to the current value of the object. |
pOptions [optional] | Default value is 0. If set to st:AlwaysQuote then all fields are wrapped in quotes, even if the field does not contain a separator. |
Parameter | Description |
---|---|
pVal | The variable to store the binary value of in the StringTheory object. The stored string is the same number of bytes as the passed variable, and each byte retains the same value. This is similar to Clarion's Over attribute. |
Parameter | Description |
---|---|
pVal | A variable to store the binary value of. |
pType | A string that contains the Clarion type for the passed parameter: 'BYTE', 'SHORT', 'USHORT', 'LONG', 'ULONG', 'REAL' etc. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound | If this is true, and the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound | If this is true, and the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text after this string (not including this string). |
Occurrence | The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end. |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound (optional) | If this is true, and the nth instance of the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
Length | The length of the resultant string. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text before this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound | If this is true, and the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text before this string (not including this string). |
Occurrence | The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end. |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound | If this is true, and the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
SearchValue | Searches for this string in the current string, and returns all the text before this string (not including this string). |
Start (optional) | The start position in the current string to start the search. If omitted the search will start at the beginning of the current string. |
End (optional) | The position in the current string to end the search. If omitted then the search will end at the end of the current string. |
NoCase (optional) | If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive. |
pClearIfNotFound | If this is true, and the searchValue is not found then the object is cleared. |
Parameter | Description |
---|---|
Left | The left hand delimiter. If this is blank, and Start is 0, then the start of the string is used. If this is blank, and the Start parameter is set then text from the start position is returned (if the Right boundary is found). |
Right | The right hand delimiter. If this is blank then the end of the string is used. |
Start [optional] | If this is specified then the search for the delimiter starts at this position in the string. Defaults to the start of the string. |
End [optional] | If this is specified then the search ends at this position in the string (delimiters after this are ignored). Defaults to the length (end) of the string. |
NoCase [optional] | If this is set then the delimiter search is case insensitive, otherwise it is case sensitive. |
Exclusive [optional] | If this is set to true (the default) then the delimiters are not included in the returned string. If it is set to false then they are included in the returned string. |
Parameter | Description |
---|---|
pValue | The string to deformat. If not passed then the current contents of the object are used. |
pPicture | The picture that hints how the string is currently formatted. Supports Extended Pictures. With some formats the picture acts as a hint only, and another picture may be used if it is a better fit. For example a time value (hh:mm:ss) will be deformatted as @t4 even if the picture passed is @t1. |
st StringTheory code st.SetValue('12/31/2022')See Also
x = st.SetDeformatValue('@d1')
Parameter | Description |
---|---|
RemoveBOM | Set to true by default. If this is true then the Byte Order Mark is removed from the front of the string. |
Parameter | Description |
---|---|
pValue | The value to format. If not passed then the current contents of the object are used. |
pPicture | The picture that determines how the string is formatted. Supports Extended Pictures. |
st StringTheory
code
st.SetFormatValue(81087,'@d1')
See AlsoParameter | Description |
---|---|
Length (optional) |
The Length of the string to set. If omitted, or zero, the
current length of the string is used. If the Length is set to less than the current string length then the string is cropped to fit. |
What (optional) | Determines what leading characters are removed. Possible
options for this parameter are; st:Spaces (This is the default value if the parameter is omitted.) st:Tabs st:cr st:lf st:zeros These options can be added together. For example to remove leading spaces and leading tabs you can use st.SetLeft( ,st:spaces + st:tabs) To remove all leading spaces, tabs, carriage returns and linefeeds use st.SetLeft( ,st:spaces + st:tabs + st:cr + st:lf) |
Pad (optional) | Allows you to specify the character to use as the padding character if the length required is greater than the current string. If omitted then the default pad character is a space. |
Parameter | Description |
---|---|
newLength | The new length for the string. |
Force | Forces the buffer to be exactly this length. If this is off (the default) then the string is set to be this length, but the buffer itself may remain larger. |
Example |
---|
|
Parameter | Description |
---|---|
Length (optional) |
The Length of the string to set. If omitted, or zero, the
current length of the string is used. If the Length is set to less than the current string length then the string is cropped to fit. |
What (optional) | Determines what trailing characters are removed. Possible
options for this parameter are; st:Spaces (This is the default value if the parameter is omitted.) st:Tabs st:cr st:lf st:zeros These options can be added together. For example to remove trailing spaces and trailing tabs you can use st.SetRight( ,st:spaces + st:tabs) To remove all trailing spaces, tabs, carriage returns and linefeeds use st.SetRight( ,st:spaces + st:tabs + st:cr + st:lf) |
Pad (optional) | Allows you to specify the character to use as the padding character if the length required is greater than the current string. If omitted then the default pad character is a space. |
Parameter | Description |
---|---|
NewValue (string) |
A string, of any length. |
pClip | If true then the string in NewValue is clipped. Only valid if NewValue is a string. |
NewValue (stringtheory) |
Allows one StringTheory object to be set to the contents of another StringTheory object. |
pOptions | One or more options, that can be added together, which
affect the copy. Current options supported are; st:lines : The Lines associated with NewValue are copied as well (any pre-existing lines in the destination object are removed). If this is omitted (the default default) then only the value is copied, not the lines queue as well, and in that case the lines queue in the destination object is left unaltered. |
Parameter | Description |
---|---|
newValueAddress | An address in memory. |
pLength | The number of bytes to copy. |
Parameter | Description |
---|---|
newValueAddress | An address in memory. |
pEncoding | The Encoding of the Cstring. If omitted then the encoding of the current object is used. If the parameter is set the the current object is changed to this encoding. The terminating character(s) depend on the encoding. For ANSI or utf-8, a single null ( aka <0> aka chr(0)) terminates the string. for utf-16 two null characters (<0,0>) are needed, for utf-32 4 null characters (<0,0,0,0>) are needed. |
Parameter | Description |
---|---|
pStart | Start position at which the replacement of the "slice" with the passed value begins. |
pEnd | End position for replacement (if not specified this is calculated from the length of the passed newValue string. |
newValue | Value to overwrite the specified region with. |
Example |
---|
|
Parameter | Description |
---|---|
start | The start position for the substring (slice) to be returned. |
end [optional] | The end position of the substring (slice) to be returned. If omitted this defaults to the length of the string. |
Example |
---|
|
Parameter | Description |
---|---|
SortType | One of st:SortNoCase (case
insensitive, alphabetic sort), st:SortCase
(case sensitive, alphabetic sort) or st:SortLength
(sorts the list by length of the line) If st:SortLength is used, and two lines have the same length, then the lines will be sort by case sensitive, alphabetic sort. |
Boundary | The Boundary parameter lets you specify the separating character. |
Quote [optional] | The optional Quote parameter allows you to specify a
"quote" character which negates the boundary. For example in
the following comma separated list, the double quote character
wraps a string that negates the comma. For example: Bruce Johnson, "Cape Town, South Africa" Quotes are removed before sorting takes place. |
QuoteEnd [optional] | If the start, and end, quote characters are different, then
the QuoteEnd parameter can be
used. For example: <Bruce Johnson>,<Cape Town, South Africa> In this case the pQuote would be set to '<' and quoteEnd to '>' If a string consists of multiple lines then the multi-character boundary '<13,10>' can be used. |
Clip [optional] | If this parameter is set to true, then each value in the string is clipped before sorting. The default for this parameter is false. If set to true then the resultant string will contain clipped values between the separators. |
Left [optional] | If this parameter is set to true, then leading spaces are removed from each value as the string is sorted. The default value of this parameter is false. |
Parameter | Description |
---|---|
textType [optional] | Defaults to ST:TEXT (0), this
removes all white space, tabs, line breaks and punctuation and
results in each word in the string separated by a single space
character. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character). This will result on only extra space characters being removed, not other characters are affected. |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?()*/+=<>:' when the TextType parameter is set to ST:HTML. |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Parameter | Description |
---|---|
pForce | If this is set to true then the memory for the object is released. If set to false then the memory is retained. |
Parameter | Description |
---|---|
Sub | The sub string to check for. If this string is empty then the method returns true. |
Case | Set this to false if the test is case insensitive. The default value is true, meaning the test is case sensitive. |
Clip | If this is true (the default) then the Sub string is clipped before comparing to the stored string. If set to false then any trailing spaces in the Sub parameter will need to match spaces in the string. |
Example |
---|
|
Parameter | Description |
---|---|
pFileName | the name of the file on the disk that will be created by this stream. |
pSize | The size of the StringTheory string, in Megabytes. In other words this is the size of the file write-cache. |
pAppendFlag | If set to true then the data is appended to the existing file. If false then a new file is created when STREAM is called. |
Example |
---|
|
Parameter | Description |
---|---|
pStart | The starting position in the string. |
pLength | The length of the substring. If omitted then the single character at the Start position is returned. |
Parameter | Description |
---|---|
newValue [Optional] | An optional value to store before returning it. |
Example |
---|
Message(st.Str(someValue)) |
Parameter | Description |
---|---|
pOther | The object to swap with. |
Parameter | Description |
---|---|
pLength | The number of characters to remove. If this value is less than 1 then the string is not changed. If this value is greater than the number of characters in the string, then the string is cleared. |
Parameter | Description |
---|---|
*blob blobField | The BLOB field to store the value in. |
Example |
---|
s.SetValue(plainText, true) ! Store a value in the StringTheory object s.ToBlob(MailData.Text) ! Store the value in the passed BLOB |
Parameter | Description |
---|---|
pSrc | The variable to store the binary value of. |
pDest | A string used to store the passed data as binary. |
pOffset | The offset index into the string for where to put the value to. If omitted then then the default position is the first character in the string. |
Example |
---|
a Long s String(10) code a = 041414141h str.ToBytes(a,s) ! s = 'AAAA' a = 042424242h str.ToBytes(a,s,5) ! s = 'AAAABBBB' |
Example |
---|
c
&cstring st StringTheory code st.SetValue('hello world') c &= st.ToCstring() ! use cstring here Dispose(c) |
Parameter | Description |
---|---|
pLength | The number of characters to remove. If this value is less than 1 then the string is not changed. If this value is greater than the number of characters in the string, then the string is cleared. |
Parameter | Description |
---|---|
Message | A string of any length which is sent to DebugView. |
pQueue | The Queue is serialized (using the SerializeQueue
method), and the result is sent to debugview. this allows the contents of a Queue to be inspected as a comma separated list. |
Parameter | Description |
---|---|
pAlphabet | A string containing characters that are considered to be white space. In other words any characters at the front, or back of the string which are also in the pAlphabet string will be removed. Defaults to a space character. |
Parameter | Description |
---|---|
pQuoteStart | Optional character to use as the opening quotation mark. Defaults to a double quote ("). |
quoteEnd | Optional character to use as the closing quotation mark. Defaults to a double quote ("). |
Example |
---|
|
Parameter | Description |
---|---|
Quote (optional) | A character to identify the start of Quoted Text. Quoted Text will not be uppered by this method. If this parameter is omitted then all the text in the string is uppered. |
QuoteEnd (optional) | The character to use as the end of Quoted Text. If omitted, and the Quote parameter is not omitted, then the same quote character will be used to delineate the start and end of text. |
Parameter | Description |
---|---|
Delimiter [optional] | The default delimiter for is a % character (hence the common name of "percent encoding". If you want an alternate character to be used then enter it here. Note that this field is limited to a single character. |
Space [optional] | The default encoding for the space character is a + character. If you want the space character to be encoded as something else then you can enter that here. note this field is limited to a single character. |
Parameter | Description |
---|---|
pText | The text to encode. If this parameter is omitted then the current contents of the object will be used. If this parameter is used then all the other parameters are NOT optional and must be explicity set to something. |
Flags | The flag field is accumulative, and any combination of the
following flags may be added together; st:dos the following characters are not encoded; / \ . $ st:NoPlus The space character is not encoded. st:BigPlus the space character is encoded as %20, not + st:php the period, hyphen, underscore and tilde characters are not encoded ( . - _ ~ ) st:NoHex The space character is not encoded st:NoColon the Colon character is not encoded ( : ) st:Parameters the ampersand character is not encoded and the first question character in the string is not encoded ( & ? ) |
Delimiter | The default delimiter for is a % character (hence the common name of "percent encoding". If you want an alternate character to be used then enter it here. Note that this field is limited to a single character. |
Space | The default encoding for the space character is a + character. If you want the space character to be encoded as something else then you can enter that here. note this field is limited to a single character. |
Alphabet | Characters specified in this string will NOT be encoded, but left as-is. |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
pIncludePort (optional) | Defaults to on. Allows you to include, or exclude the port part of the host name (if it exists). |
Parameter | Description |
---|---|
pParameter | The name of the parameter to fetch. If the parameter exists multiple times with the same name then the first value is retrieved. |
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used. This value can contain a URL complete with parameters (separated by a ? character) . A list of parameters, after the ? can also be passed without the URL part. |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
pIncludeFile (optional) | If true then the filename is included in the return string. |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
Parameter | Description |
---|---|
pURL (optional) | Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used |
Parameter | Description |
---|---|
pStartPos [optional] | The start position to begin search from. Defaults to the start of the string |
textType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character.) Can be set to ST:CONTROLCHARS - this is the same as ST:TEXT, but all control characters (Characters < 31) are considered to be word separators. |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML and '. ,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:CONTROLCHARS |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Example |
---|
|
Parameter | Description |
---|---|
StartPos [optional] | The start position to begin counting words from. Defaults to the start of the string |
textType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character) |
Dir (optional) | If Set to st:Forwards (the
default) then searches for the start of the next word. If set to st:Backwards then searches for the start of the current word. If the StartPos points to whitespace then the start of the word before the whitespace will be returned. |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML and '. ,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:CONTROLCHARS |
Example |
---|
st.SetValue('Hello World.') Message('Find words in: "' & st.GetValue() & '"') sPos = st.WordStart() ePos = st.WordEnd(sPos) Message('First word: ' & st.Slice(sPos, ePos)) sPos = st.WordStart(ePos+1) ePos = st.WordEnd(sPos) Message('Second word: ' & st.Slice(sPos, ePos)) |
Parameter | Description |
---|---|
wrapAt = 80 | The width to word wrap each line at. This is the maximum desired length for any line after wrapping. Note that this method only adds breaks at white space, so lines may be longer than the specified width if you do not contain any white space. |
keepExistingBreaks=true | Keeps existing CR/LF's in the output. If this is false then existing line-breaks are removed. Regardless of the setting existing paragraph breaks are preserved. |
pleft=false | If true then each line is left-justified, ie leading white-space is removed. |
Parameter | Description |
---|---|
Options (optional) | These options can be added together; st:Percent : replace % with % st:IgnoreIfValid : do not re-encode anything of the form & , < , > , ' , " &#nn; &#xnn; st:IgnoreIfNumber : do not re-encode anything of the form &#nn; &#xnn; st:DecimalEncode128 : convert all characters > chr(127) to the form &#nn; |
Parameter | Description |
---|---|
FromLineNumber | The first line to return. |
ToLineNumber | The last line to return. If this is 0, then all the lines from the FirstLineNumber are included in the return value. |
Separator | A string that is places between the lines as they are "joined" back together. |
Parameter | Description |
---|---|
SearchValue | The search term to look for in the lines. |
Step (optional) | The step from one line to the next. If omitted the default value is 1. |
Start (optional) | The first line number to check. If omitted the default value is 1. |
End (optional) | The highest line number to check. If omitted the default value is the number of lines. If less than the Start value, then is set to the Start value. |
Nocase (optional) | If set to true then a case in-sensitive search is made. If omitted or false then searches are case sensitive. |
WholeLine (optional) | If set to true then the SearchValue must match the contents of the whole line exactly. If omitted or false then the search looks for a sub string inside the line. |
Where (optional) | Set to one of st:begins, st:ends or st:anywhere. If this parameter is omitted then st:anywhere is used. If it is set to st:begins then the line needs to begin with the SearchValue. If set to st:ends then it needs to end with the SearchValue. |
Clip (optional) | If set to st:clip (the default) then the search value is clipped before searching. |
Parameter | Description |
---|---|
boundary | The Boundary parameter lets you specify the separating
character. For example, if a string consists of multiple lines then the multi-character boundary '<13,10>' can be used to split the string into lines. |
Quote [optional] | The optional Quote parameter allows you to specify a
"quote" string which negates the boundary. For example in the
following comma separated list, the double quote character
wraps a string that negates the comma. For example: Bruce Johnson, "Cape Town, South Africa" This string would be parsed into 2 parts, the name and the address. The Quoting characters are included in the parsed result if the RemoveQuotes parameter is not set to true. In the above example the two strings after splitting are: Bruce Johnson "Cape Town, South Africa" The quotes do not have to be at the beginning and end of the field in order to apply. Consider for example the following; 2,here,function(a,b){hello} If the quote is set as ( and the endquote is set as ) then this will split into 3 lines; 2 here function(a,b) {hello} In some cases multiple quotes are necessary. Consider the string 2,function(a,b){add a,b},php To resolve this to the 3 lines 2 function(a,b){add a,b} php it's necessary to specify multiple boundaries in a "something" separated list. (See the Separator below for the something.) To achieve the result above (assuming the separator is a /) the quote parameter would be (/{ and the QuoteEnd parameter would be )/}. The Quote (and QuoteEnd) parameters are clipped. so spaces are not allowed. |
QuoteEnd [optional] | If the start, and end, quote strings are different, then
the this parameter can be used. For example: <Bruce Johnson>,<Cape Town, South Africa> In this case the Quote parameter would be set to '<' and quoteEnd to '>' |
RemoveQuotes [optional] | If this is set to true then the quotes will be removed from the lines in the Lines Queue. Note that only quotes at the beginning or end of the string will be removed, quotes detected inside the string, although they will apply when splitting the string, will not be removed, even if this parameter is set to true. |
Clip [optional] | If this parameter is set to true, then the lines are clipped before adding them to the Lines Queue. This can be useful where the file being input contains large amounts of trailing whitespace (spaces) at the end of each line. |
Left [optional] | If this parameter is set to true, then leading spaces are removed from each line as the lines are created. The default value of this parameter is false. |
Separator [optional] | If this parameter exists, and is not blank, then the Quote
and QuoteEnd parameters are treated as a list, where the list
of possible Quote and QuoteEnd pairs are separated by this
character. Note that the Quote and QuoteEnd must have the same
number of items in them (or the QuoteEnd is omitted, and hence
treated as the same as Quote), and only the matching QuoteEnd
item matches the Quote item. The Separator should be a single character. Do not use the Space character as the Separator. |
Nested [optional] | It's possible that quote and EndQuote characters, if
different, can be nested in the string being split. If you
want to match the starting and ending pair, ignoring
internally nested pairs then set this parameter to true. For
example consider (1,2) , (3,4) , ((5,6),7) The above string has 3 terms, separated by a comma. Commas inside the brackets are ignored. In the third term though the brackets are nested, and in order to correctly split this into three terms the brackets around the 5,6 must be ignored. To do that set the Nested parameter to true. |
Example |
---|
st.SetValue('12,bruce,"po box 511,
plumstead"') st.split(',','"') ! result is ! 12 ! bruce ! "po box 511, plumstead" |
Example |
st.SetValue('12,bruce,"po box 511,
plumstead"') st.split(',','"',,true) ! result is ! 12 ! bruce ! po box 511, plumstead |
Example |
st.SetValue('[12,24,36],bruce,(po box
511, plumstead)') st.split(',','[-(',']-)',false,,,'-') ! result is ! [12,24,36] ! bruce ! (po box 511, plumstead) |
Parameter | Description |
---|---|
pLeft | The start string. |
pRight | The end string. |
pNoCase | Set this to true to do a case insensitive match. |
pExlusive | If this is set to true (the default) then the delimiters are not included in the lines. If it is set to false then they are included in the lines. |
Parameter | Description |
---|---|
pRegEx | A regular expression that indicates the boundary between the lines. |
pNoCase | Set this to true to do a case insensitive match. |
Parameter | DDescription |
---|---|
numChars | The number of characters that each new substring should contain, i.e. the length to split the string up using |
Parameter | Description |
---|---|
StartPos [optional] | The start position to begin splitting words from. Defaults to the start of the string |
textType [optional] | Defaults to ST:TEXT (0) (the
string is assumed to be normal text). If set to ST:HTML (1) the string is assumed to be HTML encoded, so escape sequences such as ' ' and other encoded characters are not treated as words. Can also be set to ST:NOPUNCTUATION (2) which will not treat punctuation as white space (and hence punctuation is included in words as a normal character) |
pCharList (optional) | The list of characters which delineate the end of a word.
The default value is '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:TEXT and '. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML. |
pSmartWords | If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words. |
Parameter | Description |
---|---|
Boundary | The character(s) to place between the lines in the eventual string. |
Quote | An optional start quote to wrap text which contains the boundary character. |
QuoteEnd | An optional endquote. If omitted the start quote is used. |
AlwaysQuote | If true then the line is always wrapped in quotes, even if the text does not contain a Boundary. |
Parameter | Description |
---|---|
Alphabet (optional) | By default empty lines are lines which only include spaces. If the Alphabet parameter is used then you can include other characters in the definition of emptyness. |
Example |
---|
st.Split(',') st.removeLines() ! removes lines with only spaces st.removeLines('<9,10,13>') ! removes lines with only tab, space, cr and lf characters. |
Parameter | Description |
---|---|
SortType | One of st:SortNoCase (case insensitive, alphabetic sort), st:SortCase (case sensitive, alphabetic sort) or st:SortLength (sorts the list by length of the line) |
Parameter | Description |
---|---|
Include | If the Include parameter is not an empty string, then all lines not containing that string will be removed. |
Exclude | If the Exclude parameter is set then all lines containing that string will be removed. Exclude is applied after Include, and will remove a line even if the Include line has specifically included it. |
NoCase | If set to st:nocase then the Include and Exclude parameters perform a case insensitive search |
Clip | If set to st:clip then the Include and Exclude parameters are clipped before searching. |
Parameter | Description |
---|---|
Value | If the Value parameter is omitted then the current string value is used, and the current string value is changed to the Clarion time number. If a value is provided then the Clarion number is returned from the method and the existing string value in the object is not changed. |
Parameter | Description |
---|---|
Value | If the Value parameter is omitted then the current string value is used, and the current string value is changed to the human-readable format. If a value is provided then a string value is returned from the method and the existing string value in the object is not changed. |
Format | The format string determines the exact format of the result.
The string is made up of the following parts. (optional parts
are encased in [ square brackets ]. [@][T]n[s][B][Z] @, T : optional. Not required by this method, but allowed. nn : up to a 5 digit number. A leading 0 indicates zero-filled hours (hh). Two leading zeros (hhh), Three leading zeros (hhhh). The number after the zeros determines the format to use. See below. s : separator. Can be an underscore (spaces will be used as a separator), a quote character (commas will be used), a period (periods will be used) or a hyphen (hyphens will be used). If omitted then colons will be used as the separator. B : Set to blank if time is < 0. Also blank if value is 0 and Z attribute is not used. Z : Time is formatted as "base 0"- in other words 0 = 0:00 and 360000 = 1:00. If left off then the default Clarion approach (base 1) is used. In "base 1" 0 is undefined, 360001 = 1:00 and so on. @T1 hh:mm 17:30 @T2 hhmm 1730 @T3 hh:mmXM 5:30PM @T03 hh:mmXM 05:30PM @T4 hh:mm:ss 17:30:00 @T5 hhmmss 173000 @T6 hh:mm:ssXM 5:30:00PM @T7 Windows Control Panel setting for Short Time (*) @T8 Windows Control Panel setting for Long Time (*) @T91 hh:mm:ss:cc 17:30:00:19 @T92 hh:mm:ss:ccXM 5:30:00:19pm (*) these formats do not support times > 23:59 |
Parameter | Description |
---|---|
pCase | If set to ST:UPPER or ST:LOWER then the result will use that case. The default is ST:LOWER. |
pSpacer | If set to true then a space is injected into the string after each hex pair. The default value is false. |
Parameter | Description |
---|---|
pByte | A byte which contains value to convert to a hexadecimal string. Return values range from '00' for a byte value of 0 to 'ff' for a byte value of 255. Hexadecimal characters 'a' through to 'f' are returned as lower case. |
Parameter | Description |
---|---|
pLong | A long that contains the value to convert to a hexadecimal string. |
Example |
---|
|
Parameter | Description |
---|---|
binData | The bytes to convert. |
pLen | If this parameter is omitted, or set to 0, then the string is clipped before conversion. If this value < 0 then an empty string is returned. |
pCase | Set to ST:UPPER or ST:LOWER. This will force the resultant Hex values to be in either upper or lower case. If omitted (or invalid) then this parameter defaults to st:Lower. |
Parameter | Description |
---|---|
x | The number to convert from Little Endian to Big Endian byte order |
Parameter | Description |
---|---|
x | The integer to convert to Little Endian |
Parameter | Description |
---|---|
encoding (optional) | Specifies the encoding of the stored string. If this is not
passed to specify the encoding of the string then .encoding property of the class
must be set to the correct value to indicate the current encoding.
If the text has been converted from ANSI to Unicode using the ToUnicode method, then this is done by the
object, otherwise it needs to be set to one of the following: st:EncodeUtf8 equate(1) st:EncodeUtf16 equate(2) |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
pBlockSize (optional) | Converting UTF-8 to ANSI can be quite memory intensive since
the string is first converted to UTF-16 and then to UTF-8. This
means a 100 Meg string will require 200 Megs of Extra ram just to
convert. By setting this setting you can set a "blocksize" which the conversion will use, converting 1 block at a time. This minimizes extra memory requirements (and can also be faster for large strings.) This value is in Megabytes. It should be in the range of 1 to 50. If set to 0 the default blocksize (10 megs) is used. If set to more than 50 then 50 megs is used. |
Parameter | Description |
---|---|
encoding (optional) | Specifies the encoding to convert the passed string to. Defaults to UTF-8. |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
Parameter | Description |
---|---|
strAnsi | A string which contains the ANSI text to convert to Unicode |
unicodeChars | A long which will be set to the number of Unicode characters on return. Not that this is not the length of the string returned, but the number of Unicode characters stored in the string. |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
Example |
---|
|
Parameter | Description |
---|---|
unicodeString | A string which contains the Unicode text. If unicodeChars is not passed to specify the number of Unicode characters in the string to convert, then the string should be null terminated. |
ansiLen | The passed long will be set to the length of the returned string. |
unicodeChars (optional) | The number of Unicode characters in the passed string to convert. If this is not passed then the unicodeString parameter should be null terminated. |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
Example |
---|
|
Parameter | Description |
---|---|
strUtf8 | The UTF-8 encoded string |
unicodeChars | On return this is set to the number of characters in the returned string. Note that this is not the size of the string returned, but the number of characters that it contains. |
Parameter | Description |
---|---|
unicodeString | A string which contains the UTF-16 encoded Unicode text to convert to UTF-8. This string should either be null terminated, or the unicodeChars parameter should be passed to specify the number of Unicode characters to convert. |
utf8Len | On return this is set to the length of the returned UTF-8 string. |
unicodeChars [optional] | The number of characters to convert. Defaults to -1, which
assumes that the passed unicodeString is null terminated. If set to -1, and the string does not contain a null terminator, then the length of the current string is used. If it is set to 0 then the length of the current string is used, and the unicodeChars is calculated from that. |
Parameter | Description |
---|---|
p_utf16Char | A string, 2 bytes long, containing a utf-16 character. |
rLen | A Long variable which will be set to the length of the returned string |
Parameter | Description |
---|---|
strUtf8 [in] | A string that contains the UTF-8 encoded text to convert to ANSI. |
ansiLen [out] | On return this is set to the length of the returned ANSI string in bytes. |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
Parameter | Description |
---|---|
strAnsi [in] | The ANSI encoded text to convert |
utf8Len [out] | Set to the length of the UTF-8 encoded string returned |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
Parameter | Description |
---|---|
pID [in] (optional) | The identifier before the encoding. For example \u or \x or whatever the string contains. |
Length [in] [optional, but required if pID is passed) |
The length of the encoding. Usually (but not always) 2
characters with \x and 4 characters with \u If the pID and length are both omitted then the string is tested for both \xHH and \uHHHH. |
CodePage (optional) | Specifies the CodePage that should be used to contain the result. The default is st:CP_US_ASCII. Other code pages are st:CP_WINDOWS_1250 through st:CP_WINDOWS_1258 and st:CP_ISO_8859_1 through st:CP_ISO_8859_15. |
base64 | long | Set to True (1) if the string currently in the object is Base64 encoded. Set to False (0) if not. |
base64nowrap | bool | If set to True (1) then no line wrapping is done when Base 64 encoding a string. By default lines are wrapped by inserting a carriage return, line feed pair (ASCII 13,10) to limit the line length to 80 characters including the CR,LF pair. |
Bytes | Long | Returns the number of bytes loaded after a call to the LoadFile method. |
CleanBuffer | Long | If this is set to true, then the SetValue method will clear the contents of the whole buffer when assigning a new value to the string. This takes longer, but may assist programs that assumed that unused parts of the buffer will be cleared. |
Codepage | long | The code page of the current string, if the string is not
unicode. This property can be set directly to one of the ST:CP
equates (see StringTheory.Inc for a complete list) or can be set
from a Font Charset using the GetCodePageFromCharset
method. If a method (like JsonDecode) needs to know the code page, and it has not been set then GetCodePageFromCharset will automatically be called. This property is set when doing a EncodedWordDecode to the CodePage of the encoded string. |
encoding | long | Text encoding. This can be set before calling the ToUnicode
method to specify the encoding to be used, or before calling ToAnsi
to specify the Unicode encoding to convert. It will also be
set by the ToUnicode and ToAnsi methods to the encoding of the
string after successful conversion. May be one of the following values: st:EncodeAnsi equate(0) !Standard ANSI text. st:EncodeUtf8 equate(1) !UTF-8 encoded Unicode text st:EncodeUtf16 equate(2) !UTF-16 encoded Unicode text |
endian | long | One of st:LittleEndian or st:BigEndian. Only applicable when encoding = st:EncodeUtf16. |
Gzipped | bool | Set to True (1) when a string has
been compressed by the Gzip method, and is
available for decompressing with the Gunzip
method. Note that if a zipped file is loaded, using LoadFile, then this property should manually be set to 1 before the string can be decompressed. |
lines | queue | A queue of strings populated by the Split method. The queue contains a single property Line. While you can access the lines queue, and the lines.line component directly, be careful because the lines property is a pointer to a string of variable length. Where possible the methods AddLine, SetLine, GetLine and DeleteLine should be used as these are safer. |
logErrors | long | Set to True (1) then errors sent to the ErrorTrap method will be forwarded to the Trace method, for output to the DebugView logging tool. |
lastError | string | The last error message passed to the Errortrap method. note that this value is not cleared when a successful call it made - it is the last error message passed to ErrorTrap, whenever that occurred. |
value | string (Private) | The current value of the string. You should use the GetValue and SetValue methods to access the string, rather than accessing the property directly. |
winErrorCode | long | The Windows Error code generated by the LoadFile or SaveFile method. |
CreatePicture | Create a Clarion picture from the current properties. |
ParsePicture | Parse a picture string into its component parts |
Parameter | Description |
---|---|
pType | Indicates the type of picture desired and hence the properties
that will be used to create the picture. Valid options are pic:Time, pic:TimeHours, pic:Date, pic:String, pic:Number, pic:Scientific, pic:Pattern, pic:KeyIn, pic:UnixTimeStamp, pic:Hex The case of the pType in the created picture is uppercase for most types (where the value is case-insensitive) and either upper or lower case for types P and K (depending on the contents of the Pattern property.) |
pFlag | 0 by default. Can be one or more of the following; st:Clarion - if this flag is set then the created picture will be compatible with the limited pictures supported by Clarion. Any extended picture options will be dropped. |
Parameter | Description |
---|---|
pPic | The Clarion picture to parse. If omitted then the current value in the pic property is parsed. |
Picture | ||
---|---|---|
pic | String(252) | The complete picture |
picType | String(1) | The Type of picture. D, N, S and so on. |
Date Pictures (@D) | ||
Fill | String(1) | If set to '0' then dates are zero padded. |
n | String(3) | The Date Picture Format. |
s | String(2) | Separation character. Only one char is valid for date pictures. This is the char in the picture - ie one of period, grave accent, hyphen, underscore or space. It is not the character displayed on the screen (that is in the Separator property) |
Separator | String(1) | The character that appears on the screen when the picture is displayed. The default is /. |
Direction | String(1) | < or > to indicate intellidate direction. |
Range | String(2) | a 2 digit number. |
B | String(1) | If set to 'B' or 'b' then the field is blank if zero. |
U | String(1) | If set to U then the data is in UNIX epoch (seconds) format rather than Clarion format. |
Milli | String(1) | If set to M then the data is in UNIX epoch (milliseconds) format rather than Clarion format. |
Local | String(1) | If set to L and the data value is 0 then use the local date as the value. |
Utc | String(1) | If set to U and the data value is zero then use the UTC date as the value. |
Key-In Pictures (@K) and Pattern Pictures (@P) | ||
Pattern | String(255) | The pattern. |
B | String(1) | If set to 'B' then the field is blank if zero. |
Upper | String(1) | p or P / k or K respectivly. |
Number, Currency (@N) and Decimal Time (@H) Pictures | ||
CurrencyBefore | String(10) | If set to '$' or 'Whatever' then shown to the left of the number. |
SignBefore | String(1) | set to '-' or '(' or leave blank. |
Fill | String(1) | If set to '0' then numbers are zero padded. |
Size | String(6) | A number, containing the number of characters in the formatted string. |
Grouping | String(1) | The grouping char for each 3 digit group. |
Separator | String(1) | The Decimal Separator. |
Places | String(6) | The number of digits after the decimal separator. |
SignAfter | String(1) | set to '-' or ')' or leave blank. |
CurrencyAfter | String(10) | If set to '$' or 'Whatever' then shown to the right of the number. |
B | String(1) | If set to 'B' or 'b' then the field is blank if zero. |
Hex Pictures (@X) | ||
Base | Long | The base-number of the numbers to display. 10 for decimal, 16 for hexadecimal and so on. Valid values are 2 through 36. |
Length | String(4) | The number of string characters to display per line, before a line break. |
s | String(2) | An optional separator character. If omitted the default is no separator. Use an underscore to separate with a space character. |
Separator | String(1) | The character that appears on the screen between the values when the picture is displayed. The default is blank. |
Upper | String(1) | If x then (hex) numbers are lowercased, if X then (hex) numbers are uppercased. |
Scientific Pictures (@E) | ||
Size | String(6) | A number, containing the number of characters in the formatted string. |
s | String(2) | The Decimal Separator and Grouping character. |
Grouping | String(1) | The grouping char for each 3 digit group. |
Separator | String(1) | The Decimal Separator. |
n | String(6 | The number of digits to the LEFT of the decimal separator. |
B | String(1) | If set to 'B' or 'b' then the field is blank if zero. |
String Pictures (@S) | ||
Length | String(4) | A number, containing the number of characters in the formatted
string. If the picture does not include a length (ie just @S) then this property will be set to -1. @S0 is considered to be a valid picture, when applied to some raw data it returns a blank string. The length is not limited to 255 characters. |
Time Pictures (@T) | ||
Fill | String(1) | If set to '0' then dates are zero padded. |
n | String(3) | The Time Picture Format. |
s | String(2) | Separation character. Only one char is valid for time pictures. This is the char in the picture - ie one of period, grave accent, hyphen, underscore or space. It is not the character displayed on the screen (that is in the Separator property) |
Separator | String(1) | The character that appears on the screen when the picture is displayed. The default is a colon (:) . |
B | String(1) | If set to 'B' or 'b' then the field is blank if zero. |
U | String(1) | If set to U then the data is in UNIX format rather than Clarion format. |
Z | String(1) | If set to Z then the time is in "Duration" rather than "Time of Day" form. ie 360000 = 1:00 not 0:59:59 |
NumberPart | String | A Numeric picture that describes how the Hours part of the number should be formatted. |
Local | String(1) | If set to L, and the value is zero, then use local time as the value. |
Utc | String(1) | If set to C and the value is zero then use UTC time as the value. |
Unix DateTime stamp Pictures (@U) | ||
@U pictures are not part of standard Clarion. They format a Unix based TimeStamp value into a date time combination. See StringFormat for more. | ||
n | String(3) | The U Picture Format. |
s | String(2) | Separation character. Only one char is valid for U pictures. This is the char in the picture. It is not the character displayed on the screen (that is in the Separator property) |
Separator | String(1) | The character that appears on the screen when the picture is displayed. The default is a T . |
datepart | String | The date picture part of the U picture |
timepart | String | The time picture part of the U picture |
ClarionToUnixDate | Takes a Clarion date (long) and a Clarion time (long) and returns the Unix Epoch datetimestamp. |
UnixToClarionDate | Takes a Unix Epoch datetimestamp and returns the date part as a Clarion Long. |
UnixToClarionTime | Takes a Unix Epoch datetimestamp and returns the time part as a Clarion Long. |
UtcDate | Returns the current UTC date, in Clarion format. |
UtcTime | Returns the current UTC time, in Clarion format. |
Parameter | Description |
---|---|
pDate | A LONG containing a Clarion Date. |
pTime | A LONG containing a Clarion Time. |
pMilli | Can be True or False (the default). If true then the return value is in thousandths of a second, not seconds. |
Parameter | Description |
---|---|
pDateTime | A Unix datetimestamp. |
pMilli | If set to -1 (the default) then auto-detection of the units for pDateTime is used. In this case values < 2147483647 will be treated as seconds, and values greater than that as milliseconds. You can set pMilli to true to force the value into milliseconds, or false to force it into seconds. |
Parameter | Description |
---|---|
pDateTime | A Unix datetimestamp. |
pMilli | If set to -1 (the default) then auto-detection of the units for pDateTime is used. In this case values < 2147483647 will be treated as seconds, and values greater than that as milliseconds. You can set pMilli to true to force the value into milliseconds, or false to force it into seconds. |
FormatValue | Format Raw data, using a picture, to created formatted data suitable for human presentation. |
Parameter | Description |
---|---|
pValue | The Clarion picture to parse. If omitted then the current value in the pic property is parsed. |
pPicture | The picture to use to format the value. If this parameter is omitted, or blank, then the value is returned as-is. |
pFlag | st:ExpandIfNeeded : If this flag
is passed then values automatically expand if they overflow. fmt.FormatValue(123,'@n02') returns '##'. The value is larger than the picture allows. Whereas fmt.FormatValue(123,'@n02',st:ExpandIfNeeded) returns '123'. |
DeformatValue | Deformat formatted data, using a picture, to created raw data suitable for machine storage. |
DeformatDate | |
DeformatHex | |
DeformatPattern | |
DeformatTime | |
DeformatTimeHours | |
DeformatUnixTimeStamp |
Parameter | Description |
---|---|
pValue | A formatted value |
pPicture | An optional picture string indicating the current formatting used by the value. This picture is used as a heuristic to aid in interpreting the value, but the value is not necessarily formatted to this picture. If the picture is omitted, or it does not contain a recognized @ value, then the pValue parameter is returned unaltered. |
Parameter | Description |
---|---|
pValue | A formatted value. |
pPicture | An optional picture string indicating the current formatting
used by the value. U : A U in the time picture indicates the returned value should be in UNIX format, not Clarion format. |
Parameter | Description |
---|---|
pValue | A formatted value. |
pPicture | An optional picture string indicating the current formatting
used by the value. |
Parameter | Description |
---|---|
pValue | A formatted (or unformatted) value. |
pPicture | An optional picture string indicating the current formatting
used by the value. If omitted then the length of the input is
not capped. |
Parameter | Description |
---|---|
pValue | A formatted value. AM and PM modifiers are only applied to times between 0:00 and 24:00. |
pPicture | An optional picture string indicating the current formatting
used by the value. This picture is used as a heuristic to aid in
interpreting the value, but the value is not necessarily
formatted to this picture. Most time formats are unambiguous
(and will be deformatted without the aid of the picture) the
following parts of the pic may impact the result; U : A U in the time picture indicates the returned value should be in UNIX format, not Clarion format. Z : A Z in the time picture indicates the value should be returned as a duration (360000=1:00) rather than a Clarion time (360001 = 1:00) If this parameter is omitted then Clarion time is returned. |
Parameter | Description |
---|---|
pValue | A formatted value. |
pPicture | An optional picture string indicating the current formatting
used by the value. |
Parameter | Description |
---|---|
pValue | A formatted value. |
pPicture | An optional picture string indicating the current formatting
used by the value. |
CapeSoft Support | |
---|---|
Telephone | +27 87 828 0123 |