CapeSoft.Com
Clarion Accessories
StringTheory
Documentation
CapeSoft Logo

CapeSoft StringTheory 2
Documentation

Download Latest Version FAQ History Methods
Installed Version Latest Version

Introduction

StringTheory provides simple string handling and manipulation, including dynamic memory allocation (the string is always the correct length, and any amount of data can be added to it), fast and simple string parsing

StringTheory will easily help you: StringTheory provides Unicode support in the form of UTF-8, as well as converting between ANSI and UTF-8 strings

We strongly recommend starting with the example applications, which are described below in the Example section.

Features

StringTheory provides dynamic memory allocation, string handling and manipulation, conversion between string and cstring data types, base64 encoding and decoding, file loading and saving, and much more.

See the Class Reference for a list of all methods and properties provided.

Using StringTheory in an APP

Add StringTheory to your application in a few Easy Steps!

Add the global and local extension

Using the StringTheory Class

The code below demonstrates using the StringTheory class for a variety of common tasks.

In general a StringTheory object is declared as simply as

st StringTheory
Where st is the label name (and can be almost anything.) The length of the string is undefined, and is dynamic. In other words the string will automatically grow, and shrink as required. You do not need to worry about the length.

Values are assigned into the string using the SetValue method, or by loading a file off the disk using the LoadFile method.

st.SetValue('hello world')

st.LoadFile('c:\windows\win.ini')
After that the string can be manipulated in a number of different ways, using the methods described in the Class Reference. For example to Base64 encode the string;

st.Base64Encode()

Using StringTheory in a Hand-Coded Project

To add StringTheory to a hand-coded project (with no APP and hence no Global Extension template) do the following;
  1. Add
    include('StringTheory.Inc'),Once
    to your main module
  2. Add the StringTheoryLinkMode and StringTheoryDllMode project defines to your project. Set
    StringTheoryLinkMode=>1
    if the class should be linked into the project, and
    StringTheoryDllMode=>1
    if the object is exported from another DLL.
  3. If you will be using the md5 function in StringTheory then add
    ojmf5.c
    to the modules to be compiled by your project, and set the project define
    MD5=>1

You can declare StringTheory objects in your code by simply doing;

str   StringTheory

Overriding or deriving StringTheory methods is not usually necessary.

Distribution

If you use the Gzip or Gunzip methods in your application then you will need to distribute the ZLIBWAPI.DLL with your application. This DLL is located in your \accessory\bin folder. It is also available from the official source at http://www.winimage.com/zLibDll/index.html. The Zlib library home can be found here http://www.zlib.net.

ZLIB is the product of Jean-loup Gailly and Mark Adler and is distributed under the terms of their license at http://www.zlib.net/zlib_license.html .

Example

Demo

This is the main StringTheory example application. It demonstrates a variety of common and useful tasks using the StringTheory class.

Some Ideas and Suggestions

Check password strength

st.SetValue(Password)
if st.ContainsA('0123456789') = false
    Message('Needs a number')
end
if st.ContainsA('ABCDEFGHIJKLMNOPQRSTUVWXYZ') = false
    Message('Needs one or more upper case characters')
end
if st.ContainsA('abcdefghijklmnopqrstuvwxyz') = false
    Message('Needs one or more lower case characters')
end
if st.IsAll('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz') = true
    Message('Must contain at least on non-alphanumeric character')
end
if st.Length() < 16
    Message('Must be at least 16 characters long')
end

Parsing a CSV File

One common use for StringTheory is to parse text files for import. One of the more common text file formats is Comma-Separated-Values, more commonly known as CSV. To effectively parse a CSV file two StringTheory objects are used - one to parse the file into rows, and the other to parse a single row into columns.
Using StringTheory in this way is a lot faster than using the ASCII or BASIC drivers, but since the whole file is loaded into Ram at the start, this approach
consumes more working memory.
The key to this approach is using the Split method.

str   StringTheory
lne   StringTheory
x     Long
  code
  str.LoadFile('Somefile.CSV')
  str.Split('<13,10>','"')
  loop x = 1 to str.Records()
    Lne.SetValue(Str.GetLine(x))
    Lne.Split(',','"','"',true)
    field1 = Lne.GetLine(1)
    field2 = Lne.GetLine(2)
  End

A variation on this is a tab-separated file which uses the tab character instead of a comma to separate the fields. The only change to the above code would be the second Split, which becomes:

    Lne.Split('<9>','"','"',true)

Prime GUID fields

For various reasons the use of randomly generated strings as primary key values is becoming more common. StringTheory allows you to easily prime these fields in the dictionary (which in turn is then applied by the Templates in the PrimeRecord method.)

  1. Create a global variable section in the dictionary. For purposes of this example assume the prefix is set to glo .
  2. Create a global variable inside this section called ST. Set the "Data Type" to Type and set the "Base Type" to StringTheory.
  3. Create a field called GUID in the necessary tables. A string(16) is the ideal type for this. Set the initial value to glo:st.MakeGuid() .
MakeGuid is a specific form of the Random method. If you like, you can use a call to Random here instead of MakeGuid with a different length or alphabet.

File Name Manipulation

There are four methods in StringTheory that make handling file names easier.

Placing a complete file name in a StringTheory object allows you to access the various parts of the file using the methods FileNameOnly, PathOnly and ExtensionOnly. For example;

str.SetValue('c:\temp\strings\table.tps')
Path = str.PathOnly()
FileNameWithExtension = str.FileNameOnly()
FilenameNoExtension = str.FileNameOnly( , false)
Extension = str.ExtensionOnly()

Alternatively you can pass the full path into the various methods. This will allow you to use an existing string, or path name, instead of first assigning it to the string. For example;

Path = str.PathOnly(NAME(Customers))

This would return the path location of the Customers TPS file.

Another useful value is COMMAND(0) Which returns the path, and name of the current EXE. So

ExeName = str.FileNameOnly(COMMAND(0))

The CleanFileName method is useful for checking a filename after the user has entered one. This checks that the filename only contains valid characters, and removes any invalid characters. For example

str.SetValue(someName)
str.CleanFileName()


Upgrading

NetTalk 7, Cryptonite, RunScreen and OddJob all depend on StringTheory. If you use any of these, and you update to StringTheory 2.00 or later then you will need to use NetTalk / NetTalk Lite 7.35 (or later), Cryptonite 1.63 or later and/or OddJob 1.36 or later.

StringTheory 2 is very backwards-compatible with StringTheory 1.xx and it is probable that you will need to make no changes to your application. There is however one change which may be significant to your program.

StringTheory 1 contains a property, a pointer to the string itself, called Value. In most cases you would not needed to have used this property, however occasionally when a string pointer is required (for example to pass to a function) you may have used it directly.

In order to determine where the property is used directly, the property itself has been change to Private. This will cause a compile error;

Invalid use of PRIVATE Data

If you are not getting this error then there is nothing for you to do. If you are getting this error then replace this with a call to .GetValuePtr()

For example

  whatever(str.value)

becomes

  whatever(str.GetValuePtr())

It is possible to make two small changes to the StringTheory INC and CLW files, and by doing so return StringTheory to Version 1 behavior. This is not recommended, but may be useful if you are having a problem upgrading.
  1. Remove the ,PRIVATE attribute from the value property in StringTheory.Inc.
  2. Remove the line self.UseBuffer = true from the Construct method in StringTheory.Clw
Note that if you are using NetTalk 7, you will need version 7.36 or later which is compatible with StringTheory 2. Versions 1.35 and earlier are not compatible. If you wish to use an older version of NetTalk then make the changes to StringTheory discussed above.

Advanced

It is possible you were doing string-slicing on the value property directly. Since the Value property is now private, this code will fail with the same error as mentioned above. While you will still have to change your code, there is a new property, valueptr, which can be used in place of value. Note that you should only use valueptr if you are sure that your code is correct. Using it directly can cause problems if the appropriate checks are not done.

For example;

str.value[4] = 'a'

becomes

str.valueptr[4] = 'a'

Regular Expressions

Regular Expressions are a way of expressing text combinations which contain variable values. For example if the character ? means "any character" then you can search for A?D to find all 3 letter combinations in a string that start with A and end in D.

Unfortunately there is no one standard for the regular expression language, so many different conventions for writing regular expressions have been developed. StringTheory follows the expression language used by Clarion (in the MATCH and STRPOS commands.) This in turn (mostly) follows the Posix ERE syntax. If you are used to regular expressions in other languages, the following tips may be useful to you. Documentation for the expression language is as follows;
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 $.

FAQ's

CCheck out general product CompilerErrors.

Compile Errors

  1. Source File ojmd5.c not found 
    You have no *.c entry in your red file. Re-run the installer, taking care to check the "Update Clarion Redirection file" checkbox.
  2. Invalid use of PRIVATE Data
    See Upgrading.

The StringTheory Templates

The Global Extension Template

There are no options for the Global extension.

The Local Extension Template

Add this extension to populate an instance of the StringTheory class for you. This can also be done very simply in your code:

st StringTheory
  code
  st.SetValue('Some Value')

Acknowledgements

StringTheory includes some code originally appearing in a StringClass, written by Rick Martin and published in ClarionMag and is used with permission.

Many thanks to Geoff Robinson for ongoing feedback and contributions to StringTheory, including bug fixes, improvements and new methods!

ZLIB is the product of Jean-loup Gailly and Mark Adler and is distributed under the terms of their license at http://www.zlib.net/zlib_license.html

Class Reference - StringTheory

StringTheory Class Reference Introduction

The StringTheory class provides a full string handling class that dynamically allocates memory as needed and provides a wide variety of string handling and manipulation methods, including:

Using the StringTheory Class

In general a StringTheory object is declared as simply as

st StringTheory

Where st is the label name (and can be almost anything.) The length of the string is undefined, and is dynamic. In other words the string will automatically grow, and shrink as required. You do not need to worry about the length.

Values are assigned into the string using the SetValue method, or by loading a file off the disk using the LoadFile method.

st.SetValue('hello world')

st.LoadFile('c:\windows\win.ini')
After that the string can be manipulated in a number of different ways, using the methods described below. For example to Base64 encode the string;

st.Base64Encode()

StringTheory 2 Method Reference

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.)
After Returns the rest of the string after 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.
AsnDecode Take a AsnEncoded value and split it into the component parts.
AsnEncode Take a string value, and encode it according to ASN rules.
AsnEncodeNumber Take a number and encode it according to ASN ruiles.
Before Returns the section of the string before 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 .
Base64Decode Decode a string that is encoded using Base64
Base64Encode Encode the string using Base64 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.
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 Clarion RGB color stored in a long to a hex string (which can be used in CSS, HTML etc.).
ColorFromHex converts a string containing the hexadecimal representation of the color to a long containing a standard RGB Clarion 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')
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.
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.
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
FormatMessage Interprets the windows API error code
Free Clears the string and returns all the memory used by the string
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.
FindChar Fast brute force find a single character
FindChars Fast brute force find for a substring
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).
FindWord Retrieve the word at the specified position from the string, and returns the position of the word as well.
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.
HtmlEntityToDec Converts the form &acute; 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')
IsAscii Returns true if the string is blank, or only contains characters from <0> to <127>.
IsTime Returns true if the string looks like a formatted time value.
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.
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.
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.
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
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
SerializeGroup Converts a group to a (something) delimited string.
SerializeQueue Converts a Queue to a (something) delimited string.
SetAll Repeats the contents of the current string, until the string is a specific length.
SetEncodingFromBOM After loading a file, sets the encoding property based the Byte-Order-Mark (if one exists.) Optionally removes the BOM.
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
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.
Sub Returns a substring of the current string
Str Returns the current string and optionally stores the passed value.
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.
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.
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
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)
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
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.

Abbreviate

Abbreviate(Long pPos, Long pRangeLeft = 15,Long pRangeRight = 15)

Description

Shortens a string by searching for a space character "near to" the requested length. Useful for shortening text, but having the abbreviated text end on a complete word. If no space can be found in the range, then the string is simply clipped at the requested position. The method looks in both directions (within the bounds set) to find the closest space.

Parameters
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.
Return Value

Returns the length of the resultant string. The contents of the string object are modified with the shortened string.

See also

Sub

AddBOM

AddBOM(Long Encoding=-1)

Description

Adds a Byte-Order-Mark (BOM) to the front of the string, based on the current string encoding (or the passed parameter.) Byte order marks are often added to the beginning of text files to indicate to editors if the file contains characters in the utf-8 or utf-16 format. If an incorrect BOM already exists then it is removed. If the correct BOM already exists the the string is not changed.

Parameters
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.
Return Value

Returns nothing. The String may be altered.

See also

SetEncodingFromBOM

After

After (String SearchValue, Long Start=1, Long End=0, Long NoCase=false)

Description

Returns the contents of the current string after a delimiter.

Parameters
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.
Return Value

Returns the contents of the current string after a delimiter. If the search string is not found then a blank string is returned.

See also

Before

All

All (Long Length=255)

Description

Repeats the current contents of the string until the string is Length characters long. This method does not affect the current string value. To change the current value use the SetAll method.

Parameters
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.
Return Value

The current string contents, repeated so the returned value is Length characters long.

See also
SetAll

Append

Append (string NewValue, <Long pClip=st:NoClip>, <String pSep>)
Append (stringTheory pStr, <String pSep>)

Description

Appends the NewValue to the current string currently stored in the object.

Parameters
Parameter Description
newValue The value to append to the string
pClip This can be one of several options.
st:NoClip - The current value is not clipped before the NewValue is appended.
st:Clip - The current value is clipped before the NewValue 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 not clipped, and the separator is not added if NewValue is blank.

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.
Return Value

None

See also

Prepend , SetValue

AppendBinary

AppendBinary (long Value,Long Length=4)

Description

