The Character Service Class
The service class
Character processes character strings in various ways. Internally, this class assumes that all character strings are sequences of 8-bit unsigned bytes -- i.e. with values in the range 0-255. Though not required all current implementations of this class use ASCII or UTF-8 variable length encoding and the descriptions of the methods assume that encoding.
Character.Compare Method
Declaration
<Method id="Compare" type="Integer" opcode="SCM.Character_Compare">
<Argument id="string1" type="String" status="ByVal" />
<Argument id="string2" type="String" status="ByVal" />
<Argument id="nCompare" type="Integer" status="ByVal" />
</Method>
The
Character.Compare method does a case-insensitive comparison between two character vectors. This is a bounded comparison. The null-character is treated exactly like any other special character. If all characters within the specified range are identical, up to case distinctions, then the method returns a zero. If two characters within the specified range disagree, then the value of the character in the first vector minus that in the second vector is returned. The parameters are:
| Parameter | Description |
| string1 | contains the first character vector in the comparison. |
| string2 | contains the second character vector in the comparison. |
| nCompare | specifies the number of characters to be compared. |
Note that the characters within the strings are retrieved and compared as byte values in the range 0 to 255.
This method is used by the engine when it evaluates the relational arguments applied to the string type. The following code shows this as well.
string name1 = "Fred";
string name2 = "Freddy";
Write.Line "Unit test for Character.Compare() Method"
if(name1 != name2) Write.Line(name1 + " does not equal " + name2);
Write.Line("Character.Compare(name1,name2,6) = " + Character.Compare(name1,name2,6));
Write.Line("Character.Compare(name2,name1,6) = " + Character.Compare(name2,name1,6));
Write.Line("Character.Compare(name1,name2,4) = " + Character.Compare(name1,name2,4));
This code produces the following output.
Unit test for Character.Compare() Method
Fred does not equal Freddy
Character.Compare(name1,name2,6) = -68
Character.Compare(name2,name1,6) = 68
Character.Compare(name1,name2,4) = 0
The inequality check fails because the comparison is done over the length of the longest string. The return value is the value in the first string minus the value in the second string as the above shows. Finally, limiting the comparison to the first four characters reports a zero difference.
Character.FindFirst Method
Declaration
<Method id="FindFirst" type="Integer" opcode="SCM.Character_FindFirst" >
<Argument id="source" type="String" status="ByVal" />
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="substr" type="String" status="ByVal" />
</Method>
The
Character.FindFirst method finds the first occurrence of substring in a string starting at the front of the string. All character comparisons are case insensitive. It returns when it finds a first occurrence or when it reaches the end of the string. Its parameters are:
| Parameter | Description |
| source | contains the string which is being searched. |
| iStart | specifies the position relative to zero of the start of the search. |
| substr | contains the substring which is being searched for. |
If all characters within the substring are identical to a sequence of characters within the string, up to case distinctions, then the method returns the position, relative to one, of the start of the matching sequence in the string. If no matching sequence can be located in the string, then a zero is returned. The following code shows this.
string input;
int index;
Write.Line "Unit test for Character.FindFirst() Method"
input = "\fkgtest\FmStocks\src\WebSite\t_begin_cart.asp";
index = Character.FindFirst(input,0,"\");
Write.Line("Index of \ in <" + input + "> is " + index);
input = Character.Replace(input,"\","_");
index = Character.FindFirst(input,0,"\");
Write.Line("Index of \ in <" + input + "> is " + index);
As the output of the code shows
Unit test for Character.FindFirst() Method
Index of \ in <\fkgtest\FmStocks\src\WebSite\t_begin_cart.asp> is 1
Index of \ in <_fkgtest_FmStocks_src_WebSite_t_begin_cart.asp> is 0
The first backslash found in the string is the 1st character, but when backslashes are replaced by underscores it is zero since there are no more backslashes.
Character.HexiDecimal Method
The
HexiDecimal method converts an unsigned integer value into a character string using hexadecimal, decimal, octal, or binary notation.
<Method id="HexiDecimal" type="string" opcode="SCM.Character_HexiDecimal" >
<Argument id="iValue" type="Integer" status="ByVal" />
<Argument id="base" type="Integer" status="ByVal" />
</Method>
Note that the decimal, octal, and binary notation digits are simply subsets of the hexadecimal digits. Its parameters are:
| Parameter | Description |
| iValue | is the integer value to be converted. |
| base | is the base to be used -- 2, 8, 10, or 16. |
The method returns the string containing the character representation. This can be seen in the following code.
void TestHexidecimal
{
int value = 59;
Write.Line "Unit test for Character.HexiDecimal() Method"
Write.Line("Representation of " + value + " as base 2 is: " + Character.HexiDecimal(value,2));
Write.Line("Representation of " + value + " as base 8 is: " + Character.HexiDecimal(value,8));
Write.Line("Representation of " + value + " as base 10 is: " + Character.HexiDecimal(value,10));
Write.Line("Representation of " + value + " as base 16 is: " + Character.HexiDecimal(value,16));
}
This method produces the following result.
Unit test for Character.HexiDecimal() Method
Representation of 59 as base 2 is: 111011
Representation of 59 as base 8 is: 73
Representation of 59 as base 10 is: 59
Representation of 59 as base 16 is: 3b
Character.Insert Method
The
Insert method inserts a substring into a base string starting at a zero-based offset.
<Method id="Insert" type="string" opcode="SCM.Character_Insert" >
<Argument id="source" type="String" status="ByVal" />
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="subStr" type="String" status="ByVal" />
</Method>
Its parameters are:
| Parameter | Description |
| source | base string that receives the substring |
| iStart | zero-based offset in the base string where the insertion is to begin |
| subStr | substring being inserted |
The method returns the result of the insertion. The following code shows how the "?" characters in an SQL select string can be replaced by the "@" character concatenated with an index value.
void TestInsert()
{
string oldSQL = "select * from accounts where accountID < ? and FirstName like ?";
string newSQL = oldSQL;
int index;
int iPos;
int lPos;
Write.Line "Unit test for Character.Insert() Method"
iPos = 0;
for(index = 0; index < 10; index = index + 1)
{
lPos = Character.FindFirst(newSQL,iPos,"?");
if(!lPos) break;
iPos = iPos + lPos - 1;
newSQL = Character.Remove(newSQL,iPos,1);
newSQL = Character.Insert(newSQL,iPos,"@" + index);
}
Write.Line("OLD: " + oldSQL);
Write.Line("NEW: " + newSQL);
}
The output of the method shows the original string and its revised version.
Unit test for Character.Insert() Method
OLD: select * from accounts where accountID < ? and FirstName like ?
NEW: select * from accounts where accountID < @0 and FirstName like @1
Character.Remove Method
The
Remove method forms a new string by removing a specified number of characters from a string starting at a zero-based offset into the string.
<Method id="Remove" type="string" opcode="SCM.Character_Remove" >
<Argument id="strValue" type="string" status="ByVal"/>
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="length" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| strValue | contains the string from which characters are to be removed |
| iStart | specifies the zero-based offset of the first character to be removed. |
| length | specifies the number of characters to be removed. |
The method returns the newly formed string. The code below shows how it can be used to remove certain name-value pairs from a connection string.
void TestRemove()
{
int iPos;
int semi;
string dbs = "UID=stocks_login;PWD=password;Database=stocks;" + "Server=GMI-CS-01.gmi.local;Driver={SQL Server};" + "DSN='';";
string connect = dbs;
Write.Line "Unit test for Character.Remove() Method"
iPos = Character.FindFirst(connect,0,"Driver=");
if(iPos)
{
iPos = iPos - 1;
semi = Character.FindFirst(connect,iPos,";");
if(semi)
{
connect = Character.Remove(connect,iPos,semi);
}
}
iPos = Character.FindFirst(connect,0,"DSN=");
if(iPos)
{
iPos = iPos - 1;
semi = Character.FindFirst(connect,iPos,";");
if(semi)
{
connect = Character.Remove(connect,iPos,semi);
}
}
Write.Line("OLD: " + dbs);
Write.Line("NEW: " + connect);
}
The output of the method shows the connection string before and after the removal.
Unit test for Character.Remove() Method
OLD: UID=stocks_login;PWD=password;Database=stocks;Server=GMI-CS-01.gmi.local;Driver={SQL Server};DSN='';
NEW: UID=stocks_login;PWD=password;Database=stocks;Server=GMI-CS-01.gmi.local;
Character.Replace Method
The
Replace method forms a new string from an existing one in which all occurrences of a specified substring have been replace by a new substring.
<Method id="Replace" type="string" opcode="SCM.Character_Replace" >
<Argument id="source" type="string" status="ByVal"/>
<Argument id="oldStr" type="integer" status="ByVal"/>
<Argument id="newStr" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| source | contains the original string to be modified. |
| oldStr | contains the substring whose occurrences are to be replaced. |
| newStr | contains the replacing substring. |
The method returns the new string. The code below shows examples of this.
void TestReplace
{
string input;
string result;
Write.Line "Unit test for Character.Replace() Method"
input = "\Manual\FmStocks\WebSite\t_begin_cart.asp";
result = Character.Replace(input,"\","_");
Write.Line("Input<" + input + "> result<" + result + ">");
input = "some sort of text/string right here";
result = Character.Replace(input,"right","in");
Write.Line("Input<" + input + "> result<" + result + ">");
input = "Mary had a little lamb.";
result = Character.Replace(input,"lamb","tiger");
Write.Line("Input<" + input + "> result<" + result + ">");
input = "Good dog, good dog";
result = Character.Replace(input, "Good","Bad");
Write.Line("Input<" + input + "> result<" + result + ">");
}
The output of the method shows both the input string and the result string.
Unit test for Character.Replace() Method
Input<\Manual\FmStocks\WebSite\t_begin_cart.asp> result<_Manual_FmStocks_WebSite_t_begin_cart.asp>
Input<some sort of text/string right here> result<some sort of text/string in here>
Input<Mary had a little lamb.> result<Mary had a little tiger.>
Input<Good dog, good dog> result<Bad dog, Bad dog>
Character.Substr Method
The
Substr method forms a new string by extracting a substring from a supplied one.
<Method id="Substr" type="string" opcode="SCM.Character_Substr" >
<Argument id="strValue" type="string" status="ByVal"/>
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="length" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| strValue | is the supplied source string. |
| iStart | is the starting offset in the source string, relative to zero, of the start of the substring. |
| length | is the desired length of the substring. If it is negative or zero, then it is added to the length of the source string to determine its final value. |
The method returns the new string. The following code shows how the method is used to extract the actual reference files from a project file.
void TestSubstr()
{
int vbpRoot;
tInfoFile vbpInfo;
Handle textStream;
int rai;
int length;
string record;
int nRecord;
int curRecord;
int nString;
string refName;
Write.Line "Unit test for Character.Substr() Method"
Store.Open("\Manual\FmStocks\usr\FmStocks.vbi",StorageUnit.USER,0);
vbpRoot = Store.FindVector("\Manual\FmStocks\src\FMStocks_DB.vbp",0);
vbpInfo = Store.GetVector(vbpRoot);
textStream = Text.Open(Store.GetHandle(),vbpInfo.textBase);
nRecord = Text.Maximum(textStream);
curRecord = 0;
while(curRecord < nRecord)
{
curRecord = curRecord + 1;
Text.Position(textStream,curRecord);
record = Text.Access(textStream, length, rai, 0);
if(length > 12)
{
if(Character.Compare(record,"Reference=",10) == 0)
{
nString = length - 10;
refName = Character.Substr(record,10,nString);
Write.Line("Found Reference: " + refName);
}
}
}
Store.Close();
}
The actual reference names found are as follows
Unit test for Character.Substr() Method
Found Reference: *\G{00020430-0000-0000-C000-000000000046}#2.0#0#..\..\..\..\..\WINDOWS\system32\stdole2.tlb#OLE Automation
Found Reference: *\G{00000205-0000-0010-8000-00AA006D2EA4}#2.5#0#..\..\..\..\..\Program Files\Common Files\system\ado\msado25.tlb#Microsoft ActiveX Data Objects 2.5 Library
Found Reference: *\G{2A005C00-A5DE-11CF-9E66-00AA00A3F464}#1.0#0#..\..\..\..\..\WINDOWS\system32\COMSVCS.DLL#COM+ Services Type Library
Character.ToLower Method
The
ToLower method forces the case of any alphabetic characters contained in a specified string to lower-case. Characters that are not alphabetic or that already have lower-case are not changed.
<Method id="ToLower" type="string" opcode="SCM.Character_Tolower" >
<Argument id="strValue" type="string" status="ByVal"/>
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="length" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| strValue | is the string containing the value to be converted. |
| iStart | is the starting relative to zero of the characters to be converted. |
| length | is the number of characters to be considered for conversion. |
The code below shows this.
void TestTolower()
{
string input;
string output;
Write.Line "Unit test for Character.Tolower() Method"
input = "abcdefg"
output = Character.Toupper(input,0,2);
Write.Line("toupper(""" + input + """,0,2) = " + output)
input = Character.Tolower(output,1,1)
Write.Line("tolower(""" + output + """,1,1) = " + input)
}
The first call sets the first two characters to upper case and then the second call sets the second character back to lower case.
Unit test for Character.Tolower() Method
toupper("abcdefg",0,2) = ABcdefg
tolower("ABcdefg",1,1) = Abcdefg
Character.ToUpper Method
The
ToUpper method forces the case of any alphabetic characters contained in a specified string to upper-case. Characters that are not alphabetic or that already have upper-case are not changed.
<Method id="ToUpper" type="string" opcode="SCM.Character_Toupper" >
<Argument id="strValue" type="string" status="ByVal"/>
<Argument id="iStart" type="integer" status="ByVal"/>
<Argument id="length" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| strValue | is the string containing the value to be converted. |
| iStart | is the starting relative to zero of the characters to be converted. |
| length | is the number of characters to be considered for conversion. |
The code below shows this.
void TestToupper()
{
string input;
string output;
Write.Line "Unit test for Character.Toupper() Method"
input = "abcdefg"
output = Character.Toupper(input,0,2);
Write.Line("toupper(""" + input + """,0,2) = " + output)
input = Character.Tolower(output,1,1)
Write.Line("tolower(""" + output + """,1,1) = " + input)
}
The first call sets the first two characters to upper case and then the second call sets the second character back to lower case.
Unit test for Character.Toupper() Method
toupper("abcdefg",0,2) = ABcdefg
tolower("ABcdefg",1,1) = Abcdefg
Character.Unpack Method
The
Unpack method extracts a specified string from a set of strings packed into a single string instance.
<Method id="Unpack" type="string" opcode="SCM.Character_Unpack" >
<Argument id="strValue" type="string" status="ByVal"/>
<Argument id="iStart" type="integer" status="ByVal"/>
</Method>
Its parameters are:
| Parameter | Description |
| strValue | contains the packed set of strings. |
| iStart | is the index relative to one of the desired string. |
The method returns the unpacked string. One of the packed string sets used by
gmBasic contains the handler and argument class names for an event. The code here extracts these for the individual events in the
ADODB.ConnectionEvents class.
void TestUnpack()
{
int classRoot;
int compRoot;
tLibComp libComp;
int evtType;
string evtInfo;
Write.Line "Unit test for Character.Unpack() Method"
Store.Open("\Manual\FmStocks\usr\FmStocks.vbi",StorageUnit.USER,0);
classRoot = Symbol.FindIdentifier("ADODB.ConnectionEvents" ,0);
for(compRoot = Store.GetFirst(classRoot); compRoot != 0; compRoot = Store.GetNext(compRoot))
{
libComp = Store.GetVector(compRoot);
if(libComp.refType == ComponentType.EVENT)
{
evtType = libComp.type;
if(evtType > Defines.OPC_MAXIMUM)
{
evtInfo = Store.GetString(evtType);
Write.Line("Event components for:" + Store.GetName(compRoot));
Write.Line(" Handler:" + Character.Unpack(evtInfo,0));
Write.Line(" Args:" + Character.Unpack(evtInfo,1));
}
}
}
Store.Close();
}
The result of the scan and unpacking is shown below.
Unit test for Character.Unpack() Method
Event components for:InfoMessage
Handler:ADODB.ConnectionEvents_InfoMessageEventHandler
Args:ADODB.ConnectionEvents_InfoMessageEvent
Event components for:BeginTransComplete
Handler:ADODB.ConnectionEvents_BeginTransCompleteEventHandler
Args:ADODB.ConnectionEvents_BeginTransCompleteEvent
Event components for:CommitTransComplete
Handler:ADODB.ConnectionEvents_CommitTransCompleteEventHandler
Args:ADODB.ConnectionEvents_CommitTransCompleteEvent
Event components for:RollbackTransComplete
Handler:ADODB.ConnectionEvents_RollbackTransCompleteEventHandler
Args:ADODB.ConnectionEvents_RollbackTransCompleteEvent
Event components for:WillExecute
Handler:ADODB.ConnectionEvents_WillExecuteEventHandler
Args:ADODB.ConnectionEvents_WillExecuteEvent
Event components for:ExecuteComplete
Handler:ADODB.ConnectionEvents_ExecuteCompleteEventHandler
Args:ADODB.ConnectionEvents_ExecuteCompleteEvent
Event components for:WillConnect
Handler:ADODB.ConnectionEvents_WillConnectEventHandler
Args:ADODB.ConnectionEvents_WillConnectEvent
Event components for:ConnectComplete
Handler:ADODB.ConnectionEvents_ConnectCompleteEventHandler
Args:ADODB.ConnectionEvents_ConnectCompleteEvent
Event components for:Disconnect
Handler:ADODB.ConnectionEvents_DisconnectEventHandler
Args:ADODB.ConnectionEvents_DisconnectEvent
Mark Juras