The dBASE String Object

Last Modified: January 31, 2001
Ken Mayer, Senior SQA Engineer
dBASE, Inc.

NOTE: This document was originally written for Visual dBASE 7.0/7.01, it has been updated for dB2K (release 1) and later versions of dBASE to include information about new properties, events, etc., and any new controls since the document was first written. If a control is new it will be noted. In updating this document, the images were left "as is" unless it was felt to be absolutely necessary to change them ...

In addition, this document refers to dB2K a lot, but unless it is about a dB2K specific aspect, the text can be used for Visual dBASE 7.0 through Visual dBASE 7.5.

The Purpose of this Document

dBASE has made character strings very powerful -- with a lot of functionality built-in that the average user has no idea about.

The string object itself has a lot of features, including the ability to generate some HTML (something a lot of folk probably will be surprised to see).

Even more interesting is that any literal character string, and any variable that references a character string, also has the properties and methods of the string class -- automatically!

It is not necessary to create a string object in order to use the functionality of the string object ... we will see this as we look at using it.

Properties and Methods of the String Object

Before we do anything else, let's look at the properties and methods of the string object.

The baseClassName and className properties are read-only and should return "STRING". baseClassName is new to dB2K.
The length property is the length of the character string.
The string property is the actual text or character string.
The anchor method will take the character string and output an HTML anchor tag using the URL passed to the method.
The asc method returns the ASCII value of the first character in the string.
The big method returns the HTML BIG tag (begin/ending tags) with the string as the text.
The blink method tags the character string as 'blinking' (HTML tag).
The bold method tags the character string as 'bold' (HTML tag).
The charAt method returns the character at a specific position in the string. The first character is zero, and the last is string.length-1.
The chr method returns the character equivalent of a specificed ASCII value.
The fixed method tags the string as 'fixed' (HTML TT tags).
The fontColor method sets the font color (HTML tag).
The fontSize method sets the font size (HTML tag).
The getByte method returns the value of the byte at the specified index in the string. (From online help: "Strings in dB2K are Unicode strings, which use double-byte characters. Use getByte() when using a string as a structure that is passed to a DLL function that you have prototyped with EXTERN, to get the values of the bytes in the structure.")
The indexOf method returns the position of the 'search' string inside the string (similar to 'at()').
The isAlpha method returns true if the first character of the string is alphanumeric.
The isDBCS method ???
The isLower method returns true if the first character of the string is in lower case.
The isUpper method returns true if the first character of teh string is in upper case.
The italics method tags the string as italic (HTML tags).
The lastIndexOf method returns the position of the search string, starting the search at the last character in the string (similar to 'rat()').
The left method returns the specified number of characters from the beginning of the string.
The leftTrim method returns the string with all leading spaces removed.
The link method tags the string as an HTML link.
The replicate method returns the specified string a repeated a specified number of times. (Same as 'replicate()').
The right method returns the specified number of characters from the right of the string.
The rightTrim method removes the string with spaces on the right removed. (Same as "trim()").
The setByte method assigns a new value to the byte at the specified position in the string.
The small method tags the string as 'small' (HTML tags).
The space method returns 'n' spaces.
The strike method tags the string as "strikeout" (HTML tags).
The stuff method returns the string with specified characters removed and others inserted in their place. (Same as 'stuff()').
The sub method tags the string as a subscript (HTML tags).
The substring method returns a substring of the specified string. Note that this starts counting at zero and the last character of the string is string.length-1.
The sup method tags the string as a superscript (HTML tags).
The toDBCS method ???
The toLowerCase method returns the string in lower case.
The toProperCase method returns the string in "proper" case.
The toSBCS method ???
The toUpperCase method returns the string in upper case.

These methods are broken into three different types, and we'll look at each below. The types are:

Those that operate on the string;
Those that return HTML tags around the string;
Those that do not operate on the string at all, but return unrelated values.

It should be noted that the methods shown do not change the value of the original string, but return a value, either based on the string, or not, depending on which method is being used. If you wished to convert the contents of a string to all upper case, and keep it that way, you would have to reassign the value:

   sMyString = new String( "This is a string" )
   sMyString.string = sMyString.toUpperCase()