A string is placed over the Value parameter, and that string is appended to the end of the current value. The number of bytes appended is passed in the optional Length parameter.

Parameters
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.
Return Value

None

AsnDecode

AsnDecode(*Long pPos, *StringTheory rAsnValue, <*String rAsnType>)

Description

Abstract Syntax Encoding (ASN) encoding is a variable-length way of encoding multiple data fields,  consisting of three parts - a type, a length and a value. This method takes a string, which contains an ASN encoded value, and splits it into those  three parts.

Note that the rAsnValue is raw bytes. If, for example, the type is an integer then the value returned is not a number, but some raw ASCII bytes. Also be aware of the length - integers might be 1, 2 or 4 bytes long. Check rAsnValue.Length() to know which it is.

Parameters
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 omiited if the type is not required.
Return Value

st:ok if the decoding was successful. st:notok if there was a problem. The original string value in the object is not altered. A value of st:NotOk usually means the data was "short" - ie did not include the number of bytes as indicated by the length.

Example

str  StringTheory
Pos  Long
DecodedType  String(1)
Decoded  StringTheory
  code
  str.SetValue(someASNencodedvalue)
  pos = 1
  str.AsnDecode (pos,Decoded,DecodedType) ! Decoded now contains the ASN value.

See Also

AsnEncode, AsnEncodeNumber

AsnEncode

AsnEncode(String pType, <String pValue>)

Description

Abstract Syntax Encoding (ASN) encoding is a variable-length way of encoding multiple data fields,  consisting of three parts - a type, a length and a value. This method adds the length, and type to the front of the existing string. If a value is passed then that is assigned to the string object before the encoding.

Note that the string value is "raw bytes". To encode a number use the AsnEncodeNumber method.

Parameters
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 omiited then the current string in the object will be used. Strings of zero length are allowed in ASN.
Return Value

Nothing. The object is updated with the new value.

Example
str  StringTheory
  code
  str.SetValue('NetTalk is cool')
  str.AsnEncode (st:ASN_OCTETSTRING) ! str now contains the ASN type, length and value.

See Also

AsnDecode, AsnEncodeNumber

AsnEncodeNumber

AsnEncodeNumber(String pType, Long pValue)

Description

Abstract Syntax Encoding (ASN) encoding is a variable-length way of encoding multiple data fields,  consisting of three parts - a type, a length and a value. This method adds the length, and type to the front of the existing string. A number is passed (as a value) and ths is converted into binary before adding it to the string.

Parameters
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.
Return Value

Nothing. The object is updated with the new value.

Example
str  StringTheory
  code
  str.Asnencode (st:ASN_INTEGER,1234) ! Str now contains the ASN value.

See Also

AsnDecode, AsnEncode

Before

Before (string SearchValue, long Start=1, long End=0, long NoCase=0)

Description

Returns the contents of the current string before a delimiter.

Parameters
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.
Return Value

Returns the contents of the current string before a delimiter. If the search string is not found then a blank string is returned.

See Also

After

Between

Between (string Left, string Right, long Start=1, long End=0, long NoCase=0, long Exclusive=1)

Description

Return the part of the string between two search strings (by default exclusively, i.e. the Left and Right delimiter are not included in the returned string). The FindBetween method performs the same functionality but also sets the passed Start and End to the position in the string that the returned string was found at, which allows for repeated calls to FindBetween to find multiple substrings using the same delimiters.

Parameters
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.
Return Value

Returns the string between the passed delimiters if it is found, otherwise a blank string is returned. Between does not alter the original string.
If Right is blank, and End is set, then the return string is clipped at the End position.

See also

FindBetween

Base64Decode

Base64Decode ()

If the Base64 property is set to True, then decodes the current string using the Base64 decode algorithm. The Base64 property is then set to False.

Parameters

None

Return Value

None

See Also

Base64Encode

Base64Encode

Base64Encode (Long pNoWrap=0)

Description

If the Base64 property is false, then encodes the current string in Base64 format. The Base64 property is set to True.

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. To disable automatic line wrapping set the base64NoWrap property to True (1) before calling Base64Encode.

Parameters

Parameter Description
NoWrap If set to true then the output will not be wrapped. Usually the output is wrapped at around the 80 character mark. Set it to st:NoWrap to force the output string not to wrap.

Return Value

None

Example

st StringTheory
  code
!-------------------------------------------------------
! Example 1: Base 64 encode a string (which may contain binary data) with
! the default line wrapping.
!-------------------------------------------------------
  st.SetValue(binaryVal)        ! Set the value, can be binary data
  st.Base64Encode()             ! Base64 encode (automatically line wraps)
  base64String = st.GetValue()  ! Store the Base64 encode value (which is now a plain text string)

!-------------------------------------------------------
! Example 2: Load a file and Base64 encode the contents with
! line wrapping disabled.
!-------------------------------------------------------
  st.LoadFile(myFileName.jpg) ! Load a file (can be binary)
  st.base64NoWrap = true      ! Disable line wrapping
  st.Base64Encode()
  encodedFile = st.GetValue() ! Get the Base64 encode file as a string

See Also

Base64Decode

Capitalize

Capitalize(long pCount=1, long pStartPos=1, long pEndPos=0, <String pCharlist>)

Description

Capitalizes the first letter of one, or more, words in the string. Does not affect other letters in the string. Specifically does not "lower" any characters in the string.

Parameters
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>,-;"''!?&()*/+=<>:'
Return Value

Noting. The string currently in the object is changed.

See Also

Upper, Lower

ChangeBase

ChangeBase (Long pBaseFrom=16, Long pBaseTo=10)

Description

Treating the string as a number, this changes the base of the number from one base to another base.

Parameters
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 34.
pBaseTo The base to change 10. Use 10 for decimal, 16 for Hexadecimal and so on. Valid values are in the range 2 through 34.
Return Value

Str:Ok if the conversion was valid. str:NotOk if the FromBase or ToBase parameter is invalid. The current string is altered by this method.

Example

str.setvalue('12345')
str.ChangeBase(10,16)
s = str.GetValue() ! s = 3039
See Also


 

Chars

Chars(Long pEncoding=-1, <String pStr>)

Description

Returns the number of characters in the string (not the number of bytes.) Works for ANSI, Utf-8 and Utf-16 encodings

Parameters
Parameter Description
pEncoding Possible values are st:EncodingANSI, st:EncodingUft8,  st:EncodingUtf16. 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.
Return Value

The number of characters in the string

See Also

ToAnsi , ToUnicode , Length
 

CleanFileName

CleanFileName (<string fileName>, <string replaceChar>)

Description

Returns a string which contains a cleaned version of the passed file name, with any invalid characters removed.
The filename should not include the path as the \ character is included in the list of characters which is cleaned.

Parameters
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.

Return Value

Returns a string which contains a cleaned version of the passed file name, with any invalid characters removed. If the pFileName parameter was omitted then the current value is updated. If the filename parameter is passed, then the current value is not updated.

See Also

FileNameOnly, ExtensionOnly, PathOnly, ClipLength, Trim, Squeeze

Clip

Clip ()

Description

Clips the string (removes trailing white space).

Parameters

None

Return Value

None

See Also

ClipLength, Trim, Squeeze

ClipLength

ClipLength ()

Description

Returns the length of the current string, ignoring any trailing spaces.
See the Length method for returning the length of the string including trailing spaces.

Parameters

None

Return Value

Returns the length clipped length of the current string (the length minus trailing spaces).

See Also

Length

ColorToHex

ColorToHex (long claColor, bool addHash=false)

Converts a Clarion BGR color stored in a long to a string that contains the hexadecimal representation of the color. The hexadecimal string is made up of six characters (and is optionally prefixed by a hash character if addHash is passed as true).

If the clacolor parameter contains a Clarion color equate (COLOR:SCROLLBAR through COLOR:MENUBAR) then the current system color is fetched and that color is returned as a fixed hex value.

Parameters
Parameter Description
claColor A long that contains the color to convert
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.
Return Value

Returns a string that contains the string hexadecimal representation (in lower case) of the color. The current contents of the string are not altered.

Example
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'
See Also

ColorFromHex

ColorFromHex

ColorFromHex  (string hexColor)

Description

Converts a string that contains the hexadecimal representation of a color to a long that contains a standard Clarion BGR color. The hexadecimal string is made up of six or three characters and may be prefixed by a hash character.

Parameters
Parameter Description
hexColor A string that contains the hexadecimal color.
Can be upper or lower case and can have a hash character as a prefix (HTML/CSS style).
Examples include ABCDEF, fff, #ABC, #123456
Return Value

Returns a long that contains the Clarion BGR color. The current value of the string is not altered.

Example
Example
col long
hCol string(7)
St StringTheory
  code
  hCol = 'ff0000'
  col = St.ColorFromHex(hCol)
  hCol = '#eeeeee'
  col = St.ColorFromHex(hCol)
See Also

ColorToHex

ContainsA

ContainsA (String Alphabet, [String TestString], [Long pClip])

Description

Returns True if the string contains at least one character from the passed alphabet.

Parameters

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)

Return Value

Returns True (1) if the string contains at least one character from the passed alphabet and False (0) otherwise.

See Also

IsAllDigits, ContainsADigit, IsAll , ContainsChar

ContainsADigit

ContainsADigit ()

Description

Returns True if the string contains at least one digit character ('0' to '9'). This method is equivalent to calling
self.ContainsA('0123456789')

Parameters

None

Return Value

Returns True (1) if the string contains at least one digit character ('0' to '9'), and False (0) otherwise.

See Also

IsAllDigits, ContainsA

ContainsChar

ContainsChar(String Char, [String TestString])

Description

Returns True if the string contains the specified character.

Parameters

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".


Return Value

Returns True if the string contains the specified character, and False (0) otherwise.
If the Char is blank then return

See Also

IsAllDigits, ContainsA

ConvertAnsiToOem

ConvertAnsiToOem()

Description

Applies the Clarion ConvertAnsiToOem function to the string.

Parameters

None

Return Value

Nothing

See Also

ConvertOemToAnsi

ConvertOemToAnsi

ConvertOemToAnsi()

Description

Applies the Clarion ConvertOemToAnsi function to the string.

Parameters

None

Return Value

Nothing

See Also

ConvertAnsiToOem

Count

Count (string searchValue, long pStep=1, long pStart=1, long pEnd=0, long noCase=0, bool softClip = true, Overlap = true)

Description

Returns the number of times that the searchValue appears in the current string. The search area can be limited using pStart and pEnd. If omitted, or zero, the whole string is used.

For case insensitive matches set the noCase parameter to true (the default value is false for case sensitive matching). By default 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.

This method does not alter the current string.

Parameters
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.
Return Value

Returns the number of times that the searchValue string is found within the current string. Returns zero if no occurrences are found.

Examples

Example 
st.SetValue('abcabcabc')
Message('Count all instances: ' & st.Count('abc'))                      ! Returns 3
Message('Count with start and end: ' & st.Count('abc', 1, 1, 8))        ! Returns 3
Message('Count with softClip=false: ' & st.Count('abc', 1, 1, 8, False, False)) ! Returns 2 with softClip=false
See Also

CountWords, WordStart, WordEnd, Instring, Replace

CountWords

CountWords (long startPos = 1, long TextType = ST:Text, <String pCharList>)

Description

Returns the number of words in the string

Parameters
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 '&nbsp;' 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)
Return Value

The number of words in the string, or zero if string is empty, contains no words, or the passed parameters are invalid.

See Also

WordStart, WordEnd

Crop

Crop (<long start>, <long end>)

Description

Sets the string to be a subset of itself. The portions of the original string outside the crop are discarded. This is equivalent to calling Slice() to extract a substring and then setting the value of the StringTheory object to the slice. For example, if the current string contains '123456789' and Crop(4,7) is called then the current string will contain '4567'. The start and end parameters are optional and default to the start (first character) and end (last character) of the string respectively. Crop is inclusive and will include the start and end positions.

Parameters
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).
Return Value

None. The contents of the object are changed.

Example
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
See Also

Slice, Sub, SetLength, Split, Trim, Left, Clip

DecEntityToChar

DecEntityToChar()

Description

Converts any text in the string of the form &#nnn; to the actual character. If the string is in ANSI mode then ErrorTrap will be called for any characters greater than 255.

EndsWith

EndsWith (String pStr, Long pCase=True, Long pClip=True)

Description

Checks to see if the current object ends with a particular sub string.

Parameters
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.
Return Value

True if there is a match, or the Sub parameter is empty or False if there isn't a match.

Example
Example 
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 point
See Also

StartsWith

Equals

Equals (StringTheory pOtherValue,  Long pOptions=ST:SimpleCompare)
Equals (String pOtherValue, Long pOptions=ST:SimpleCompare + ST:Clip)

Description

Checks to see if the contents of the StringTheory object match another StringTheory object.
A fixed text (ANSI) value may be used in place of another StringTheory object.
This method can do a simple comparison, or compare ANSI, utf-8 and utf-16 strings with each other.

Parameters
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.
Return Value

True if the objects match.

See Also

ErrorTrap

ErrorTrap (string MethodName, string Message)

Description

This method is called when there is an error raised in the Load or Save methods. If the LogErrors property is set to true then the error message will be passed on to the Trace method. This is an ideal method to use to add custom error handling to the LoadFile and SaveFile methods.

EncodedWordDecode

EncodedWordDecode()

Description

Encoded-Word encoding is used by mail clients when special characters are required in the header fields (like the Subject). This method converts the current string (which is in Encoded-Word format) to be a normal ANSI string.

The form of the text is is
=?charset?encoding?encoded?text?=

The charset may be any character set registered with IANA. Typically (but not necessarily) it would be the same charset as the message body. The encoding can be either "Q" denoting Q-encoding that is similar to the quoted-printable encoding, or "B" denoting base64 encoding.
Encoded text is the Q-encoded or base64-encoded text.

