Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Text Utilities Reference

Routines / Defining and Specifying Strings

NewString

The NewString function allocates memory in the heap for a string, copies its contents, and produces a handle for the heap version of the string.

FUNCTION NewString (theString: Str255): StringHandle;

theString

A Pascal string that you want copied onto the heap.

DESCRIPTION

NewString returns a handle to the newly allocated string. If the string cannot be allocated, NewString returns NIL. The size of the allocated string is based on the actual length of theString, which may not be 255 bytes.

Note

Before using Pascal string functions that can change the length of the string, it is a good idea to maximize the size of the string object on the heap. You can call either the SetString procedure or the Memory Manager procedure SetHandleSize to modify the string's size.

SPECIAL CONSIDERATIONS

NewString may move memory; your application should not call this function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for the NewString function is

Trap macro
_NewString