CHAPTER 19 - PART 2

• Numeric Format Resource. The numeric format ('itl0') resource contains short date and time formats, and formats for currency, numbers, and the preferred unit of measurement. It provides separators for decimals, thousands, and lists. It also contains the region code for this particular resource. Three of the several variations in short date and time formats are as follows:

  System Software	Morning	Afternoon	Short Date
  United States	1:02 AM	1:02 PM	2/1/90
  Sweden	01:02	13:02	90-01-01
  Germany	1:02 Uhr	13:02 Uhr	2.1.1990

• Long Date Format Resource. The long date format ('itl1') resource specifies the long and abbreviated date formats for a particular region, including the names of days and months and the exact order of presentation of the elements. It also contains a region code for this particular resource. Three of the several variations of the long and abbreviated date formats are as follows:

  System Software	Abbreviated Date	Long Date
  United States	Tue, Jan 2, 1990	Tuesday, January 2 1990
  French	Mar 2 Jan 1990	Mardi 2 Janvier 1990
  Australian	Tue, 2 Jan 1990	Tuesday, 2 January 1990

• Tokens Resource. The tokens ('itl4') resource contains, amongst other things, a table for formatting numbers. This table, which is called the number parts table, contains standard representations for the components of numbers and numeric strings. As will be seen, certain Text Utilities number formatting functions use the number parts table to create number strings in localised formats.

The date-time (DateTimeRec) and the long date-time (LongDateRec) structures are as follows:

                                               union LongDateRec
                                               {
        struct 
     struct DateTimeRec                          {
     }                                              short  era;
       short  year;                                 short  year;
       short  month;                                short  month;
       short  day;                                  short  day;
       short  hour;                                 short  hour;
       short  minute;                               short  minute;
       short  second;                               short  second;
       short  dayOfWeek;                            short  dayOfWeek;
     };                                             short  dayOfYear;
                                                    short  weekOfYear;
     typedef struct DateTimeRec DateTimeRec;        short  pm;
                                                    short  res1;
                                                    short  res2;
                                                    short  res3;
                                                  } ld;
                                                  short  list[14];
                                                  struct
                                                  {
                                                    short    eraAlt;
                                                    DateTimeRec  oldDate;
                                                  } od;
                                                };

                                                typedef union LongDateRec LongDateRec;

Converting Between Values and Structures

Converting Date-Time Values Into Strings

Output Format - Date. When you use DateString and LongDateString, you can specify, in the longFlag parameter, an output format for the resulting date string. This format can be one of the following three values of the DateForm enumerated data type:

Output Format - Time. When you use TimeString and LongTimeString, you can request an output format for the resulting time string by specifying either true or false in the wantSeconds parameter. true will cause seconds to be included in the string.

DateString, LongDateString, TimeString and LongTimeString use the date and time formatting information in the format resource that you specify in the resource handle (intlHandle) parameter. If you specify NULL for the value of the resource handle parameter, the appropriate format resource for the current script system is used.

Converting Date-Time Strings Into Internal Numeric Representation

You usually call StringToDate and StringToTime sequentially to parse the date and time values from an input string and fill in these fields. Note that StringToDate assigns to its lengthUsed parameter the number of bytes that it uses to parse the date. Use this value to compute the starting location of the text that you can pass to StringToTime.

The "confidence level" value returned by both StringToDate and StringToTime is of type StringToDateStatus, a set of bit values which have been OR'd together. The higher the resultant number, the lower the confidence level. Three of the twelve StringToDateStatus values, and their meanings, are as follows:

Date Cache Structure. Both StringToDate and StringToTime take a date cache structure as one of their parameters. A date cache structure (a data structure of type DateCacheRec) stores date conversion data used by the date and time conversion functions. You must declare a data cache structure in your application and initialise it by calling InitDateCache once, typically in your main program initialisation code.

Numbers

The range of values accommodated by these functions is -2,147,483,647 to 2,147,483,648. No comma insertion or other formatting is performed.

Number Format Specification Strings

Parts. Each number format specification string contains up to three parts:

• The positive number format.

• The negative number format.

• The zero number format.

Elements. A number format specification string can contain the following elements:

• Number parts separators (, and .) for specifying the decimal separator and the thousands separator.

• Literals to be included in the output. (Literals can be strings or brackets, braces and parentheses, and must be enclosed in quotation marks.)