The current string may contain multiple encoded segments within the string. All encoded segments will be decoded. If the last segment charset is utf-8 or utf-16 then the encoding property will be set to st:EncodeUtf8 or st:EncodeUtf16. If the last segment is not utf-8 or utf-16 then the encoding property will be set to st:encodeAnsi, and the codepage property will be set to the the appropriate code page. If there are multiple segments, and they do not have the same codepage, then the string will be converted to utf-8.

See also

EncodedWordEncode, Base64Encode, Base64Decode, URLEncode, URLDecode

EncodedWordEncode

EncodedWordEncode([String Charset], [Long Encoding=st:QuotedPrintable])

Description

Encoded-Word encoding is used by mail clients when special characters are required in the header fields (like the Subject). This method encodes the current string into encoded word format.

An encoded-word may not be more than 75 characters long, including charset, encoding, encoded text, and delimiters. If it is desirable to encode more text than will fit in an encoded-word of 75 characters, multiple encoded-words (separated by CRLF SPACE) will be created.

Parameters

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.

Returns

Nothing

See also

EncodedWordDecode, Base64Encode, Base64Decode, URLEncode, URLDecode

ExtensionOnly

ExtensionOnly ([String FileName])

Description

Returns just the extension part of the filename, ie the part after the last period character. If there is no period in the string then the method returns a blank string. If the FileName parameter is omitted, then the current string value is used.

Parameters
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.

Returns

The extension part of the filename, not including the period. The current string value is not altered by this method.

See also

PathOnly , FileNameOnly , CleanFileName

FileNameOnly

FileNameOnly ([String FileName],Long IncludeExtension=true)

Description

If the passed string contains a fully qualified filename, ie a filename including the path, then this method strips off the path part, and returns just the filename part (including the extension).  If the FileName parameter is omitted, then the current string value is used.

Parameters
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.
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.

Returns

The filename (not including the period) or the filename and extension (with a period separator) depending on the value of the IncludeExtension parameter. . The current string value is not altered by this method.

Example
Example
st   stringtheory
s    string(255)
  code
  s = command(0)
  s = st.FileNameOnly(s)

SSee also

PathOnly , ExtensionOnly , CleanFileName

FindBetween

FindBetween (string Left, string Right, *long Start, *long End, bool NoCase=0, long Exclusive=true)

Description

Return the part of the string between two search strings (exclusively, i.e. the Left and Right delimiter are not included in the returned string). Also sets the passed Start and End to the position in the string that the returned string was found at, which allows for repeated calls to FindBetween to find multiple substrings using the same delimiters.

Parameters
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.
Return Value

Returns the string between the passed delimiters if it is found, otherwise a blank string is returned.
If Right is blank, and End is set, then the return string is clipped at the End position.

Example

Find all strings between the start and end delimiters: '[[' and ']]'
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
See also

Between, FindBetweenPosition

FindBetweenPosition

FindBetweenPosition(string Left, string Right, *long Start, *long End, bool NoCase=0, long Exclusive=true)

Description

Same as FindBetween, but does not return the string found. This can be used as a faster version of FindBetween in cases where the sub string is not required.

FindChar

FindChar (string pSearchValue, long pStart=1, long pEnd=0, [String pText])

Description

A fast brute force single character search. Faster than the standard Instring for some cases. This search is case sensitive.

Parameters
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.

Return Value

Returns the position that the character was found at, or zero if was not found.

FindChars

FindChars (string pSearchValue, long pStart=1, long pEnd=0, <String pText>)

Description

A fast brute force string search. Faster than the standard Instring for some cases. This search is case sensitive.

Parameters
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.
Return Value

Returns the position that the substring was found at, or zero if not found.

FindMatch

FindMatch(string pRegEx, *long pStart, *long pEnd, long pMode=Match:Regular, long pNoCase=0)

Description

Finds a regular expression result in the current object. It returns the found substring, and also the start and end positions of the found substring.

Parameters
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.

Return Value

Returns the string that was found. In addition pStart and pEnd are set to the location in the object where the searchstring was found. The current object is not altered by this method.

See Also

FindMatchPosition, Match, Instring, FindChars, Regular Expressions, SplitByMatch

FindMatchPosition

FindMatchPosition(string pRegEx, *long pStart, *long pEnd, long pMode=Match:Regular, long pNoCase=0)

Description

Same as FindMatch, but does not return the SubString found. This method is included for performance reasons as a faster alternative in cases where the actual string is not required.

FindWord

FindWord (long WordNumber, long startPos = 1, long TextType=ST:Text, *Long Start, *Long End, <String pCharList>)

Description

Returns a string that contains the word at the passed position.n.

Parameters
Parameter DescDescription
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 '&nbsp;' 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.
Return Value

