CapeSoft.Com
Clarion Accessories
StringTheory
Documentation
Download Latest Version Index FAQ History Classes Methods Extended Pictures
CapeSoft Logo

CapeSoft StringTheory
Documentation

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.

Copyright And License

This product is copyright 2010-2024 by CapeSoft Software. It is based on work by Rick Martin, published in ClarionMag, and used with permission.

This product is provided as-is. CapeSoft Software and CapeSoft Electronics (collectively trading as CapeSoft), their employees and dealers explicitly accept no liability for any loss or damages which may occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Use of this product implies your acceptance of this, along with the recognition of the copyright stated above. In no way will CapeSoft , their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

For the full EULA see https://capesoft.com/eula.html

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

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 https://www.winimage.com/zLibDll/index.html. The Zlib library home can be found here https://www.zlib.net.
.

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()


Streaming to a Disk file (Write-Caching)

One common use for StringTheory is to collect text into one place, before writing it to disk. While this is very fast, it incurs the memory overhead of the whole disk file - in other words the string is first accumulated in memory, then sent to the disk in a single lump. In situations where memory is constrained, this may be undesirable.

To overcome this memory constraint, it is possible to use the STREAM method.

A stream can be thought of as a disk write-cache which accumulates data, so that a reasonable amount is accumulated before writing to disk (to optimize disk write time) but at the same time automatically flushes the string to disk as it grows larger, so as not to consume too much memory.

Naturally the operations you can perform on a stream are limited. Since the string is not "in memory" but rather being written away to the disk, it is not possible to manipulate the string after it has been added to the stream (except to add more data to the stream.)

The primary method for streaming is STREAM. This method takes the name of the disk file, as well as optionally the size of the cache (defaults to 10 Megabytes). So unlike the SaveFile method (which takes the name at the end of the string construction), the Streaming approach takes the name at the start of the string construction.

If there is data in the object when STREAM is called, then it is included in the stream.

Should you wish to manually flush the cache to the actual disk, then the FLUSH command can be used. You do not need to manually call this command, it will be automatically called for you when the data in the cache exceeds the cache size.

Calling the Free method, or if the object goes out of scope, will also automatically trigger a Flush.

Automatic Flush Triggers

The following actions will automatically flush the cache to the disk;
  • A call to SetValue
  • A call to SetValueByAddress
  • A call to Stream (to a different filename)
  • A call to Append, FromBlob, Cat or CatAddr which would result in the cache size being exceeded
  • A call to the Start method. This will also terminate the streaming.
  • A call to the Free method. If the Force parameter is True, then Streaming will also be terminated.
  • If the object goes out of scope, then the DESTRUCT method is automatically called. This will trigger a FLUSH before the object disappears.

NoStream

Calling the NOSTREAM method does NOT call the FLUSH method. Using this method leaves the contents of the object unaltered, but immediately turns off further streaming to the disk file. The current contents of the object are not written to disk.

Undefined Behaviors

Generally speaking calling a method, not listed above, on a stream is generally inadvisable. All methods not listed should be considered to have undefined behavior, that may change without notice. If other methods are required it is recommended to first FLUSH the object, then call NOSTREAM, and then treat the object as normal. To recommence streaming call STREAM again. (Note that calling STREAM on an object with existing data DOES include that existing data in the stream.)

Show a Directory Listing in a Text Control

Clarion has a DIRECTORY function which reads the contents of a directory listing into a queue. To display this queue on the screen, a string needs to be constructed. StringTheory has a method called SerializeQueue which makes this easy to do.

DIRECTORY(FilesQ,'C:\Clarion11\Bin\Cla*.DLL',ff_:NORMAL)
str.SerializeQueue(FilesQ,'<13,10>', ',', '"')
str.Prepend('File Name,Short,Date,Time,Size,Attrib<13,10>')
?TextControl{prop:value} = str.GetValue()

The output looks something like this;

File Name,Short,Date,Time,Size,Attrib
ClaADO.dll,ClaADO.dll,80022,4863701,54808,32
Claapp.dll,Claapp.dll,80022,3899601,57856,32
ClaASC.dll,ClaASC.dll,80022,4864001,75288,32
Claasl.dll,Claasl.dll,80022,4872701,339480,32
Claasm.dll,Claasm.dll,80022,3870701,68608,32

Adding a StringTheory object to a local (or global) data pad

To create a StringTheory object in your data pad;
  1. Click the Add button to add to the pad as normal
  2. Set the Data Type to TYPE
  3. Set the Base Type to StringTheory
  4. Make sure the Reference Checkbox is off
DataPad

Upgrading

As with all upgrading it matters what you are upgrading from more than what you are upgrading to. See the notes below for significant changes that will need to be applied as you upgrade from older versions of StringTheory.

From before Version 2.00

NetTalk, 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 from before Version 2.00

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

Check 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')

String Formatting

Data is often stored in a very different format to the way it is displayed, or entered, by humans. To overcome this difference data needs to be Formatted and Deformatted. Indeed this process is not only needed for humans but also oftne for cases where one program is communicating with another program. In these cases the specific formatting of the data into a very precise layout is very important.

Clarion provides two functions which are used to make this data transformation. FORMAT and DEFORMAT. Both of these functions take in a format description, known as a PICTURE, which describes to the functions the way in which the data should be (or has been) formatted.

While generally adequate for screen and report use, the current functions are limited, both in the number of data types they support, as well as the variety of pictures they support.

It should be noted that Clarion itself does not support these Extended Pictures. Therefore you cannot use these pictures to automatically format data on browses, forms and reports. You will need to use String fields in those places, formatting the data manually as appropriate for the situation.

StringTheory 3 introduces 3 new classes which make interacting with formatted, and unformatted data more powerful. This can make it easier to display, input, import and export data in more flexible ways.

Extended Pictures

The pictures supported by the Clarion FORMAT command have not been updated for many years. The StringPicture, StringFormat and StringDeformat classes extend some of the pictures, and support all-new pictures. This support can be used for displaying strings, interpreting user input, or converting values before storage. You cannot use extended pictures on Screen Entry fields.

A summary of the extensions, and new pictures, are included below.
String (@S)
@S[length] Length is considered to be optional. If omitted the passed string is returned as-is.
Length is not limited to 255 as it is by the Clarion FORMAT command.
Length can be 0 - ie @S0 is a valid picture, returning a blank string when formatted.
Pattern (@P / @K)
Use a > character in place of a < character. Three important facts conspire to cause a common programming error.

a) In the pattern # and < are used to represent required and optional digits.
b) The picture to this parameter is passed as a string.
c) In Clarion, putting << into a string results in the compiler changing this to <

Put together, this means that the picture @p<<<<p, when passed as a string actually represents 2, not 4, digits. To help avoid this error the DeformatPattern command supports the use of the > character in place of the < character in the pattern. The two characters have exactly the same meaning.
Date (@D)
Add a M to the end of any Date picture This indicates that the raw data is in Unix Epoch Datetime (milliseconds) (aka JavaScript) format rather than Clarion Long format.
Add a U to the end of any Date picture This indicates that the raw data is in Unix Epoch Datetime (seconds) format rather than Clarion Long format.
Add a L to the end of any date picture This indicates that if the value is zero, then the current local date will be used in the format. (Useful in conjunction with @U formats)
Add a T to the end of any date picture This indicates that if the value is zero, then the current UTC date will be used in the format. (Useful in conjunction with @U formats)
Alternate Separator ! Setting the separator in the picture to ! indicates that no separator should be used. In other words @D10!  is the same as @D12.
@D91 New Date Picture - yyyy/Www - where ww is the ISO 8601 Week Number
@D92 New Date Picture - Www/yyyy - where ww is the ISO 8601 Week Number
@D93 New Date Picture - yyyy/Www/d - where ww is the ISO 8601 Week Number and d is the day number.
Time (@T)
Add a M to the end of any Time picture This indicates that the raw data is in Unix Epoch Datetime (milliseconds) (aka JavaScript) format rather than Clarion Long (centiseconds) format.
Add a U to the end of any Time picture This indicates that the raw data is in Unix Epoch Datetime (seconds) format rather than Clarion Long (centiseconds) format.
Add a L to the end of any Time picture This indicates that if the value is zero, then the current local time will be used in the format. (Useful in conjunction with @U formats)
Add a T to the end of any Time picture This indicates that if the value is zero, then the current UTC time will be used in the format. (Useful in conjunction with @U formats)
Add a Z to the end of any Time picture. This indicates that the value should be rounded up by 1 hundredth of a second. In other words
FormatValue(360000,'@T1Z ') returns 1:00 instead of 0:59:59:99. This simplifies the display of "round numbers" and makes time-math easier. Is especially useful where the time is a "duration" rather than a "time of day".
@T1, @T2, @T4, @T5, @T91 support values greater than 24 hours. The standard Clarion format command allows for a maximum time of 23:59:59. This works for time-of-day, but is less suitable for time-duration. The StringFormat class allows for any time up to (plus or minus) 2 billion hours for these time pictures. A REAL data type is supported (in addition to the traditional LONG) to support very large time values.
NumberPart Because some time pictures allow for numbers greater than 23 hours, it's possible that these times could be very large. For example Accumulated-Time-Worked by a large department for a year might be thousands, or hundreds of thousands of hours. Thus the "hours" part of this time requires its own format string. This is achieve by concatenating a Numeric picture to the Time picture. For example;
@T1@N6
In this case the time will be displayed as hh,hhh:mm - the @n6 part is applied to the Hours part of the time.
@T91 New Time Picture. hh:mm:ss:cc
@T92 New Time Picture. hh:mm:ss:cc xm
@T93 New Time Picture. hh:mm:ss.mmm
@T94 New Time Picture. hh:mm:ss.mmm xm
  The Clarion FORMAT command does not include a space between the time, and the AM or PM.
However using capitals, and no space, is considered poor layout by today's standards. By default the FormatClass separates the time from the am or pm with a space, and am or pm is in lower case.
TimeHours Pictures (@H)

Time pictures display time as hours, minutes and seconds. Number pictures display a numeric value.

TimeHours pictures behave exactly as Number pictures, except that the value is divided by 360000 (1 standard Clarion hour). In other words TimeHours pictures display Clarion Time, but as a Decimal Number.
So 2 and a half hours is 2.5 rather than 2:30.

All the format options for Numeric pictures are supported - and the behavior is exactly as for numeric pictures, but the value returned has been divided by 360000.
Unix Date & Time Pictures (@U)
@Un[S][M][D][T][@d][@t] Takes in a  Unix Epoch Datetime value (or Clarion Date / Time value) and returns a date/time stamp of the form dateTtime.

n is the picture number (1 or 2)

[S] is an optional separator character. If omitted the default is T. Use an underscore to separate the date and time with a space character.

[M] indicates the value is in Milliseconds rather than seconds. If M is included then the separator character [S] MUST be included.

[D] indicates the value is a Clarion Date rather than seconds. If D is included then the separator character [S] MUST be included. The output will treat the time part as 0.

[T] indicates the value is a Clarion Time rather than seconds. If T is included then the separator character [S] MUST be included. The output will treat the date part as 0.

The @d part of the picture refers to the picture for the date part, the @t part of the picture refers to the time part. If @d is omitted then @D010 (yyyy/mm/dd) is used. If @t is omitted then @T04 (hh:mm:ss) is used.


@U1 -- The separator has a space before and after it
@U2 -- The separator has no spaces before or after it
@U3 -- There is no separator

@U1_  - The separator is a space character
@U1x - The separator is a x character - where x is any character (except underscore or a digit)

Examples :

@U1              1970/01/01 T 00:00:00
@U2              1970/01/01T00:00:00
@U2_             1970/01/01 00:00:00
@u1@d06          01/01/1970 T 00:00:00
@u1@d6@t1        1/01/1970 T 0:00
@U2@D010-@T93Z   yyyy-mm-ddThh:mm:ss.ccc
HEX Pictures (@X)
@Xn[S][Bm] Takes in a value, and displays it as a raw hexadecimal or binary format.

X displays ABCDEF values in Capital letters.
x displays abcdef in lower case letters.

n is the number of string characters to display per line, before a line break. For example @X4 _would display as
00 00 00 00
00 00 00 00
Set n to 0 to indicate no line breaks.

[S] is an optional separator character. If omitted the default is no separator. Use an underscore to separate with a space character.

[Bm] specifies the base of the numbers to display. So to display as Binary is B2, Octal is B8, Decimal is B10 and Hexadecimal is B16.
m can be any number in the range of 2 to 36. If omitted the default value is 16 (Hexadecimal).

@X8_  - The separator is a space character
@X8x - The separator is a x character - where x is any character (except underscore)

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 https://www.zlib.net/zlib_license.html

Class Reference

Classes

StringTheory Class

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 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.)
AdjustLength Adjust the length of the string.
After Returns the rest of the string after a delimiter.
AfterLast Returns the rest of the string after the last instance of a delimiter.
AfterNth Returns the rest of the string after the nth instance of a delimiter.
All Returns the current string, repeated until the returned value is a specific length.
Append Append a value to the end of the string
AppendBinary Append a (long / short / byte) to the end of the string, but as binary characters.
Ascii85Decode, Ascii85Encode See Base85Decode and Base85Encode.
AsnDecode Take a ASN.1 Encoded value and split it into the component parts.
AsnEncode Take a string value, and encode it according to ASN.1 rules.
AsnEncodeNumber Take a number and encode it according to ASN.1 rules.
Before Returns the section of the string before a delimiter.
BeforeLast Returns the section of the string before the last instance of a delimiter.
BeforeNth Returns the section of the string before the nth instance of a delimiter.
Between Returns the string between the passed delimiters if it exists. Also see FindBetween which returns the start and end positions and allows multiple strings to be located and returned between the same delimiters .
Base32Decode Decode a string that is encoded using Base32
Base32Encode Encode the string using Base32 encoding method
Base64Decode Decode a string that is encoded using Base64
Base64Encode Encode the string using Base64 encoding method
Base85Decode
 Decode a string that is encoded using Base85 / ASCII85