A Detailed Look at The Methods

Creating an Instance of the String
There are a couple of ways you can do this:

   sMyString = new String()
   sMyString.string = "Some Text Here"

   // or 
   sMyString = new String( "Some Text Here" )

   // or (believe it or not!)
   sMyString = "Some Text Here"

Stacking Methods
It is possible, and you will see examples in the following, to stack methods of the string object so that you can avoid creating a whole series of commands.

A simple example might be:

    ? sMyString.left(5).toUpperCase()

This will return the first five characters of the string in all capital letters.

We'll take a look at each of the three types of methods, and various examples will be given so that you can see the results.

Methods That Operate on The String
Most of the methods shown here have direct equivalents in older versions of dBASE, some going all the way back to the beginning of dBASE (dBASE II). A note showing the equivalent will be given for these ...

charAt
The charAt() method returns the character at a specific position in the string. This can be useful if you need to parse a string and find a specific character and manipulate the string based on that character.

Note that this is zero-based -- it means that the first character is actually zero, and if you need to work through the string one character at a time, you would want to check for the stringObj.length-1. If you attempt to go beyond the end of the string no error occurs, but no value is returned.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.charAt( 3 )

This example would return a lower case 's' (this is the fourth character in the string ...).

getByte
This was added to the string object because strings in dB2K are in Unicode. It is sometimes necessary for some functionality to work with bytes rather than dBASE characters. This can be very important when working with the Windows API. Don't ask this author for a lot of details on this one, because frankly, he doesn't know ...

Luckily online help gives a very detailed example of this, so that if you need it, you have a place to look.

indexOf
This method is used to find the location of a string within the actual string object. Keep in mind that the positions are zero based (the first character is zero, the last character is the length of the string - 1). This method is very similar to the at() function in dBASE. The search is case-sensitve, so you may want to use toUpperCase() or toLowerCase() to deal with case insensitive searches. See also lastIndexOf() ...

Examples:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase().indexOf( "IS" )

Will return a numeric 2 (remember that we start counting at zero -- the characters 'is' start at the third position).

If you wanted to start looking at a position other than zero, you can use an optional parameter:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase().indexOf( "IS", 4 )

This tells the indexOf method to start at position four (the fifth character), and should return the numeric value of 5.

If the return value is negative one, then one of the following has occurred:

The search string isn't found
Either the search or target strings are empty
The search string is longer than the target string.

("Target" is the string you are looking in ...)

isAlpha
This returns a true if the first character of the string is alphanumeric. This is equivalent to the dBASE ISALPHA() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.isAlpha()

This should return a value of 'true'.

isLower
This returns a true if the first character of the string is a lower case (alphabetic) character. This is equivalent to the dBASE ISLOWER() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.isLower()

This should return a value of 'false'.

isUpper
This returns a true if the first character of the string is an upper case (alphabetic) character. This is equivalent to the dBASE ISUPPER() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.isUpper()

This should return a value of 'true'.

lastIndexOf
This method is used to find the location of a string within the actual string object. Keep in mind that the positions are zero based (the first character is zero, the last character is the length of the string - 1). This method is the opposite of the indexOf() method, in that it starts the search at the right side of the string. This method is very similar to the RAT() function in dBASE. The search is case-sensitve, so you may want to use toUpperCase() or toLowerCase() to deal with case insensitive searches. See also indexOf() ...

Examples:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase().lastIndexOf( "IS" )

Will return a numeric 5 (remember that we start counting at zero -- the first occurance of the characters 'is' are at position 5, if you start counting from the right)

If you wanted to start looking at a position other than zero, you can use an optional parameter:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase().lastIndexOf( "IS", 4 )

This tells the indexOf method to start at position four (the fifth character), and should return the numeric value of 2.

If the return value is negative one, then one of the following has occurred:

The search string isn't found
Either the search or target strings are empty
The search string is longer than the target string.

("Target" is the string you are looking in ...)

left
The left method returns 'n' characters from the left side of the string, where 'n' is a number you supply to the method. This is the equivalent of the dBASE LEFT() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.left( 6 )

