Important: The information in this document is obsolete and should not be used for new development.
Munger
TheMunger
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 theh
parameter. The manipulation begins at a byte offset, specified inoffset
, in the string. Munger searches for the string specified byptr1
andlen1
; when it finds an instance of that string, it replaces it with the substitution string, which is specified byptr2
andlen2
.
- IMPORTANT
Munger
operates on a byte-by-byte basis, which can produce inappropriate results for 2-byte script systems. TheReplaceText
function works properly for all languages. You are encouraged to useReplaceText
instead ofMunger
whenever possible.Munger
takes special action if either of the specified pointer values isNIL
or if either of the length values is0
.
- If
ptr1
isNIL
,Munger
replaces characters without searching. It replaceslen1
characters starting at theoffset
location with the substitution string.- If
ptr1
isNIL
andlen1
is negative,Munger
replaces all of the characters from theoffset
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 theoffset
location and returns the offset of the first byte past where the insertion occurred.- If
ptr2
isNIL
,Munger
searches but does not replace. In this case,Munger
returns the offset at which the string was found.- If
len2
is 0 andptr2
is notNIL
,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 thatMunger
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 theGetHandleSize
andSetHandleSize
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 theMunger
function is
Trap macro _Munger