Returns a string that contains the word at the specified position if successful, or an empty string otherwise (if the passed position is invalid or doesn't exist). The Start and End parameters are set to the position of the located word, or 0 otherwise.

See also

GetWord

FromBlob

FromBlob (*blob blobField)

Description

Load the value from a BLOB into the StringTheory object

Parameters
Parameter Description
*blob blobField The BLOB to retrieve the data from.
Return Value

Returns true (1) for success and zero for failure

Examples
Example
ss               StringTheory
blobContents    string
  code
    s.FromBlob(MailData.Text)     ! Store the data
    blobContents = s.GetValue()   ! Get the stored data

FormatMessage

FormatMessage (long Error)

Description

This method converts the Windows Error Code into a Text description of the error.
See also ErrorTrap method, and WinErrorCode property.

Free

Free (long Lines=false, Long Force=false)

Description

A method used to clear the string free the memory used by the object.

Parameters
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.

FromBytes

FromBytes (*string pSrc, *byte pDest, long pOffset=1),
FromBytes (*string pSrc, *short pDest, long pOffset=1)
FromBytes (*string pSrc, *ushort pDest, long pOffset=1)
FromBytes (*string pSrc, *long pDest, long pOffset=1)
FromBytes (*string pSrc, *ulong pDest, long pOffset=1)
FromBytes (*string pSrc, *sreal pDest, long pOffset=1)
FromBytes (*string pSrc, *real pDest, long pOffset=1)
FromBytes (*string pSrc, *decimal pDest, long pOffset=1)
FromBytes (*string pSrc, *cstring pDest, long pOffset=1)
FromBytes (*string pSrc, *pstring pDest, long pOffset=1)
FromBytes (*string pSrc, *string pDest, long pOffset=1)
Description

Retrieves the binary value from the pSrc string parameter (at the position indicated by pOffset) and stores it in the passed second parameter variable. The actual bytes are moved from the string to the destination value. 
The final three forms of the method is a simple move from one string to another.

The opposite of the FromBytes method is the ToBytes method.

FromBytes and ToBytes to not use, or alter, the current contents of the StringTheory object. For an equivalent pair of methods that work on the object itself see GetBytes and SetBytes.

Parameters
Parameter DDescription
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

Example
a   Long
s   String(10)
  code
  s = 'AAAABBBB'
  str.FromBytes(s,a)
  ! a = 1094795585 = 041414141h

  str.FromBytes(s,a,5)
  ! a = 1111638594 = 042424242h

Return Value

None

See Also

ToBytes  , GetBytes , SetBytes

GetBytes

GetBytes (*byte pDest, long pOffset=1),
GetBytes (*short pDest, long pOffset=1)
GetBytes (*ushort pDest, long pOffset=1)
GetBytes (*long pDest, long pOffset=1)
GetBytes (*ulong pDest, long pOffset=1)
GetBytes (*sreal pDest, long pOffset=1)
GetBytes (*real pDest, long pOffset=1)
GetBytes (*decimal pDest, long pOffset=1)
GetBytes (*cstring pDest, long pOffset=1)
GetBytes (*string pDest, long pOffset=1)
GetBytes (*pstring pDest, long pOffset=1)

Description

Retrieves the binary value of bytes from the StringTheory object and stores it in the Destination variable. This method is used in combination with SetBytes to store and retrieve binary values without any transformation.

Parameters
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.

Return Value

None.

See Also

SetBytes , ToBytes, FromBytes

GetBytes

GetBytes (*? pVal, string pType), bool

Description

Retrieves the binary value from the StringTheory object and stores it in the passed variable. This method is used in combination with SetBytes to store and retrieve binary values without any transformation. This wrapper method allows any type to be passed along with the Clarion TYPE for the variable passed ('STRING', 'LONG', 'REAL' etc.)

Parameters
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.

Return Value

Returns True if successful, or False if an error occurs (an unsupported data type, incorrect length, no data stored etc.)

SSee Also

SetBytes, ToBytes, FromBytes

GetAddress

GetAddress()

Description

Returns the current address of the string in memory. This can be used when you need to pass an address to functions that take an address to a block of memory. Note that this address can chance, so the value should not be stored and reused.

Return Value

Returns a Long containing the address of the string.

See also

GetValuePtr

GetCodePageFromCharset

GetCodePageFromCharset(<Long pCharSet>)

Description

Given a Clarion font charset, it returns a codepage equate.

Parameter

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.

Return Value

Returns a Long containing the StringTheory equate for the code page. For example charset:greek returns st:CP_WINDOWS_1253.

See also

JsonDecode, EncodedWordDecode

GetValue

GetValue ()

Description

Returns the value of the string currently stored in the object.

See also

SetValue , GetValuePtr

GetValuePtr

GetValuePtr()

Description

Returns a pointer to the value of the string currently stored in the object. Use this rather than the value property directly.

See also

GetValue, GetAddress

GetWord

GetWord(long WordNumber, long startPos = 1, long textType=ST:TEXT, <String pCharlist>)

Description

Returns a string that contains the word at the passed position.

Parameters
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 '&nbsp;' 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.
Return Value

Returns a string that contains the word at the specified position if successful, or an empty string otherwise (if the passed position is invalid or doesn't exist).

See Also

FindWord, WordStart, WordEnd, CountWords

Gunzip

Gunzip ()

Description

This function decompresses a string that has been compressed using GZIP (either the external GZIP utility, or the Gzip method.)

Note that this method requires that the ZLIBWAPI.DLL is shipped with your application. You can find this DLL in your \clarion\accessory\bin folder.

Example

If you have a file stored on the disk it can be loaded using the LoadFile method, then unzipped using the Gunzip method.
Example
str.LoadFile('whatever.txt.gz')
str.gzipped = 1
str.Gunzip()
str.SaveFile('whatever.txt')
Return Value

The method will only decompress the string if the gzipped property is set to True. If it is set to False then the function returns st:Z_OK, and the contents of the string are unchanged.

If the decompression fails for some reason, the function will return an error code. The original contents of the string will not be changed. Possible Error codes are;
st:Z_ERRNO             Equate(-1)
st:Z_STREAM_ERROR      Equate(-2)
st:Z_DATA_ERROR        Equate(-3)
st:Z_MEM_ERROR         Equate(-4)
st:Z_BUF_ERROR         Equate(-5)
st:Z_VERSION_ERROR     Equate(-6)
st:Z_NORAM_ERROR       Equate(-98)
st:Z_DLL_ERROR         Equate(-99)

If the decompression is successful then the method returns st:Z_OK, and the gzipped property is set to False.

See Also

Gzip

Gzip

Gzip (long pLevel=5)

Description

This method compressed the current string using the GZIP format. this is the same as using the GZIP.EXE utility to create a .gz file, but the result of the compression remains in the string, not on disk.

If the string is already compressed (i.e. the gzipped property is set to 1) then the function returns without changing the string.

Note that this method requires that the ZLIBWAPI.DLL is shipped with your application. You can find this DLL in your \clarion\accessory\bin folder.

Parameters
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

IIf you have a file stored on the disk it can be loaded using the LoadFile method, then zipped using the Gzip method.
Example
str.LoadFile('whatever.txt')
str.Gzip()
str.SaveFile('whatever.txt.gz')

Return Value

The method will only compress the string if the gzipped property is set to False. If it is set to True then the function returns st:Z_OK, and the contents of the string are unchanged.

If the compression fails for some reason, the function will return an error code. The original contents of the string will not be changed. Possible Error codes are;
st:Z_ERRNO             Equate(-1)
st:Z_STREAM_ERROR      Equate(-2)
st:Z_DATA_ERROR        Equate(-3)
st:Z_MEM_ERROR         Equate(-4)
st:Z_BUF_ERROR         Equate(-5)
st:Z_VERSION_ERROR     Equate(-6)
st:Z_NORAM_ERROR       Equate(-98)
st:Z_DLL_ERROR         Equate(-99)

If the compression is successful then the method returns st:Z_OK, and the gzipped property is set to True.

See Also

Gunzip

HtmlEntityToDec

HtmlEntityToDec()

Description

In HTML, non-ASCII characters can be encoded using a "special name", known as an HTML Entity. For example the familiar copyright symbol,©, can be written in html as &copy; . Ideally this should be represented though in a unicode format as &#169; which is a more generic encoding and "more compatible" with things other than HTML.

This method finds a range of entities in the string, and replaces them with the more standard unicode encoding.

Return Value

None. The current string is altered by this method.

Insert

Insert (long Start, string insertValue)

Description

Inserts the passed string into the stored string at the specified position. The stored string is expanded as needed.

Parameters
Parameter Description
Start SStart 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.

Return Value

None

Examples
Example 
st.Insert(st.Length()-2, '-NewValue-')

Instring

Instring (string SearchValue,[Long Step],[Long Start],[Long End],[Long NoCase],[Long WholeWord])

Description

Similar to the Clarion INSTRING function, this is used to locate a substring in a string. Some additional parameters, and one behavioral change, make it somewhat more useful though.

Parameters
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.
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).
Return Value

The position of the substring in the value, if it is found. If no match is found then 0 is returned. Note that if the Step parameter is set then the Step number, not the Position number of the located string is returned.

Special note: Unlike the Clarion INSTRING command, the default value of Step is 1, not the length of the Search value.

Special note: The Clarion Instring command returns the "step number" (not the position) of the located text when the STEP parameter > 1. The StringTheory version ALWAYS returns the POSITION regardless of the value in STEP.

IsAll

IsAll (String Alphabet, <String TestString>, Long Clip=true)

Description

Returns True if the string contains only characters in the passed alphabet.

Parameters
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.
Return Value

Returns True (1) if the string only contains characters from the alphabet, or False (0) otherwise.

EExample

st  StringTheory
  code
  st.SetValue(somestring)
  If st.IsAll('ABCDEF0123456789')
    ! contains a hex number
  End

See Also

ContainsADigit, ContainsA, IsAllDigits

IsAllDigits

IsAllDigits ()

Description

Returns True if the string only contains digit characters ('0' to '9'). this is the equivalent of calling
self.IsAll('01233456789')

Parameters

None

Return Value

Returns True (1) if the string contains only digit characters ('0' to '9'), or False (0) otherwise.

Example

st StringTheory
  Code
  st.SetValue(somestring)
  If st.IsAllDigits()
    ! only contains digits
  End

See Also

ContainsADigit, ContainsA, IsAll

IsAscii

IsAscii()

Description

Returns True if the string is blank, or only contains characters from <0> to <127> - in other words 7-bit characters.

Parameters

None

Return Value

Returns True (1) if the string contains only characters from <0> to <127> or False (0) otherwise.

Example

st StringTheory
  Code
  st.SetValue(somestring)
  If st.IsAscii()
    ! only contains ASCII characters, ie 127 and below.
  End

See Also

ContainsADigit, ContainsA, IsAll

IsTime

IsTime ([string Value])

Description

Returns True if the string appears to contain a human-readable time.
Note that this method does not detect a lot of values that would be acceptable to the DeformatTime method. That method assumes the value IS a time, and so is not considering that it might just be a number. This method narrows the pattern considerably.
Parameters
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.
Return Value

Returns True (1) if the string appears to contain a Time or False (0) otherwise.

See Also

FormatTime,DeformatTime

JsonDecode

JsonDecode()

Description

Decodes a string that has previously been encoded into the JSON format.

Return Value

Nothing. The current string is altered by this method.

See Also

JsonEncode

JsonEncode

JsonEncode(Long pOptions=0)

Description

Encodes a string so it is a valid JSON string. This treats the \ character as an "escape" character and then followed by a short list of characters that need to be modified.

Parameters
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.

Return Value

Nothing. The current string is altered by this method.

SSee Also

JsonDecode

KeepChars

KeepChars(string Alphabet)

Description

Removes any characters from the string which are not included in the Alphabet parameter.
 
Parameters
Parameter Description
Alphabet Only characters specified in this string will be preserved. This string is case sensitive.
Return Value

Returns the number of characters removed from the string. The text in the object is changed.

See Also

RemoveChars

Left

Left ([Long Length],[Long What],[String Pad])

Description

Returns the contents of the string, with leading characters removed. If the length parameter is used then the returned value is either padded with characters, or cropped, so it is exactly the specified length.
Note that this method does not affect the actual stored string. To set the string use the SetLeft method.

Parameters

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.

Return Value

Returns the left-justified string.

Example

str  Stringtheory
  code
  str.SetValue('  abc')
  c = str.Left()   ! c = 'abc  ' ! note the trailing spaces

See Also

Right, SetLeft, SetRight,

Length

Length ()

Description

RReturns the current length of the string currently stored in the object.

Note:In Clarion 5.5 the Length keyword is reserved, so in Clarion 5.5, for this method, use the method name LengthA instead.

Parameters

None

Return Value

Returns the length (in byte) of the stored string, or zero if nothing is being stored.

LineEndings

LineEndings (Long Endings = st:Windows)

Description

Converts any ASCII line endings between Windows (CR/LF), MAC (CR) and UNIX (LF) formats. This can be useful for files downloaded from an FTP server that modifies the line endings in text files.

Parameters

Parameter Description
Endings
(optional)		 The format desired for the text. Valid options are st:Windows, st:Mac and st:Unix. If this parameter is omitted then st:Windows is used.

Return Value

RReturns nothing. The contents of the object are altered to the preferred line ending.

Loadfile

Loadfile (String FileName, Long Offset=0, Long Length=0, Long RemoveBOM=false)

Description

Loads a file off the disk, and places it in the current string value. The maximum size of the file is limited only by the maximum size of a string in Clarion (which is a around two gigabytes.) The existing contents of the object are discarded before the file is loaded.

Parameters
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.
Return Value

Returns True (1) for success, or False (0) for failure. If an error occurs the ErrorTrap method is called with additional error information. The number of bytes actually read is available in the bytes property. If the load is successful then the object will contain the file, if it unsuccessful then the object will be empty.

Example
Example 
st  stringtheory
  code
    if not st.LoadFile('c:\windows\win.ini')
        Message('An error occured loading the file')
    end
See Also

SaveFile , SetEncodingFromBOM, ErrorTrap

LongDivision

LongDivision(Long pDivisor, *Long rRemainder, Long pBase)

Performs "long division" maths on a string. Works on a string of any length.
Note that this method is not fast, it is designed to work on numbers which cannot be stored in other data types, so it cannot make use of CPU maths.

Parameters
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 34. If this base is invalid then then method will terminate with a return value of str
Example
Example
st stringtheory
r  long
  code
  st.SetValue('184694349FB2A2C700000000532BC82B')
  st.LongDivision(10,r,16)
! st now contains '26d7538765ea9e0b33333333b8460d1'
! r contains 1

Return Value

Returns st:ok if division successful. Returns st:notOk if pBase parameter is invalid. The contents of the string are changed. Alphabetic characters are set into lower case.

See Also



LLower

Lower ([String Quote],[String QuoteEnd])

Converts all the characters (except the ones in quotes) in the current string to lower case.

Parameters
Parameter Description
Quote (optional) AA 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
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'

Return Value

Returns nothing. The contents of the string are changed. The base of the string is not change

See Also

Upper , Capitalize

MakeGuid

MakeGuid (long pLength=16, long pFlags=st:Upper+st:Number)

Same as Random but with different default parameters. This method makes it simpler to call a method where the default parameters are configures to provide a random string which is suitable for a database unique identifier.

Match

Match(string pRegEx, Long pStart=1, Long pEnd=0, long pMode=Match:Regular, long pNoCase=0)

Similar to INSTRING but allows regular expression matching.

Parameters
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
Example
 

Return Value

Returns a LONG indicating the position of the start of the searched-for string in the object. If the string is not found then 0 is returned.  The contents of the string is not changed.

See Also

 Instring, FindMatch, Regular Expressions

MatchBrackets

MatchBrackets (String pLeftBracket, String pRightBracket, Long pStart=1)

Finds the matching end bracket of a given start bracket.

Parameters
Parameter Description
LeftBracket A single character, indicating the left bracket of the search. For example, ( or < or { and so on.
RightBracket The right character 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.
Example
Example
st stringtheory
x  Long
  code
  st.SetValue('(a+b)=((c+d)*4)')
  x = st.MatchBrackets('(',')',7) ! x = 15

Return Value

Returns a LONG indicating the position of the right bracket. If the matching bracket is not found then 0 is returned.  The contents of the string is not changed.

See Also

 

MD5

MD5 (Long pFormat=st:EncHex)

Returns the MD5 hash value of the current string.

Parameters
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.

Return Value

A string which contains the MD5 hash of the value in the StringTheory object.

Example
Example 1 
st.SetValue(myValue)  ! Store the value to create a hash of
hashVal = st.MD5()    ! ! Get the hex encoded hash from the string
Example 2
st.SetValue(myValue)        ! Store the value to create a hash of
st.SetValue(st.Md5(st:EncBase64)) ! Store the hash in the object
hashString = st.GetValue()  ! Get the base64 encoded hash from the string
Notes

MD5 is no longer considered a safe hash for security purposes. When hashing for security rather use sha-256 (available in Cryptonite.) When used for non-security purposes (for example as an advanced form of crc) then MD5 is still ok.

NOTE: This method is only included if your project has the MD5=>1 project define included (this can be enabled on the global extension by ticking the "Enable MD5" tickbox).

MergeXml

MergeXml (String New, Long Where)

Description

This method allows you to inject a new xml block into an existing xml document, in other words inside the current xml root tag.. The object contains the current XML block, and the contents of the object are changed.

Parameters
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
Examples

st    StringTheory
xml   String(255)
  code
  st.SetValue('<docroot><node>Hello</node></docroot>')
  xml = '<anotherNode>World</anotherNode>'

Taking the above as the starting point, the following line

st.MergeXML(xml,st:first)
would result in st containing something like this;

<docroot><anotherNode>World</anothernode><node>Hello</node></docroot>

whereas

st.MergeXML(xml,st:last)

would result in st containing something like this;

<docroot><node>Hello</node><anotherNode>World</anothernode></docroot>
Returns

Nothing

Normalize

Normalize(Form=st:NFKD, PreserveEncoding=true)

Description

Unicode contains multiple possible encodings for the same character, depending on the encoding style. This can cause problems when trying to do string comparisons. Normalizing reduces the strings to the "same" encoding style which makes for easier comparisons.

Normalizing is only applicable to Unicode (utf-8 or utf-16) strings. If this method is called, and the current encoding is ANSI then the method returns without doing anything.

Normalizing is also used to remove ligatures, usually in preparation for conversion to ANSI.  It is invoked automatically by the ToAnsi method.

Parameters
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.)

Returns

Nothing. The current value of the string is possible changed, and the encoding of the string may be changed to utf-16.
 

PathOnly

PathOnly ([String FileName])

Description

If the passed string contains a fully qualified filename, i.e. a filename including the path, then this method strips off the filename part, and returns just the path part. If the FileName parameter is omitted, then the current string value is used.

Parameters
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.

Returns

The path part of the filename. The trailing \ is not included. The current string value is not altered by this method.

Example
Example
st   stringtheory
s    string(255)
  code
    s = command(0)
    s = st.PathOnly(s)  ! c:\program\bob

See also

FileNameOnly , ExtensionOnly , CleanFileName

PeekRAM

PeekRAM (uLong pAdr, Long pLen, Long pFormat=st:Decimal)
PeekRAM (Long pFormat=st:Decimal)

Description

A debugging method.

This method allows you to inspect machine memory at a specific address. The output is sent to DebugView in both ASCII and Number format. The number format used is either decimal or hexadecimal.

Note that peeking at memory that does not belong to you can cause a GPF.

Parameters
Parameter Description
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.

Returns

Nothing. The current object is not altered. All output goes to DebugView.

See Also

Append

Prepend

Prepend (String NewValue,<Long pClip>,<String pSep>)
Prepend (stringTheory pStr, <String pSep>)

Description

The opposite of the Append method. The passed parameter is added to the front of the current string.

Parameters
Parameter Description
newValue The value to prepend to the string
pClip 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.

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.

See Also

Append

Quote

Quote (<string pQuotestart>, <string pQuoteEnd>)

Description

Wraps the string in the passed quotation marks.

Parameters
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.
Return Value

None. The current object is changed by adding the quotation marks. If the current object is blank then quotes are not added and the object is left unchanged.

Example
Example
st.Quote() ! Wrap the string in double quotes

QuotedPrintableEncode

QuotedPrintableEncode()

Description

This method encodes the current string into QuotedPrintable format. Often used by email systems, this converts all data to a 7 bit format, with a maximum line length of 76 characters. It uses the equals sign (=) as the escape character.

Parameters

None

Returns

Nothing. The current value in the object is changed.

Example
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.
See Also

QuotedPrintableDecode

QuotedPrintableDecode

QuotedPrintableDecode()

Description

This method decodes the current string from QuotedPrintable format. Often used by email systems, this data in in a 7 bit format, with a maximum line length of 76 characters. It uses the equals sign (=) as the escape character.

Parameters

None

Returns

Nothing. The current value in the object is changed.

Example
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.
See Also

QuotedPrintableEncode

Random

Random ([Long Length], [Long Flags], [String Alphabet])

Description

Fills the string with random characters.
This function is useful when generating random file names, or creating GUID strings or things like that.
Because of the ability to generate only digits it's also useful for generating really large random numbers (in a string).

Parameters
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: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:DNA - Includes the uppercase characters GCAT.
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. Not that if you want to include a space in your alphabet, and 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.
Returns

The string created. The contents of the string created are also placed in the object value.

Remove

Remove (string pLeft,<string pRight>,long pNoCase=0,long pContentsOnly=0, long pCount=0)

Description

This method allows you to remove a block of text from the string by using a start and end delimiter.

Parameters
Parameter Description
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.

Return value

The number of items removed from the string.

Example
Example 
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())
The output (value stored in the StringTheory object) of the above example is: 'Hello World'

See Also

RemoveAttributes, Replace

RemoveAttributes

RemoveAttributes (String pTag, Long pCount=0)

Description

Finds all instances of <tag> in the string, and removes all attributes from those tags. Designed for making parsing HTML simpler (although XML and any other format that uses tags and attributes is supported), by removing the attributes, but leaving the tags in place. For example for the tag 'td':

'<td class="tabledata" align="left" colspan="2" valign="middle" id="td_11">'

Would become:

'<td>'

Parameters
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.
Return value

None

Examples
Example 
htmlString = <td class="tabledata" align="left" ' |
           & 'colspan="2" valign="middle" id="td_11">' |
           & 'Hello World</td>'

st.SetValue(htmlString)
st.RemoveAttributes('td')
Message(st.GetValue())
The output (value stored in the StringTheory object) of the above example is: '<td>Hello World</td>'

RemoveChars

RemoveChars(string Alphabet)

Description

Removes any characters from the string which are specified in the Alphabet parameter.
 
Parameters
Parameter Description
Alphabet All characters specified in this string will be removed.
Return Value

Returns the number of characters removed from the string. The text in the object is changed.

See Also

KeepChars

RemoveHTML

RemoveHTML()

Description

Removes all HTML markup from the object, leaving just text behind.

Notes

Everything between <head> and </head>, between <style> and </style> and between <script> and </script> are removed.
 
Return Value

Returns nothing, The text in the object is changed.

See Also


RemoveXMLPrefixes

RemoveXMLPrefixes()

Description

Inspects the strings for XML tags of the form <tag> and </tag>. If the tag name contains a prefix then it is removed. For example <ns:tag> becomes <tag>.
 
Return Value

Nothing is returned. The text in the object is changed.

See Also

RemoveAttributes , MergeXML

Replace

Replace (string oldValue, string newValue, [long count=0], [long start=1], [long end=0], [long NoCase=0], [bool Recursive=false])

Description

Searches for instances of Old Value in the current string and replaces them with NewValue.

Parameters
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.
Return value

The number of items replaced in the string.

Examples
Example 
! Replace all occurrences of findString with replaceString:
st.SetValue('Frank-Was-Here')
st.replace('-',' ')

! Replace only the first occurrence
st.SetValue('Frank-Was-Here')
st.replace('-',' ',1)

! Replace all. Case insensitive, starting at character 10,
! ending at character 20 in the search string.
st.SetValue('Frank-Was-Here-On-A-Wednesday-Last-Month')
st.replace('-',' ', ,10,20,true)

ReplaceSingleChars

ReplaceSingleChars (string OldChars, string NewChars, bool OnceOnly=False)

Description

For each character in OldChars, replace it with the matching character in NewChars. This is faster than calling Replace multiple times when just substituting one character for another. It's also possible to use this method to swap characters, without the need for an interim "temp" character.

Parameters
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.
Return value

The number of items replaced in the string. If the OldChars and NewChars strings are not the same length then the method returns st:error, and the ErrorTrap method is called.

Examples
Example 
str.setValue('Hello')
str.ReplaceSingleChars('loe','pya')   ! str now contains 'Happy'

str.SetValue('aba')
str.ReplaceSingleChars('ab',ba')      ! str now contains aaa

str.SetValue('aba')
str.ReplaceSingleChars('ab',ba',true) ! str now contains bab

See Also

Replace

Reverse

Reverse([String pString])

Description

Reverses the byte order inside a string. So ABCD becomes  DCBA.

Parameters

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.

Return Value

Returns nothing (if no parameter) or the reversed version of the passed parameter.

Example

str  StringTheory
  code
  str.SetValue('ABCD')
  str.Reverse()
  ! str now contains DCBA

Example

str  StringTheory
s    string(10)
  code
  s = str.reverse('ABCD')
  ! s now contains DCBA


 

Right

Right ([Length],Long What = 0,[String Pad])

Description

Returns the contents of the string, with trailing characters removed. If the length parameter is used then the returned value is either padded with spaces at the front, or cropped, so it is exactly the specified length.
Note that this method does not affect the actual stored string. To set the string use the SetRight method.

Parameters

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.

Return Value

Returns the right-justified string.

See Also

Left, SetLeft, SetRight

SaveFile

SaveFile (string fileName, <long appendFlag>)
SaveFile (*string newValue, string fileName, long appendFlag, <long dataLen>)

Description

Saves the current string (or a passed string) to the disk as a file, or appends the current string to an existing file on the disk.

If the newValue parameter is used, then the value in that string is saved, rather than the current string.
If the appendFlag parameter is set to true then the string is appended to the current file. If it set to false then the current string is saved, and the current values in the file, if the file already exists, is lost.

Parameters
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.
Return Value

Returns True (1) for success and False (0) for failure. If an error occurs then the ErrorTrap method is called with additional information.

See Also

LoadFile , ErrorTrap

SerializeGroup

SerializeGroup(*Group pGroup,<String pBoundary>, <string pQuotestart>, <string pQuoteEnd>, Long pLevel=1, Long pFree=true)

Description

Serializes a group into a separated string. The separator can be any character, or characters specified in the boundary.

Nested groups can use different separators. For example in EDI applications it's possible to have a comma separated list, where the sub level fields are * separated and those can in turn contain ^ separated fields.

Parameters
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.

Return Value

The number of fields which have been serialized.
The contents of the object are altered.

Examples

Example 1

str StringTheory
Grp Group
a     String(20)
b     Long
c     String(20)
    End

  Code
  grp.a = 'hello'
  grp.b = 100
  grp.c = 'worlds'
  str.serializeGroup(grp)
  ! str now contains hello,100,worlds

Example 2

str StringTheory
EdiGroup Group
a          String(20)
b          Long
c          String(20)
SubGroup1  Group
d            String(5)
e            String(5)
SubGroup2    Group
f              Long
g              String(10)
             End
           End
h          String(10)
         End

  CODE
  EdiGroup.a = 'here'
  EdiGroup.b = 10
  EdiGroup.c = 'there'
  EdiGroup.SubGroup1.d = 'went'
  EdiGroup.SubGroup1.e = 'the'
  EdiGroup.SubGroup1.SubGroup2.f = 99
  EdiGroup.SubGroup1.SubGroup2.g = 'rabbit'
  EdiGroup.h = 'pie'
  str.SerializeGroup(EdiGroup,',I*I^')
  ! str now contains here,10,there,went*the*99^rabbit,pie
See Also

 SerializeQueue

SerializeQueue

SerializeQueue(*Queue pQueue, String pRecordBoundary, String pFieldBoundary, <String pQuotestart>, <String pQuoteEnd>, Long pLevel=1, Long pFree=true)

Description

This method is the same as SerializeGroup except that it serializes a Queue not a Group. An additional parameter (pRecordBoundary) allows you to set the record boundary. If omitted then a CRLF ('<13,10>') is used as the record boundary.

See Also

SerializeGroup

SetBytes

SetBytes (*byte pVal),
SetBytes (*short pVal)
SetBytes (*ushort pVal)
SetBytes (*long pVal)
SetBytes (*ulong pVal)
SetBytes (*sreal pVal)
SetBytes (*real pVal)
SetBytes (*decimal pVal)
SetBytes (*cstring pVal)
SetBytes (*string pVal)
SetBytes (*pstring pVal)

Description

Retrieves the binary value from the StringTheory object and stores it in the passed variable. This method is used in combination with SetBytes to store and retrieve binary values without any transformation - for example when storing an encrypting numeric values.

Parameters
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.
Return Value

None

See Also

SetBytes, ToBytes, FromBytes

SetBytes

SetBytes (*? pVal, string pType), bool

Description

Stores the binary value of passed variable. This method is used in combination with GetBytes to store and retrieve binary values without any transformation - for example when storing an encrypting numeric values. This wrapper method allows any type to be passed along with the Clarion TYPE for the variable passed ('STRING', 'LONG', 'REAL' etc.)

Parameters
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.
Return Value

Returns True if successful, or False if an error occurs (an unsupported data type, incorrect length, no data stored etc.)

See Also

GetBytes, ToBytes, FromBytes

SetAll

SetAll (long Length=255)

Description

Repeats the current contents of the string until the current string is Length characters long.

Parameters
Parameter Description
Length The length of the resultant string.
Return Value

None

SetEncodingFromBOM

SetEncodingFromBOM(Long RemoveBOM=true)

Description

Text files on disk are sometimes stored with two, or three, initial characters which indicate that the file contains unicode characters. These are known as Byte Order Marks. This method looks for, and optionally removes, the Byte Order Mark, and sets the encoding property to utf-8 or utf-16.

This method is called automatically by the LoadFile method but does not remove the BOM in this case (unless specifically set to do so by the call to LoadFile.) To remove the BOM either call Loadfile with an appropriate parameter or just call this method again with no parameters.

Parameters
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.
Return Value

None. The .Encoding property may be set, and the string object may be changed.

See Also

LoadFile, AddBOM

SetLeft

SetLeft ([Long Length],[Long What],[String Pad])

Description

Changes the contents of the string, removing leading characters. If the length parameter is used the string is either padded with characters at the end, or cropped, so it is exactly the specified length.
Note that this method affects the actual stored string. To get the string without altering it use the Left method.

Parameters

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 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.

Return Value

Nothing. The contents of the string are altered.

Example

str  Stringtheory
  code
  str.SetValue('  abc') ! str = 'abc  ' ! note the trailing spaces

 See Also

Right, Left, SetRight

SetLength

SetLength (long NewLength, Long Force=false)

Description

Sets the space allocated to the string to a specific length. This is mostly for internal use to be used when extra space is required - for example in the base64 encoding method.

This method is not needed when calling SetValue as that adjusts the length of the string automatically.

See also the Length method to get the current length of the string.

Parameters
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.
Return Value

None

Examples
Example 
st.SetLength(st.Length() + 20) ! Increase the length by 20 characters

SetRight

SetRight ([Length], Long What=0, [string Pad])

Description

Changes the contents of the string, with trailing characters removed. If the length parameter is used then the string is either padded with some character at the front, or cropped, so it is exactly the specified length.
Note that this method affects the actual stored string. To get the string without altering it use the Right method.

Parameters

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.

Return Value

Nothing. This method alters the current string value.

See Also

Right, Left, SetLeft

SetValue

SetValue (string NewValue, long pClip=false)
SetValue (stringTheory NewValue)

Description

Sets the value of the object to the parameter passed. The passed string can be of any size.

Parameters
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.

Notes

If the clip parameter is omitted (or False (0)) then the value being added to the string is not clipped, otherwise it is clipped. Defaults to not clipping the string.

If the value you are passing into the object is Base64 encoded, then set the Base64 property to 1 at the same time.

See Also

GetValue, Append

SetSlice

SetSlice (ulong pStart=1, ulong pEnd=0, string newValue)

Description

Sets the value of the specified region within the string to the passed string. The string is expanded if needed.

Parameters
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.
Return Value

None

Notes

If the length of NewValue is greater than the space provided (pEnd-pStart+1) then NewValue is truncated to fit into the space.

If the pEnd is greater than the current length of the string, then the string will be made longer to accommodate the new value.

If the pStart is greater than the end of the string, then the string will be lengthened, and the space between the end and pStart will be space padded.


Examples
Example 
st.SetSlice(10, 20, '-NewValue-')

Slice

Slice (long Start, <long End>), string

Descriptions

Returns a substring of the current string. The current string is not altered.

If the end parameter is omitted then the string from the start position to the end of the string is returned.

Parameters
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.
Return Value

Returns the substring of the stored value from the start to end positions specified.

Example
Example 
st      StringThory
  code
  st.SetValue('1234567890abcdefghikjlmnop')
  Message(st.Slice(10))      ! Displays: 0abcdefghikjlmnop
  Message(st.Slice(10, 13))  ! Displays: 0abc
See Also

Sub, SetLength, Between, FindBetween

Sort

Sort (Long SortType, string Boundary, [string Quote], [string QuoteEnd], bool Clip = false, bool Left=false)

Description

Splits the string into lines based on the Boundary parameter, sorts the lines based on the SortType parameter, then joins the lines back together in sorted order. In other words this method sorts the contents of the string, based on a separator string.

Parameters
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.
Return Value

None. The contents of the object are altered by this call. The Lines queue (as created by Split) is empty after this call.

See Also

Split, Join, Sort

Squeeze

Squeeze (long textType=ST:TEXT, <String pCharList>)

Removes excess white space (each word in the string is separated by a single space). By default punctuation is treated as white space and also "squeezed" (removed). Setting the textType parameter to ST:NOPUNCTUATION ensures that punctuation is not removed and is treated in the same manner as other none whitespace characters. With this option specified only extra spaces are removed.

Parameters
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.
Return Value

None

Start

Start()

This method frees the String object, clears out the Lines from a Split, and sets all the properties of the class back to the default setting. It is useful if you are re-using the object and you want to start it as if it had just been constructed.

Return Value

None

StartsWith

StartsWith (String pStr, Long pCase=True, Long pClip=True)

Description

Checks to see if the current object begins with a particular sub string.

Parameters
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.
Return Value

True if there is a match, or the Sub parameter is empty or False if there isn't a match.

Example
Example 
st     StringTheory
  code
  st.SetValue('123456789')
  x = st.StartsWith('89')    ! x is false at this point.
  x = st.StartsWith('')      ! x is true at this point.
  x = st.StartsWith('123')   ! x is true at this point.
See Also

EndsWith

Sub

Sub (ulong pStart=1, ulong pLength=1)

Description

Extract a substring from the current string.

Parameters
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.

Returns

Returns a substring of the current string. The current string is not altered.

See Also

Slice, SetSlice, Abbreviate

Str

Str (), string
Str (string newValue), string
Str (*string newValue), string

Description

Returns the current string value. If a string is passed then the passed value is first stored and then returned. This is the equivalent of calling SetValue() followed by GetValue()

Parameters
Parameter Description
newValue [Optional] An optional value to store before returning it.
Return Value

None

Examples
Example
Message(st.Str(someValue))

ToBlob

ToBlob (*blob blobField)

Description

Saves the current value to the passed BLOB.

Parameters
Parameter Description
*blob blobField The BLOB field to store the value in.
Return Value

Returns True (1) for success or (0) for failure. If an error occurs the ErrorTrap() method is called with additional information.

Examples
Example
s.SetValue(plainText, true)  ! Store a value in the StringTheory object
s.ToBlob(MailData.Text)      ! Store the value in the passed BLOB

ToBytes

ToBytes (*byte pSrc, *string pDest, long pOffset=1)
ToBytes (*short pSrc, *string pDest, long pOffset=1)
ToBytes (*ushort pSrc, *string pDest, long pOffset=1)
ToBytes (*long pSrc, *string pDest, long pOffset=1)
ToBytes (*ulong pSrc, *string pDest, long pOffset=1)
ToBytes (*sreal pSrc, *string pDest, long pOffset=1)
ToBytes (*real pSrc, *string pDest, long pOffset=1)
ToBytes (*decimal pSrc, *string pDest, long pOffset=1)
ToBytes (*cstring pSrc, *string pDest, long pOffset=1)
ToBytes (*pstring pSrc, *string pDest, long pOffset=1)
ToBytes (*string pSrc, *string pDest, long pOffset=1)

Description

Retrieves the binary value from the pSrc parameter and stores it in the passed second string parameter variable at the offset determined by the third parameter. The actual bytes are moved from the source variable to the destination value. 
The final three forms of the method is a simple move from one string to another.

The opposite of the ToBytes method is the FromBytes method.

FromBytes and ToBytes to not use, or alter, the current contents of the StringTheory object. For an equivalent pair of methods that work on the object itself see GetBytes and SetBytes.

Parameters
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.

Return Value

None

Example
Example
a   Long
s   String(10)
  code
  a = 041414141h
  str.ToBytes(a,s)     ! s = 'AAAA'
  a = 042424242h
  str.ToBytes(a,s,5)   ! s = 'AAAABBBB'

See Also

GetBytes , SetBytes , FromBytes

ToCString

ToCString ()

Description

Returns a pointer to a Cstring. The contents of the Cstring will be set to the current string. This is useful if you wish to pass the string to other functions that require a Cstring.

NOTE: POTENTIAL MEMORY LEAK WARNING: The Cstring is created using the NEW keyword. It is the responsibility of the programmer to DISPOSE this cstring. The FreeCstring() method can also be used to safely dispose the string reference.

Example
Example
c  &cstring
st StringTheory

  code
    st.SetValue('hello world')
    c &= st.ToCstring()
    ! use cstring here
     Dispose(c)

Trace

Trace ([string Message])
Trace ([queue pQueue])

Description

A method to send data to debugview, primarily for debugging purposes. If no paramter is used then the current contents of the string are sent to debugview.

Parameters
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.

Notes

DebugView is a useful free utility provided by Microsoft for viewing the all output to the system debug log, as well as allowing it to be filtered, specified strings to be highlighted etc. DebugView is a free 286KB download, available for all version of Windows from XP onwards, from http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx.

A better version of DebugView is DebugView++. This can be found on Github at https://github.com/djeedjay/DebugViewPP.

Returns

Nothing


Trim

Trim (<String pAlphabet>)

Description

Removes white space from the start and the end of the string.

Parameters

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.

Return Value

None. The object is updated by this method.

UnQuote

UnQuote (<string pQuotestart>,<string pQuoteEnd>)

Description

Removes the quotes wrapping the string. By default this removes double quotation marks at the start and end of the string, or the passed start and end quote characters.

Parameters
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 (").
Return Value

None

Examples
Example 
st.UnQuote()  ! Removes double quotes wrapping the string

Upper

Upper ([String Quote],[String QuoteEnd])

Converts all the characters (except the ones in quotes) in the current string to upper case.

Parameters
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.
Example
Example 
st  stringtheory
  code
  st.SetValue('This is a "test" of the UPPER method')
  st.lower('"')
  ! st now contains 'THIS IS A "test" OF THE UPPER METHOD'

Return Value

Returns nothing. The contents of the string are changed.

See Also

Lower , Capitalize

UrlDecode

UrlDecode ([String Delimiter],[String Space])

Description

URL (percent) decodes the string.

Parameters
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.
Returns

Nothing

See Also

URLDecode

UrlEncode

UrlEncode (long Flags = 0, [String Delimiter], [String Space], [String Alphabet])
UrlEncode (String pText, long Flags, String Delimiter, String Space, String Alphabet)

Description

URL (percent) encodes the string. All non alpha-numeric characters are replaced with a delimiter, and a number (in Hex format) representing the number of the character in the ASCII table.

Parameters
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.

Returns

Nothing

See Also

URLDecode

UrlFileOnly

UrlFileOnly(<string pURL>)

Description

Extracts the file part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
file  is returned.

Parameters
Parameter Description
pURL (optional) Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used

Returns

A string. The filename  part of the URL. If the filename is omitted from the url then a blank string is returned.  The current string value is not altered by this method.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
name = str.UrlFileOnly() ! name = 'index.htm'

str.setvalue('www.capesoft.com')
name = str.UrlFileOnly() ! name = ''

See Also

UrlProtocolOnly, UrlPortOnly, UrlHostOnly, UrlPathOnly,  UrlParametersOnly

UrlHostOnly

UrlHostOnly(<string pURL>,Long pIncludePort=true)

Description

Extracts the host part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
host or host:port is returned.

Parameters
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).

Returns

A string. The host part of the URL. If the protocol is omitted from the url then a blank string is returned. The trailing :// part of the protocol is not included in the returned value. The current string value is not altered by this method.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
host = str.UrlHostOnly() ! host = 'www.capesoft.com:80'

host = str.UrlHostOnly('https://www.capesoft.com:80/accessories/index.htm',false) ! host = 'www.capesoft.com'

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
host = str.UrlHostOnly( , false) ! host = 'www.capesoft.com'

See Also

UrlProtocolOnly, UrlPortOnly, UrlPathOnly, UrlFileOnly, UrlParametersOnly

UrlParameter

UrlParameter(String pParameter,<string pURL>)

Description

Extracts the value of a parameter in a URL.

Parameters
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.

Returns

A string. The value of the named parameter. The value is already URL Decoded.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm?user=charles&uid=1')
user = str.UrlParameter('user') ! user = 'charles'

str.setvalue('user=charles&uid=1')
user = str.UrlParameter('uid') ! uid = 1


See Also

UrlParametersOnly

UrlParametersOnly

UrlParametersOnly(<string pURL>)

Description

Extracts the parameters part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
parameters is returned.

Parameters
Parameter Description
pURL (optional) Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used

Returns

A string. The parameters part of the URL (ie everything after the ? character. If there are not parameters in the URL then a blank string is returned. The leading ? character is not included in the returned value. The current string value is not altered by this method.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm?user=charles&uid=1')
parameters = str.UrlParametersOnly() ! parameters = 'user=charles&uid=1'

str.setvalue('www.capesoft.com')
parameters = str.UrlParametersOnly() ! parameters = ''

See Also

UrlProtocolOnly, UrlHostOnly, UrlPortOnly, UrlPathOnly, UrlFileOnly , UrlParameter

UrlPathOnly

UrlPathOnly (<string pURL>, Long pIncludeFile=true)

Description

Extracts the URL part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
urlpath or urlpath/file is returned.

Parameters
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.

Returns

A string. The path part of the URL. If the path is omitted from the URL then a blank string is returned. The leading / part, and trailing / part, of the path is not included in the returned value. The current string value is not altered by this method.

If the pIncludeFile parameter is true then

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
urlpath = str.UrlPathOnly() ! url = 'accessories/index.htm'

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
urlpath = str.UrlPathOnly( , false) ! url = 'accessories'

str.setvalue('www.capesoft.com/index.htm')
urlpath = str.UrlPathOnly() ! url = 'index.htm'

str.setvalue('www.capesoft.com/index.htm')
urlpath = str.UrlPathOnly(, false) ! url = ''

See Also

UrlProtocolOnly, UrlHostOnly, UrlPortOnly, UrlFileOnly, UrlParametersOnly

UrlPortOnly

UrlPortOnly (<string pURL>)

Description

Extracts the port part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
port is returned.

Parameters
Parameter Description
pURL (optional) Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used

Returns

A Long. The port part of the URL. If the port is omitted from the url then a 0 is returned. The leading : part of the port is not included in the returned value. The current string value is not altered by this method.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
port = str.UrlPortOnly() ! port = 80

str.setvalue('www.capesoft.com')
port = str.UrlPortOnly() ! port = 0


See Also

UrlProtocolOnly, UrlHostOnly, UrlPathOnly, UrlFileOnly, UrlParametersOnly

UrlProtocolOnly

UrlProtocolOnly (<string pURL>)

Description

Extracts the protocol part of a fully qualified URL. So given a string of the form
protocol://host:port/urlpath/file?parameters
protocol is returned.

Parameters
Parameter Description
pURL (optional) Contains the full URL to parse. If omitted, or blank, then the current contents of the string are used

Returns

A string. The protocol part of the URL. If the protocol is omitted from the url then a blank string is returned. The trailing :// part of the protocol is not included in the returned value. The current string value is not altered by this method.

Examples

str.setvalue('https://www.capesoft.com:80/accessories/index.htm')
protocol = str.UrlProtocolOnly() ! protocol = 'http'

str.setvalue('www.capesoft.com')
protocol = str.UrlProtocolOnly() ! protocol = ''

See Also

UrlHostOnly, UrlPortOnly, UrlPathOnly, UrlFileOnly, UrlParametersOnly

Word

Description

this method has been deprecated and removed from the class because of a name clash with the WORD EQUATE declared in some files. Use the GetWord method instead.

WordEnd

WordEnd (long pStartPos=1, long textType=ST:TEXT,<String pCharlist>)

Description

Returns the end position of the word when passed the start position. Returns 0 if the start position is invalid. Returns the position of the final character in the string if no white space is found before the end of the string. Also supports searching within a HTML string (handles escaped characters etc.). Note for HTML this won't skip over HTML tags, that needs to be handled by the caller.
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 '&nbsp;' 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 and
'. ,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:CONTROLCHARS

Return Value

Returns the end position of the word when passed the start position. Returns 0 if the start position is invalid.
If the position is not in a word (ie it's already on punctuation) then 0 is returned.
Returns the position of the final character in the string if the no white space is found before the end of the string.

Example
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))
See Also

WordStart, CountWords

WordStart

WordStart (long StartPos=1, long textType=ST:TEXT, Long Dir=1,<String pCharlist>)

Description

Find the start of the next word in the string from the passed starting position. Also supports searching within data from an HTML string (handles escaped character etc.). Note for HTML this won't skip over HTML tags, that needs to be handled by the caller.

Parameters
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 '&nbsp;' 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
Return Value

Returns the start position of the next word.
Returns zero if no word is found, or if the passed pStartPos is greater than the length of the string.

Example
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))
See Also

WordEnd, CountWords , SplitIntoWords, GetWord

WrapText

WrapText (long wrapAt=80, bool keepExistingBreaks=true, bool pleft=false)

Description

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.

Wrapping adds CR/LF characters to the string at the appropriate places. Using the Split method using <13,10> as the split text allows you to extract the individual lines.

Parameters
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.
Return Value

None. The contents of the object are changed by the addition of CR and LF characters.

See Also

Split

XMLDecode

XMLDecode()

Description

Decodes a string that has previously been encoded into the XML format. The &, ", ' , < and > characters are decoded from &amp;, &quot; &apos; &lt; and &gt; respectively.

Return Value

Returns nothing. The current string is altered by this method.

See Also

XMLEncode

XMLEncode

XMLEncode(Long pOptions=0)

Description

Encodes a string so it is a valid XML string which can be used in an XML file. XML reserved characters (&, <, ", ' and >) are encoded.

Parameters
Parameter Description
Options (optional) Reserved for future use.

Return Value

Returns nothing. The current string is altered by this method.

See Also

XMLDecode

Split, manipulate, and Join strings


The following methods are provided to split a string into parts, manipulate the parts, then (optionally) join the string back together again. This is a powerful way to take a string and manipulate the various parts of the string.

AddLine

AddLine (long LineNumber, String Value)

Description

Adds the value od the string to the queue, at the specific line number. Lines after this line are moved down by one. If the LineNumber parameter is greater than the lines in the queue, then the line is added to the bottom of the queue.

DeleteLine

DeleteLine (long LineNumber)

Description

The line at the specified position is deleted. All lines after that line are moved up in the queue by one position. The function returns true if the line specified does not exist, or false otherwise.

FreeLines

FreeLines ()

Description

A method used to free the the Lines Queue populated by the Split command. This safely, and without leaking memory, empties the existing queue of lines.
See also the Split method. Note that the Lines queue will be safely disposed when the object destructs.

See Also

Split, RemoveLines, Filter, DeleteLine

GetLine

GetLine (long LineNumber)

Description

Returns the value of a specific line in the string, after calling the Split method.

See also the Split, SetLine methods.

InLine

InLine (string SearchValue, long Step=1, long Start=1, long End=0, long Nocase=0, long WholeLine=0, Long Where=st:anywhere)

Description

Searches the split lines for a specific string. Before calling this method you need to call SPLIT to split the string into lines.

Parameters
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.

Returns

The line number of the located value. If the value is not found then it returns 0.

See also
Split, GetLine, SetLine

Split

Split (string Boundary, [String Quote],[string QuoteEnd],[RemoveQuotes = false],[Clip = false],[Left = false],[String Separator],Long Nested=false)

Description

The current string is "split" into a number of strings, which are then easily accessible in the Lines Queue. This allows for the easy parsing of "anything separated lists", for example the semi-colon separated lists used for emails, or the string returned from a multi-select FileDialog function.

Parameters
Parameter Description
boundary The Boundary parameter lets you specify the separating character.
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 endquote parameter would be )/>.

The Quote (and EndQuote) parameters are clipped. so spaces are not allowed.
QuoteEnd [optional] If the start, and end, quote strings 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.
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, 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] IIt'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.
Examples

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)

