Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Using the Text Utilities

Defining Strings

Before you use a string in your application, you must define it in some way. You can use a string variable to represent text characters, or you can allocate an object in the heap to represent those text characters. Many strings, including error messages and lists of input choices, originate in the resource fork of your application; you need access to these string resources before using any of the Text Utilities routines with the strings. This section describes several routines that you can use to allocate strings and to access string resources.

Working With String Handles

When you need to modify a string, it is useful to create a version of the string as an object in the heap. That way, you can increase or reduce the memory allocated for the string object as necessary. String handles provide a means for you to work with heap-oriented strings.

The Text Utilities include two routines that work with strings and string handles. The NewString function creates a copy of a specified string in the heap and returns a handle to that string. The SetString procedure changes the contents of the string referenced by a string handle by copying a specified string into its area of the heap. If you pass SetString a string that is longer than the one originally referenced by the handle, SetString automatically resizes the handle and copies in the contents of the specified string.

For example, suppose that you want to write a routine that creates both an uppercase and lowercase version of an input string. The MyUpperAndLower function shown in Listing 5-1 replaces the contents of the lowerStr parameter with a lowercase version of the str parameter, and returns a new string handle to the uppercase version.

Listing 5-1 Using the NewString and SetString routines

FUNCTION MyUpperAndLower (str: Str255;
                           VAR lowerStr: StringHandle): StringHandle;
VAR
   myStr: StringHandle;
   len: Integer;
BEGIN
   myStr := NewString(str);   {create string handle to be converted to upper}
   SetString( lowerStr, str); {set string handle to be converted to lower}
   len := ord(str[0]);

   HLock(Handle(myStr));      {UppercaseText can move memory}
   UppercaseText(@myStr^^[1], len, smSystemScript);
   HLock(Handle(myStr));

   HLock(Handle(lowerStr));      {LowercaseText can move memory}
   LowercaseText(@lowerStr^^[1], len, smSystemScript);
   HLock(Handle(lowerStr));
   MyUpperAndLower := myStr;
END;

Working With String Resources

Since many of the strings in your Macintosh applications are specified in resource files, you need access to those strings. Strings are defined by two different resource types: the string ('STR ') resource and the string list ('STR#') resource. To work with the string resource, you use the GetString function, and to work with a string list resource, you use the GetIndString procedure.

The GetString function reads a string resource into memory and returns the handle to the string resource as its result. GetString does not copy the string, so you must create your own copy if you are going to modify the string in your application. If the resource has already been read into memory, GetString simply returns a handle to the string.

If you use a number of strings in your application, it is more efficient to specify them in a string list resource rather than as individual resources. This is because the system software that reads in the resources can operate more efficiently when reading a collection of strings from a file than when reading and storing each individually.

To work with an element in a string list, use the GetIndString procedure. It reads the resource, locates the string, and copies the string into a Pascal string variable you supply. You can then use the NewString function to create a copy of the string in the heap, if you wish.