• Digit place holders. (Digit place holders that you want displayed must be indicated by digit symbols. Zero digits (0) add leading zeroes whenever an input digit is not present. Skipping digits (#) only produce output characters when an input digit is present. Padding digits (^) are like zero digits except that a padding character such as a non-breaking space is used instead of leading zeros to pad the output string.)

• Quoting mechanisms for handling literals correctly.

• Symbol and sign characters.

The number formatting functions always fill in integer digits from the right and decimal places on the left. The following examples, in which a literal is included in the middle of the format strings, demonstrate this behaviour:

Overflow and Rounding. If the input string contains more digits than are specified in the number format specification string, an error (formatOverflow) will be generated. If the input string contains too many decimal places, the decimal portion is automatically rounded. For example, given the format ###.###, a value of 1234.56789 results in an error condition, and a value of 1.234999 results in the rounded-off value 1.235.

Converting Number Format Specification Strings to Internal Numeric Representations. With the required number format specification string defined, you must then convert the string into an internal numeric representation. The internal representation of format strings is stored in a NumFormatString structure. You use the following functions to convert a number format specification string to a NumFormatString structure and vice versa.

Number Parts Table. The internal numeric representation allows you to map the number into different output formats. One of the parameters taken by StringToFormatRec is a number parts table. The number parts table specifies which characters are used for certain purposes, such as separating parts of a number, in the format specification string.

For example, a thousands separator is a comma in Australia and a decimal point in France.

The FormatRecToString function also contains a number parts table parameter. By using a different table than was used in the call to StringToFormatRec, you can produce a number format specification string that specifies how numbers are formatted for a different region of the world. You use FormatRecToString when you want to display the number format specification string to the user for perusal or modification.

As previously stated, the number parts table is contained in the 'itl4' resource. A handle to the 'itl4' resource may be obtained by a call to GetIntlResourceTable, specifying iuNumberPartsTable in the tableCode parameter.

Converting Between Floating Point Numbers and Numeric Strings

PowerPC Considerations. The PowerPC-based Macintosh follows the IEEE 754 standard for floating point arithmetic. In this standard, float is 32 bits and double is 64 bits. (Apple has added the 128 bit long double type.) However, the PowerPC floating point unit does not support Motorola's 80/96-bit extended type, and neither do the PowerPC numerics. To accommodate this, you can use Apple-supplied conversion utilities to move to and from extended. For example, the functions x80tod and dtox80 (see the header file fp.h) can be used to directly transform 680x0 80-bit extended data types to double and back.

StringToFormatRec, FormatRecToString, StringToExtended, and ExtendedToString return a result of type FormatStatus, which is an integer value. The low byte is of type FormatResultType. Typical examples of the returned format status are as follows:

Main TextEdit Constants, Data Types and Functions

teFlushDefault  = 0
teCenter        = 1
teFlushRight    = -1
teFlushLeft     = -2

doFont   = 1
doFace   = 2
doSize   = 4
doColor  = 8
doAll    = 15
addSize  = 16

teFAutoScroll             = 0
teFTextBuffering          = 1
teFOutlineHilite          = 2
teFInlineInput            = 3
teFUseWhiteBackground     = 4
teFUseInlineInput         = 5
teFInlineInputAutoScroll  = 6

typedef char Chars[32001];
typedef char *CharsPtr;
typedef CharsPtr *CharsHandle;

struct TERec
{
  Rect         destRect;     // Destination rectangle.
  Rect         viewRect;     // View rectangle.
  Rect         selRect;      // Selection rectangle.
  short        lineHeight;   // Vert spacing of lines. -1 in multistyled edit structure.
  short        fontAscent;   // Font ascent. -1 in multistyled edit structure.
  Point        selPoint;     // Point selected with the mouse.
  short        selStart;     // Start of selection range.
  short        selEnd;       // End of selection range.
  short        active;       // Set when structure is activated or deactivated.
  WordBreakUPP    wordBreak; // Word break function.
  TEClickLoopUPP  clickLoop; // Click loop function.
  long         clickTime;    // (Used internally.)
  short        clickLoc;     // (Used internally.)
  long         caretTime;    // (Used internally.)
  short        caretState;   // (Used internally.)
  short        just;         // Text alignment.
  short        teLength;     // Length of text.
  Handle       hText;        // Handle to text to be edited.
  long         hDispatchRec; // Handle to TextEdit dispatch structure.
  short        clikStuff;    // (Used internally)
  short        crOnly;       // If <0, new line at Return only.
  short        txFont;       // Text font.   // If multistyled edit struct (txSize = -1),
  StyleField   txFace;       // Chara style. // these bytes are used as a handle
  SInt8         filler;      //              // to a style structure (TEStyleHandle).
  short        txMode;       // Pen mode.
  short        txSize;       // Font size. -1 in multistyled edit structure.
  GrafPtr      inPort;       // Pointer to grafPort for this edit structure.
  HighHookUPP  highHook;     // Used for text highlighting, caret appearance.
  CaretHookUPP caretHook;    // Used from assembly language.
  short        nLines;       // Number of lines.
  short        lineStarts[16001];  // Positions of line starts.
};
typedef struct TERec TERec;
typedef TERec *TEPtr;
typedef TEPtr *TEHandle;

struct TEStyleRec
{
  short         nRuns;      // Number of style runs. 
  short         nStyles;    // Size of style table. 
  STHandle      styleTab;   // Handle to style table. 
  LHHandle      lhTab;      // Handle to line-height table. 
  long          teRefCon;   // Reserved for application use. 
  NullStHandle  nullStyle;  // Handle to style set at null selection. 
  StyleRun  runs[8001];     // ARRAY [0..8000] OF StyleRun. 
};
typedef struct TEStyleRec TEStyleRec;
typedef TEStyleRec *TEStylePtr;
typedef TEStylePtr *TEStyleHandle;

struct STElement
{
  short       stCount;   // Number of runs in this style. 
  short       stHeight;  // Line height. 
  short       stAscent;  // Font ascent. 
  short       stFont;    // Font (family) number. 
  StyleField  stFace;    // Character Style. 
  short       stSize;    // Size in points. 
  RGBColor   stColor;    // absolute (RGB) color. 
};
typedef struct STElement STElement;
typedef STElement TEStyleTable[1777];
typedef STElement *STPtr;
typedef STPtr *STHandle;

struct LHElement
{
  short  lhHeight;  // Maximum height in line. 
  short  lhAscent;  // Maximum ascent in line. 
};
typedef struct LHElement LHElement;
typedef LHElement LHTable[8001];
typedef LHElement *LHPtr;
typedef LHPtr *LHHandle;

struct StyleRun
{
  short  startChar;   // Starting character position.
  short  styleIndex;  // index in style table.
};
typedef struct StyleRun StyleRun;

struct NullStRec
{
  long          teReserved;  // Reserved.
  StScrpHandle  nullScrap;   // Handle to scrap style table. 
};
typedef struct NullStRec NullStRec;
typedef NullStRec *NullStPtr;
typedef NullStPtr *NullStHandle;

struct StScrpRec
{
  short        scrpNStyles;   // Number of styles in scrap. 
  ScrpSTTable  scrpStyleTab;  // Table of styles for scrap. 
};
typedef struct StScrpRec StScrpRec;
typedef StScrpRec *StScrpPtr;
typedef StScrpPtr *StScrpHandle;

struct ScrpSTElement
{
  long        scrpStartChar;  // starting character position. 
  short       scrpHeight;     // Character height. 
  short       scrpAscent;     // Ascent above baseline this font.
  short       scrpFont;       // Font (family) number.
  StyleField  scrpFace;       // Character style.
  short       scrpSize;       // Font size (points).
  RGBColor    scrpColor;      // Colour used this style.
};
typedef struct ScrpSTElement ScrpSTElement;
typedef ScrpSTElement ScrpSTTable[1601];  //  ARRAY [0..1600] OF ScrpSTElement. 

struct TextStyle
{
  short       tsFont;   // Font (family) number. 
  StyleField  tsFace;   // Character Style. 
  short       tsSize;   // Size in point. 
  RGBColor    tsColor;  // Absolute (RGB) color. 
};
typedef struct TextStyle TextStyle;
typedef TextStyle *TextStylePtr;
typedef TextStylePtr *TextStyleHandle;

void      TEInit(void);
TEHandle  TENew(const Rect *destRect,const Rect *viewRect);
TEHandle  TEStyleNew(const Rect *destRect,const Rect *viewRect);
void      TEDispose(TEHandle hTE);

void  TEActivate(TEHandle hTE);
void  TEDeactivate(TEHandle hTE);

void           TEKey(short key,TEHandle hTE);
void           TESetText(const void *text,long length,TEHandle hTE);
CharsHandle    TEGetText(TEHandle hTE);
void           TESetStyleHandle(TEStyleHandle theHandle,TEHandle hTE);
TEStyleHandle  TEGetStyleHandle(TEHandle hTE);

void  TEIdle(TEHandle hTE);
void  TEClick(Point pt,Boolean fExtend,TEHandle h);
void  TESetSelect(long selStart,long selEnd,TEHandle hTE);

void  TESetAlignment(short just,TEHandle hTE);
void  TEUpdate(const Rect *rUpdate,TEHandle hTE);
void  TETextBox(const void *text,long length,const Rect *box,short just);
void  TECalText(TEHandle hTE);
long  TEGetHeight(long endLine,long startLine,TEHandle hTE);
void  TEScroll(short dh,short dv,TEHandle hTE);
void  TEPinScroll(short dh,short dv,TEHandle hTE);
void  TEAutoView(Boolean fAuto,TEHandle hTE);
void  TESelView(TEHandle hTE);

void   TEDelete(TEHandle hTE);
void   TEInsert(const void *text,long length,TEHandle hTE);
void   TEStyleInsert(const void *text,long length,StScrpHandle hST,
void   TECut(TEHandle hTE);
void   TECopy(TEHandle hTE);
void   TEPaste(TEHandle hTE);
void   TEStylePaste(TEHandle hTE);
OSErr  TEFromScrap(void); 
OSErr  TEToScrap(void); 

#define  TEScrapHandle(); (* (Handle*) 0xAB4);
#define  TEGetScrapLength(); ((long) * (unsigned short *) 0x0AB0);
void     TESetScrapLength(long length);; 

void          TESetStyle(short mode,const TextStyle *newStyle,Boolean redraw,
              TEHandle hTE);
void          TEReplaceStyle(short mode,const TextStyle *oldStyle,
              const TextStyle *newStyle,Boolean fRedraw,TEHandle hTE);
Boolean       TEContinuousStyle(short *mode,TextStyle *aStyle,TEHandle hTE);
void          TEStyleInsert(const void *text,long length,StScrpHandle hST,
              TEHandle hTE);
TEStyleHandle TEGetStyleHandle(TEHandle hTE);
StScrpHandle  TEGetStyleScrapHandle(TEHandle hTE);
void          TEUseStyleScrap(long rangeStart,long rangeEnd,StScrpHandle newStyles,
              Boolean fRredraw,TEHandle hTE);
long          TENumStyles(long rangeStart,long rangeEnd,TEHandle hTE);

short  TEGetOffset(Point pt,TEHandle hTE);
Point  TEGetPoint(short offset,TEHandle hTE);

void  TESetClickLoop(TEClickLoopUPP clikProc,TEHandle hTE);; 
void  TESetWordBreak(WordBreakUPP wBrkProc,TEHandle hTE);; 
void  TECustomHook(TEIntHook which, UniversalProcPtr *addr,TEHandle hTE);

short  TEFeatureFlag(short feature,short action,TEHandle hTE);

fatalDateTime      = 0x8000  Mask to a fatal error.
longDateFound      = 1       Mask to long date found.
leftOverChars      = 2       Mask to warn of left over characters.
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.
tokenErr           = 0x8100  Mask for 'tokenizer err encountered'.
cantReadUtilities  = 0x8200
dateTimeNotFound   = 0x8400
dateTimeInvalid    = 0x8800

fFormatOK           = 0
fBestGuess          = 1
fOutOfSynch         = 2
fSpuriousChars      = 3
fMissingDelimiter   = 4
fExtraDecimal       = 5
fMissingLiteral     = 6
fExtraExp           = 7
fFormatOverflow     = 8
fFormStrIsNAN       = 9
fBadPartsTable      = 10
fExtraPercent       = 11
fExtraSeparator     = 12
fEmptyFormatString  = 13

typedef short StringToDateStatus;
typedef SInt8 DateForm;
typedef short FormatStatus;
typedef Sint8 FormatResultType;

struct DateCacheRecord
{
  short  hidden[256];  // Only for temporary use.
};
typedef struct DateCacheRecord DateCacheRecord;
typedef DateCacheRecord *DateCachePtr;

struct NumFormatString
{
  UInt8  fLength;
  UInt8  fVersion;
  char   data[254];  // Private data.
};
typedef struct NumFormatString NumFormatString;
typedef NumFormatString NumFormatStringRec;

void  GetDateTime(unsigned long *secs);
void  GetTime(DateTimeRec *d);

void  DateToSeconds(const DateTimeRec *d,unsigned long *secs); 
void  SecondsToDate(unsigned long secs,DateTimeRec *d);
void  LongDateToSeconds(const LongDateRec *lDate,LongDateTime *lSecs);
void  LongSecondsToDate(LongDateTime *lSecs,LongDateRec *lDate);

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

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

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

FormatStatus  StringToFormatRec(ConstStr255Param inString,const NumberParts *partsTable,
              NumFormatString *outString)
FormatStatus  FormatRecToString(const NumFormatString *myCanonical,
              const NumberParts *partsTable,Str255 outString,TripleInt positions)

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

void    x80told(const extended80 *x80,long double *x);
void    ldtox80(const long double *x,extended80 *x80);
double  x80tod(const extended80 *x80);
void    dtox80(const double *x, extended80 *x80);