Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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


Code Block
languagexml
themeEclipse
linenumberstrue
<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
string1contains the first character vector in the comparison.
string2contains the second character vector in the comparison.
nComparespecifies 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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


Code Block
languagexml
themeEclipse
linenumberstrue
<Method id="FindFirst" type="Integer" opcode="SCM.Character_FindFirst" >
   <Argument id="source" type="String" status="ByVal" />
   <Argument id="
length
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
sourcecontains the string which is being searched.
length
iStartspecifies the
length
position relative to zero of the start of the search
range or zero, which indicates that the entire string is to be searched
.
substrcontains 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
iValueis the integer value to be converted.
baseis 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
sourcebase string that receives the substring
iStartzero-based offset in the base string where the insertion is to begin
subStrsubstring 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
strValuecontains the string from which characters are to be removed
iStartspecifies the zero-based offset of the first character to be removed.
lengthspecifies 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
sourcecontains the original string to be modified.
oldStrcontains the substring whose occurrences are to be replaced.
newStrcontains the replacing substring.


The method returns the new string. The code below shows examples of this.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
strValueis the supplied source string.
iStartis the starting offset in the source string, relative to zero, of the start of the substring.
lengthis 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
strValueis the string containing the value to be converted.
iStartis the starting relative to zero of the characters to be converted.
lengthis the number of characters to be considered for conversion.


The code below shows this.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
strValueis the string containing the value to be converted.
iStartis the starting relative to zero of the characters to be converted.
lengthis the number of characters to be considered for conversion.


The code below shows this.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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.


Code Block
languagexml
themeEclipse
linenumberstrue
<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
strValuecontains the packed set of strings.
iStartis 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.


Code Block
languagecpp
themeEclipse
linenumberstrue
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.


Code Block
languagenone
themeEclipse
linenumberstrue
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
Panel
bgColorCCFFFF
titleTable of Contents

Table of Contents