#ifndef TEXTUTILS_H
#define TEXTUTILS_H

#ifndef MACTYPES_H
#include <CarbonCore/MacTypes.h>
#endif

#ifndef NUMBERFORMATTING_H
#include <CarbonCore/NumberFormatting.h>
#endif

#ifndef STRINGCOMPARE_H
#include <CarbonCore/StringCompare.h>
#endif

#ifndef DATETIMEUTILS_H
#include <CarbonCore/DateTimeUtils.h>
#endif


#include <HYS/CarbonCore/TextUtils.h>
#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*Munger

Searches text for a specified string pattern and replaces it with another string.

long Munger (
   Handle h,
   long offset,
   const void * ptr1,
   long len1,
   const void * ptr2,
   long len2
);
Parameters
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.
Return Value

A negative value if Munger cannot find the designated string. 
Discussion

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.

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 NULL or if either of the length values is 0.
If ptr1 is NULL, Munger replaces characters without searching. It replaces len1 characters starting at the offset location with the substitution string. 
If ptr1 is NULL 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 NULL, 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 NULL, 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. 

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

Munger calls the GetHandleSize and SetHandleSize functions to access or modify the length of the string it is manipulating. 
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.
Availability
Available in Mac OS X v10.0 and later.
Declared In
TextUtils.h*/
long Munger (
   Handle h,
   long offset,
   const void * ptr1,
   long len1,
   const void * ptr2,
   long len2
);

/*GetIndString

Loads a string from a string list ('STR#') resource into memory, given the resource ID of the string list and the index of the individual string. (Deprecated in Mac OS X v10.4. Use CFBundleCopyLocalizedString instead.)

void GetIndString (
   Str255 theString,
   short strListID,
   short index
);
Parameters
theString

On output, the Pascal string result; specifically, a copy of the string from a string list that has the resource ID provided in the strListID parameter. If the resource that you specify cannot be read or the index that you specify is out of range for the string list, GetIndString sets theString to an empty string. 
strListID

The resource ID of the 'STR#' resource that contains the string list. 
index

The index of the string in the list. This is a value from 1 to the number of strings in the list that is referenced by the strListID parameter.
Discussion

If necessary, GetIndString reads the string list from the resource file by calling the Resource Manager function GetResource. GetIndString accesses the string specified by the index parameter and copies it into theString. 
Special Considerations

GetIndString may move memory; your application should not call this function at interrupt time.
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/
void GetIndString (
   Str255 theString,
   short strListID,
   short index
);

/*CopyCStringToPascal

Converts a C string to a Pascal string. (Deprecated in Mac OS X v10.4. You should store strings as Core Foundation CFStrings instead. See CFString Reference.)

void CopyCStringToPascal (
   const char * src,
   Str255 dst
);
Parameters
src

The C string you want to convert.
dst

On output, the Pascal string.
Discussion

This function allows in-place conversion. That is, the src and dst parameters can point to the memory location.
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/

void CopyCStringToPascal (
   const char * src,
   Str255 dst
);

/*GetString

Loads a string from a string ('STR') resource into memory. (Deprecated in Mac OS X v10.4. Use CFBundleCopyLocalizedString instead.)

StringHandle GetString (
   short stringID
);
Parameters
stringID

The resource ID of the string ('STR ') resource containing the string. 
Return Value

A handle to a string with the specified resource ID. If necessary, GetString reads the handle form the resource file. If GetString cannot read the resource, it returns NULL. 
Discussion

GetString calls the GetResource function of the Resource Manager to access the string. This means that if the specified resource is already in memory, GetString simply returns its handle.

Like the NewString function, GetString returns a handle whose size is based upon the actual length of the string.

If your application uses a large number of strings, it is more efficient to store them in a string list ('STR#') resource than as individual resources in the resource file. You then use the GetIndString function to access each string in the list. 
Special Considerations

GetString does not create a copy of the string.

GetString may move memory; your application should not call this function at interrupt time.
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/
StringHandle GetString (
   short stringID
);

/*UpperString

Converts any lowercase letters in a Pascal string to their uppercase equivalents, using the Macintosh file system rules. (Deprecated in Mac OS X v10.4. Use CFStringUppercase instead.)

void UpperString (
   Str255 theString,
   Boolean diacSensitive
);
Parameters
theString

On input, this is the Pascal string to be converted. On output, this contains the string resulting from the conversion. UpperString traverses the characters in theString and converts any lowercase characters with character codes in the range 0x00 through 0xD8 into their uppercase equivalents. UpperString places the converted characters in theString. 
diacSensitive

A flag that indicates whether the case conversion is to strip diacritical marks. If the value of this parameter is TRUE, diacritical marks are considered in the conversion; if it is FALSE, any diacritical marks are stripped. 
Discussion

Only a subset of the Roman character set (character codes with values through $D8) are converted. Use this function to emulate the behavior of the Macintosh file system. 
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/

void UpperString (
   Str255 theString,
   Boolean diacSensitive
);

/*c2pstrcpy

Converts a C string to a Pascal string. (Deprecated in Mac OS X v10.4. You should store strings as Core Foundation CFStrings instead. See CFString Reference.)

void c2pstrcpy (
   Str255 dst,
   const char * src
);
Parameters
dst

On output, the Pascal string.
src

The C string you want to convert.
Discussion

This function allows in-place conversion. That is, the src and dst parameters can point to the memory location.
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/
void c2pstrcpy (
   Str255 dst,
   const char * src
);


/*CopyPascalStringToC

Converts a Pascal String to a C string. (Deprecated in Mac OS X v10.4. You should store strings as Core Foundation CFStrings instead. See CFString Reference.)

void CopyPascalStringToC (
   ConstStr255Param src,
   char * dst
);
Parameters
src

The Pascal string you want to convert.
dst

On output, the C string.
Discussion

This function allows in-place conversion. That is, the src and dst parameters can point to the same memory location.
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
TextUtils.h*/

void CopyPascalStringToC (
   ConstStr255Param src,
   char * dst
);



#ifdef __cplusplus
}
#endif

#endif
