Legacy Document

Inside Macintosh: Text /

Chapter 5 - Text Utilities / Text Utilities Reference

Routines / Searching for and Replacing Strings

Munger

The Munger function searches text for a specified string pattern and replaces it with another string.

FUNCTION Munger (h:  Handle; offset: LongInt; ptr1: Ptr;
                len1: LongInt; ptr2: Ptr; len2: LongInt): LongInt;

h

A handle to the text string that is being manipulated.

offset

The byte offset in the destination string at which Munger begins
its operation.

ptr1

A pointer to the first character in the string for which Munger is searching.

len1

The number of bytes in the string for which Munger is searching.

ptr2

A pointer to the first character in the substitution string.

len2

The number of bytes in the substitution string.

DESCRIPTION

Munger manipulates bytes in a string to which you specify a handle in the h parameter. The manipulation begins at a byte offset, specified in offset, in the string. Munger searches for the string specified by ptr1 and len1; when it finds an instance of that string, it replaces it with the substitution string, which is specified by ptr2 and len2.

IMPORTANT

Munger operates on a byte-by-byte basis, which can produce inappropriate results for 2-byte script systems. The ReplaceText function works properly for all languages. You are encouraged to use ReplaceText instead of Munger whenever possible.

Munger takes special action if either of the specified pointer values is NIL or if either of the length values is 0.

• If ptr1 is NIL, Munger replaces characters without searching. It replaces len1 characters starting at the offset location with the substitution string.
• If ptr1 is NIL and len1 is negative, Munger replaces all of the characters from the offset location to the end of the string with the substitution string.
• If len1 is 0, Munger inserts the substitution string without replacing anything. Munger inserts the string at the offset location and returns the offset of the first byte past where the insertion occurred.
• If ptr2 is NIL, Munger searches but does not replace. In this case, Munger returns the offset at which the string was found.
• If len2 is 0 and ptr2 is not NIL, Munger searches and deletes. In this case, Munger returns the offset at which it deleted.
• If the portion of the string from the offset location to its end matches the beginning of the string that Munger is searching for, Munger replaces that portion with the substitution string.

Munger returns a negative value when it cannot find the designated string.

WARNING

Be careful not to specify an offset with a value that is greater than the length of the destination string. Unpredictable results may occur.

SPECIAL CONSIDERATIONS

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

The destination string must be in a relocatable block that was allocated by the
Memory Manager.

SEE ALSO

Munger calls the GetHandleSize and SetHandleSize routines to access or modify the length of the string it is manipulating. These routines are described in the book Inside Macintosh: Memory Manager.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro for the Munger function is

Trap macro
_Munger