Introduction to Data Utilities

The data utilities are a collection of classes, methods and macros which provide simple low level support. There are several different types of utilities and classes, involving strings, byte order routines, error message support, and string formatting support. These routines are used extensively throughout the YAAF libraries.

String Conversion

The Macintosh and some internal YAAF resources use Pascal format strings: a string with a byte length followed by the characters in a string. These routines provide a simple mechanism for converting between Pascal and C formatted strings.

> unsigned char *cvtc2p(unsigned char *dest, const char *src);

> > Copy a C string to dest, converting it to a Pascal string in the process.

> char *cvtp2c(char *dest, const unsigned char *src);

> > Copy a Pascal string to dest, converting it to a C string in the process.

Pascal String Support

These are simple Pascal string utilities which help with string manipulation in the Macintosh version of YAAF. These are the equivalent to their C counterparts, but use Pascal strings instead.

> unsigned char *pstrcpy(unsigned char *dest, const unsigned char *src);

> > Copy a Pascal string from src to dest.

> unsigned char *pstrcat(unsigned char *dest, const unsigned char *src);

> > Concatenate the Pascal string dest with the contents of the Pascal string src.

> long pstrcmp(const unsigned char *a, const unsigned char *b);

> > Compare two Pascal strings. Returns 0 if the two strings are equal, < 0 if a < b, and > 0 if a > b.

Short/Long Integer Compression

In a couple of places in the YAAF libraries, two short integers are passed as a long integer. There are three macros to support creating a long integer from two short integers, and for getting the short integers out.

> MAKEDWORD(x,y)

> > Create a long integer by using x and y.

> GETLOWORD(x)

> > Get the low order word from this long integer.

> GETHIWORD(x)

> > Get the high order word from this long integer.

Byte Order Routines

There are several byte swap routines. These are used to maintain binary compatability with different files regardless of the environment the application is compiled on. There are four different subroutines and eight different macros which swap byte order.

> unsigned short SwapWord(unsigned short);
> unsigned long SwapLong(unsigned long);
> float SwapFloat(float);
> double SwapDouble(double);

> > These routines swap the byte order from one endian order to another. Generally you will use the following eight macros, which selectively expand to either nothing or one of these routines, depending on the native byte order of the host environment.

> ESwapWord(x)
> ESwapLong(x)
> ESwapFloat(x)
> ESwapDouble(x)

> > These macros swap the byte order from a non-network byte order to the native byte order of the host environment and back again.

> NSwapWord(x)
> NSwapLong(x)
> NSwapFloat(x)
> NSwapDouble(x)

> > These macros swap the byte order from a network byte order to the native byte order of the host environment and back again.

Error Message Support

This routine gets the two strings from the specified error strings from the error messages compiled by CompileMessages.

> short GetResourceMessage(short resID, short index, char *smsg, char *lmsg);

> > Get the short and long strings associated with the error message specified by resID and index.

String Formatting Support

These routines are used for formatting the optional parameters into an error string. These routines operate similarly to sprintf(), except using a different formatting character, and can be used as a replacement in the case where you are unable to link to the standard C libraries.

> void yformat(char *out, const char *arg, ...);

> > This is the equivalent to sprintf, but with different formatting characters. The formatting parameters are able to format strings, even rearrange the order in which strings are inserted.

> void vyformat(char *out, const char *arg, va_list vlist);

> > The varargs version of the yformat routine.