This would return the characters:

This i

leftTrim
The leftTrim() method removes spaces on the left of a character string. This can be useful for situations where, perhaps, you have built up a string through some process, and want to display it now without the extra spaces.

Example:

   sMyString = new String( "     This is some text" )
   ? sMyString.leftTrim()

Without the use of the leftTrim method, we would see:

     This is some text

With the use of it, we see:

This is some text

right
The left method returns 'n' characters from the right side of the string, where 'n' is a number you supply to the method. This is the equivalent of the dBASE RIGHT() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.right( 6 )

This would return the characters:

e text

rightTrim
The rightTrim() method removes spaces on the right of a character string. If you store or reference values from fields in a .DBF, these fields will be padded with spaces -- you can remove them easily ...

Example:

   ? queryName.rowset.fields["first name"].value.rightTrim()+;
       " "+ queryName.rowset.fields["last name"].value

This would trim the spaces from the first name field, add (concatenate) a single space, and then concatenate the last name field to the end of that.

setByte
This was added to the string object because strings in dB2K are in Unicode. It is sometimes necessary for some functionality to work with bytes rather than dBASE characters. This can be very important when working with the Windows API. Don't ask this author for a lot of details on this one, because frankly, he doesn't know ...

Luckily online help gives a very detailed example of this, so that if you need it, you have a place to look.

stuff
The stuff() method is used to replace some characters in a string with other characters. This method is nearly identical with the dBASE STUFF() function, but remember character strings are zero based.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.stuff( 8, 4, "more" )

This replaces the word "some" with the word "more", and you should see:

This is more text

substring
The substring() method is used to extract a number of characters from inside the string. You must specify the beginning position and the ending position of the characters to extract. It is important to remember that this is zero based, so the first character is zero, and the last is string.length-1.

This is similar to the dBASE SUBSTR() function, but is not exactly the same.

Examples:

   sMyString = new String( "This is some text" )
   // three characters starting at the fourth one:
   ? sMyString.substring( 3, 6 )

Should return:

s i

The substring parameters might be defined as the first is the beginning of the character string you wish to extract and is zero based; the second is the end of the string you wish to extract (the last character), and is one based. I.e., in the example above, the first parameter is the fourth character in the string, but you use "3" because it is zero based. The last character is the sixth character in the string, and you use "6" because the second parameter is one based. (Odd, but true.)

toLowerCase
This returns the lower case equivalent of the character string. This is exactly the same as the dBASE LOWER() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.toLowerCase()

This would return the characters:

this is some text

toProperCase
This returns the proper case equivalent of the character string. This is exactly the same as the dBASE PROPER() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.toProperCase()

This would return the characters:

This Is Some Text

toUpperCase
This returns the upper case equivalent of the character string. This is exactly the same as the dBASE UPPER() function.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase()

This would return the characters:

THIS IS SOME TEXT

Methods That Wrap the String in HTML Tags
These can be useful if you want to generate HTML, either for text objects in forms or reports, or if you wanted to actually create an HTML page (using the file object, for example ...). These tags may also work in the editor control if the editor's evalTags property is set to true.

In all cases, the HTML tags have beginning and ending tags associated with them. In some cases you have to pass a parameter to the method, in others you do not.

anchor
The anchor method is used to generate the HTML <A NAME= ...> and </A> tags with the contents of the string between them. This is used in combination with the link tags in HTML (see link below).

Example:

   sMyString = new String( "This is an anchor ..." )
   ? sMyString.anchor( "NameOfAnchor" )

This should display:

   <A NAME="NameofAnchor">This is an anchor ...</A>

big
This method will generate the HTML <BIG> and </BIG> tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, it should be larger than the other text (this is roughly equivalent to ).

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.big()

This should display:

   <BIG>This is some text</BIG>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

blink
This method will generate the HTML <BLINK> and </BLINK> tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, it should blink. This should be used sparingly! A lot of web designers think it is a very poor design tool, and some browsers don't recognize the BLINK tag.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.blink()

This should display:

   <BLINK>This is some text</BLINK>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

bold
This method will generate the HTML and tags with the string itself between them. The text will appear as boldfaced in any HTML enabled control or HTML document ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.bold()

