Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Text /: Chapter 5 - Text Utilities

Summary of Text Utilities

Pascal Summary

Constants

CONST
         {StringToDate and StringToTime status values }
   longDateFound     = 1;     {mask to long date found}
   leftOverChars     = 2;     {mask to warn of left over chars}
   sepNotIntlSep     = 4;     {mask to warn of non-standard separators}
   fieldOrderNotIntl = 8;     {mask to warn of non-standard field order}
   extraneousStrings = 16;    {mask to warn of unparsable strings in text}
   tooManySeps       = 32;    {mask to warn of too many separators}
   sepNotConsistent  = 64;    {mask to warn of inconsistent separators}
   fatalDateTime     = $8000; {mask to a fatal error}
   tokenErr = $8100;          {mask for 'tokenizer err encountered'}
   cantReadUtilities = $8200; {mask for can't access needed resource}
   dateTimeNotFound = $8400;  {mask for date or time not found}
   dateTimeInvalid = $8800;   {mask for date/time format not valid}
         {Constants for truncWhere argument in TruncString and TruncText} 
   truncEnd       = 0;        {truncate at end}
   truncMiddle    = $4000;    {truncate in middle}
         {Constants for TruncString and TruncText results}
   NotTruncated   = 0;        {no truncation was necessary}
   Truncated      = 1;        {truncation performed}
   TruncErr       = -1;       {general error}
         {Special language code values for Language Order}
systemCurLang  = -2; { current language for system script (from 'itlb')}
systemDefLang  = -3; { default language for system script (from 'itlm')}
currentCurLang = -4; { current language for current script (from 'itlb')}
currentDefLang = -5; { default language for current script (from 'itlm')}
scriptCurLang  = -6; { current lang for specified script (from 'itlb')}
scriptDefLang  = -7; { default language for specified script (from 'itlm')}

Data Types

TYPE

FormatStatus = Integer;

TruncCode = Integer;

DateForm = (shortDate,longDate,abbrevDate);
FormatResultType = 
(fFormatOK,fBestGuess,fOutOfSynch,fSpuriousChars,fMissingDelimiter,
   fExtraDecimal,fMissingLiteral,fExtraExp,fFormatOverflow,fFormStrIsNAN,
   fBadPartsTable,fExtraPercent,fExtraSeparator,fEmptyFormatString);
FormatClass = (fPositive,fNegative,fZero);
StyledLineBreakCode = {BreakWord, BreakChar, BreakOverflow};
DateCacheRecord =
PACKED RECORD
   hidden: ARRAY [0..255] OF Integer;{only for temporary use}
END;

DateCachePtr = ^DateCacheRecord;
NumFormatStringRec =
PACKED RECORD
   fLength: Byte;
   fVersion: Byte;
   data: PACKED ARRAY [0..253] OF SignedByte;   {private data}
END;
FVector = 
RECORD
   start: Integer;
   length: Integer
END;

TripleInt = ARRAY[0..2] OF FVector;          {index by [fPositive..fZero]}
OffPair =
RECORD
   offFirst: Integer;
   offSecond: Integer;
END;

OffsetTable = ARRAY[0..2] OF OffPair;
ScriptRunStatus =
RECORD
   script: SignedByte;
   variant: SignedByte;
END;

Routines

Defining and Specifying Strings

FUNCTION NewString         (theString: Str255): StringHandle;
PROCEDURE SetString        (theString: StringHandle; strNew: Str255);
FUNCTION GetString         (stringID: Integer): StringHandle;
PROCEDURE GetIndString     (VAR theString: Str255; strListID: Integer; 
                            index: Integer);

Comparing Strings for Equality

FUNCTION EqualString       (aStr, bStr: Str255;
                            caseSens, diacSens: Boolean): Boolean;
FUNCTION IdenticalString   (aStr, bStr: Str255;
                            itl2Handle: Handle): Integer;
FUNCTION IdenticalText     (aPtr, bPtr: Ptr; aLen, bLen: Integer; 
                            itl2Handle: Handle): Integer;

Determining Sorting Order for Strings in Different Languages

FUNCTION ScriptOrder       (script1, script2: ScriptCode): Integer;
FUNCTION LanguageOrder     (lang1, lang2: LangCode): Integer;
FUNCTION StringOrder       (aStr, bStr: Str255; aScript, bScript: 
                            ScriptCode; aLang, bLang: LangCode): Integer;
FUNCTION TextOrder         (aPtr, bPtr: Ptr; aLen, bLen: Integer;
                            aScript, bScript: ScriptCode;
                            aLang, bLang: LangCode): Integer;

Determining Sorting Order for Strings in the Same Language

FUNCTION RelString         (aStr, bStr: Str255;
                            caseSens, diacSens: Boolean): Integer;
FUNCTION CompareString     (aStr, bStr: Str255;
                            itl2Handle: Handle): Integer;
FUNCTION CompareText       (aPtr, bPtr: Ptr; aLen, bLen: Integer): Integer;

Modifying Characters and Diacritical Marks

PROCEDURE UpperString      (VAR theString: Str255; diacSens: Boolean);
PROCEDURE LowercaseText    (textPtr: Ptr; len: Integer;
                            script: ScriptCode);
PROCEDURE UppercaseText    (textPtr: Ptr; len: Integer;
                            script: ScriptCode);
PROCEDURE StripDiacritics  (textPtr: Ptr; len: Integer;
                            script: ScriptCode);
PROCEDURE UppercaseStripDiacritics
                           (textPtr: Ptr; len: Integer;
                            script: ScriptCode);

Truncating Strings

FUNCTION TruncString       (width: Integer; VAR theString: Str255; 
                            truncWhere: TruncCode): Integer;
FUNCTION TruncText         (width: Integer; textPtr: Ptr;
                            VAR length: Integer;
                            truncWhere: TruncCode): Integer;

Searching for and Replacing Strings

FUNCTION ReplaceText       (baseText, substitutionText: Handle;
                            key: Str15): Integer;
FUNCTION Munger            (h: Handle; offset: LongInt;
                            ptr1: Ptr; len1: LongInt;
                            ptr2: Ptr; len2: LongInt): LongInt;

Working With Word, Subscript, and Line Boundaries

PROCEDURE FindWordBreaks   (textPtr: Ptr; textLength: Integer;
                            offset: Integer; leadingEdge: Boolean; 
                            nBreaks: NBreakTablePtr;
                            VAR offsets:OffsetTable );
FUNCTION StyledLineBreak   (textPtr: Ptr; textLen: LongInt;
                            textStart, textEnd, flags: LongInt;
                            VAR textWidth: Fixed;
                            VAR textOffset: LongInt): StyledLineBreakCode;
FUNCTION FindScriptRun     (textPtr: Ptr; textLen: LongInt;
                            VAR lenUsed: LongInt): ScriptRunStatus;

Converting Date and Time Strings Into Numeric Representations

FUNCTION InitDateCache     (theCache: DateCachePtr): OSErr;
FUNCTION StringToDate      (textPtr: Ptr; textLen: LongInt;
                            theCache: DateCachePtr;
                            VAR lengthUsed: LongInt;
                            VAR dateTime: LongDateRec): StringToDateStatus;
FUNCTION StringToTime      (textPtr: Ptr; textLen: LongInt;
                            theCache: DateCachePtr;
                            VAR lengthUsed: LongInt;
                            VAR dateTime: LongDateRec): StringToDateStatus;

Converting Numeric Representations Into Date and Time Strings

PROCEDURE DateString       (dateTime: LongInt; longFlag: DateForm;
                            VAR result: Str255; intlHandle: Handle);
PROCEDURE TimeString       (dateTime: LongInt; wantSeconds: Boolean;
                            VAR result: Str255; intlHandle: Handle);

Converting Long Date and Time Values Into Strings

PROCEDURE LongDateString   (VAR dateTime: LongDateTime; longFlag: DateForm;
                            VAR result: Str255; intlHandle: Handle);
PROCEDURE LongTimeString   (VAR dateTime: LongDateTime; 
                            wantSeconds:Boolean; VAR result: Str255; 
                            intlHandle: Handle);

Converting Between Integers and Strings

PROCEDURE NumToString      (theNum: LongInt; VAR theString: Str255);
PROCEDURE StringToNum      (theString: Str255; VAR theNum: LongInt);

Using Number Format Specification Strings for International Number Formatting

FUNCTION StringToFormatRec (inString: Str255; partsTable: NumberParts;
                            VAR outString: NumFormatString): FormatStatus;
FUNCTION FormatRecToString (myFormatRec: NumFormatString;
                            partsTable: NumberParts;
                            VAR outString: Str255;
                            VAR positions: TripleInt): FormatStatus;

Converting Between Strings and Floating-Point Numbers

FUNCTION StringToExtended  (source: Str255; myFormatRec: NumFormatString; 
                            partsTable: NumberParts;
                            VAR x: Extended80): FormatStatus;
FUNCTION ExtendedToString  (x: Extended80; myFormatRec: NumFormatString; 
                            partsTable: NumberParts;
                            VAR outString: Str255): FormatStatus;

C Summary

Constants

enum {      /*StringToDate and StringToTime status values*/
   longDateFound = 1;         /*mask to long date found*/
   leftOverChars = 2;         /*mask to warn of left over chars*/
   sepNotIntlSep = 4;         /*mask to warn of non-standard separators*/
   fieldOrderNotIntl = 8;     /*mask to warn of non-standard field order*/
   extraneousStrings = 16;    /*mask to warn of unparsable strings */
   tooManySeps = 32;          /*mask to warn of too many separators*/
   sepNotConsistent = 64;     /*mask to warn of inconsistent separators*/
   fatalDateTime = 0x8000;    /*mask to a fatal error*/
   tokenErr = 0x8100;         /*mask for 'tokenizer err encountered'*/
   cantReadUtilities = 0x8200;/*mask for can't access needed resource*/
   dateTimeNotFound = 0x8400; /*mask for date or time not found*/
   dateTimeInvalid = 0x8800;  /*mask for date/time format not valid*/
};
enum {   /*constants for truncWhere argument in TruncString and TruncText*/
   truncEnd = 0,              /*truncate at end*/
   truncMiddle = 0x4000,      /*truncate in middle*/
};
enum {   /*constants for TruncString and TruncText results*/
   notTruncated = 0,       /*no truncation was necessary*/
   truncated = 1,          /*truncation performed*/
   truncErr = -1,          /*general error*/
};
enum {   /*special language code values for Language Order*/
   systemCurLang = -2,  /*current lang for system script (from 'itlb')*/
   systemDefLang = -3,  /*default lang for system script (from 'itlm')*/
   currentCurLang = -4, /*current lang for current script (from 'itlb')*/
   currentDefLang = -5, /*default lang for current script (from 'itlm')*/
   scriptCurLang = -6,  /*current lang for specified script (from 'itlb')*/
   scriptDefLang = -7,  /*default lang for specified script (from 'itlm')*/
};
enum {
   BreakWord,
   BreakChar,
   BreakOverflow
};
enum {
   fPositive,
   fNegative,
   fZero
};
enum{
   fFormatOK,
   fBestGuess,
   fOutOfSynch,
   fSpuriousChars,
   fMissingDelimiter,
   fExtraDecimal,
   fMissingLiteral,
   fExtraExp,
   fFormatOverflow,
   fFormStrIsNAN,
   fBadPartsTable,
   fExtraPercent,
   fExtraSeparator,
   fEmptyFormatString
};
enum {
   shortDate,
   longDate,
   abbrevDate
};

Types

typedef short StringToDateStatus;
typedef unsigned char StyledLineBreakCode;
typedef unsigned char FormatClass;
typedef short TruncCode;
typedef unsigned char FormatResultType;
typedef unsigned char DateForm;
struct DateCacheRecord {
   short hidden[256];            /*only for temporary use*/
};

typedef struct DateCacheRecord DateCacheRecord;
typedef DateCacheRecord *DateCachePtr;
struct NumFormatString {
   char fLength;
   char fVersion;
   char data[254];               /*private data*/
};

typedef struct NumFormatString NumFormatStringRec;
struct FVector {
   short start;
   short length;
};

typedef struct FVector FVector;
typedef FVector TripleInt[3];    /* index by [fPositive..fZero] */
struct ScriptRunStatus {
   char script;
   char variant;
};

typedef struct ScriptRunStatus ScriptRunStatus;
struct OffPair {
   short offFirst;
   short offSecond;
};

typedef struct OffPair OffPair;
typedef OffPair OffsetTable[3];

Routines

Defining and Specifying Strings

pascal StringHandle NewString
                              (ConstStr255Param theString);
pascal void SetString         (StringHandle theString,
                               ConstStr255Param strNew);
pascal StringHandle GetString
                              (short stringID);
pascal void GetIndString      (Str255 theString, short strListID,
                               short index);

Comparing Strings for Equality

pascal Boolean EqualString    (ConstStr255Param aStr, ConstStr255Param bStr, 
                               Boolean caseSens, Boolean diacSens );
pascal short IdenticalString
                              (ConstStr255Param aStr, ConstStr255Param bStr, Handle itl2Handle);
pascal short IdenticallText   (const void *aPtr, const void *bPtr,
                               short aLen, short bLen, Handle itl2Handle);

Determining Sorting Order for Strings in Different Languages

pascal short ScriptOrder      (ScriptCode script1, ScriptCode script2);
pascal short LanguageOrder    (LangCode language1, LangCode language2);
pascal short StringOrder      (ConstStr255Param aStr, ConstStr255Param bStr, 
                               ScriptCode aScript, ScriptCode bScript, 
                               LangCode aLang, LangCode bLang);
pascal short TextOrder        (const void *aPtr, const void *bPtr,
                               short aLen, short bLen,
                               ScriptCode aScript, ScriptCode bScript, 
                               LangCode aLang, LangCode bLang);

Determining Sorting Order for Strings in the Same Language

pascal short RelString        (ConstStr255Param aStr, ConstStr255Param bStr, 
                               Boolean caseSens, Boolean diacSens);
pascal short CompareString    (ConstStr255Param aStr, ConstStr255Param bStr, 
                               Handle itl2Hande);
pascal short CompareText      (const void *aPtr, const void *bPtr,
                               short aLen, short bLen, Handle itl2Handle);

Modifying Characters and Diacritical Marks

pascal void UpperString       (Str255 theString, Boolean diacSens);
pascal void LowercaseText     (Ptr textPtr, short len, ScriptCode script);
pascal void UppercaseText     (Ptr textPtr, short len, ScriptCode script);
pascal void StripDiacritics   (Ptr textPtr, short len, ScriptCode script);
pascal void UppercaseStripDiacritics
                              (Ptr textPtr, short len, ScriptCode script);

Truncating Strings

pascal short TruncString      (short width, Str255 theString,
                               TruncCode truncWhere);
pascal short TruncText        (short width, Ptr textPtr, short *textLen, 
                               TruncCode truncWhere);

Searching for and Replacing Strings

pascal short ReplaceText      (Handle baseText, Handle substitutionText, 
                               Str15 key);
pascal long Munger            (Handle h, long offset, const void *ptr1,
                               long len1, const void *ptr2, long len2);

Working With Word, Subscript, and Line Boundaries

pascal void FindWordBreaks    (Ptr textPtr, short textLen, short offset, 
                               Boolean leadingEdge, NBreakTablePtr breaks, 
                               OffsetTable offsets);
pascal StyledLineBreakCode StyledLineBreak
                              (Ptr textPtr, long textLen, long textStart,
                               long textEnd, long flags, Fixed *textWidth, long *textOffset);
pascal ScriptRunStatus FindScriptRun
                              (Ptr textPtr, long textLen, long *lenUsed);

Converting Date and Time Strings Into Numeric Representations

pascal OSErr InitDateCache    (DateCachePtr theCache);
pascal StringToDateStatus StringtoDate
                              (Ptr textPtr, long textLen,
                               DateCachePtr theCache, long *lengthUsed, LongDateRec *dateTime);
pascal StringToDateStatus StringToTime
                              (Ptr textPtr, long textLen,
                               DateCachePtr theCache, long *lengthUsed, LongDateRec *dateTime);

Converting Numeric Representations Into Date and Time Strings

pascal void DateString        (long dateTime, DateForm longFlag,
                               Str255 result, Handle intlHandle);
pascal void TimeString        (long dateTime, Boolean wantSeconds,
                               Str255 result, Handle intlHandle);

Converting Long Date and Time Values Into Strings

pascal void LongDateString    (LongDateTime *dateTime, DateForm longFlag, 
                               Str255 result, Handle intlHandle);
pascal void LongTimeString    (LongDateTime *dateTime, Boolean wantSeconds, 
                               Str255 result, Handle intlHandle);

Converting Between Integers and Strings

pascal void NumToString       (long theNum, Str255 theString);
pascal void StringToNum       (ConstStr255Param theString, long *theNum);

Using Number Format Specification Strings for International Number Formatting

pascal FormatStatus StringToFormatRec
                              (ConstStr255Param inString,
                               const NumberParts *partsTable,
                               NumFormatString *outString);
pascal FormatStatus FormatRecToStr
                              (const NumFormatString *myFormatRec,
                               const NumberParts *partsTable,
                               Str255 outString, TripleInt positions);

Converting Between Strings and Floating-Point Numbers

pascal FormatStatus StringToExtended
                              (ConstStr255Param source,
                               const NumFormatString *myFormatRec,
                               const NumberParts *partsTable, extended80 *x);
pascal FormatStatus ExtendedToString
                              (extended80 x,
                               const NumFormatString *myFormatRec,
                               const NumberParts *partsTable,
                               Str255 outString);

Assembly-Language Summary

Trap Macros

Trap Macro Names
Pascal name Trap macro name
CompareText _CompareText
`DateString` _DateString
ExtendedToString _ExtendedToString
FindScriptRun _FindScriptRun
FindWordBreaks _FindWordBreaks
FormatRecToString _FormatRecToString
IdenticalText _IdenticalText
InitDateCache _InitDateCache
LanguageOrder _LanguageOrder
LongDateString _LongDateString
LongTimeString _LongTimeString
`NumToString` _NumToString
ReplaceText _ReplaceText
ScriptOrder _ScriptOrder
StringToDate _StringToDate
StringToExtended _StringToExtended
StringToFormatRec _StringToFormatRec
StringToNum _StringToNum
StringToTime _StringToTime
StyledLineBreak _StyledLineBreak
TextOrder _TextOrder
TimeString _TimeString
TruncString _TruncString
TruncText _TruncText

Pascal name	Trap macro name
CompareText	_CompareText
`DateString`	_DateString
ExtendedToString	_ExtendedToString
FindScriptRun	_FindScriptRun
FindWordBreaks	_FindWordBreaks
FormatRecToString	_FormatRecToString
IdenticalText	_IdenticalText
InitDateCache	_InitDateCache
LanguageOrder	_LanguageOrder
LongDateString	_LongDateString
LongTimeString	_LongTimeString
`NumToString`	_NumToString
ReplaceText	_ReplaceText
ScriptOrder	_ScriptOrder
StringToDate	_StringToDate
StringToExtended	_StringToExtended
StringToFormatRec	_StringToFormatRec
StringToNum	_StringToNum
StringToTime	_StringToTime
StyledLineBreak	_StyledLineBreak
TextOrder	_TextOrder
TimeString	_TimeString
TruncString	_TruncString
TruncText	_TruncText

Trap Macros With Trap Words
Trap macro name Trap word
_CmpString `$A03C`
_GetString `$A9BA`
_LowerText `$A056`
_Munger `$A9E0`
_NewString `$A906`
_RelString `$A050`
_SetString `$A907`
_StripText `$A256`
_StripUpperText `$A656`
_UpperText `$A456`
_UprString `$A054`

Trap macro name	Trap word
_CmpString	`$A03C`
_GetString	`$A9BA`
_LowerText	`$A056`
_Munger	`$A9E0`
_NewString	`$A906`
_RelString	`$A050`
_SetString	`$A907`
_StripText	`$A256`
_StripUpperText	`$A656`
_UpperText	`$A456`
_UprString	`$A054`

Trap Macros Requiring Routine Selectors

_PACK6

Selector	Routine
$000E	`DateString`
$0010	TimeString
$0014	LongDateString
$0016	LongTimeString
$001A	CompareText
$001C	IdenticalText
$001E	ScriptOrder
$0020	LanguageOrder
$0022	TextOrder

_PACK7

Selector	Routine
$0000	NumToString
$0001	StringToNum

_ScriptUtil

Selector	Routine
$8204 FFF8	InitDateCache
$8208 FFE0	TruncString
$820C 0026	FindScriptRun
$820C FFDC	ReplaceText
$820C FFEC	StringToFormatRec
$820C FFDE	TruncText
$8210 FFE6	StringToExtended
$8210 FFE8	ExtendedToString
$8210 FFEA	FormatRecToString
$8214 FFF6	StringToDate
$8214 FFF4	StringToTime
$821C FFFE	StyledLineBreak
$C012 001A	FindWordBreaks

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Legacy Document

Summary of Text Utilities

Pascal Summary

Constants

Data Types

Routines

Defining and Specifying Strings

Comparing Strings for Equality

Determining Sorting Order for Strings in Different Languages

Determining Sorting Order for Strings in the Same Language

Modifying Characters and Diacritical Marks

Truncating Strings

Searching for and Replacing Strings

Working With Word, Subscript, and Line Boundaries

Converting Date and Time Strings Into Numeric Representations

Converting Numeric Representations Into Date and Time Strings

Converting Long Date and Time Values Into Strings

Converting Between Integers and Strings

Using Number Format Specification Strings for International Number Formatting

Converting Between Strings and Floating-Point Numbers

C Summary

Constants

Types

Routines

Defining and Specifying Strings

Comparing Strings for Equality

Determining Sorting Order for Strings in Different Languages

Determining Sorting Order for Strings in the Same Language

Modifying Characters and Diacritical Marks

Truncating Strings

Searching for and Replacing Strings

Working With Word, Subscript, and Line Boundaries

Converting Date and Time Strings Into Numeric Representations

Converting Numeric Representations Into Date and Time Strings

Converting Long Date and Time Values Into Strings

Converting Between Integers and Strings

Using Number Format Specification Strings for International Number Formatting

Converting Between Strings and Floating-Point Numbers

Assembly-Language Summary

Trap Macros

Trap Macros With Trap Words Trap macro nameTrap word _CmpString$A03C _GetString$A9BA _LowerText$A056 _Munger$A9E0 _NewString$A906 _RelString$A050 _SetString$A907 _StripText$A256 _StripUpperText$A656 _UpperText$A456 _UprString$A054

Trap Macros Requiring Routine Selectors

Trap Macros With Trap Words
Trap macro name Trap word
_CmpString `$A03C`
_GetString `$A9BA`
_LowerText `$A056`
_Munger `$A9E0`
_NewString `$A906`
_RelString `$A050`
_SetString `$A907`
_StripText `$A256`
_StripUpperText `$A656`
_UpperText `$A456`
_UprString `$A054`