Download

Icetips Utilities: String Class Tutorial

String Class   (ITStringClass)

The String Class contains 45 methods as of version 1.2.2433 that was released on June 29, 2015. It includes several very useful methods to handle strings and text files. Note that not all of the methods are documented as of that release.

Below are short tutorials on how to accomplish various things with this class. The tutorials are short and demonstrate simple use of the methods. For more detailed documentation of the string class please see the online documentation. This tutorial is also included in the documentation.

Reading and writing text files

Export comma separated files

Export XML files

Create lines from strings

Removing spaces and punctuation from strings

Reading and writing text files

The String class has a method, ReadFileToString, to read a text file directly into a string buffer that is dynamically allocated by the string and is big enough to read the entire file into it. No file drivers or clarion files are used, rather the method uses API to open the file and read from it. Reading the file is extremely fast and once read, the entire content of the file is stored in the FileString property of the String class.

ITS  ITStringClass
 Code
 ITS.ReadFileToString('C:\Temp\Filename.txt')

Once this code executes, the entire contents of C:\Temp\Filename.txt is in the ITS.FileString property and you can do with it what you want.

A related method is the WriteStringToFile. This is the opposite of ReadFileToString as it takes a string and writes it to a file.

Example:

ITS  ITStringClass
S    String(1024) ! 1K buffer
 Code
 S = 'This is a test<13,10>writing to a text file!'
 ITS.WriteStringToFile('C:\Temp\Filename.txt',S)

This will create a text file that would look like this:

This is a test
writing to a text file!

Export comma separated files

There is a third method to write to files, WriteQToFile, that is used along with the AddLine method to build up a text file. This is very convenient for example to create all kinds of export files, i.e. comma separated files to transfer data from one program to another.

Example:

ITS  ITStringClass
Fn   CString(2049)
 Code
 Set(CUS:NameKey)
 ITS.AddLine('Name,Email,Address,State,PostalCode,Country',True)
 Loop
   If Access:Customers.Next() <> LEVEL:Benign
     Break
   End
   ITS.AddLine('"' & Clip(CUS:Name) & '",' &|
               '"' & Clip(CUS:Email) & '",' &|
               '"' & Clip(CUS:Address) & '",' &|
               '"' & Clip(CUS:State) & '",' &|
               '"' & Clip(CUS:PostalCode)  & '",' &|
               '"' & Clip(CUS:Country) & '"')
 End
 If FileDialog('Save CSV file',Fn,|
    'Export files (*.csv)|*.csv|All files (*.*)|*.*',|
               FILE:Save + FILE:KeepDir + FILE:LongNames)
   ITS.WriteQToFile(Fn)
 End

As with the ReadFileToString and WriteStringToFile there are no file drivers involved, just API codes that makes this very fast. The first line is added right before the loop. The second parameter tells the class to free the queue before it starts adding to it, i.e. by using True as the second parameter you are telling the class that this is the first line. Each loop through the data file adds a single line to the queue that holds the lines, ITS.Lines. After the loop is done going through the data a Save dialog is opened to get the filename for the file and the contents of the queue are written to the selected file. Note that you can place CR+LF charcters into the line string thus building up more than one line to write into the text file.

Export XML files

Exporting to XML is certainly possible using the String Class. Since xml files are much more flexible than CSV files the way you do it completely depends on how you need the xml file to look.

Example:

ITS  ITStringClass
Fn   CString(2049)
I    Long
 Code
 
 ITS.AddLine('<?xml version="1.0" ?>',True)  !! First line

 Loop I = 1 To 10
   ITS.AddLine('  <item>' & I & '</item>')
 End
 If FileDialog('Save XML',Fn,|
    'XML (*.xml)|*.xml',FILE:Save + FILE:KeepDir + FILE:LongName)
   ITS.WriteQToFile(Fn)
 End

This produces a very simple xml that will look like this:

<?xml version="1.0" ?>
  <item>1</item>
  <item>2</item>
  <item>3</item>
  <item>4</item>
  <item>5</item>
  <item>6</item>
  <item>7</item>
  <item>8</item>
  <item>9</item>
  <item>10</item>

Obviously this is an extremely simple example, but it demonstrates how you could construct xml one line at the time, without too much effort.

Create lines from strings

One of the features of the string class is the ability to split a string into lines using the SplitString method. This means that you can make it split a text file that you have read with ReadFileToString into lines and then use the lines rather than use the string buffer directly.

Example:

ITS  ITStringClass
I    Long
Q    Queue
OneLine CString(1025)
     End

Window WINDOW('Lines'),AT(,,260,100),GRAY
       LIST,AT(13,10,234,81),USE(?List1),VSCROLL,|
         FONT('Courier New',9,,),FORMAT('1024L(2)'),FROM(Q)
     END

 Code
 ITS.ReadFileToString('Export.clw')
 ITS.SplitString(ITS.FileString,'<13,10>')
 ITS.DumpLinesInQ(Q,Q.OneLine)
 Open(Window)
 Display
 Accept
 End
 Close(Window)
 Free(Q)

This code reads in a file called Export.clw and displays it in a listbox. Note that you need version 1.1.2352 or later of the Icetips Utilities for this code to work as the DumpLinesInQ was added in 1.1.2352. This code uses the SplitString to split the string using the CR+LF as delimiter, i.e. to indicate where the string should split. Note that you cannot use the ITS.Lines queue directly in a listbox because the data is contained in a reference variable. Hence the need for a local queue and the DumpLinesInQ method.

You can use the SplitString to split any string using any delimiter that you want, for example the pipe character, '|', if you have a pipe delimited string that you want to split up.

Example:

ITS  ITStringClass
I    Long
S    String(100)
X    CString(101)
R    Long
 Code
 S = 'First|Second|Third|Fourth|Fifth'
 ITS.SplitString(S,'|')
 R = Records(ITS.Lines)
 Loop I = 1 To R
   Get(ITS.Lines,I)
   X = X & ITS.Lines.OL & Choose(I<R,' + ','')
 End
 Message('New string = ' & X)

Removing spaces and punctuation from strings

The String class has a method called CompactString. It can be very useful for all kinds of purposes, particularly as a sort field in queues where names or words may be typed differently. It is also invaluable when comparing strings that may be typed differently when the difference is not just the case, which can be worked around with Upper() or Lower(). All punctuation and spaces are removed from the string and it can optionally be set to all upper case to eliminate case sensitivity.

Example:

ITS  ITStringClass
S1    String(100)
S2    String(100)

 Code
 S1 = 'This is a test to show how a string is compacted!'
 S2 = 'This.is.a.test.to.show.how.a.string.is.compacted!'
 If S1 = S2
   Message('String S1 and S2 are the same before Compacting')
 Else
   Message('String S1 and S2 are NOT the same before Compacting|' &|
             S1 & '|' & S2)
 End
 S1 = ITS.CompactString(S1,True)
 S2 = ITS.CompactString(S2,True)
 If S1 = S2
   Message('String S1 and S2 are the same after Compacting|' &|
           S1 & '|' & S2)
 Else
   Message('String S1 and S2 are NOT the same after Compacting|' &|
            S1 & '|' & S2)
 End

Here I used a period between each word to make them different. The text is exactly the same. Those two strings are not equal in comparison and obviously will show the "String S1 and S2 are NOT the same before Compacting" message. After the compacting however, since all the punctuation and spaces are gone the two strings match as: "THISISATESTTOSHOWHOWASTRINGISCOMPACTED"

How to buy

The String Class is part of the Icetips Utilities, which are included Icetips' premium high-value Gold Subscription for $299. The Icetips Utilities may also be purchased separately for just $99.  (Multiple copy pricing is available.)