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

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 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