Base85Encode
 Encode the string using Base85 / ASCII85 encoding method
Capitalize Capitalizes the first letter in one or more words in the string.
ChangeBase Treat the string as a number, change the base of the number.
Chars Returns the number of Characters in the string (not the number of bytes). Works for strings in ANSI, Utf-8 or Utf-16 encodings.
CharToDecEntity Converts all the characters (in a range) to the form &#nn;
CleanFileName Cleans and returns a file name with any invalid characters replaced.
Clip Clips the string (removed trailing whitespace)
ClipLength Get the length of the string, ignoring trailing spaces
ColorToHex Converts a color stored in any format to a hex string (which can be used in CSS, HTML etc.).
ColorToLong Converts a color stored in any format to a standard Clarion long color.
ContainsA Returns true if the string contains at least one character from a matching alphabet.
ContainsADigit Returns True if the string contains at least one digit character ('0' to '9')
ContainsByte Returns true if the string contains a specific ASCII Byte.
ContainsChar Returns true if the string contains a specific character.
ConvertAnsiToOem Applies the Clarion ConvertAnsiToOem function to the string.
ConvertOemToAnsi Applies the Clarion ConvertOemToAnsi function to the string.
ConvertTabs Expand tabs to the next tab point, using spaces.
Count Returns the number of times that the Search Value appears in the current string
CountWords Returns the number of words in the string. Also see WordStart and WordEnd.
Crop Removes part of the string from either the front, or rear, or both, of the string
DecEntityToChar Converts the for &#nnn; into a character.
DeformatValue
 Returns a deformatted value.
EndsWith Checks to see if the string ends with a substring.
Equals Compares one StringTheory object with another StringTheory object.
ErrorTrap Called if an OS error occurs
ExtensionOnly Splits the extension part out of a file name.
FileNameOnly Splits the file name part out of a fully qualified path name
FindBetween Finds and returns a string between the passed start and end delimiters and returns the start and end position of the string found.
FindBetweenPosition Same as FindBetween, but does not return the Substring.
FindByte Fast brute force find a single byte value
FindChar Fast brute force find a single character
FindChars Fast brute force find for a substring
FindEndOfString Finds the end of a null-terminated string.
FindLast Find the last instance of a substring in a string.
FindMatch Find a regular-expression string in the object. Returns the string found, and the position of the string in the object
FindMatchPosition The same as FindMatch, but does not return the found string (for performance reasons).
FindNth Finds the nth instance of a substring in a string.
FindWord Retrieve the word at the specified position from the string, and returns the position of the word as well.
FlexPolylineDecode Decode a string containing a Flexible Polyline Encoding
Flush Flushes a disk-write-cache to the disk. See Streaming to a Disk file (Write-Caching)
FormatHTML Format text according to HTML indenting and line ending rules.
FormatMessage Interprets the windows API error code
FormatValue Returns a formatted value.
Free Clears the string and returns all the memory used by the string
FromBlob Retrieves the data from the passed BLOB and stores it.
GetAddress Return the current address of the string in memory.
GetCodePageFromCharset Given a Clarion Charset select a code page to match.
GetValue Returns the current value of the string
GetValuePtr Returns a pointer to the current value of the string.
GetWord See Word.
GuidDecode Remove hyphens and brackets, and hex-decode a string.
GuidEncode Hex encode, and add hyphens, to a 16 character binary string.
HtmlEntityToDec Converts the form &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')
IsAllLower Returns true if value contains ONLY lower case letters (a through z). Any other characters will return false.
IsAllUpper Returns true if value contains ONLY upper case letters (A through Z). Any other characters will return false.
IsAscii Returns true if the string is blank, or only contains characters from <0> to <127>.
IsLower Returns true if value contains no upper case letters - the value would be unchanged by doing LOWER on it
IsTime Returns true if the string looks like a formatted time value.
IsUpper Returns true if value contains no lower case letters - the value would be unchanged by doing UPPER on it
IsValidUtf8 Returns true if the string is valid utf-8, false if it is not.
Join See Split, Manipulate and Join Strings
JsonDecode Converts a string that was encoded for transport in JSON format.
JsonEncode Encodes a string into JSON format, suitable for adding to a JSON packet.
KeepCharRanges Removes ll non-specified characters from the string.
KeepChars Removes all non-specified characters from the string.
Left Returns the non-space characters from the left of the string.
Length The current length of the string
LineEndings Change <13,10> to <13> or <10> or vice versa.
LoadFile Load a file off the disk into the string
LongDivision Divide any length string by a number.
Lower Change all the characters in the string to be lower case
MakeGuid Create a random string suitable for a unique identifier.
MakeGuid4 Make a binary Guid value, to conform to RFC 4122, version 4.
Match find the position of a regular expre
MatchBrackets Find the matching end bracket in a string.
MD5 Generates the MD5 Hash of a string
MergeXML Merge a new XML node into an existing XML document.
Normalize Normalizes a string reducing it to a form suitable for comparisons.
NoStream Ceases Streaming, without Flushing. See Streaming to a Disk file (Write-Caching)
PathOnly Gets the path part of a fully qualified file name
PeekRAM Debugging method to view the raw content of a variable.
Prepend Adds a sub string to the front of the string
Quote Adds the specified "quotes" to the stored (wraps the string in the passed quotes).
Random Fills the string with random characters
Remove Remove some text from the string.
RemoveAttributes Removes the attributes from an HTML tag.
RemoveByteRange Removes all specified characters from the string.
RemoveCharRanges Removes all specified characters from the string.
RemoveChars Removes all specified characters from the string.
RemoveFromPosition Removes a number of characters from a position in the string.
RemoveHTML Removes all HTML markup, leaving just the text.
RemoveXMLPrefixes Removes all prefixes from inside xml tags.
Replace Replaces one, or more, instances of the search string with a new value
ReplaceBetween Replaces one, or more, instances of the search string with a new value, if it's between known left and right strings.
ReplaceLast Replaces the last instance of a substring in a string.
ReplaceNth Replace the nth instance of a substring in a string.
ReplaceSingleChars Replaces several possible single characters, with several other possible single characters.
Reverse Reverses the contents of the string so the first byte is last and so on.
Right Returns the non-space characters from the right of the string.
SaveFile Saves the current string to disk
SeedRandom Reseeds the random number generator.
SerializeGroup Converts a group to a (something) delimited string.
SerializeQueue Converts a Queue to a (something) delimited string.
SetAfter Alters the string to text after a specific search value.
SetAfterLast Alters the string to text after the last instance of a specific search value.
SetAfterNth Alters the string to text after the nth instance of a specific search value.
SetAll Repeats the contents of the current string, until the string is a specific length.
SetBefore Alters the string to text before a specific search value.
SetBeforeLast Alters the string to text before the last instance of a specific search value.
SetBeforeNth Alters the string to text before the nth instance of a specific search value.
SetBetween Injects text into the string, or replaces text already in the string, between two boundaries.
SetDeformatValue Sets the contents of the object to a Deformatted value.
SetEncodingFromBOM After loading a file, sets the encoding property based the Byte-Order-Mark (if one exists.) Optionally removes the BOM.
SetFormatValue,  Sets the contents of the object to a formatted value.
SetLeft Removes leading spaces, and possibly limits the length of the string.
SetLength Sets the length of the string
SetRight Adds leading spaces so the string is the specified length, but has no trailing spaces.
SetValue Assigns a new value to the current string
SetValueByAddress Copies memory into the current string.
SetValueByCstringAddress set the contents of the object from ram, where the string is null terminated. either <0> or <0,0> or <0,0,0,0> depending on encoding.
SetSlice Sets the value of a substring within the stored string
Slice Returns a substring of the current string
Sort Sorts the contents of a string.
Split See Split, Manipulate and Join Strings
Squeeze Removes additional white space from between words in the string (word will be separated by only a single space after calling squeeze).
Start Reset all properties back to the default to reuse the object.
StartsWith Checks to see if the string starts with a substring.
Stream Starts a disk stream. See Streaming to a Disk file (Write-Caching)
Sub Returns a substring of the current string
Str Returns the current string and optionally stores the passed value.
Swap Swaps one object with another.
Tail Remove characters from the end of the string.
ToAnsi Converts the current Unicode (UTF-8 or UTF-16) string to ANSI
ToCString Creates a CString and copies in the current string value
ToBlob Saves the data stored by the StringTheory object in the passed BLOB.
Top Removes characters from the front of the string.
ToUnicode Converts the current ANSI string to Unicode (either UTF-8 or UTF-16)
Trace Sends a string to the DebugView program for logging
Trim Removes whitespace from the start and the end of the string
UnQuote Removes quotation marks (or the specified values) from the start and end of the string.
Upper Converts all the lower case characters to upper case
UrlEncode Method URL (percent) encodes the passed string
UrlDecode Methods decodes the passed URL (percent) encoded string.
UrlFileOnly Extracts the Filename part of a URL
UrlHostOnly Extracts the Host part of a URL
UrlParameter Returns the value of a single parameter from a URL.
UrlParametersOnly Extracts the Parameters part of a URL
UrlPathOnly Extracts the Path part of a URL
UrlPortOnly Extracts the Port part of a URL
UrlProtocolOnly Extracts the Protocol part of a URL
Word Retrieve the word at the specified position from the string.
WordEnd Returns the end position of the next word in the string given a start position to begin searching from.
WordStart Returns the start of the next word in the string given a starting position to being search from.
WrapText performs word wrapping to wrap the text to a fixed width by breaking lines as close the the specified width as possible. Lines are only broken on white space (tabs and spaces). The default wrap width is 80 characters.
XMLDecode Decodes a string that was encoded for transport in XML format.
XMLEncode Encodes a string into XML format, suitable for adding to an XML packet.
ZeroXDecode Decodes a string stored as a hex-encoded-byte-array.
ZeroXEncode Encodes a string as a hex-encoded-byte-array, consistent with C, JavaScript etc languages.
Split, manipulate and Join strings
Split Splits the string into parts based on the specified delimiters
SplitBetween Splits the string into parts based on a left and right substring.
SplitByMatch Splits the string into parts, based on a regular expression.
SplitEvery Splits the string into substrings of the specified length.
SplitIntoWords Splits the string into a queue of words.
Join Creates a string from the separate lines (where the lines are made by Split)
AddLine Adds a line to the line queue, at a specific position.
DeleteLine Deletes a line from the line queue.
FreeLines Frees the Queue populated by the Split method
GetLine Gets a specific line after a call to the Split method
GetLines Gets a group of lines after the call to the Split method.
InLine Searches the lines for a specific substring
Records Returns the number of records after a call to the Split method
RemoveLines Remove empty lines, or lines which only contain specific characters.
SetLine Sets the Value of a specific line in the queue
Sort Sorts the lines alphabetically
Filter Remove some lines, based on the presence, or absence, of a string on that line.
Formatting and Deformatting
FormatTime Formats a number (Clarion standard time) into a String
DeformatTime Formats a string into a number (Clarion Standard Time)
FormatHTML Format text according to HTML indenting and line ending rules.
Base Conversion, Hexadecimal encoding and Byte Ordering
ToHex Converts the stored string to a hex string - each bytes is converted to two characters representing the hexadecimal equivalent.
FromHex Converts a string that is encoded as a hex string back to the original value.
DecToBase Converts a decimal number to a number using the specified base (such as Hexadecimal - base 16)
BaseToDec Converts the passed number stored in a string to a decimal
ByteToHex Returns a string that contains the hexadecimal equivalent of the passed byte
LongToHex Converts a long of 4 bytes to hex. Returns a string that contains the hex of each byte in big endian order (the most significant byte first)
StringToHex Returns a string that contains the hexadecimal equivalent of each byte in the passed string (which is treated as binary data).
HexToString Decodes the passed hex string and returns a pointer to a new string that contains the unencoded data.
BigEndian Returns a big endian long when passed a little endian one
LittleEndian Returns a little endian long when passed a big endian one
SwitchEndian Switches between big endian and little endian (returns a little endian long when passed a big endian one and vice versa).
ReverseByteOrder Reverse the byte order of the stored string (the entire string is reversed).
Unicode Encoding, Conversion and Handling
ToAnsi Converts the current Unicode (UTF-8 or UTF-16) string to ANSI
ToUnicode Converts the current ANSI string to Unicode (either UTF-8 or UTF-16)
AnsiToUtf16 Converts the pass ANSI string to UTF-16 encoded Unicode
Utf16ToAnsi Converts the passed UTF-16 encoded Unicode string to ANSI
Utf8To16 Converts UTF-8 to UTF-16
Utf16To8 Converts UTF-16 to UTF-8
Utf16ToUtf8Char Converts a Utf-16 (2 byte) character to a (1 to 3 byte long) Utf-8 character
Utf8ToAnsi Converts the passed UTF-8 encoded Unicode string to ANSI
AnsiToUtf8 Converts the passed ANSI string to UTF-8 encoded Unicode
DecodeHexInline Converts text encoded with \x or \u in an ANSI string into the appropriate character
BigEndian Makes sure the string (if utf-16) is in BigEndian form.
LittleEndian Makes sure the string (if utf-16) is in LittleEndian form.
Other Encodings
Base64Decode Decode a string that is encoded using Base64
Base64Encode Encode the string using Base64 encoding method
Base85Decode Decode a string that is encoded using Base85 / ASCII85
Base85Encode Encode the string using Base85 / ASCII85 encoding method
EncodedWordDecode Decodes the string if it's encoded in "Encoded Word" format.
EncodedWordEncode Encodes the string to "Encoded Word" format.
ToHex Converts the stored string to a hex string - each bytes is converted to two characters representing the hexadecimal equivalent.
FromHex Converts a string that is encoded as a hex string back to the original value.
HtmlEntityToDec Converts HTML Entity names to Unicode Decimal encoding.
JsonDecode Decodes a string that was encoded for transport in JSON format.
JsonEncode Encodes a string into JSON format, suitable for adding to a JSON packet.
QuotedPrintableEncode Encodes the string to QuotedPrintable Format.
QuotedPrintableDecode Decodes the string from QuotedPrintable format.
UrlEncode Method URL (percent) encodes the passed string
UrlDecode Methods decodes the passed URL (percent) encoded string.
XMLDecode Decodes a string that was encoded for transport in XML format.
XMLEncode Encodes a string into XML format, suitable for adding to an XML packet.
Binary Data handling and storage
FromBytes Converts a value stored as binary within a string back into the native data type (for example retrieving a Long value from a String). Prevents any automatic type conversion and retrieves the actual binary value stored in a string for the following types: byte, short, ushort, long, ulong, sreal, real, decimal, cstring, string
ToBytes Stores the passed value in a string as binary. Does not do any type conversion - the data is stored as a sequence of bytes with the same values as in the original. Support the following types: byte, short, ushort, long, ulong, sreal, real, decimal, cstring, string
GetBytes Retrieves a binary value stored in the StringTheory object.
SetBytes Stores a binary value in the StringTheory object.
Compression and Decompression
Gzip Compress the string to the .gz (gzip) format using the external zlibwapi.dll.
Gunzip Decompress the string from the .gz (gzip) format using the external zlibwapi.dll
NOTE: To make use of the GZIP and GUNZIP methods, you must copy the ZLIBWAPI.DLL into your application folder.
StringTheory

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