This should display:

   <B>This is some text</B>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

fixed
This method will generate the HTML <TT> and </TT> tags with the string itself between them. The text will appear monospaced ("TeleType") in any HTML enabled control or HTML document ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.fixed()

This should display:

   <TT>This is some text</TT>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

fontColor
This method will generate the HTML and tags with the string itself between them. You must pass the method the color designator. The text will appear in that color (if possible) in any HTML enabled control or HTML document ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.fontColor("RED")

This should display:

   <FONT COLOR="RED">This is some text</FONT>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

Colors in HTML can be set in two ways -- one is by the name of the color (there is a limit as how many colors actually have names ...); the other is to actually specify a hexidecimal string with the RGB values specified. Red = "$FF0000" (the first two characters after the $ are the hex for red, FF means "all the red you got" and lesser values mean less red. 00 in the Green positon means no green, and 00 in the Blue position means no blue ... hence black would be 000000 (no color) and white would be FFFFFF (all colors))

fontSize
This method will generate the HTML and tags with the string itself between them. You must pass the method the font size, between 1 and 7. The text will appear in that size in any HTML enabled control or HTML document ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.fontSize(5)

This should display:

   <FONT SIZE="5">This is some text</FONT>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

Font sizes are 1 through 7, 3 is the default, 7 is largest, 1 is the smallest font. You can also use relative sizes (if you want something to be one font size larger than whatever the current font is, you could use "+1" for the font size, if you wanted to go one size smaller than the current font size you could use "-1"). HTML will ignore values that do not make sense ...

italics
This method will generate the HTML and tags with the string itself between them. The text will appear in italics in any HTML enabled control or HTML document ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.italics()

This should display:

   <I>This is some text</I>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

link
This method will generate the HTML <A HREF="some link"> and tags with the string itself between them. If the link exists, and the user clicks on the tag in a browser, they should be taken to that link. On the other hand, if the link does not exist, or if the user is not in a browser, then nothing will happen.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.link( "http://www.somewhereOverTheRainbow.com" )

This should display:

   <A HREF="http://www.somewhereOverTheRainbow.com">This is some text</A>

In a browser this should look like:

This is some text

small
This method will generate the HTML and tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, it should be smaller than the other text (this is roughly equivalent to ).

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.small()

This should display:

   <SMALL>This is some text</SMALL>

In a browser, or as noted in a text control on a form or report, this should look like:

This is some text

strike
This method will generate the HTML <STRIKE> and </STRIKE> tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, the text will appear to have been "struck out" ...

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.strike()

This should display:

   <STRIKE>This is some text</STRIKE>

In a browser, or as noted in a text control on a form or report, this should look like:

~~This is some text~~

sub
This method will generate the HTML and tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, the text will appear as a subscript (slightly below the line).

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.sub()+" and some other text"

This should display:

   <SUB>This is some text</SUB>  and some other text

In a browser, or as noted in a text control on a form or report, this should look like:

_{This is some text} and some other text.

sup
This method will generate the HTML and tags with the string itself between them. If you display the text in either a text object on a form or report, or in an HTML document, the text will appear as a superscript (slightly above the line).

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.sup()+" and some other text"

This should display:

   <SUP>This is some text</SUP> and some other text

In a browser, or as noted in a text control on a form or report, this should look like:

^{This is some text} and some other text

Methods That Do Not Operate on The String
Note that although these examples use:

   sMyString = new String( "This is some text" )

this is done simply for clarity. These methods will work equally well if you use:

   sMyString = ""

or any other method that creates a string object.

asc
The asc() method is used to return the ASCII (numeric) value of the first character of the string. This is direct equivalent of the ASC() function in dBASE.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.asc( "This" )

This will return the ascii numeric equivalent of "T" which is 84.

chr
The chr() method is used to return the character equivalent of the specified ASCII (numeric) value This is directly equivalent to the CHR() function in dBASE.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.chr( 252 )

This would return:

(small u with an umlaut).

replicate
The replicate() method is used to return 'n' number of a specified character or characters. This is directly equivalent to the REPLICATE() function in dB2K.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.replicate( "*", 5 )