Return Value

None

Tip

It may be necessary to use the { } brackets as quote characters. In Clarion, in order to put the { character in a string, you need to type {{. Thus to split {a,b},{c,d} into two terms, the call to the Split method will be

st.split(',','{{','}')

See Also

Join, SplitEvery, SplitByMatch, SplitBetween, SplitIntoWords, GetLine, SetLine, AddLine, Records

SplitBetween

SplitBetween(string pLeft, string pRight, long  pNoCase=false, long pExclusive=true)

Description

Same as the SPLIT method, but allows text between a start and end string to be extracted.

Parameters
Parameter Description
pLeft Set this to true to do a case insensitive match.
pRight Set this to true to do a case insensitive match.
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.
Example
str.SetValue('(123)(456)(789)')
str.splitBetween('(',')')
! str getline(1) = 123
! str getline(2) = 456
! str getline(3) = 789
Returns

Nothing

See Also

Split, SplitEvery, SplitByMatch, SplitIntoWords


SplitByMatch

SplitByMatch(string pRegEx, long pNoCase=0)

Description

Same as the SPLIT method, but allows the break to be done using a regular expression.

Parameters
Parameter Description
pRegEx  A regular expression that indicates the boundary between the lines.
pNoCase Set this to true to do a case insensitive match.
Returns

Nothing

See Also

Split, SplitEvery, SplitBetween, SplitIntoWords


SplitEvery

SplitEvery (long numChars)

Description

Splits the string in numChars lengths and stores each new substring as a line in the self.lines queue.

If the string is shorter than numChars then a single "line" entry is added which contains the string. If the string is not an exact multiple of numChars then the last substring split contains however many characters remain.

Parameters
Parameter DDescription
numChars The number of characters that each new substring should contain, i.e. the length to split the string up using
Returns

None

See Also

Split, SplitByMatch, SplitBetween, SplitIntoWords

SplitIntoWords

SplitIntoWords(long StartPos = 1, long TextType=ST:TEXT, <String pCharlist>)

Description

Splits the string into words and stores each new word as a line in the self.lines queue.

Only the words are added to the queue, not the word separators, or punctuation, so the lines cannot be JOINed together to create the original string again.

Parameters
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 '&nbsp;' 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.
Returns

None

See Also

Split, SplitEvery, SplitByMatch, SplitBetween, WordStart

Join

Join (String Boundary, [String Quote],[string QuoteEnd], [AlwaysQuote])

Description

The opposite of the Split method. The current string value is cleared. The string is then constructed from the parts in the Lines Queue. The result is placed in the current value.
Each line is separated from the others using the Boundary parameter.

If a Quote parameter is used, and a line contains the boundary character(s), then the line will be prefixed by the Quote parameter (if it isn't already). The line will also be ended by either the QuoteEnd parameter (if it exists) or the Quote Parameter. If the

Parameters
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.

Returns

Nothing.   The Lines Queue remains as-is after this call. It is not cleared. The Object is updated to contain the concatenated lines.

See also

Split, SplitEvery, Records

RemoveLines

RemoveLines ([string Alphabet])

Description

This method works on the Lines created by the Split method.  It removes empty lines from the queue (allowing you to specify which characters are included in the definition of emptyness.)
 
Parameters
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
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.

Returns

The number of lines removed.

See also

FreeLines, Filter

Records

Records ()

Description

Returns the number of lines parsed after a call to the Split method.

See also

Split

SetLine

SetLine (long LineNumber, String Value)

Description

Sets the value of a specific line in the string, usually after calling the Split method. If the line does not exist, then the string is added at the end of the queue (ie in the next available line.)

See also

Split, GetLine methods.

Sort

Sort (Long SortType)

Description

Note this method is only available in Clarion 6.3 (build 9050 and later.)

Sorts the lines, created by the Split method. Three sorts are offered, case sensitive, case insensitive and length.

Parameters
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)
See also

Split, GetLine, Sort methods.

Filter

Filter (string Include, string Exclude)

Description

This method works on the Lines created by the Split method. It allows you to delete some of the lines, based on an Instring of that line. It is possible to specify both an include, and an exclude at the same time.

Parameters
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.

 See Also

RemoveLines

Formating and Deformating

Converting Strings between raw data and display using display pictures.

DeformatTime

DeformatTime ([String Value])

Description

An incoming string value, representing time in "human" terms is converted to a standard Clarion time value, suitable for storing in a LONG. Note that a time picture is not needed here. The method will determine the incoming picture and will deformat it appropriately.

Parameters
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.
Return Value

If the Value parameter is omitted then nothing is returned.
If a value is provided then the Clarion number is returned.

See Also

IsTime,FormatTime

FormatTime

FormatTime ([Long Value],String Format)

Description

An incoming Clarion standard time value is converted to a human-readable format. The format parameter is required to determine the exact human-readable form of the time.
Support for a time value > 23:59:59 is supported (for totalling hours, etc).

Parameters
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
   

Return Value

If the Value parameter is omitted then nothing is returned.
If a value is provided then the Clarion number is returned.

See Also

IsTime,DeformatTime

Base Conversion, Hexadecimal Encoding and Byte Ordering

The following methods are provided to convert numbers between bases. Frequently used bases include 2 (binary) and 10 (decimal) and 16 (hexadecimal)

ToHex

ToHex (Long pCase=ST:LOWER, pSpacer=false )

Description

Converts the stored string to a hexadecimal string. Each byte is converted to two characters which represent the value of that byte (0 to 255). For example 'Hello World' would be encoded to: '48656c6c6f20576f726c64'. This is generally used for encoding small amounts of binary data in a human legible form (for example the value of a hash).

Parameters
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.
Examples

str.SetValue('Hello World')
str.ToHex(st:lower,false) ! str now contains 48656c6c6f20576f726c64

str.SetValue('Hello World')
str.ToHex(st:lower,true) ! str now contains 48 65 6c 6c 6f 20 57 6f 72 6c 64

Return Value

The method returns nothing, the current contents of the string are altered.

See Also

FromHex

FromHex

FromHex ()

Description

Converts the stored string from hexadecimal encoding back to the original value. Every two characters in the string represent the value of a byte (0 to 255).

Any characters in the string which are not Hex characters are simply discarded from the conversion. So any separator etc will be ignored.

Parameters

There are no parameters. The current contents of the string are used as input.

Examples

str.setvalue('48656c6c6f20576f726c64')
str.FromHex() ! str now contains 'Hello World'

str.setvalue('48 65 6c 6c 6f 20 57 6f 72 6c 64')
str.FromHex() ! str now contains 'Hello World'

Returns

Nothing. The current contents of the string are changed to contain the decoded value.

See Also

ToHex

Base conversion

DecToBase

DecToBase (long num, long base=16, long lowerCase=1)

Description

Converts a decimal number to a number using the specified base (such as Hexadecimal - base 16).

Returns

The number is returned as a string of ASCII characters representing the number in the specified base. For example passed 255 will return 'ff'.

 

BaseToDec

BaseToDec Procedure (string num, long base=16)

Description

Converts the string of characters representing a number in a base other than 10 to a decimal and returns a long that contains the value.
The method is case insensitive. Supports bases from 2 to 36. "Out of range" digits, including spaces, commas and periods are ignored.

Returns

For example passed 'ff' will return 255 when the base is set to 16 (hexadecimal).

Byte based conversion to hex

ByteToHex

ByteToHex (byte pByte), string, virtual

Converts a byte to a two character string that contains the hexadecimal equivalent of the byte value. For example a byte that contains 255 would return 'ff'.

Parameters
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.
Return Value

Returns string which contains the hexadecimal equivalent of the passed value.

LongToHex

LongToHex (long pLong), string, virtual

Description

Converts a long integer (4 bytes) to a hexadecimal string. Returns a string that contains the hexadecimal of each byte in big endian order (the most significant byte first).

For example:

The value 255 would be stored as four bytes with the decimal values: 00 00 00 255, and the hexadecimal values: 00 00 00 FF; and LongToHex would return the string: '000000ff'.

12 128 72 57, the hexadecimal values: 0C 80 48 39; and LongToHex would return a string: '0c804839'

Parameters
Parameter Description
pLong A long that contains the value to convert to a hexadecimal string.
Return Value

Returns a string that contains the hexadecimal representation of the number passed. The string returned will always be 8 characters (bytes) long as each byte in the passed integer is presented by a pair of characters.
Examples
Example 
st         StringTheory
  code
    Message('255 -> ' & st.LongToHex(255) & ', 209733689 -> ' &
    st.LongToHex(209733689 ))

    ! Displays:
	! 255 -> 000000ff, 209733689 -> 0c804839

StringToHex

StringToHex (string binData, Long pLen=0, Long pCase=0)

Description

Returns a string containing ASCII characters representing the hexadecimal values of each byte in the input string. This can be used to encode binary (or any other data) in a form that only uses ASCII text and is suitable for display. The returned string is twice the size of the original, so for more efficient encoding use the Base64 encoding methods.

Parameters
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.

Important: You must dispose the returned string once it is not longer needed in order to avoid leaking memory. For this reason this method should only be used in special cases. For most situations using the ToHex method would be a better choice.

See Also

ToHex

HexToString

HexToString (string hexData), *string, virtual

Description

Returns a string containing the original data after decoding the input string of pairs of ASCII characters representing the hexadecimal value of each of the bytes in the output string.

Important: You must dispose the returned string once it is not longer needed in order to avoid leaking memory.

BigEndian

BigEndian (ulong x), ulong, virtual

Description

This method works on a long. To change the current string to big endian byte order see BigEndian.

Returns a Big Endian long when passed a Little Endian one (the byte order is reversed).

"Little Endian" means that the low-order byte of the number is stored in memory at the lowest address (first), and the high-order byte at the highest address (last). The little end comes first. "Big Endian" means that the high-order byte of the number is stored in memory at the lowest address (first), and the low-order byte at the highest address (last). The big end comes first.
Parameters
Parameter Description
x The number to convert from Little Endian to Big Endian byte order
Return Value

Returns a ulong that contains the bytes in the opposite order to those in the passed parameter.

See Also

LittleEndian, ReverseByteOrder

LittleEndian

LittleEndian (ulong x), ulong, virtual

Description

This method works on a long. To change the current string to little endian byte order see LittleEndian.

Returns a Little Endian long when passed a Big Endian one (the byte order is reversed).

"Little Endian" means that the low-order byte of the number is stored in memory at the lowest address (first), and the high-order byte at the highest address (last). The little end comes first. "Big Endian" means that the high-order byte of the number is stored in memory at the lowest address (first), and the low-order byte at the highest address (last). The big end comes first.

Parameters
Parameter Description
x The integer to convert to Little Endian
Return Value

Returns a ulong that contains the bytes in the opposite order to those in the passed parameter.

See Also

BigEndian, ReverseByteOrder

ReverseByteOrder

ReverseByteOrder (), virtual

Reverses the byte order of the string being stored. The entire string is reversed, so '123456ABC' would become 'CBA6543321'. This is useful when transferring data between systems which stored the bytes in different orders (such as certain file formats, operating systems, network protocol, cryptography etc.).

Parameters

None

Return Value

None

See Also

BigEndian, LittleEndian

Unicode Encoding, Conversion and Handling

The following methods provide handling for Unicode text, conversion between encoding types, and conversion between ANSI and Unicode text.

ToAnsi

ToAnsi (long encoding=0, [ulong CodePage], [Long pBlockSize]), long, proc

Description

Converts the current Unicode (UTF-8 or UTF-16) string to ANSI. If the encoding parameter 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)
Parameters
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.
Return Value

Returns True (1) for success and False (0) for failure.

See Also

ToUnicode

ToUnicode

ToUnicode Procedure (long encoding =st:EncodeUtf8, [ulong CodePage]), long, proc

Description

Converts the current string to Unicode format (UTF-8 or UTF-16 ).
The current string can be ANSI or a Unicode format.

Supported encoding types for the encoding parameter are:

st:EncodeUtf8 equate(1)
st:EncodeUtf16 equate(2)

Parameters
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.
Return Value

Returns True (1) for success and False (0) for failure. If an error occurs then the ErrorTrap method is called with additional information.

See Also

ToAnsi

Conversion between ANSI and UTF-16

AnsiToUtf16

AnsiToUtf16 Procedure(*string strAnsi, *long unicodeChars, ulong codepage=st:CP_US_ASCII), *string

Converts a standard ANSI string to a UTF-16 encoded Unicode string. Note that the converted string uses 16 bits (two bytes) per character. The unicodeChars parameter is set t the number of characters returned - this is not the number of bytes in the returned string (the Unicode string uses two bytes per character with UTF-16 encoding).

Parameters
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.
Return Value

Returns a pointer to a string that contains the Unicode text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string to ensure that the application does not leak memory!

Examples
Example 
st           StringTheory
ansiText     string(255)
unicodeText  &string
unicodeLen   long
  code
  ansiText = 'Hello World'
  unicodeText &= st.AnsiToUtf16(ansiText, unicodeLen)
  ! Use the unicodeText and then Dispose it once done:
  Dispose(unicodeText)

Utf16ToAnsi

Utf16ToAnsi (*string unicodeString, *long ansiLen, long unicodeChars=-1, ulong codepage=st:CP_US_ASCII), *string

Description

Converts a UTF-16 encoded Unicode string to a ANSI string.

Parameters
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.
Return Value

Returns a pointer to a string which contains the ANSI text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string to ensure that the application does not leak memory!

Examples
Example 
st           StringTheory
ansiText     &string
ansiLen      long
code
  ansiText &= st.Utf16ToAnsi(unicodeText, ansiLen)
  ! Use the ansiText and then Dispose it once done:
  Dispose(ansiText)

Conversion between UTF-8 and UTF-16

Utf8To16

Utf8To16 Procedure (*string strUtf8, *long unicodeChars), *string

Description

Converts the passed UTF-8 string to UTF-16 and returns a string that contains the new UTF-16 encoded Unicode text.

Parameters
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.
Return Value

Returns a pointer to a string which contains the UTF-16 Unicode text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string to ensure that the application does not leak memory!

Utf16To8

Utf16To8 Procedure (*string unicodeString, *long utf8Len, long unicodeChars=-1), *string

Description

Converts the passed UTF-16 encoded text to UTF-8 encoding.

Parameters
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.
Return Value

Returns a pointer to a string which contains the UTF-8 Unicode text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string to ensure that the application does not leak memory!

Utf16ToUtf8Char

Utf16ToUtf8CharProcedure (String p_utf16Char,*Long rLen),string

Description

Converts the passed UTF-16 encoded text to UTF-8 encoding.

Parameters
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
Return Value

Returns a string of 1,2 or 3 bytes long which contains the same character but in utf-8 format, not utf-16 format.

Conversion between ANSI and UTF-8

Utf8ToAnsi

Utf8ToAnsi (*string strUtf8, *long ansiLen, [ulong CodePage]), *string, virtual

Description

Convert the UTF-8 string to an ANSI string

Parameters
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.
Return Value

Returns a pointer to a string which contains the standard ANSI text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string to ensure that the application does not leak memory!

AnsiToUtf8

AnsiToUtf8 Procedure (*string strAnsi, *long utf8Len, [ulong CodePage]), *string, virtual

Description

Convert ANSI encoded text to UTF-8 encoded Unicode text

Parameters
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.
Return Value

A pointer to a string that contains the UTF-8 encoded Unicode text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string.

BigEndian

BigEndian()

Description

This method works on a string. To change a Long to big endian byte order see BigEndian.

If the current string is encoded as utf-16, then ensures that the string is in Big-Endian order. Windows uses little endian, however it may be necessary to swap the byte order if communicating with a program that requires BigEndian strings.

If the incoming string has a byte-order-mark then the current encoding can be set from this mark. This is done automatically by SetEncodingFromBOM when the LoadFile, ToUnicode or ToAnsi methods are used, however if a string comes from another source then this will need to be done manually.

If the string is already in BigEndian mode then the string is left unaltered. If the string is not currently marked as being utf-16 encoded, then the string is unaltered.

Return Value

Nothing

See Also

LittleEndian, SetEncodingFromBOM, AddBOM

DecodeHexInline

DecodeHexInline Procedure ([string pId, Long pLength], [ulong pCodePage]), *string, virtual

Description

Converts an ANSI string, containing encoded unicode characters, to an ANSI string of the specified code page, where the characters are decoded.

Parameters
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.

Example
str.SetValue('\x41zi\u00ebhavenweg')
str.DecodeHexInline(st:CP_WINDOWS_1250) ! string value is now Aziëhavenweg

In the above example \x precedes a 2 digit hex code (41) which is the ANSI character A.
\u precedes a 4 character hex code (00EB) which when converted to ANSI, using code page Windows-1250 is the character ë.

Return Value

A pointer to a string that contains the UTF-8 encoded Unicode text if successful and Null if it fails.

Important: The caller is responsible for disposing the returned string.

LittleEndian

LittleEndian()

Description

This method works on a string. To change a Long to little endian byte order see LittleEndian.

If the current string is encoded as utf-16, then ensures that the string is in Little-Endian order. Windows uses little endian for all APIs.

If the incoming string has a byte-order-mark then the current encoding can be set from this mark. This is done automatically by SetEncodingFromBOM when the LoadFile, ToUnicode or ToAnsi methods are used, however if a string comes from another source then this will need to be done manually.

If the string is already in LittleEndian mode then the string is left unaltered. If the string is not currently marked as being utf-16 encoded, then the string is unaltered.

Return Value

Nothing

See Also

BigEndian, SetEncodingFromBOM, AddBOM

StringTheory Property Reference

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.

StringPicture Class

StringPicture Class Reference Introduction

Clarion uses format strings when displaying data on the screen or on a report. These format strings are known as PICTURES. A variety of picture types exist, including pictures for Dates, Times, Numbers and so on. These format strings are used by the Clarion FORMAT and DEFORMAT commands.

In order to manipulate pictures in code it is necessary to be able to parse a picture into it's component parts, examine or alter each part, and then recombine the parts to the format string. This class assists in performing these functions.

Using StringPicture

Two primary methods, ParsePicture and CreatePicture are used to parse an existing picture into parts, or to create a picture from parts. Each picture type supports a number of properties. A typical use-case might be to parse a picture simply to know what the picture consists of. Another use case might be to parse a picture, change an element, and then put the picture back together again.

Note that this class is not designed to explicitly validate a picture. It is assumed that the passed picture is valid, although invalid pictures can be detected in most cases by comparing the result of CreatePicture to the original picture (taking case sensitivity into account.)

Example

Consider the picture @N-10.2
this displays a number, with a leading - sign (if the value is negative.)
To change this picture to surrounding negative numbers in brackets, you would do something like this;

spic  StringPicture
  code
  spic.ParsePicture('@N-10.2')
  spic.SignBefore = '('
  spic.SignAfter = ')'
  result = spic.CreatePicture('N')

StringPicture Method Reference

CreatePicture Create a Clarion picture from the current properties.
ParsePicture Parse a picture string into its component parts

CreatePicture

CreatePicture(String pType)

Description

Takes the current properties, and constructs a Clarion picture from them.

Parameters
Parameter Description
pType Indicates the type of picture desired and hence the properties that will be used to create the picture.
Valid options are S, D, T, N, E, P or K.

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.)
Return Value

Returns the Clarion picture. The picture is also placed in the pic property for later use if desired.

See also

ParsePicture

ParsePicture

ParsePicture(<String pPic>)

Description

Takes a Clarion picture and parses it into its component parts. These parts are then made available as properties. The exact properties used varies from one picture type to the next.

Parameters
Parameter Description
pPic The Clarion picture to parse. If omitted then the current value in the pic property is parsed.
Return Value

Returns st:ok if the string contains a picture. Return st:notOk otherwise.

See also

CreatePicture

StringPicture Properties

Date Pictures
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, hypen,  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.
Key-In Pictures
Pattern String(255) The Key-In pattern.
B String(1) If set to 'B' then the field is blank if zero.
Number and Currency 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.
Pattern Pictures
Pattern String(255) The pattern.
B String(1) If set to 'B' then the field is blank if zero.
Scientific Pictures
m String(6) A number, containing the number of characters in the formatted string.
s String(2) The Decimal Separator and Grouping character.
n String(6 The number of digits after the decimal separator.
B String(1) If set to 'B' or 'b' then the field is blank if zero.
String Pictures
Length String(4) A number, containing the number of characters in the formatted string.
Time Pictures
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, hypen,  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 /.
B String(1) If set to 'B' or 'b' then the field is blank if zero.

Support

This template is copyright © 2010-2018 by CapeSoft Software. 

Your questions, comments and suggestions are welcome.  You can also contact us in one of the following ways:
CapeSoft Support
Email
Telephone +27 87 828 0123

History

If you are upgrading from StringTheory 1.xx then be sure to read Upgrading.

This document is for StringTheory 2. For StringTheory 3 History see here.

Version 2.91 25 May 2021 Version 2.90 28 November 2018 Version 2.89 12 November 2018 Version 2.88 1 November 2018 Version 2.87 16 October 2018 Version 2.86 13 September 2018 Version 2.85 5 September 2018 Version 2.84 31 July 2018 Version 2.83 27 July 2018 Version 2.82 24 July 2018 Version 2.81 28 June 2018 Version 2.80 13 June 2018 Version 2.79 1 June 2018 Version 2.78 14 May 2018 Version 2.77 26 April 2018 Version 2.76  25 April 2018 Version 2.75  24 April 2018 Version 2.74  19 March 2018 Version 2.73  2 March 2018 Version 2.72  1 February 2018 Version 2.71  15 January 2018 Version 2.70  10 January 2018 Version 2.69  10 January 2018 Version 2.68  9 January 2018 Version 2.67  30 November 2017 Version 2.66  6 September 2017 Version 2.64  23 August 2017

Thanks to Geoff Robinson who contributed many of the changes in this release. Version 2.63  27 July 2017 Version 2.62  7 June 2017 Version 2.61  31 May 2017 Version 2.60  15 May 2017 Version 2.59  12 May 2017 Version 2.58  11 April 2017 Version 2.57  2 March 2017 Version 2.56  22 February 2017 Version 2.55  21 February 2017 Version 2.54  6 February 2017 Version 2.53  3 January 2017 Version 2.52  19 December 2016 Version 2.51  27 October 2016 Version 2.50  16 September 2016 Version 2.49  7 September 2016 Version 2.48  30 August 2016 Version 2.47 5 August 2016 Version 2.46 7 July 2016 Version 2.45 6 July 2016 Version 2.44 29 April 2016 Version 2.43 29 November 2015 Version 2.42 23 November 2015 Version 2.41 13 November 2015 Version 2.40 4 November 2015 Version 2.39 3 November 2015 Version 2.38 15 September 2015 Version 2.37 10 September 2015 Version 2.36 29 August 2015 Version 2.35 13 August 2015 Version 2.34 28 July 2015 Version 2.33 24 July 2015 Version 2.32 15 July 2015 Version 2.31 14 July 2015 Version 2.30 9 July 2015 Version 2.29 30 June 2015 Version 2.28 19 June 2015 Version 2.27 16 June 2015 Version 2.26 19 May 2015 Version 2.25 18 May 2015 Version 2.24 15 May 2015 Version 2.23 14 May 2015 Version 2.22 4 May 2015 Version 2.21 7 April 2015 Version 2.20 7 April 2015 Version 2.19 24 March 2015 Version 2.18 23 March 2015 Version 2.17 20 March 2015 Version 2.16 19 March 2015 Version 2.15 25 February 2015 Version 2.14 5 January 2015 Version 2.13 1 December 2014 Version 2.12 29 November 2014 Version 2.11 27 November 2014 Version 2.10 25 November 2014 Version 2.09 1 September 2014 Version 2.08 30 June 2014
Version 2.07 29 May 2014 Version 2.06 26 May 2014
Version 2.05 15 May 2014
Most changes in this build courtesy of Geoff Robinson Version 2.04 20 March 2014
Some changes in this build courtesy of Geoff Robinson Version 2.03 14 March 2014 Version 2.02 11 March 2014 Version 2.01 10 March 2014 Version 2.00 27 February 2014
Some changes in this build courtesy of Geoff Robinson Version 1.97 10 February 2014 Version 1.96 31 January 2014 Version 1.95 21 January 2014 Version 1.94 13 January 2014 Version 1.93 14 November 2013 Version 1.92 12 August 2013
Version 1.91 10 July 2013 Version 1.90 20 June 2013 Version 1.89- 10 June 2013 Version 1.88- 30 May 2013 Version 1.87 - 27 May 2013 Version 1.86 - 22 May 2013 Version 1.85 - 9 May 2013 Version 1.84 - 2 May 2013 Version 1.83 - 2 May 2013 Version 1.82 - 1 May 2013 Version 1.81 - 29 April 2013 Version 1.80 - 25 April 2013 Version 1.79 - 23 April 2013 Version 1.78 - 14 March 2013 Version 1.77 - 7 March 2013 Version 1.76 - 27 February 2013 Version 1.75 - 21 February 2013 Version 1.74 - 20 February 2013 Version 1.73 - 15 February 2013 Version 1.72 - 25 January 2013 Version 1.71 - 3 January 2013 Version 1.70 - 27 December 2012 Version 1.69 - 10 December 2012 Version 1.68 - 20 November 2012 Version 1.67 - 12 November 2012 Version 1.66 - 2 November 2012 Version 1.65 - 31 October 2012 Version 1.64 - 12 October 2012 Version 1.63 - 27 August 2012 Version 1.62 - 20 July 2012 Version 1.61 - 19 June 2012 Version 1.60 - 24 May 2012 Version 1.59 - 14 May 2012 Version 1.58 - 25 April 2012 Version 1.57 - 17 April 2012 Version 1.56 - 20 February 2012 Version 1.55 - 15 February 2012 Version 1.54 - 12 January 2012 Version 1.53 - 4 January 2012 Version 1.52 - 22 November 2011 Version 1.51 - 9 November 2011 Version 1.50 - 16 September 2011

Required for CryptoNite 1.1.8 and up Version 1.45 - 20 August 2011

Required for CryptoNite 1.1.8 and up Version 1.44 - 20 August 2011

Required for CryptoNite 1.1.8 and up Version 1.43 - 19 August 2011

Required for CryptoNite 1.1.8 and up Version 1.42 - 02 August 2011

Required for CryptoNite 1.1.8 and up Version 1.41 - 27 July 2011

Required for CryptoNite 1.1.8 and up Version 1.40 - 18 July 2011

Required for CryptoNite 1.1.8 and up Version 1.39 - 07 June 2011

Required for CryptoNite 1.1.8 and up Version 1.38 - 06 June 2011

Required for CryptoNite 1.1.8 and up Version 1.37 - 03 June 2011

Required for CryptoNite 1.1.8 and up Version 1.36 - 5 May 2011 Version 1.35 - 15 April 2011

Required for CryptoNite 1.15 and up Version 1.34 - 15 April 2011

Required for CryptoNite 1.15 and up Version 1.33 - 29 March 2011

Required for CryptoNite 1.12 and up Version 1.32 - 19 January 2011

Required for CryptoNite 1.12 and up Version 1.31 - 18 January 2011

Required for CryptoNite 1.04 and up Version 1.30 - 21 December 2010

Required for CryptoNite 1.04 Version 1.29 - 10 December 2010

Required for CryptoNite 1.11 Version 1.28 - 27 November 2010 Version 1.27 - 27 October 2010

Required for CryptoNite 1.03 Version 1.26 - 15 June 2010

Required for CryptoNite 1.02 Version 1.25 - 22 September June 2010 Version 1.24 and prior (not available as a stand alone product) - 15 June 2010