StringTheory

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

StringTheory

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

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

AfterLast

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

Description

Returns the contents of the current string after the last instance of a delimiter.

Parameters
Parameter Description
SearchValue Searches for this string in the current string, and returns all the text after the last instance of this string (not including this string).
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
Return Value

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

See also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

AfterNth

AfterNth (String SearchValue, long pOccurrence, Long Start=1, Long End=0, Long NoCase=false)

Description

Returns the contents of the current string after the nth instance of a delimiter.

Parameters
Parameter Description
SearchValue Searches for this string in the current string, and returns all the text after the last instance of this string (not including this string).
Occurrence The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end.
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
Return Value

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

See also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

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
StringTheory

Append

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

Description

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

Parameters
Parameter Description
newValue The value to append to the string
pOptions This can be one of several options.
st:NoClip - The NewValue is not clipped before being added to the object.
st:Clip - The NewValue is clipped before it is appended
st:NoBlanks - If the NewValue is blank, then the pSep parameter is not added to the string.
st:Clip + st:NoBlanks- the string is clipped, and the separator is not added if NewValue is blank.
st:Lines - the Lines Queue from the pStr is added to the lines for this object. (Lines are added after the existing lines.)

Note: Only text data should be clipped. Clipping binary data is not recommended.
pStr Another StringTheory object. If this form of the method is used then the contents of pStr will be appended to the current object.
pSep If the string already contains text, then the optional Separator is added between the existing text, and the new text. If the string is currently blank then the separator is ignored. The separator is not clipped (thus allowing for space separators) so care should be taken with the string being passed.
Return Value

None

See also

Prepend , SetValue
StringTheory

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

StringTheory

AdjustLength

AdjustLength (long pLen)

Description

The length of the string is adjusted by the pLen parameter. If the parameter is negative, then the string is shortened. If the parameter is positive then the string is lengthened. The additional space is padded with Space characters.

Parameters
Parameter Description
pLen The amount to adjust the length of the string by. This value can be positive or negative.
Return Value

The new length of the string.

See Also

SetLength, Tail


StringTheory

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

StringTheory

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

StringTheory

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

StringTheory

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, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

BeforeLast

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

Description

Returns the contents of the current string before the last instance of a delimiter.

Parameters
Parameter Description
SearchValue Searches for this string in the current string, and returns all the text before the last instance of this string (not including this string).
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
Return Value

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

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

BeforeNth

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

Description

Returns the contents of the current string before the nth instance of a delimiter.

Parameters
Parameter Description
SearchValue Searches for the nth instance this string in the current string, and returns all the text before the last instance of this string (not including this string).
Occurrence The nth occurrence of the SearchValue to look for. If the value is positive the search is from the start, if negative then backwards from the end.
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
Return Value

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

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

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 , SetBetween
StringTheory

Base32Decode

Base32Decode (Long pOptions=0, <String pAlphabet>)

Decodes a string which is encoded using one of the Base32 formats. The contents of the object are decoded, and the result is placed in the object.
Cunningly, the Base32 standard is somewhat varied, and there are different alphabets that may have been used. This method allows you to specify the specific alphabet that was used.

Parameters

Parameter Description
pOptions st:noCase: Upper and Lower case are treated the same

st:detectAlphabet: use this if you do not know the alphabet - it will try to work it out based on first 1000 chars (or less if not that much data). If an alphabet is passed in, then that will be tested first. If that fails the default alphabet will be used. If that fails the ExtendedHex alphabet (0123456789ABCDEFGHIJKLMNOPQRSTUV=) will be used.


If st:detectAlphabet is set then st:noCase is implied (whether it is set or not).

If st:Tolerant is used then characters not in the alphabet will be discarded before decoding. If the result is not a multiple of 8 characters, then padding is automatically added to make up the missing characters before decoding commences.

If st:Tolerant is not used, then only whitespace (CR,LF,Tab,Space) will be removed. The remaining characters must all be part of the alphabet.
pAlphabet A string containing the alphabet to use. If omitted the default alphabet is
'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567='

The alphabet MUST be 33 characters long, consisting of the 32 char alphabet, and the padding character (usually =). If a 32 char alpabet is passed in, the padding char is set to =. If an alphabet length of a different length is used, the method will return st:notok.
the padding character may not be one of the alphabet characters. Alphabets may not contain formatting characters (CR, LF, Tab, Space)


Return Value

st:ok if ok, st:notok otherwise. If an error occurs the string will NOT be preserved - it will be cleared.

See Also

Base64Encode, Base64Decode, Base85Encode, Base85Decode, Base32Encode .

StringTheory

Base32Encode

Base32Encode (Long pOptions=0, <String pAlphabet>)

Description

Encodes the current string in Base32 format.

By default lines are wrapped by inserting a carriage return, line feed pair (ASCII 13,10) to limit the line length to 75 characters including the CR,LF pair.

Parameters

Parameter Description
pOptions This parameter allows for a number of options which affect the outcome. These options can be added together if multiple options are required.

st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length.

st:NoPadding : Usually base32 output is padded with = characters to be a multiple of 8 bytes. If this option is on that padding is removed.
pAlphabet The alphabet to use. If not passed, the default alphabet (ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=) is used.

Return Value

st:ok if ok, st:notok otherwise. If the function fails then the current string is cleared.

Example

st StringTheory
code
st.SetValue(binaryVal) ! Set the value, can be binary data
st.Base32Encode() ! Base32 encode (automatically line wraps)

See Also

Base64Encode, Base64Decode, Base85Encode, Base85Decode, Base32Decode .

StringTheory

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

st:ok if ok, st:notok otherwise.

See Also

Base64Encode, Base85Encode, Base85Decode .

StringTheory

Base64Encode