This would return:

*****

space
The space() method is used to return 'n' number of spaces. This is directly equivalent to the SPACE() function in dB2K.

Example:

   sMyString = new String( "This is some text" )
   ? sMyString.space( 5 ) + sMyString.string

This would return:

     This is some text

Using the String Object's Methods

Ok, now that you know what the methods are, there are a couple of other things that it doesn't hurt to know ...

First, any string can use the string object methods. Take a look at the following examples:

   sMyString = new String( "This is some text" )
   ? sMyString.toUpperCase()

   ?"test text".toUpperCase()

   c = "Another test string"
   ?c.toUpperCase()

In all three cases, we displayed the upper case version of the text ... the first is a string object defined as a dBASE object is normally defined. The second is a literal string, and the last is a memory variable.

This gives you a ton of functionality at your fingertips, because this means that any string in your application automatically can use these methods ... you can do the same thing with a rowset's field:

   ? queryName.rowset.fields["somefield"].value.toUpperCase()

As long as the value of the field is character, this will work.

Can you use the string methods on non-string values? Well, yes and no. You can't do it directly, but ... dB2K has a feature called "autoCasting" -- it means that if you combine values of different types, dBASE will sort them out. You couldn't, for example, use the right() method on a date, but you could autocast the date to a string, and use the right() method on that:

   ? d.right( date()+"", 4 )

This would print the right four characters of the date. You can do the same type of thing with numeric values, and more.

Stacking Methods
As shown in other sections of this document, it is possible to "stack" methods, or use methods to affect the returned value of other methods. You might want to combine some HTML and other features:

   ? "this is some text".toProperCase().bold().italics()

This should actually display:

   <I><B>This Is Some Text</B></I>

And when actually displayed either in a text control (on a form or report), an editor control, or an HTML file, you would see:

This Is Some Text

Working Character-by-Character Through String
Something I periodically have to do is search through a string for a specific character.

You can use code along the following lines to do this:

   c = "Some character string * with a star in it"
   for i = 1 to c.length // length of string
       // check character at 'i-1' -- remember, we have
       // to start counting at zero ... see if it's the
       // character we need:
       if c.charAt( i-1 ) == "*"
          // do something
          ? "Found a star"
       endif
    next

Strings and Nulls
If you attempt to concatenate any type of value with a value that evaluates to a null value, the returned value will always become null. (This is sort of like multiplying by zero ...) Example: a field, by default, is null -- if the user does not enter a value, then the value contained in the field is null (unless the developer changes it in the table definition or in some other fashion).

This can be problematic, particularly if you are trying to create reports. The last thing you want is to put together a calculated expression and end up with nothing displaying on the report.

You can actually get around this situation (this is a feature of dB2K, and is working-as-designed) by using the string class. If you pass a string through the String class constructor, and it evaluates to null, the string class will actually make it an empty string.

This example is from online help:

For example, suppose you are combining, first name, middle initial, and last name. The middle initial field may be null. You can safely combine the three like this:

   fullName = firstName + " " + new String( middleInitial + " " ) + ;
              lastName

If the middle initial is null, adding a space to it results in null, and the String object will be an empty string. If the middle initial is not null, adding a space will result in a space between the middle initial and the last name.

Summary

Well, this was a bit on the brief side, but it should give you some ideas on how to manipulate your character strings better ...

DISCLAIMER: the author is an employee of dBASE, Inc., but has written this on his own time. If you have questions regarding this .HOW document, or about dB2K you can communicate directly with the author and dBVIPS in the appropriate newsgroups on the internet.
.HOW files are created as a free service by members of dBVIPS and dBASE, Inc. employees to help users learn to use dB2K more effectively. They are edited by both dBVIPS members and dBASE, Inc. Technical Support (to ensure quality). This .HOW file MAY NOT BE POSTED ELSEWHERE without the explicit permission of the author, who retains all rights to the document.
Copyright 2001, Kenneth J. Mayer. All rights reserved.
Information about dBASE, Inc. can be found at:
       http://www.dbase.com
    

EoHT: STRING.HTM -- January 31, 2001 -- KJM