Base64Encode (Long pOptions=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.

Parameters

Parameter Description
pOptions This parameter allows for a number of options which affect the outcome. These options can be added together if multiple options are required.

st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length.

st:URLSafe : If this option is used then an alternate base64 alphabet is used. This output is suitable for use in a URL or HTTP header. If this option is set then st:nowrap is also set. This alphabet replaces + with - and / with _.

st:NoPadding : Usually base64 output is padded with = characters to be a multiple of 3 bytes. If this option is on that padding is removed.

Return Value

st:ok if ok, st:notok otherwise.

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.Base64Encode(st:noWrap)
  encodedFile = st.GetValue() ! Get the Base64 encode file as a string

!-------------------------------------------------------
! Example 3: generate a URL Safe string.
!-------------------------------------------------------
  st.SetValue('whatever')
  st.Base64Encode(st:URLSafe + st:NoPadding)
  base64String = st.GetValue()

See Also

Base64Decode, Base85Encode, Base85Decode .

StringTheory

Base85Decode

Base85Decode ()

Description

The content of the string is decoded using the Base85 (aka ASCII85) format.

Return Value

Returns 0 for success otherwise the position of the first invalid character. The current contents of the object are changed.

See Also

Base85Decode, Base64Encode, Base64Decode , Wikipedia.


StringTheory

Base85Encode

Base85Encode (Long pOptions=0)

Description

The contents of the string are encoded using the Base85 (aka ASCII85) format.

Parameters
Parameter Description
pOptions This parameter allows for a number of options which affect the outcome. These options can be added together if multiple options are required.

st:noWrap : If this option is used, CR/LF characters are not included in the output, regardless of string length.
st:Adobe85 : If this option is used then the encoding uses the Adobe variant. The Adobe variant is bounded by <~ and ~>.
Return Value

Nothing is returned, the contents of the string are altered.

See Also

Base85Decode , Base64Encode, Base64Decode , Wikipedia.


StringTheory

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
StringTheory

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


 
StringTheory

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:EncodeANSI, st:EncodeUft8,  st:EncodeUtf16. If omitted then the current value in the st.Encoding property is used
pStr The string to count the characters for. If omitted then the current value of the object is used.
Return Value

The number of characters in the string

See Also

ToAnsi , ToUnicode , Length
 
StringTheory

CharToDecEntity

CharToDecEntity(long pFrom=128, long pTo=255)

Description

Converts any character in the current object, in the range (inclusive) from pFrom to pTo to the form &#nnn; .

Parameters
Parameter Description
pFrom The character value to encode from. Must be from 0 to 255. Defaults to 128.
pTo The character value to encode from. Must be from 0 to 255. Defaults to 255.

Returns

Nothing. The current value in the object is changed with this method.

See Also

DecEntityToChar

StringTheory

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
StringTheory

Clip

Clip (<String pAlphabet>)

Description

Clips the string (removes trailing white space).

Parameters

Parameter Description
pAlphabet Defines the white-space characters to be clipped from the end of the string. If omitted then only space characters are clipped.

Return Value

None

Examples

str.clip()
str.clip('<32,13,10>')

See Also

ClipLength, Trim, Squeeze
StringTheory

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
StringTheory

ColorToLong

ColorToLong(String pColor)

Takes a color in either Clarion (Long), or Web (#hex) format, or standard color name, or Comma-Separated-List (rgb(r,g,b)) format and returns it in Clarion Long format.

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

Parameters
Parameter Description
pColor A color in either long, hex, csl or name format.
Return Value

Returns a long  that contains the Clarion representation (in lower case) of the color. The current contents of the string are not altered. If the pColor is not a valid color then the method returns color:none.

Example
Example
Str    StringTheory
color  Long
  code
  color = str.ColorToLong(color:red)
  color = str.ColorToLong('red')
  color = str.ColorToLong('#F00')
  color = str.ColorToLong('#FF0000')
  color = str.ColorToLong(color:MenuBar)
  color = str.ColorToLong('rgb(255,0,0)')
  color = str.ColorToLong('(255,0,0)')
  color = str.ColorToLong('255,0,0')
See Also

ColorToHex, Color Names
StringTheory

ColorToHex

ColorToHex (string pColor, bool pAddHash=false)

Takes a color in either Clarion (Long), or Web (#hex) format, or standard color name, or Comma-Separated-List (rgb(r,g,b)) format and returns it in hexadecimal format. 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 pColor 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
pColor A color in either Clarion (Long), or Web (#hex) format, or standard color name, or Comma-Separated-List (rgb(r,g,b)) format
addhash [optional] If this is set to True then the hexadecimal string starts with a hash character. Primarily for compatibility with web (HTML, CSS etc.) colors. For example 0 (black) would produce '#000000'. Default value is false.
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. If the pColor field is blank then a blank string is returned.

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

ColorToLong, Color Names
StringTheory

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
StringTheory

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
StringTheory

ContainsByte

ContainsByte(Byte pByte, <String TestString>)

Description

Returns True if the string contains the specified byte.

Parameters

Parameter Description
pByte A single byte value to test in the string.
TestString (optional) The string to test. If omitted the current string value of the object is used. If the testString is passed, then it is not clipped, so trailing spaces will count as "containing a space".

Return Value

Returns True(1) if the string contains the specified byte, and False (0) otherwise.

See Also

IsAllDigits, ContainsA
StringTheory

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
StringTheory

ConvertAnsiToOem

ConvertAnsiToOem()

Description

Applies the Clarion ConvertAnsiToOem function to the string.

Parameters

None

Return Value

Nothing

See Also

ConvertOemToAnsi
StringTheory

ConvertOemToAnsi

ConvertOemToAnsi()

Description

Applies the Clarion ConvertOemToAnsi function to the string.

Parameters

None

Return Value

Nothing

See Also

ConvertAnsiToOem
StringTheory

ConvertTabs

ConvertTabs(long pTabSize=8, <string pLineEnding>)

Description

Replaces tab characters with a variable number of spaces. The number of spaces will move the following character to the next tab boundary.

Parameters

Parameter Description
pTabSize The tab boundary. Defaults to every 8 characters.
pLineEnding (optional) The characters that indicate the end of a line. Defaults to CRLF - ie ('<13,10>').

Return Value

Nothing. The contents of the string are altered with this call.

Example

str.setvalue('red<9>green<9>blue<9>')
str.ConvertTabs() ! result is 'red    green  blue   '

See Also

Replace

StringTheory

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
StringTheory

CountWords

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

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)
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.
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
StringTheory

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
StringTheory

DecEntityToChar

DecEntityToChar()

Description

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

See Also

CharToDecEntity

StringTheory

DeformatValue

DeformatValue (String pValue, String pPicture)
DeformatValue (String pPicture)

Description

Returns the deformatted value of a string. Makes use of the StringDeformat class.

Parameters
Parameter Description
pValue The string to deformat. If not passed then the current contents of the object are used.
pPicture The picture that hints how the string is formatted. Supports Extended Pictures. With some formats the picture acts as a hint only, and another picture may be used if it is a better fit. For example a time value (hh:mm:ss) will be deformatted as @t4 even if the picture passed is @t1.
Return Value

An unformatted string containing the deformatted value. The current contents of the object are not changed by this call.

Example
st     StringTheory
  code
  st.SetValue('12/31/2022')
  x = st.DeformatValue('@d1')
See Also

FormatValue, DeformatValue, SetFormatValue, SetDeformatValue

StringTheory

EndsWith

EndsWith (String pSub, 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
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
StringTheory

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.
st:NoCaseCompare : The strings are compared in a case insensitive way. (Some unicode comparisons are incomplete at this time.)
Return Value

True if the objects match. False if they don't match.

See Also

StringTheory

ErrorTrap

ErrorTrap (string MethodName, string Message, byte forceLog=false)

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.

If ForceLog is set to true, then the output is sent to Debugview, regardless of the state of the logging property.

StringTheory

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
StringTheory

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
StringTheory

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
StringTheory

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 name of that file is returned. If the parameter is not passed then the contents of the string is treated as a filename, and only the file name of that is returned.
IncludeExtension (optional) If omitted, or True, then the filename returned will include the extension part of the name. If the parameter is set to False then the name without the extension is returned.

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

StringTheory

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.
If the string is not found then Start is set to zero.

If the Left and Right delimiters are found, but there is no text between them, then End will be set to Start-1. For example;

str.SetValue('<table></table>')
str.FindPosition('<table>','</table>',s,e)  ! s = 8, e= 7



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
StringTheory

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.

StringTheory

FindByte

FindByte (Byte 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 byte to search for.
pStart [optional] The position to start searching at. Defaults to the start of the string.
pEnd [optional] The position to end searching. Defaults to the end of the string.
pText [optional] The string to search. If omitted the object value is searched.

Return Value

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

See Also

FindChar
StringTheory

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

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

FindEndOfString

FindEndOfString (Long pEncoding, Long pStringAddress, Long pMaxLength=255)

Description

  Given a block of memory, find the first null character in the block.

Parameters
Parameter Description
pEncoding One of st:EncodeAnsi, st:EncodeUtf8 or st:EncodeUtf16. For ANSI and UTF-8 encodings a single null character is needed to end the string. If the UTF-16 encoding is used, then two null characters are needed to end the string.
pStringAddress The start of the memory block to start searching
pMaxLength The maximum length to look for. The default is 255. This prevents searches from exceeding possible string limits.

Return Value

Returns the position that the character was found at. If a null character was not found, then the pMaxLength is returned.

StringTheory

FindLast

FindLast (string pSearchValue, long pStart=1, long pEnd=0, long pNocase=false)

Description

Find the last instance of the SearchValue in the current object.

Parameters
Parameter Description
pSearchValue The sub string value to look for.
pStart The position in the current value to begin searching from. If this parameter is omitted then the search starts at the beginning of the current value.
pEnd The position in the current value to stop searching. If this parameter is omitted then the search ends at the end of the current value.
pNoCase If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive.

Return Value

Returns the position that the character was found at. If the search value is not found then it returns 0. 

See Also

FindNth, Instring

StringTheory

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

StringTheory

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.

StringTheory

FindNth

FindNth(string pSearchValue, long pOccurrence, long pStart=1, long pEnd=0, long pNocase=false)

Description

Finds the nth instance of a searchvalue in the string.

Parameters
Parameter Description
pSearchValue The characters to search for.
pOccurrence The nth instance of the characters to search for. If this value is positive then it searches from the start, if negative it searches from the end.
pStart The position to start searching at. Defaults to the start of the string. The start position of the found string is returned here. If the searched-for string is not found then this value changes to 0.
pEnd The position to end searching. Defaults to the end of the string. The end position of the found string. If the searched-for string is not found then this value changes to 0.
pNoCase Set this to true (st:nocase) to do a case insensitive match.

Return Value

Returns the position of the nth instance of the searchValue in the current object string. If the nth instance is not found then 0 is returned.

See Also

Instring, ReplaceNth , FindLast .

StringTheory

FlexPolylineDecode

FlexPolylineDecode()

Description

Note: This method requires Clarion 9.1 or higher.
Decodes a string that contains a flex polyline value. This decodes the string into a list of coordinate pairs or coordinate triples.

Returns

Nothing. The contents of the object are decoded, and the decoded value is now in the string.

See Also



StringTheory

Flush

Flush()
Flush(*string pStr)
Flush(StringTheory pStr)

Description

Flush writes the data currently in the write-cache to the disk. The contents of the object are discarded after the write. The object remains in Streaming mode after Flush is called. To terminate streaming mode call NoStream after calling Flush.

Parameters
Parameter Description
pStr Typically used  with a very large string. If passed this will be written to the disk file, after flushing the current cache.

Returns

st:ok if the flush was successful. st:notok if the write to the disk failed.

See Also

Stream , NoStream, Streaming to a Disk file (Write-Caching)

StringTheory

FlushAndKeep

FlushAndKeep()
Description

FlushAndKeep writes the data currently in the write-cache to the disk. The contents of the object are NOT discarded after the write. The object remains in Streaming mode after FlushAndKeep is called. To terminate streaming mode call NoStream.

Returns

st:ok if the flush was successful. st:notok if the write to the disk failed.

See Also

Stream , NoStream, Streaming to a Disk file (Write-Caching)

StringTheory

FindWord

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

Description

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

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".
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.
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.
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
StringTheory

FormatValue

FormatValue (String pValue, String pPicture)
FormatValue (String pPicture)

Description

Returns the formatted value of a string. Makes use of the StringFormat class.

Parameters
Parameter Description
pValue The value to format. If not passed then the current contents of the object are used.
pPicture The picture that determines how the string is formatted. Supports Extended Pictures.
Return Value

An string containing the formatted value. The current contents of the object are not changed by this call.

Example
st     StringTheory
  code
  s = st.FormatValue(81087,'@d1')
See Also

FormatValue, DeformatValue, SetFormatValue, SetDeformatValue

StringTheory

FormatHTML

FormatHTML()

Description

Assuming the object contains valid HTML, this method formats the string contents so that they are human-readable with suitable line breaks, and indenting.

Return Value

Nothing. The contents of the object are altered by this method.

See also

HtmlEntityToDec, RemoveHTML, RemoveAttributes

StringTheory

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
StringTheory

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

Free

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

Description

A method used to clear the string and (optionally) 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.
See Also

Start
StringTheory

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 Description
PSrc A string that contains the binary value to be retrieved.
pVal The variable to store the binary value into
pOffset The offset index into the string for where to get the value from. If omitted then then the default position is the first character in the string.

Example

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

StringTheory

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

StringTheory

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
StringTheory

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 change, so the value should not be stored and reused.

Return Value

Returns a Long containing the address of the string.

See also

GetValuePtr

StringTheory

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

StringTheory

GetValue

GetValue ()

Description

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

See also

SetValue , GetValuePtr
StringTheory

GetValuePtr

GetValuePtr(<Long pStart>,<Long pEnd>)

Description

Returns a pointer to the value of the string currently stored in the object. Use this rather than the value property directly when passing to procedures that need a *string parameter.

Parameters
Parameter Description
pStartAllows for an offset into the current string value. In other words returns a pointer to a string, where the string starts not from the beginning of the string, but from somewhere in the string. Default value is 0.
pEndAllows for an early-end of the current string value. In other words allows passing of "part of the string" to another function which takes a *string as input. Default value is the end of the current object.

See also

GetValue, GetAddress
StringTheory

GetWord

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

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.
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.
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
StringTheory

GuidDecode

GuidDecode ()

Description

Converts a guid in human-text format back to a binary string. In effect it does a FromHex on the string, removing any curly-brackets, hypens, spaces or any other characters in the string.

If passed a valid UUID string, then it should be 16 characters in length after the decode, however it does not validate that the current value is a valid guid, so the result may not be a valid guid.

See also

GuidEncode, MakeGuid4 .
StringTheory

GuidEncode

GuidEncode (Long pOptions=st:Hyphen)

Description

Takes a 16 character binary string, and represents it as 32 hexadecimal (base-16) digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 hexadecimal characters and 4 hyphens).

For example;
123e4567-e89b-12d3-a456-426614174000

Parameters

Parameter Description
long pOptions By default the method will encode the string using Hex encoding, and hypens.
The hypens can be suppressed using st:NoHypens. If curly brackets are desired, then these can be added using st:brackets. these two options can be added together.

Returns

Nothing. The current contents of the object are changed.
If the current contents of the string is not exactly 16 characters long, then the string is unaltered.

Example

   str.GuidEncode()
   str.GuidEncode(st:brackets)
   str.GuidEncode(st:NoHyphens + st:brackets)

See also

GuidDecode, MakeGuid4 .
StringTheory

Gunzip

Gunzip (Long pOffset=0)

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.

Parameters

Parameter Description
long pOffset By default the string is assumed to contain a compressed value. If the string is partially uncompressed (the "header" part) and then compressed (the "body" part) then this allows you to specify the starting point of the decompression. Specifically the pOffset value is the number of uncompressed bytes at the start of the string.

Example

If you have a file stored on the disk it can be loaded using the LoadFile method, then unzipped using the Gunzip method.

str.LoadFile('whatever.txt.gz')
str.Gunzip()
str.SaveFile('whatever.txt')

If you have a string, returned from a WebServer, where the header is uncompressed, and the body is compressed

x = str.instring('<13,10,13,10>')
str.Gunzip(x+3)

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
StringTheory

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
StringTheory

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.

See Also

RemoveHTML, RemoveAttributes, FormatHTML

StringTheory

Insert

Insert (long Start, string insertValue)
Insert (long Start, StringTheory 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 Start position to insert at. If the Start parameter is less than or equal to 1, then the new value is prepended to the front of the string. If it is higher than the current length of the string then the current string is padded with spaces so that the new value can be added at the specified position.
insertValue The string to insert at the specified position. This value is not clipped, so clip if necessary.

Return Value

None

Examples

st.Insert(st.Length()-2, '-NewValue-')
StringTheory

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. If step=0 then only value at the Start position is checked.
Start The position in the current value to begin searching from. If this parameter is omitted then the search starts at the beginning of the current value.
End The position in the current value to stop searching. If this parameter is omitted then the search ends at the end of the current value.
NoCase If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive.
WholeWord If this parameter is set to not zero, then only sub strings which form a Whole Word will be returned. A whole word is defined as any sequence not immediately followed, or preceded by an alpha-numeric character (A through Z, a through z and 0 through 9).
Return Value

The position of the substring in the value, if it is found. If no match is found then 0 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. The position returned is relative to the start of the string, not relative to the Start parameter.

See Also

FindNth , FindLast .
StringTheory

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.

Example

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

See Also

ContainsADigit, ContainsA, IsAllDigits
StringTheory

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
StringTheory

IsAllLower

IsAllLower ()

Description

Determines if all the characters in the string are lower case.

Parameters

None

Return Value

Returns true (1) if value only contains lower case letters, false (0) otherwise.

Example

st StringTheory
Code
st.SetValue(somestring)
If st.IsAllLower()
! contains no characters other than lower case letters, a through z.
End

See Also

ContainsADigit, ContainsA, IsAll, IsAllUpper, IsUpper, IsLower
StringTheory

IsAllUpper

IsAllUpper ()

Description

Determines if all the characters in the string are upper case.

Parameters

None

Return Value

Returns true (1) if value only contains upper case letters, false (0) otherwise.

Example

st StringTheory
Code
st.SetValue(somestring)
If st.IsAllUpper()
! contains no characters other than upper case letters, A through Z.
 End

See Also

ContainsADigit, ContainsA, IsAll, IsAllLower, IsUpper, IsLower .
StringTheory

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, IsAllLower, IsUpper, IsLower .
StringTheory

IsLower

IsLower()

Description

Checks to see if any characters in the string are uppercase.

Parameters

None

Return Value

Returns True (1) if the string contains no upper case characters or false if the string contains any upper case characters.

Example

st StringTheory
Code
st.SetValue(somestring)
If st.IsLower()
! contains no uppercase characters.
End

See Also

ContainsADigit, ContainsA, IsAll, IsAllUpper, IsAllLower, IsUpper, IsLower .
StringTheory

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
StringTheory

IsUpper

IsUpper()

Description

Checks to see if any characters in the string are lowercase.

Parameters

None

Return Value

Returns True (1) if the string contains no lowercase characters or false if the string contains any lowercase characters.

Example

st StringTheory
Code
st.SetValue(somestring)
If st.IsUpper()
! contains no lowercase characters.
End

See Also

ContainsADigit, ContainsA, IsAll, IsAllUpper, IsAllLower, IsUpper, IsLower .
StringTheory

IsValidUtf8

IsValidUtf8 ()

Description

Used to determine if the string in the object is a valid utf-8 string.

Return Value

Returns true if valid, and false if not.

See Also

ToUnicode, ToAnsi .
StringTheory

JsonDecode

JsonDecode()

Description

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

Return Value

0 if successful. The position of the invalid JSON encoding if the decoding fails. This method changes the contents of the object.

See Also

JsonEncode

StringTheory

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.

See Also

JsonDecode

StringTheory

KeepCharRanges

KeepCharRanges(string Alphabet, <String pReplacementChar>)

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. This parameter can include ranges, characters separated by a hyphen. So 'A-Z' would keep all characters from (and including) A to Z. '<0>-<31>' would keep all control characters, and so on.
pReplacementChar If this parameter exists then any chars not in the alphabet are not removed, but replaced with this character. This parameter is only a single character long - any additional characters are ignored.
Return Value

Returns the number of characters removed from (or replaced in) the string. The text in the object is changed.

See Also

RemoveChars, KeepChars, RemoveCharRanges .
StringTheory

KeepChars

KeepChars(string Alphabet, <String pReplacementChar>)

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.
pReplacementChar If this parameter exists then any chars not in the alphabet are not removed, but replaced with this character. This parameter is only a single character long - any additional characters are ignored.
Return Value

Returns the number of characters removed from (or replaced in) the string. The text in the object is changed.

See Also

RemoveChars, KeepCharRanges, RemoveCharRanges.
StringTheory

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,
StringTheory

Length

Length ()

Description

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

LineEndings

LineEndings (Long Endings = st:Windows, Long pFrom = 0)

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.

When converting from an HTML format then typical HTML line endings are converted to the appropriate CR/LF combination. HTML tags converted are <br>, <br/>, <hr>, <hr/>, </p> and <p/>. When converting to HTML then the <br/> line ending is used.

Parameters

Parameter Description
Endings
(optional)		 The format desired for the text. Valid options are st:None, st:Windows, st:Mac, st:Unix and st:web. If this parameter is omitted then st:Windows is used.
pFrom If the source document is known to be HTML, and conversion of <br> etc is desired then set this parameter to st:web.

Return Value

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

See Also

RemoveHTML

StringTheory

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
StringTheory

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



StringTheory

Lower

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) A character to identify the start of Quoted Text. Quoted Text will not be lowered by this method. If this parameter is omitted then all the text in the string is lowered.
QuoteEnd (optional) The character to use as the end of Quoted Text. If omitted, and the Quote parameter is not omitted, then the same quote character will be used to delineate the start and end of text.
Example
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

StringTheory

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.

StringTheory

MakeGuid4

MakeGuid4(Long pOptions)

Makes a 16 character (128 bit) Binary random value, in accordance with RFC 4122, using the version 4 version.
Note that as a binary value, this is not suitable for non-binary formats like Excel, or CSV. If used it XML or JSON it will need to be properly encoded.

For formatting this value to a human-readable text form see GuidEncode.

Parameters
Parameter Description
pOptions If set to st:format then the returned value is not binary, but already passed through GuidEncode. Options for GuidEncode can be used here as well.
Example

st.MakeGuid4()
st.MakeGuid4(st:format)
st.MakeGuid4(st:format + st:brackets)

Return Value

Nothing. The contents of the string is changed.

See Also

GuidEncode , GuidDecode .

StringTheory

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

StringTheory

MatchBrackets

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

Finds the matching end bracket of a given start bracket.

Parameters
Parameter Description
LeftBracket A string, indicating the left bracket of the search. For example, ( or < or { and so on.
RightBracket A string indicating the right bracket in the search.
Start The position to start in the string. The first instance of the LeftBracket after the start marks the beginning of the search. If omitted the search starts at the beginning of the string.
Example

st stringtheory
x  Long
  code
  st.SetValue('(a+b)=((c+d)*4)')
  x = st.MatchBrackets('(',')',7) ! x = 15

Example

st stringtheory
x  Long
  code
  st.SetValue(someXmlData)
  x = st.MatchBrackets('<table>','</table>') ! finds the position of </table> after <table>

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

 

StringTheory

MD5

MD5 (Long pFormat=st:EncHex, <*String pStr>, Long pLength=0)

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.
pStr (optional) If passed, then the MD5 is calculated on the passed string, not the current string contents. If ot passed then the contents of the object are used to calculate the hash.
pLength (optional) If the pStr parameter is passed, then the length of the data to hash must be passed as well.

Return Value

A string which contains the MD5 hash of the value.

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

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
StringTheory

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

NoStream

NoStream()

Description

This method terminates streaming, WITHOUT flushing the current contents of the object. Use with care.

Returns

Nothing.

See Also

Stream, Flush, Streaming to a Disk file (Write-Caching)

StringTheory

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

StringTheory

PeekRAM

PeekRAM (stringTheory pResult, uLong pAdr, Long pLen, Long pFormat=st:Decimal)
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
pResult Optional. If omitted the output is sent to Debugview. If passed then the result is placed into the passed object.
pAdr The address of the memory (or variable) to be peeked at. If the second form of the method is used (ie this parameter is not passed) or this value is 0, then the current contents of the StringTheory object are peeked.
pLen The length of memory to Peek.
pFormat One of st:Decimal or st:Hex. Determines the number format of the value being output.

Returns

Nothing. The current object is not altered. All output goes to either the pResult parameter or DebugView.

See Also

Append

StringTheory

Prepend

Prepend (String NewValue,<Long pOptions>,<String pSep>)
Prepend (stringTheory pStr, <String pSep>)
 Prepend (stringTheory pStr, Long pOptions, 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
pOptions This can be one of several options.
st:NoClip - The new value is not clipped before the NewValue is prepended.
st:Clip - The NewValue value is clipped before the NewValue is prepended to the string.
st:NoBlanks - If the NewValue is blank, then the pSep parameter is not prepended to the string.
st:Clip + st:NoBlanks- the new value is not clipped, and the separator is not added if NewValue is blank.
st:Lines - the Lines Queue from the pStr is added to the lines for this object. (Lines are added before the existing lines.)

Note: Only text data should be clipped. Clipping binary data is not recommended.
pStr Another StringTheory object. If this form of the method is used then the contents of pStr will be prepended to the current object.
pSep If the string already contains text, then the optional Separator is added between the existing text, and the new text. If the string is currently blank then the separator is ignored. The separator is not clipped (thus allowing for space separators) so care should be taken with the string being passed.

See Also

Append
StringTheory

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
StringTheory

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
StringTheory

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:Binary - Includes characters from chr(0) to chr(255). The Alphabet parameter, and other flags, are ignored.
st:AlmostBinary - Includes characters from chr(1) to chr(255). The Alphabet parameter, and other flags, are ignored.
st:Alphabet - Use only the Alphabet parameter
st:Upper - Includes Uppercase letters from A to Z in the alphabet.
st:Lower - Includes lowercase letter from a to z in the alphabet.
st:Number - Includes decimal digits from 0 to 9 in the alphabet
st:Hex - Includes A to F and 0 to 9 in the alphabet. (Only works if st:Upper, st:Lower and st:Number are all excluded from the flags)
st:space - Include a space character in the alphabet.
st:DNA - Includes the uppercase characters GCAT. (Ignored if st:Upper is set).
st:AlphaFirst - Regardless of the other bit settings, the first character must be an uppercase letter, A through Z.
Alphabet [optional] In addition to the alphabet created by the Flags settings, add the following specific characters as well. Note that if you want to include a space in your alphabet, then it must not be the last character in the alphabet as this parameter is clipped before usage.
If both the Alphabet and Flags parameters are omitted then the default alphabet is st:Upper.
This parameter is not used if the Flags includes st:Binary or st:AlmostBinary
Returns

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

See Also

MakeGuid, SeedRandom, SetRandom

StringTheory

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 DDescription
pLeft The start delimiter of the text to remove. Note that this parameter is not clipped by the method, so you may want to call clip yourself.
pRight The end delimiter of the text to remove. If this parameter is omitted then the text in pLeft is removed. Note that this parameter is not clipped by the method, so you may want to call clip yourself.
pNoCase If set to not zero then the search is case insensitive. If this parameter is omitted (or 0) then the search is case sensitive.
pContentsOnly Only the text between the delimiters, not including the delimiters, is removed. The default is false, meaning that the delimiters are removed as well as the contained text.
pCount The number of occurrences to remove. If set to 0 (the default) then all instances of the text are removed.

Return value

The number of items removed from the string.

Example
EExample
  htmlString = <td class="tabledata" align="left" ' |
    & 'colspan="2" valign="middle" id="td_11">' |
    & 'Hello World</td>'
  st.SetValue(htmlString)
  st.Remove('<td','>')
  st.Remove('</td>')
  Message(st.GetValue())
The output (value stored in the StringTheory object) of the above example is: 'Hello World'

See Also

RemoveAttributes, Replace
StringTheory

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

See Also

HtmlEntityToDec, RemoveHTML, FormatHTML

StringTheory

RemoveByteRange

RemoveByteRange(byte pLow, byte pHigh)

Description

Removes any characters from the string which are between the low and high byte (inclusively). Similar to RemoveCharRanges, but only supports a single range, and works on byte values, not String values.

Parameters
Parameter Description
pLow The ASCII value of the low byte to remove
pHighThe ASCII value of the high byte to remove.
Return Value

Returns the number of characters removed (or replaced) from the string. The text in the object is changed.

See Also

KeepChars, RemoveChars, KeepCharRanges , RemoveCharRanges .
StringTheory

RemoveCharRanges

RemoveCharRanges(string Alphabet,<String pReplacementChar>)

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. This parameter can include ranges, characters separated by a hyphen. So A-Z would remove all characters from (and including) A to Z. <0>-<31> would remove all control characters, and so on.
pReplacementCharIf this parameter exists then any chars not in the alphabet are not removed, but replaced with this character. This parameter is only a single character long - any additional characters are ignored.
Return Value

Returns the number of characters removed (or replaced) from the string. The text in the object is changed.

See Also

KeepChars, RemoveChars, KeepCharRanges .
StringTheory

RemoveChars

RemoveChars(string Alphabet,<String pReplacementChar>)

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.
pReplacementCharIf this parameter exists then any chars not in the alphabet are not removed, but replaced with this character. This parameter is only a single character long - any additional characters are ignored.
Return Value

Returns the number of characters removed (or replaced) from the string. The text in the object is changed.

See Also

KeepChars, RemoveCharRanges, KeepCharRanges .
StringTheory

RemoveFromPosition

RemoveFromPosition(long pPosition, long pLength)

Description

Removes the specified number of characters from the string at the specified position.
 
Parameters
Parameter Description
pPosition The position to remove the characters from.
pLength The number of characters to remove from the position.
Return Value

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

See Also

Remove
StringTheory

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

HtmlEntityToDec, RemoveAttributes, FormatHTML, LineEndings

StringTheory

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

StringTheory

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

ReplaceBetween, ReplaceSingleChars, ConvertTabs
StringTheory

ReplaceBetween

ReplaceBetween (string pLeft, <string pRight>, string pOldValue, string pNewValue, long pCount=0, long pStart=1, long pEnd=0, long pNoCase=0, long pReplaceAll=false)
Description

Searches for instances of Old Value in the current string and replaces them with NewValue. Limits the replacement to being between some known left and right boundaries.

Parameters
Parameter Description
pLeft The left edge of the string to search.
pRight The right edge of the string to search. If omitted the same text as pLeft is used.
pOldValue The value to search for. If this value is blank then the replacement value is inserted immediately after the pLeft string.
pNewValue The replacement value.
pCount [optional] If the Count parameter is set, then the method will terminate after Count instances of OldValue have been found, and replaced.
pStart [optional] Position to start searching from. Defaults to 1 (the start of the string)
pEnd [optional] Position to stop search the string at. Defaults to 0 (which will search to the end of the string).
pNoCase [optional] If the NoCase parameter is  st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive).
pReplaceAll If this is set to st:replaceAll then the pOldValue is ignored, and all the text between the pLeft and pRight is replaced with the pNewValue.
Return value

The number of items replaced in the string.

Examples
Example 
! Replace all occurrences of findString with replaceString:
st.SetValue('his name was "12 Lisbon street"')
st.replaceBetween('"','"','street','road')
See Also

Replace, , ReplaceSingleChars
StringTheory

ReplaceExceptBetween

ReplaceExceptBetween(string pLeft, <string pRight>, string pOldValue, string pNewValue, long pCount=0, long pStart=1, long pEnd=0, long pNoCase=0)
Description

Searches for instances of Old Value in the current string and replaces them with NewValue. Text between the left and right boundaries is NOT replaced.

Parameters
Parameter Description
pLeft The left edge of the string to search.
pRight The right edge of the string to search. If omitted the same text as pLeft is used.
pOldValue The value to search for. This value may not be blank.
pNewValue The replacement value.
pCount [optional] If the Count parameter is set, then the method will terminate after Count instances of OldValue have been found, and replaced.
pStart [optional] Position to start searching from. Defaults to 1 (the start of the string)
pEnd [optional] Position to stop search the string at. Defaults to 0 (which will search to the end of the string).
pNoCase [optional] If the NoCase parameter is  st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive).
Return value

The number of items replaced in the string.

Examples
Example 
! Replace all occurrences of findString with replaceString:
st.SetValue('Mr Lisbon lived at "12 Lisbon street"')
st.replaceExceptBetween('"','"','Lisbon','Smith')
See Also

Replace, , ReplaceSingleChars
StringTheory

ReplaceLast

ReplaceLast(string pOldValue, string pNewValue, long pStart=1, long pEnd=0, long pNocase=0)
Description

Searches for the last instance of Old Value in the current string and replaces it with NewValue.

Parameters
Parameter Description
pOldValue The value to search for. This value may not be blank.
pNewValue The replacement value.
pStart [optional] Position to start searching from. Defaults to 1 (the start of the string)
pEnd [optional] Position to stop search the string at. Defaults to 0 (which will search to the end of the string).
pNoCase [optional] If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive).
Return value

1 if a value was replaced, 0 otherwise.

See Also

FindNth , FindLast .

StringTheory

ReplaceNth

ReplaceNth(string pOldValue, string pNewValue, long pOccurrence, long pStart=1, long pEnd=0, long pNocase=0)
Description

Searches for the nth instance of  Old Value in the current string and replaces it with NewValue.

Parameters
Parameter Description
pOldValue The value to search for. This value may not be blank.
pNewValue The replacement value.
pOccurrence The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end.
pStart [optional] Position to start searching from. Defaults to 1 (the start of the string)
pEnd [optional] Position to stop search the string at. Defaults to 0 (which will search to the end of the string).
pNoCase [optional] If the NoCase parameter is st:nocase then a case-insensitive search will be done. The default is 0 (case sensitive).
Return value

1 if a value was replaced, 0 otherwise.

See Also

FindNth , ReplaceLast .

StringTheory

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

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

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

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, ReplaceBetween
StringTheory

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


 
StringTheory

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
StringTheory

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
StringTheory

SeedRandom

SeedRandom()

Description

Reseeds the Clarion Random Number Generator. This is a utility method and does not need to be called directly.

See Also

Random, MakeGuid

StringTheory

SerializeGroup

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

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.
pOptions [optional]Default value is 0. If set to st:AlwaysQuote then all fields are wrapped in quotes, even if the field does not contain a separator.

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

StringTheory

SerializeQueue

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

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

StringTheory

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
StringTheory

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
StringTheory

SetAfter

SetAfter(string pSearchValue, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the SearchValue in the string, and then crops the string from that point. The SearchValue is not included in the result. Only the string after that point is kept.

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.
pClearIfNotFound If this is true, and the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

SetAfterLast

SetAfterLast(string pSearchValue, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the last instance of the SearchValue in the string, and then sets the string from that point. The SearchValue is not included in the result. Only the string after that point is kept.

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.
pClearIfNotFound If this is true, and the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

SetAfterNth

SetAfterNth(string pSearchValue, long pOccurrence, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the nth instance of the SearchValue in the string, and then sets the string from that point. The SearchValue is not included in the result. Only the string after that point is kept.

Parameters
Parameter Description
SearchValue Searches for this string in the current string, and returns all the text after this string (not including this string).
Occurrence The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end.
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
pClearIfNotFound (optional) If this is true, and the nth instance of the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

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
StringTheory

SetBefore

SetBefore (string pSearchValue, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the SearchValue in the string, and then crops the string at that point. The SearchValue is not included in the result. Only the text before the found point is kept.

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.
pClearIfNotFound If this is true, and the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

SetBeforeNth

SetBeforeNth (string pSearchValue, long pOccurrence, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the nth instance of the SearchValue in the string, and then crops the string at that point. The SearchValue is not included in the result. Only the text before the found point is kept.

Parameters
Parameter Description
SearchValue Searches for this string in the current string, and returns all the text before this string (not including this string).
Occurrence The nth occurrence of the SearchValue to look for. If positive then search is from the start, if negative then searches from the end.
Start (optional) The start position in the current string to start the search. If omitted the search will start at the beginning of the current string.
End (optional) The position in the current string to end the search. If omitted then the search will end at the end of the current string.
NoCase (optional) If set to true the search value is case insensitive. By default the search value is assumed to be case sensitive.
pClearIfNotFound If this is true, and the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

SetBeforeLast

SetBeforeLast (string pSearchValue, long pStart=1, long pEnd=0, long pNoCase=0, long pClearIfNotFound=false)

Description

Finds the last instance of the SearchValue in the string, and then crops the string at that point. The SearchValue is not included in the result. Only the text before the found point is kept.

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.
pClearIfNotFound If this is true, and the searchValue is not found then the object is cleared.
Return Value

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

After, AfterLast, AfterNth, SetAfter, SetAfterLast, SetAfterNth, Before, BeforeLast, BeforeNth, SetBefore, SetBeforeLast, SetBeforeNth

StringTheory

SetBetween

SetBetween (string pLeft, string pRight, long pStart=1, long pEnd=0, long pNoCase=0, long pExclusive=true, long pClearIfNotFound=false)

Description

Finds the Left and Right values in the string, and then crops the string to those points.. The SearchValue is not included in the result. Only the text between lef

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

If the search term was found then the function returns st:ok. If the search term is not found then it returns st:notFound.

See Also

Between, Before, After, SetAfter, SetBefore

StringTheory

SetDeformatValue

SetDeformatValue (String pValue, String pPicture)
SetDeformatValue (String pPicture)

Description

Sets the object to the deformated value of a string. Makes use of the StringDeformat class.

Parameters
Parameter Description
pValue The string to deformat. If not passed then the current contents of the object are used.
pPicture The picture that hints how the string is currently formatted. Supports Extended Pictures. With some formats the picture acts as a hint only, and another picture may be used if it is a better fit. For example a time value (hh:mm:ss) will be deformatted as @t4 even if the picture passed is @t1.
Return Value

Nothing. The current contents of the object are changed by this call.

Example
st     StringTheory
  code
  st.SetValue('12/31/2022')
  x = st.SetDeformatValue('@d1')
See Also

FormatValue, DeformatValue, SetFormatValue, SetDeformatValue

StringTheory

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

StringTheory

SetFormatValue

SetFormatValue (String pValue, String pPicture)
SetFormatValue (String pPicture)

Description

Sets the contents of the object to the formatted string of a value. Makes use of the StringFormat class.

Parameters
Parameter Description
pValue The value to format. If not passed then the current contents of the object are used.
pPicture The picture that determines how the string is formatted. Supports Extended Pictures.
Return Value

Nothing. The current contents of the object are changed by this call.

Example
st     StringTheory
  code
  st.SetFormatValue(81087,'@d1')
See Also

FormatValue, DeformatValue, SetFormatValue, SetDeformatValue

StringTheory

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
StringTheory

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
StringTheory

SetRandom

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

Description

This is the same as the Random method, except it does not return a value. So it's slightly faster in cases where the object needs to be set, but the return value is not needed.

See Also

Random
StringTheory

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
StringTheory

SetValue

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

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.
pOptions One or more options, that can be added together, which affect the copy. Current options supported are;
st:lines : The Lines associated with NewValue are copied as well (any pre-existing lines in the destination object are removed). If this is omitted (the default default) then only the value is copied, not the lines queue as well, and in that case the lines queue in the destination object is left unaltered.

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

StringTheory

SetValueByAddress

SetValueByAddress(long newValueAddress, long pLength)
Description

Sets the value of the object to the contents of some memory address. Note that this makes a copy of the memory at that address, it does not alter the original memory.

Parameters
Parameter Description
newValueAddress An address in memory.
pLength The number of bytes to copy.

Notes

Passing an invalid length could cause a GPF in the program.

See Also

SetValue, stSetValueByCStringAddress .

StringTheory

SetValueByCStringAddress

SetValueByCStringAddress(long newValueAddress, long pEncoding = -1)
Description

Sets the value of the object to the contents of some memory address. Note that this makes a copy of the memory at that address, it does not alter the original memory. By contrast to SetValueByAddress, this parameter does not take a Length parameter. Rather the length of the string is determined by the contents of the string - in other words the string is null-terminated. Using this method a CString in memory can be copied into a StringTheory object, without first determining the length.

Parameters
Parameter Description
newValueAddress An address in memory.
pEncoding The Encoding of the Cstring. If omitted then the encoding of the current object is used. If the parameter is set the the current object is changed to this encoding. The terminating character(s) depend on the encoding. For ANSI or utf-8, a single null ( aka <0> aka chr(0)) terminates the string. for utf-16 two null characters (<0,0>) are needed, for utf-32 4 null characters (<0,0,0,0>) are needed.

Notes

Passing an address which contains a "never terminating string" could cause a GPF in the program.

See Also

SetValue, SetValueByAddress

StringTheory

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-')
StringTheory

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
StringTheory

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
StringTheory

Squeeze

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

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.
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.
Return Value

None
StringTheory

Start

Start(long pForce=true)

Description

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.

Parameters
Parameter Description
pForce If this is set to true then the memory for the object is released. If set to false then the memory  is retained.

Return Value

None
StringTheory

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

StringTheory

Stream

Stream (string pFilename, long pSize=10, bool pAppendFlag=false)

Description

Stream associates a StringTheory object with a File on the disk. This allows you to write to the object and (transparently) to data is written to the disk instead. The object will cache data (up to the specified size) before FLUSHing to the disk, although some specific methods can trigger an immediate FLUSH as well.

This allows you to create very large strings, but as disk files rather than as strings in memory. Note however that this is only applicable when creating strings, by appending data. Other manipulations of the string (Base64 encoding etc) are not supported, or, more accurately, will continue to work only on the portion of the string which is currently in the object.

For this reason it is recommended that only the following methods are used when streaming is in progress;

Parameters
Parameter Description
pFileName the name of the file on the disk that will be created by this stream.
pSize The size of the StringTheory string, in Megabytes. In other words this is the size of the file write-cache.
pAppendFlag If set to true then the data is appended to the existing file. If false then a new file is created when STREAM is called.
Return Value

st:ok if the command was successful, st:notok if not. If not ok then ErrorTrap will be called.

Example
Example 
st     StringTheory
  code
  st.Stream('C:\temp\log.txt')
  st.append('many things')
  st.Flush()
See Also

Flush , NoStream , Streaming to a Disk file (Write-Caching)

StringTheory

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

StringTheory

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))
StringTheory

Swap

Swap (StringTheory pOther)

Description

Swaps two StringTheory objects .

Parameters
Parameter Description
pOther The object to swap with.
Return Value

Nothing

Example

str1.SetValue('abcde')
str2.SetValue('vwxyz')
str1.swap(str2)

See Also

 

StringTheory

Tail

Tail (Long pLength)

Description

Removes characters from the end of the string

Parameters
Parameter Description
pLength The number of characters to remove. If this value is less than 1 then the string is not changed. If this value is greater than the number of characters in the string, then the string is cleared.
Return Value

The number of characters removed from the string,

Example

str.SetValue('abcde')
str.Tail(2)             ! str now contains 'abc'

See Also

Top, AdjustLength, Length

StringTheory

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
StringTheory

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
StringTheory

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.

Example
Example
c  &cstring
st StringTheory

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

Top

Top (Long pLength)

Description

Removes characters from the front of the string

Parameters
Parameter Description
pLength The number of characters to remove. If this value is less than 1 then the string is not changed. If this value is greater than the number of characters in the string, then the string is cleared.
Return Value

The number of characters removed from the string,

Example

str.SetValue('abcde')
str.Top(2) ! str now contains 'cde'

See Also

Tail, AdjustLength, Length

StringTheory

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 https://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


StringTheory

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
StringTheory

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

st stringtheory
  code
  st.SetValue('This is a "test" of the UPPER method')
  st.upper('"')   ! 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
StringTheory

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

StringTheory

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

In the first case nothing is returned, the object itself is altered. In the second case the encoded string is returned and the object itself is unaltered.

See Also

URLDecode

StringTheory

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

StringTheory

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

StringTheory

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

StringTheory

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

StringTheory

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

StringTheory

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

StringTheory

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 = 'https'

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

See Also

UrlHostOnly, UrlPortOnly, UrlPathOnly, UrlFileOnly, UrlParametersOnly

StringTheory

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.

StringTheory

WordEnd

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

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

Can be set to ST:CONTROLCHARS - this is the same as ST:TEXT, but all control characters (Characters < 31) are considered to be word separators.
pCharList (optional) The list of characters which delineate the end of a word. The default value is
'. <13><10><9>,-;"''!?&()*/+=<>:'  when the TextType parameter is set to ST:TEXT and
'. <13><10><9>,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:HTML and
'. ,-;"''!?&()*/+=<>:' when the TextType parameter is set to ST:CONTROLCHARS
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.

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
StringTheory

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.

Notes

If StartPos is set, and StartPos is a alphabetic character, then startpos will be returned as the start of the word. For example;

str.setvalue('Risk of Collapse')
x = str.GetWord(2) ! x = 2

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

StringTheory

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. The individual lines are also already in the LinesQueue, and can be accessed using any of the Line-Specific methods.

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

StringTheory

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

StringTheory

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.
The null character, CHR(0) , is encoded as #0;
Optionall, the percent symbol can also be encoded (The Notification Services XML vocabulary reserves the percent sign (%) for denoting parameters.)

Parameters
Parameter Description
Options (optional) These options can be added together;
st:Percent : replace % with &#37;
st:IgnoreIfValid : do not re-encode anything of the form &amp; , &lt; , &gt; , &apos; , &quot; &#nn; &#xnn;
st:IgnoreIfNumber : do not re-encode anything of the form &#nn; &#xnn;
st:DecimalEncode128 : convert all characters > chr(127) to the form &#nn;

Return Value

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

See Also

XMLDecode

StringTheory

ZeroXDecode

ZeroXDecode()

Description

Decodes a string which is represented as a hex-encoded-byte-array. Such arrays are common in the source code of some languages, like C, JavaScript etc.


Return Value

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

See Also

ZeroXEncode

StringTheory

ZeroXEncode

ZeroXEncode()

Description

Encodes a string so that it is represented as a hex-encoded-byte-array. Such arrays are common in the source code of some languages, like C, JavaScript etc.

This string is surrounded in square-brackets, and each character in the string is represented by  0xnn where nn is a 2 digit hex number. Characters are comma separated. For example [0x41,0x42,0x43] = ABC.

Return Value

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

See Also

ZeroXDecode

StringTheory

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.

StringTheory

AddLine

AddLine (long LineNumber, String Value)
AddLine (String Value)

Description

Adds the value to 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.

If the LineNumber parameter is omitted then the line is added at the end of the queue.
StringTheory

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.

StringTheory

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
StringTheory

GetLine

GetLine (long LineNumber)

Description

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

See also

Split, SetLine , GetLines .

StringTheory

GetLines

GetLines (long FromLineNumber, Long ToLineNumber, String Separator)

Description

Returns a selection of lines, as a single "joined" string.

Parameters
Parameter Description
FromLineNumber The first line to return.
ToLineNumberThe last line to return. If this is 0, then all the lines from the FirstLineNumber are included in the return value.
SeparatorA string that is places between the lines as they are "joined" back together.

Returns

A single string, containing all the lines selected, separated by the separator.  The contents of the object are unaltered.

See Also

GetLine, Split

StringTheory

InLine

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

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.
Clip (optional) If set to st:clip (the default) then the search value is clipped before searching.

Returns

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

See also
Split, GetLine, SetLine

StringTheory

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.

For example, if a string consists of multiple lines then the multi-character boundary '<13,10>' can be used to split the string into lines.
Quote [optional] The optional Quote parameter allows you to specify a "quote" string which negates the boundary. For example in the following comma separated list, the double quote character wraps a string that negates the comma. For example:
Bruce Johnson, "Cape Town, South Africa"

This string would be parsed into 2 parts, the name and the address. The Quoting characters are included in the parsed result if the RemoveQuotes parameter is not set to true. In the above example the two strings after splitting are:
Bruce Johnson
"Cape Town, South Africa"

The quotes do not have to be at the beginning and end of the field in order to apply. Consider for example the following;

2,here,function(a,b){hello}

If the quote is set as ( and the endquote is set as ) then this will split into 3 lines;
2
here
function(a,b) {hello}

In some cases multiple quotes are necessary. Consider the string
2,function(a,b){add a,b},php

To resolve this to the 3 lines
2
function(a,b){add a,b}
php
it's necessary to specify multiple boundaries in a "something" separated list. (See the Separator below for the something.) To achieve the result above (assuming the separator is a /) the quote parameter would be (/{ and the QuoteEnd parameter would be )/}.

The Quote (and QuoteEnd) parameters are clipped. so spaces are not allowed.
QuoteEnd [optional] If the start, and end, quote strings are different, then the this parameter can be used. For example:

<Bruce Johnson>,<Cape Town, South Africa>

In this case the Quote parameter would be set to '<' and quoteEnd to '>'
RemoveQuotes [optional] If this is set to true then the quotes will be removed from the lines in the Lines Queue. Note that only quotes at the beginning or end of the string will be removed, quotes detected inside the string, although they will apply when splitting the string, will not be removed, even if this parameter is set to true.
Clip [optional] If this parameter is set to true, then the lines are clipped before adding them to the Lines Queue. This can be useful where the file being input contains large amounts of trailing whitespace (spaces) at the end of each line.
Left [optional] If this parameter is set to true, then leading spaces are removed from each line as the lines are created. The default value of this parameter is false.
Separator [optional] If this parameter exists, and is not blank, then the Quote and QuoteEnd parameters are treated as a list, where the list of possible Quote and QuoteEnd pairs are separated by this character. Note that the Quote and QuoteEnd must have the same number of items in them (or the QuoteEnd is omitted, and hence treated as the same as Quote), and only the matching QuoteEnd item matches the Quote item.
The Separator should be a single character. Do not use the Space character as the Separator.
Nested [optional] It's possible that quote and EndQuote characters, if different, can be nested in the string being split. If you want to match the starting and ending pair, ignoring internally nested pairs then set this parameter to true. For example consider

(1,2) , (3,4) , ((5,6),7)

The above string has 3 terms, separated by a comma. Commas inside the brackets are ignored. In the third term though the brackets are nested, and in order to correctly split this into three terms the brackets around the 5,6 must be ignored. To do that set the Nested parameter to true.
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

StringTheory

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 The start string.
pRight The end string.
pNoCase Set this to true to do a case insensitive match.
pExlusive If this is set to true (the default) then the delimiters are not included in the lines. If it is set to false then they are included in the lines.
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


StringTheory

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


StringTheory

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
StringTheory

SplitIntoWords

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

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.
pSmartWords If set to true (the default) then some punctuation (, . / :) between two digits does not count as a word end. This prevents Numbers (formatted as 1,234,56), dates and times, from being split into different words.
Returns

None

See Also

Split, SplitEvery, SplitByMatch, SplitBetween, WordStart
StringTheory

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

StringTheory

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
StringTheory

Records

Records ()

Description

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

See also

Split

StringTheory

SetLine

SetLine (long LineNumber, String Value)
SetLine (long LineNumber, StringTheory 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
StringTheory

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



StringTheory

Filter

Filter (string Include, string Exclude, long NoCase=st:nocase, long Clip=st:clip)

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.
NoCase If set to st:nocase then the Include and Exclude parameters perform a case insensitive search
Clip If set to st:clip then the Include and Exclude parameters are clipped before searching.

 See Also

RemoveLines

Formating and Deformating

Converting Strings between raw data and display using display pictures.
StringTheory

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
StringTheory

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, [long 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, [long 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.
If set to -1, and the string does not contain a null terminator, then the length of the current string is used.
If it is set to 0 then the length of the current string is used, and the unicodeChars is calculated from that.
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.
Classes

StringPicture Class

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

The StringFormat class supports extended pictures that are not supported by the Clarion FORMAT command. The StringPicture class can parse, or create, extended pictures.

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
StringPicture

CreatePicture

CreatePicture(String pType, Long pFlag=0)

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 pic:Time,  pic:TimeHours, pic:Date,  pic:String,  pic:Number,  pic:Scientific, pic:Pattern,  pic:KeyIn,  pic:UnixTimeStamp, pic:Hex

The case of the pType in the created picture is uppercase for most types (where the value is case-insensitive) and either upper or lower case for types P and K (depending on the contents of the Pattern property.)
pFlag 0 by default. Can be one or more of the following;
st:Clarion - if this flag is set then the created picture will be compatible with the limited pictures supported by Clarion.
Any extended picture options will be dropped.
Return Value

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

See also

ParsePicture

StringPicture

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

Picture
picString(252)The complete picture
picTypeString(1)The Type of picture. D, N, S and so on.
Date Pictures (@D)
Fill String(1) If set to '0' then dates are zero padded.
n String(3) The Date Picture Format.
s String(2) Separation character. Only one char is valid for date pictures. This is the char in the picture - ie one of period, grave accent, hyphen,  underscore or space. It is not the character displayed on the screen (that is in the  Separator property)
Separator String(1) The character that appears on the screen when the picture is displayed. The default is /.
Direction String(1) < or > to indicate intellidate direction.
Range String(2) a 2 digit number.
B String(1) If set to 'B' or 'b' then the field is blank if zero.
U String(1) If set to U then the data is in UNIX epoch (seconds) format rather than Clarion format.
MilliString(1)If set to M then the data is in UNIX epoch (milliseconds) format rather than Clarion format.
LocalString(1)If set to L and the data value is 0 then use the local date as the value.
UtcString(1)If set to U and the data value is zero then use the UTC date as the value.
Key-In Pictures (@K) and Pattern Pictures (@P)
Pattern String(255) The pattern.
B String(1) If set to 'B' then the field is blank if zero.
Upper String(1) p or P / k or K respectivly.
Number, Currency (@N) and Decimal Time (@H) Pictures
CurrencyBefore String(10) If set to '$' or 'Whatever' then shown to the left of the number.
SignBefore String(1) set to '-' or '(' or leave blank.
Fill String(1) If set to '0' then numbers are zero padded.
Size String(6) A number, containing the number of characters in the formatted string.
Grouping String(1) The grouping char for each 3 digit group.
Separator String(1) The Decimal Separator.
Places String(6) The number of digits after the decimal separator.
SignAfter String(1) set to '-' or ')' or leave blank.
CurrencyAfter String(10) If set to '$' or 'Whatever' then shown to the right of the number.
B String(1) If set to 'B' or 'b' then the field is blank if zero.
Hex Pictures (@X)
Base Long The base-number of the numbers to display. 10 for decimal, 16 for hexadecimal and so on. Valid values are 2 through 36.
Length String(4) The number of string characters to display per line, before a line break.
s String(2) An optional separator character. If omitted the default is no separator. Use an underscore to separate with a space character.
Separator String(1) The character that appears on the screen between the values when the picture is displayed. The default is blank.
Upper String(1) If x then (hex) numbers are lowercased, if X then (hex) numbers are uppercased.
Scientific Pictures (@E)
Size String(6) A number, containing the number of characters in the formatted string.
s String(2) The Decimal Separator and Grouping character.
Grouping String(1) The grouping char for each 3 digit group.
Separator String(1) The Decimal Separator.
n String(6 The number of digits to the LEFT of the decimal separator.
B String(1) If set to 'B' or 'b' then the field is blank if zero.
String Pictures (@S)
Length String(4) A number, containing the number of characters in the formatted string.
If the picture does not include a length (ie just @S) then this property will be set to -1.
@S0 is considered to be a valid picture, when applied to some raw data it returns a blank string.
The length is not limited to 255 characters.
Time Pictures (@T)
Fill String(1) If set to '0' then dates are zero padded.
n String(3) The Time Picture Format.
s String(2) Separation character. Only one char is valid for time pictures. This is the char in the picture - ie one of period, grave accent, hyphen,  underscore or space. It is not the character displayed on the screen (that is in the  Separator property)
Separator String(1) The character that appears on the screen when the picture is displayed. The default is a colon (:)  .
B String(1) If set to 'B' or 'b' then the field is blank if zero.
U String(1) If set to U then the data is in UNIX format rather than Clarion format.
Z String(1) If set to Z then the time is in "Duration" rather than "Time of Day" form. ie 360000 = 1:00 not 0:59:59
NumberPart String A Numeric picture that describes how the Hours part of the number should be formatted.
LocalString(1)If set to L, and the value is zero, then use local time as the value.
UtcString(1)If set to C and the value is zero then use UTC time as the value.
Unix DateTime stamp Pictures (@U)
    @U pictures are not part of standard Clarion. They format a Unix based TimeStamp value into a date time combination. See StringFormat for more.
n String(3) The U Picture Format.
s String(2) Separation character. Only one char is valid for U pictures. This is the char in the picture. It is not the character displayed on the screen (that is in the  Separator property)
Separator String(1) The character that appears on the screen when the picture is displayed. The default is a T .
datepart String The date picture part of the U picture
timepart String The time picture part of the U picture
Classes

UnixDate Class

UnixDate Introduction

This class consists of some simply utility methods to convert between Clarion date and time values and UNIX date and time values. It acts as a base class for StringFormat and StringDeformat, so these methods are available to those classes.

UnixDate Method Reference

ClarionToUnixDate Takes a Clarion date (long) and a Clarion time (long) and returns the Unix Epoch datetimestamp.
UnixToClarionDate Takes a  Unix Epoch datetimestamp and returns the date part as a Clarion Long.
UnixToClarionTime Takes a  Unix Epoch datetimestamp and returns the time part as a Clarion Long.
UtcDateReturns the current UTC date, in Clarion format.
UtcTimeReturns the current UTC time, in Clarion format.
UtcNowReturns the current UTC date and time as a REAL (milliseconds.)
UnixDate

ClarionToUnixDate

ClarionToUnixDate (Long pDate, Long pTime, Long pMilli=false)

Description

Takes a Clarion date (Long) and a Clarion time (Long) and returns the Unix Epoch datetimestamp.

Parameters
Parameter Description
pDate A LONG containing a Clarion Date.
pTime A LONG containing a Clarion Time.
pMilli Can be True or False (the default). If true then the return value is in thousandths of a second, not seconds.
Return Value

Returns a REAL containing an Unix Epoch time value (in Seconds or Millseconds)

Example

fmt  StringFormat
ut   Real
  code
  ut = fmt.ClarionToUnixDate(today(),clock())


UnixDate

UnixToClarionDate

UnixToClarionDate (Real pDateTime, Long pMilli=-1)

Description

Takes a  Unix Epoch datetimestamp and returns the date part as a Clarion Long.

Parameters
Parameter Description
pDateTime A Unix datetimestamp.
pMilli If set to -1 (the default) then auto-detection of the units for pDateTime is used. In this case values < 2147483647 will be treated as seconds, and values greater than that as milliseconds. You can set pMilli to true to force the value into milliseconds, or false to force it into seconds.
Return Value

Returns a LONG in Clarion date format.

UnixDate

UnixToClarionTime

UnixToClarionTime (Real pDateTime, Long pMilli=-1)

Description

Takes a  Unix Epoch datetimestamp and returns the time part as a Clarion Long.

Parameters
Parameter Description
pDateTime A Unix datetimestamp.
pMilli If set to -1 (the default) then auto-detection of the units for pDateTime is used. In this case values < 2147483647 will be treated as seconds, and values greater than that as milliseconds. You can set pMilli to true to force the value into milliseconds, or false to force it into seconds.
Return Value

Returns a LONG in Clarion time format.

UnixDate

UTCDate

UTCDate ()

Description

Takes a Unix Epoch datetimestamp and returns the date part as a Clarion Long.

Return Value

Returns a LONG in Clarion date format.

UnixDate

UTCTime

UTCTime ()

Description

Takes a Unix Epoch datetimestamp and returns the time part as a Clarion Long.

Return Value

Returns a LONG in Clarion time format.

UnixDate

UTCNow

UTCNow ()

Description

Gets the current UTC time, and returns it as a REAL Unix Epoch datetimestamp in milliseconds.

Return Value

Returns a REAL.

Classes

StringFormat Class

StringFormat Class Introduction

The StringFormat class was created to take raw data in, and convert it to a human-readable display. Inspired by, and building on, the work of the Clarion FORMAT command it takes some of the concepts there and extends them by adding additional pictures and format types.

This class is derived from the UnixDate class, and the methods of that class are in scope here.

Using StringFormat

The Stringformat class consists primarily of a single method, called FormatValue. This takes in some raw data and a picture, using the picture to convert the data to a human readable form.

Example

fmt  StringFormat
  code
  s = fmt.FormatValue(75123,'@d1')

StringFormat Method Reference

This class is derived from the UnixDate class, and the methods of that class are in scope here.
FormatValue Format Raw data, using a picture, to created formatted data suitable for human presentation.
StringFormat

FormatValue

FormatValue (String pValue,<String pPicture>,Long pFlag=0)

Description

Takes in a raw value, and returns a formatted value based on the picture.

All the pictures for the Clarion FORMAT command are supported, and those are not documented here. See the Clarion Help for that documentation.

Parameters
Parameter Description
pValue The Clarion picture to parse. If omitted then the current value in the pic property is parsed.
pPicture The picture to use to format the value. If this parameter is omitted, or blank, then the value is returned as-is.
pFlag st:ExpandIfNeeded : If this flag is passed then values automatically expand if they overflow.
fmt.FormatValue(123,'@n02') returns '##'. The value is larger than the picture allows. Whereas
fmt.FormatValue(123,'@n02',st:ExpandIfNeeded) returns '123'.
Return Value

Returns the data as a formatted string.

Example

str   StringTheory
fmt   StringFormat
now   Real
s     string(24)
  code
  now = str.UtcNow()
  s = fmt.FormatValue(now,'@U2@D10-@T93Z') ! yyyy-mm-ddThh:mm:ss.ccc

See Also

Extended Pictures


StringFormat Property Reference

This class has no properties.
Classes

StringDeformat Class

StringDeformat Class Introduction

The StringFormat class was created to take raw data in, and convert it to a human-readable display. Inspired by, and building on, the work of the Clarion DEFORMAT command it takes some of the concepts there and extends them by adding additional pictures and picture options.

The key difference between the DEFORMAT command and the StringDeformat Class is in the role of the Picture parameter. The DEFORMAT command takes the picture, and reverses the input based on that picture. Nothing else is taken into consideration. The StringDeformat class takes the input and treats the picture as a hint or a guide to deformatting the value. However it looks beyond the picture to deformat the data regardless of the value.

Take TIME pictures as an example. The following (human readable) strings are all unambiguous:
1am, 1pm, 1:00, 1:00am, 1:00 am, 1:00pm, 1:00:00, 1:00:00pm
A human could enter the time as any of these, and they should be automatically deformatted to the correct Clarion Value.
But DEFORMAT does not do this - even though the text is unambiguous, it fails to correctly deal with several of the above options correctly.

The StringDeformat class aims to deformat more possible data options, in a more intelligent, and flexible, way in order to make human input more forgiving and more accurate.

This class is derived from the UnixDate class, and the methods of that class are in scope here.

Using StringDeformat

The StringDeformat class consists primarily of a single method, called DeformatValue. This takes in some formatted data and a picture, and uses the picture (and other heuristics) to convert the data to a raw machine form.

Example

dfmt  StringDeformat
l     long
  code
  l = dfmt.DeformatValue('5/09/19','@d1')

StringDeformat Method Reference

This class is derived from the UnixDate class, and the methods of that class are in scope here.
DeformatValue Deformat formatted data, using a picture, to created raw data suitable for machine storage.
DeformatDate  
DeformatHex  
DeformatPattern  
DeformatTime  
DeformatTimeHours  
DeformatUnixTimeStamp  
StringDeformat

DeformatValue

DeformatValue (String pValue,<String pPicture>)

Description

Takes in a formatted value (entered by a human), and returns a deformatted value suitable for machine storage.

Parameters
Parameter Description
pValue  A formatted value
pPicture An optional picture string indicating the current formatting used by the value. This picture is used as a heuristic to aid in interpreting the value, but the value is not necessarily formatted to this picture. If the picture is omitted, or it does not contain a recognized @ value, then the pValue parameter is returned unaltered.
Notes

This method uses the @ value of the picture (@T, @D etc) to determine which Deformat method to call. If the value is a known type (date, time etc) then the specific DeformatType method can be called instead of this method. For example, if the value is known to be a time then DeformatTime can be called directly in place of a call to this method.

If a StringPicture (@S), or not picture at all, is passed to the method, then the value is returned unaltered.

Return Value

Returns a STRING.

See Also

Extended Pictures

StringDeformat

DeformatDate

DeformatDate(String pValue,<String pPicture>)

Description

Equivalent to calling DeformatValue with an @D picture. 

This method uses the date picture to resolve ambiguity, but only in cases where the date is not "obvious". For example a date such as 1 jan 2019 is unambiguous, as is 12/31/2018 as is 2018/04/05 as is 31/12/2018 and so on. All of these dates can be parsed without a picture, so the picture is ignored. In other cases, such as 05/04/2018 this could mean the 5th of April, or the 4th of May, depending on the format, so in these cases the picture resolves the ambiguity.

If no date picture is supplied then @d1 (mm/dd) is assumed (in cases of ambiguity).

Parameters
Parameter Description
pValue  A formatted value.
pPicture An optional picture string indicating the current formatting used by the value.
U : A U in the time picture indicates the returned value should be in UNIX format, not Clarion format.
Return Value

Returns a REAL containing the Clarion date (the number of days since 29 Dec 1800). In the case of a UNIX value returns a REAL indicating the number of seconds since 1 Jan 1970.

Example

dfmt   StringDeformat
r      long
  code
  r = dfmt.DeformatDate('1 jan 2018')
  r = dfmt.DeformatDate('12/12/12','@d6')
  r = dfmt.DeformatDate('2018 jan 5','@d1u')

See Also

Extended Pictures

StringDeformat

DeformatHex

DeformatHex(String pValue,<String pPicture>)

Description

Equivalent to calling DeformatValue with an @X picture. 

This method converts a string, which contains fixed-numbers, representing characters, into a binary string. For example;

00 00 00 00 could be deformatted to <0,0,0,0> or
41 42 43 44 could be deformatted to 'ABCD'

Parameters
Parameter Description
pValue  A formatted value.
pPicture An optional picture string indicating the current formatting used by the value.
Return Value

Returns a binary STRING. Because of the possibility of chr(0) in the result a CSTRING is not recommended to hold the result.

Example

dfmt   StringDeformat
r      long
  code
  r = dfmt.deformatHex('101 102 103 104','@X0_B8') ! ABCD
See Also

Extended Pictures

StringDeformat

DeformatPattern

DeformatPattern(String pValue,<String pPicture>)

Description

Equivalent to calling DeformatValue with an @P or @K picture. 

This method removes all non-numeric characters from the input, and (possibly) trims the length of the input.

This method behaves somewhat differently to the Clarion DEFORMAT command. The Clarion DEFORMAT command requires that all expected formatting MUST be included in the input. For example;

DEFORMAT('0878280123','@p(###) ### ####p') returns 878012.

By contrast DeformatPattern allows for formatting characters to be excluded. So

dfmt.DeformatValue('0878280123','@p(###) ### ####p') returns 0878280123.


Parameters
Parameter Description
pValue  A formatted (or unformatted) value.
pPicture An optional picture string indicating the current formatting used by the value.  If omitted then the length of the input is not capped.
Return Value

Returns only the numeric characters included in the pValue parameter. If the input contains more numeric characters than indicated in the picture then trailing digits are removed. The return value is a string so leading zeros are not cropped from the return value.

Notes

Three important facts conspire to cause a common programming error.

a) In the pattern # and < are used to represent required and optional digits.
b) The picture to this parameter is passed as a string.
c) In Clarion, putting << into a string results in the compiler changing this to <

Put together, this means that the picture @p<<<<p, when passed as a string actually represents 2, not 4, digits.
To help avoid this error the DeformatPattern command supports the use of the > character in place of the < character in the pattern. The two characters have exactly the same meaning.

Example

dfmt   StringDeformat
s      string
  code
  s = dfmt.deformatPattern('(087) 828 0123','@p(###) ### ####') ! 0878280123
  s = dfmt.deformatPattern('(087) 828 0123','@p(>>>) ### ####') ! 0878280123
  s = dfmt.deformatPattern('(087) 828 0123','@p(<<<<<<) ### ####') ! 0878280123
See Also

Extended Pictures

StringDeformat

DeformatTime

DeformatTime(String pValue,<String pPicture>)

Description

Equivalent to calling DeformatValue with an @T picture.  Supports negative time values as well as time values (durations) greater than 24 hours. Can return time in Clarion format (hundredths of a second) or UNIX format (seconds). Times including a hundredths of a second part (hh:mm:ss:cc) are supported.

Parameters
Parameter Description
pValue  A formatted value.
AM and PM modifiers are only applied to times between 0:00 and 24:00.
pPicture An optional picture string indicating the current formatting used by the value. This picture is used as a heuristic to aid in interpreting the value, but the value is not necessarily formatted to this picture. Most time formats are unambiguous (and will be deformatted without the aid of the picture) the following parts of the pic may impact the result;
U : A U in the time picture indicates the returned value should be in UNIX format, not Clarion format.
Z : A Z in the time picture indicates the value should be returned as a duration (360000=1:00) rather than a Clarion time (360001 = 1:00)
If this parameter is omitted then Clarion time is returned.
Return Value

Returns a REAL containing the time (or duration) in hundredths of a second. (If UNIX time is specified then seconds, not hundredths).
Value can be positive or negative, and can exceed 8640000 (1 day)

Example

dfmt  StringDeformat
r      real
  code
  r = dfmt.DeformatTime('13:22')
  r = dfmt.DeformatTime('13:22:66:33pm')
  r = dfmt.DeformatTime('15:22:66:55','@T91UZ')

StringDeformat

DeformatTimeHours

DeformatTimeHours(String pValue,<String pPicture>)

Description

Equivalent to calling DeformatValue with an @H picture. 

If time is entered as a decimal value (usually when duration is being captured) then it can be converted to a standard clarion time by multiplying by 360000 (one standard clarion hour). This method performs that operation.

Parameters
Parameter Description
pValue  A formatted value.
pPicture An optional picture string indicating the current formatting used by the value.
Return Value

Returns a REAL containing the time in hundredths of a second.

Example

dfmt   StringDeformat
r      long
  code
  r = dfmt.DeformatTimeHours(2.5)
See Also

Extended Pictures

StringDeformat

DeformatUnixTimeStamp

DeformatUnixTimeStamp(String pValue, <String pPicture>)

Description

Equivalent to calling DeformatValue with an @U picture. 

If a date time combination is received as text, then it can be deformatted to a REAL value (number of seconds since 1 Jan 1970) using this method.
The date, and time, parts can then be extracted using the UnixToClarionDate and UnixToClarionTime methods.

Parameters
Parameter Description
pValue  A formatted value.
pPicture An optional picture string indicating the current formatting used by the value.
Return Value

Returns a REAL containing the time in seconds since 1 Jan 1970

Notes

The deformat picture for the common format  2022-01-25T08:20:54-08:00 format is '@U2TM@D10-@T04'

Example

dfmt   StringDeformat
r      real
d      long
t      long
  code
  r = dfmt.DeformatUnixTimeStamp('1 Jan 2019 T 11:55am')
  t = dfmt.UnixToClarionTime(r)
  d = dfmt.UnixToClarionDate(r)
See Also

Extended Pictures

StringDeformat Property Reference

This class has no properties

Support

This template is copyright 2010-2024  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

Version 3.70 - 14 October 2024
Version 3.69 - 30 May 2024
Version 3.68 - 29 May 2024
Version 3.67 -  9 February 2024
Version 3.66 -  22 January 2024
Version 3.65 -  17 January 2024Version 3.64 -  8 November 2023Version 3.63 -  3 October 2023Version 3.62 - 4 August 2023Version 3.61 - 3 July 2023Version 3.60 - 21 June 2023Version 3.59 - 19 June 2023Version 3.58 - 31 May 2023Version 3.57 - 10 May 2023Version 3.56 - 5 May 2023Version 3.55 - 13 April 2023Version 3.54 - 27 February 2023Version 3.53 - 2 November 2022Version 3.52 - 22 August 2022 Version 3.51 - 1 August 2022 Version 3.50 - 1 August 2022 Version 3.49 - 24 July 2022 Version 3.48 - 21 July 2022 Version 3.47 - 20 July 2022 Version 3.46 - 9 May 2022 Version 3.45 - 11 April 2022 Version 3.44 - 6 April 2022 Version 3.43 - 22 November 2021 Version 3.42 - 22 November 2021 Version 3.41 - 19 November 2021 Version 3.40 - 21 October 2021 Version 3.38 - 11 May 2021 Version 3.37 - 6 April 2021 Version 3.36 - 26 March 2021 Version 3.35 - 6 November 2020 Version 3.34 - 5 November 2020 Version 3.33 - 29 October 2020 Version 3.32 - 12 October 2020 Version 3.31 - 7 October 2020 Version 3.30 - 6 October 2020 Version 3.29 - 10 August 2020 Version 3.28 - 15 July 2020 Version 3.27 - 13 July 2020 Version 3.26 - 29 June 2020 Version 3.25 - 26 June 2020 Version 3.24 - 16 June 2020 Version 3.23 - 13 June 2020 Version 3.22 - 10 June 2020 Version 3.21 - 23 March 2020 Version 3.20 - 10 February 2020
Version 3.19 - 6 February 2020 Version 3.18 - 28 January 2020 Version 3.17 - 27 January 2020 Version 3.16 - 23 January 2020 Version 3.15 - 25 October 2019 Version 3.14 - 22 October 2019 Version 3.13 - 9 October 2019 Version 3.12 - 3 September 2019 Version 3.11 - 2 August 2019 Version 3.10 - 13 June 2019 Version 3.09 - 31 May 2019
Version 3.08 - 23 May 2019 Version 3.07 - 16 April 2019 Version 3.06 - 15 March 2019 Version 3.05 - 29 January 2019 Version 3.04 - 28 January 2019 Version 3.03 - 28 January 2019 Version 3.02 - 25 January 2019 Version 3.00 / 3.01 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