| Volume Number: | 3 | |||
| Issue Number: | 11 | |||
| Column Tag: | Programmer's Workshop | |||
Pascal String Library for C 
By Troy Clark, PO Box 2647, Carefree, AZ 85377
Breaking away from C strings and the Stdio Library
Many Mac C programmers use C style strings in order to remain compatible with the Stdio library which provides several commonly needed functions. Unfortunately, C strings are incompatible with virtually all the ROM routines that take strings as arguments. I will point out the draw backs to the most common solution to this compatibility problem and then discuss how to eliminate it altogether.
In this process, I will show you how to create libraries of code in such a way as to allow LightspeedC to link only the code that was actually used, as well as give you examples of how to use Apple’s SANE, Str2Dec and Dec2Str libraries. I will also demonstrate how to write functions in C that take a variable number of arguments. More importantly, I have provided the source for a complete Pascal String Library.
Need for a Pascal String Library
The easiest way around the string compatibility problem is to use the MacTraps routines CtoPstr() and PtoCstr() to convert back and fourth between C and Pascal strings at run time. However, using these extra function calls will increase the size of your code and may hinder your application’s overall performance since it takes time to do the conversions. Including the Stdio library adds approxiamtely 16K to your application alone. Couple this fact with the string conversion overhead neccessary to stay on speaking terms with the ROM, and you’ve got a real mess!
You could eliminate the problem altogether by using Pascal strings, exclusively. This implies having to write your own code as a functional replacement for the Stdio library. How dependent are you on the Stdio? Since getchar() and printf() are next to useless in the Mac environment, there are really only two areas of concern--file and Pascal string handling.
Reading the File Manager chapter of Inside Macintosh will get your wheels rolling in the file handling department. It is very easy to create, delete, open, close, read and write files using the ROM routines. If you need examples of how to use the routines and you can’t find them anywhere else, you can always dig through the Stdio’s source code. Yes--even the Stdio uses the ROM! Implementing a high quality Pascal String Library is not as easy, so I have taken this burden off your shoulders by providing one for you.
Writing the functions to draw, copy, concatenate and search Pascal strings was fairly straight forward. It is important to remember that type ‘char’ is actually a signed quantity and that character values greater than 127 will be considered negative. I got around this “feature” by declaring all Pascal string arguments as ‘unsigned char *’ (i.e. a pointer to an unsigned char). The signed quantity issue was particiliarly important for the PStrFind functions which take ‘char’s as arguments. Since all K&R standard C compilers convert ‘char’s to ‘int’s before passing them to a function, I declared the argument as type ‘int’ within the function definition and then manually stripped the sign extension off via: int_var &= 0xFF;
Fig. 1 Demo shows how to use the string library
Immediate char values such as ‘•’ DO NOT get sign extended! During a few moments of carelessness, you could easily write a function that works correctly with ‘immediate’ character arguments, but FAILS when tested with ‘char’ type arguments! Note that sign extension of type ‘char’ (i.e. or any other signed type) occurs BEFORE a cast takes affect, so casting type ‘char’ to type ‘unsigned int’ for example will not solve the problem.
(In hopes of reducing redundant expressions, I will henceforth substitute “standard type” in place of “type int, long, float, short double and double”)
Writing the functions to: 1) create a Pascal string representation of any standard type of number. 2) set the value of any standard type of number to the value represented in a Pascal string--was far more challenging. Rather than writing seperate functions for each type of number, I wrote two functions capable of operating on any standard type. This was made possible by using the SANE, Dec2Str and Str2Dec libraries!
SANE Contributions
There are two structures defined in the sane.h file which you need to be aware of in order to understand these libraries. Decimal structures are used to store decimal string representations of numeric values in up to 20 digits of precision. DecForm structures are used to specify the number of significant digits and whether you want a FLOATDECIMAL (i.e. scientific notation) or FIXEDDECIMAL (i.e. decimal) representation of a value.
SANE provides procedures to set a Decimal structure equal to the value of any standard type of number, as well as procedures to set the value of any standard type of number equal to a Decimal record. The Dec2Str library provides a procedure to create a Pascal string representation of a value in a Decimal structure according to the settings of a DecForm structure. The Str2Dec library provides a procedure to set a Decimal structure to the value represented in a Pascal string. These procedures are documented in the Apple Numerics Manual. I used them to create the PStr2Num() and Num2PStr() functions listed below--notice how little code was required!
Functions with Variable Arguments
LightspeedC generates code that uses a calling convention designed to allow programmers to write functions accepting a variable number of arguments:
; High memory ; Callers Code looks like this MOVE . . ., -(SP) ; last argument . . . MOVE . . ., -(SP) ; first argument JSR function ADD #. . ., -(SP) ; total size of arguments ; Functions’s code looks like this LINK A6, #. . . ; (optional) . . . MOVE . . ., D0 ; result UNLK A6 ; (optional) ; Low memory
The first argument passed to a function is always in the same location relative to the stack pointer (register A7) regardless of how many additional arguments are supplied. Thus, all the arguments can be found by adding positive offsets to the address of the first which is usually an integer specifying how many arguments are to follow. The responsiblity of removing the arguments from the stack lies with the party that knows how many arguments were actualy passed--the caller. The PStrCat() and ShowVars() listed below are examples of functions written to accept a variable number of arguments. In LightspeedC, the maximum number of arguments is 31.
Fooling LS C into using Strip-able Code Libraries
LightspeedC’s linker considers libraries built with ‘Build Library...’ command as ATOMIC code units. If any code is used then the ALL the code gets linked! If a library is itself a project, however, then all the source files and libraries with in it are individually eligible for removal. This is the key to creating ‘strip-able’ code libraries in LightSpeed C! All you have to do is: 1) create a seperate source file for each function 2) create a new project and add all the files 3) compile the files. You can now consider this project a ‘libary’ and include it in any other project you want.
String Library Demo Shows How to Use It!
I have also provide the source for an application that DEMO’s the Pascal String Library. It’s basically an online tutorial that explains the ‘how to’s and ‘results of’ using each function in the library.
You can find stuff like this only in MacTutor! I would like to thank David Smith for allowing me to share this information with you. Until next time...
/* File: PStrLib.h */
#ifndef _PStrLib_
#define_PStrLib_
#ifndef _WindowMgr_
#include <WindowMgr.h>
#endif
#ifndef _FontMgr_
#include <FontMgr.h>
#endif
#ifndef _saneh_
#include <sane.h>
#endif
extern char _char[];
#defineBOOL1
#defineCDBLFFEXT
#defineCSHORTDBLFFDBL
#defineCFLOAT FFSGL
#defineCINTFFINT
#defineCLONG FFLNG
#defineCCOMP FFCOMP
#definePSTR2
#defineDEC FIXEDDECIMAL
#defineSCI FLOATDECIMAL
#defineALL 255
#defineNIL 0L
#defineCEN (-1)
#defineNL1 (-1)
#defineNL2 (-2)
#defineCUR (-3)
#defineplain ‘’
#define _alpha 1
#define _digit 2
#define _hex 4
#define _octal 8
#define_ascii 16
#define_cntrl 32
#define _punct 64
#define _space 128
/*
The c character passed to the macros below should be’declared as’ or
‘cast to’ type ‘Byte’ or ‘unsigned char’. Type char gets sign extended
to an integer. Thus, when c > 127 the _char[] subscript becomes negative!
Note that immediate chars such as ‘•’ do not get sign extended so they’re
okay.
*/
#define IsAlphaNum(c) (_char[(c)+1]&(_alpha|_digit))
#defineIsAlpha(c) (_char[(c)+1]&_alpha)
#defineIsAscii(c) (_char[(c)+1]&_ascii)
#defineIsCntrl(c) (_char[(c)+1]&_cntrl)
#define IsCSym(c) ((_char[(c)+1]&(_alpha|_digit))||(c)==’_’)
#define IsCSymF(c) ((_char[(c)+1]&_alpha)||(c)==’_’)
#define IsDigit(c) (_char[(c)+1]&_digit)
#defineIsGraph(c) ((c)>=’!’&&(c)<=’~’)
#defineIsOctDigit(c)(_char[(c)+1]&_octal)
#defineIsPrint(c) ((c)>=32&&(c)<=255)
#defineIsPunct(c) (_char[(c)+1]&_punct)
#defineIsSpace(c) (_char[(c)+1]&_space)
#defineIsHexDigit(c)(_char[(c)+1]&_hex)
#endif
/* FILE: macros_char.c
Contains _char[] used by macros in PStrLib.h */
#include“PStrLib.h”
char _char[257] =
{/* char masks allow for efficient macros */
0, _cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii|_space, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii|_space, _cntrl|_ascii|_space,
_cntrl|_ascii|_space, _cntrl|_ascii|_space,
_cntrl|_ascii|_space, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _cntrl|_ascii, _cntrl|_ascii,
_cntrl|_ascii, _space|_ascii, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _digit|_hex|_octal|_ascii,
_digit|_hex|_octal|_ascii, _digit|_hex|_octal|_ascii,
_digit|_hex|_octal|_ascii, _digit|_hex|_octal|_ascii,
_digit|_hex|_octal|_ascii, _digit|_hex|_octal|_ascii,
_digit|_hex|_octal|_ascii, _digit|_hex|_ascii,
_digit|_hex|_ascii, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _alpha|_hex|_ascii,
_alpha|_hex|_ascii, _alpha|_hex|_ascii,
_alpha|_hex|_ascii, _alpha|_hex|_ascii,
_alpha|_hex|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_alpha|_ascii|_hex, _alpha|_ascii|_hex,
_alpha|_ascii|_hex, _alpha|_ascii|_hex,
_alpha|_ascii|_hex, _alpha|_ascii|_hex,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _alpha|_ascii,
_alpha|_ascii, _alpha|_ascii, _ascii|_punct,
_ascii|_punct, _ascii|_punct, _ascii|_punct,
_cntrl|_ascii,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
};
/* FILE: Num2PStr.c
Creates a pascal string rep of a given type of
number, returning TRUE if it fails to do so. */
#include“PStrLib.h”
Num2PStr(type, numPtr, pStr, format, places)
inttype;/* type of var pointed at by numPtr */
void *numPtr; /* size of *numPtr depends on type */
register char *pStr;/* points to a PASCAL string */
int format; /* specifies Dec or Sci notation */
intplaces;/* # digits to right of Dec point */
{
auto Decimal _Decimal_;
auto DecForm _DecForm_;
register int n = 1;
/*
NOTE: When Dec2Str() fails, it sets pStr == ‘?’. The most common cause
of failure is trying to convert a large number to DEC string format using
a large places value. The do-while loop below catches such failures and
fixes them by changing the format to SCI which virtually never fails
(See the Apple Numerics Manual for more details).
*/
do {
_DecForm_.style = n > 0 ? format : FLOATDECIMAL;
_DecForm_.digits = format == FLOATDECIMAL ? places + 1 : places;
fp68k(&_DecForm_, numPtr, &_Decimal_, type + FOB2D);
Dec2Str(_DecForm_, &_Decimal_, pStr);
} while (pStr[1] == ‘?’ && --n >= 0);
Kreturn(pStr[1] == ‘?’); /* Ret TRUE if Dec2Str() FAILED */
}
/* FILE: PStr2Num.c
Sets value of a given type of number based on a pascal string representation,
returning TRUE if it fails to do so. */
#include“PStrLib.h”
PStr2Num(pStr, type, numPtr)
char *pStr;/* points to a PASCAL string */
inttype;/* type of variable n points at */
void *numPtr; /* generic pointer */
{
auto Decimal _decimal_;
auto int valid, index = 1;
/* start-scan pos. of pStr */
Str2Dec(pStr, &index, &_decimal_, &valid);
fp68k(&_decimal_, numPtr, type + FOD2B);
return(!valid); /*returns TRUE if failed */
}
/* FILE: PStrCat.c
Concatenates 2-30 Pascal strings. */
#include“PStrLib.h”
PStrCat(count, dst)
register intcount; /* # of strings (including dst) */
unsigned char *dst; /* destination pascal string */
{
register unsigned char *dstPtr, *srcPtr;
register unsigned char **argList = &dst;
register int argLen, totLen;
if ((totLen = *dst) < 255) {
if (count > 30)
count = 30;/* max. # of string args 30 */
dstPtr = dst + totLen;
/* dstPtr = 1 past end of dst */
while (--count > 0 && totLen < 255) {
srcPtr = *++argList;
argLen = srcPtr[0];
if (totLen + argLen > 255)
argLen = 255 - totLen;
/* max totLen = 255 */
totLen += argLen;
while (--argLen >= 0) /* add arg’s char to dst */
*++dstPtr = *++srcPtr;
}
dst[0] = totLen;/* sets length of dst */
}
}
/* FILE: PStrCmp.c
Compares src to dst returning <0 less than, =0 equal, >0 greater */
#include“PStrLib.h”
PStrCmp(src, dst)
register unsigned char *src, *dst; /* Pascal strings */
{
register int slen = *src, dlen = *dst;
register int mlen = *src <= *dst ? *src : *dst;
while (--mlen >= 0 && *++src == *++dst);
return(((slen != dlen && *src == *dst) ? slen - dlen : *src - *dst));
}
/* FILE: PStrCopy.c
Copys count char from pos of src to dst. */
#include“PStrLib.h”
PStrCopy(src, pos, count, dst)
register unsigned char *src, *dst; /* Pascal strings */
register intpos, count;
{
register int max;
--pos;
if (count > (max = *src - pos))
count = max;
src += pos;
*dst = count;
while (--count >= 0) *++dst = *++src;
}
/* FILE: PStrDel.c
Deletes count chars from pos of dst. */
#include“PStrLib.h”
PStrDel(s, pos, count)
register unsigned char *s; /* Pascal string */
register intpos, count;
{
register unsigned char *t;
register int shift;
if (*s) {
if (--pos + count > *s)
count = *s - pos;
shift = *s - pos;
*s -= count;
s += pos;
t = s + count;
while (--shift >= 0)
*++s = *++t;
}
}
/* FILE: PStrDraw.c
Draws 1 to 10 Pascal strings at specified locations in the current GrafPort.
It Offers auto-centering and New-Line modes. If h == 0 then it uses
the last (current) h position. If v == 0 then it uses the last (current)
v position. If x < 0 then s is centered inside the portRect. If y <
0 then it offsets -y number of lines from current v pos. Otherwise, h
and v represent the desired x and y coordinates. */
#include“PStrLib.h”
PStrDraw(count, s, h, v)
intcount; /* number of { s, h, v} sets to follow */
char *s; /* a pascal string to draw */
inth; /* horizontal position */
intv; /* vertical position */
{
register char *argPtr = (char *)&count;
register char *sp;
register Rect *rp = &thePort->portRect;
register int x, y, lineHeight = 1.5 * thePort->txSize;
static int old_x = 0, old_y = 0;
while (--count >= 0) {
sp = *(char **)(argPtr += 2);
x = *(int *)(argPtr += 4);
y = *(int *)(argPtr += 2);
if (x >= 0)
old_x = x;
else if (x != CUR)/* Auto-Center Mode? */
old_x = (rp->right - rp->left - StringWidth(sp)) / 2;
if (y >= 0)
old_y = y;
else if (y != CUR)/* New-Line Mode? */
old_y += -y * lineHeight;
MoveTo(old_x, old_y);
DrawString(sp);
old_x += StringWidth(sp);
}
}
/* FILE: PStrFind.c
Finds first occurance of p in t. */
#include“PStrLib.h”
PStrFind(p, t, pos)
unsigned char *p, *t; /* Pascal strings */
register intpos; /* char pos to start search */
{/* range of pos: 1 to 255 */
register unsigned char *tp = t + pos, *pp = p, *ppe=p + *p;
register long tpe = (long)(t + *t); /*trick ptr!*/
while (++pp <= ppe && tp <= (unsigned char *)tpe) {
while (*pp != *tp) {
tp = t + ++pos; /* tp to next pos in text */
pp = p + 1;/* sp to start of pattern */
}
++tp; /* compare next char for match */
}
return(pp > ppe ? pos : 0);
/* 0 if Not Found, else char position in t */
}
/* FILE: PStrFindFC.c
Finds first occurance of c in s. */
#include“PStrLib.h”
PStrFindFC(s, c)
register unsigned char *s; /* Pascal string */
register intc; /* char to find */
{
register int n = *s;
register unsigned char *sp = s;
c &= 0xFF;
/* strip sign ext. in case caller was type char */
while (*++sp != c && --n >= 0);
return(n >= 0 ? sp - s : 0);
}/* Result: 0 if Not Found, else char position */
/* FILE: PStrFindFNS.c
Finds first occurance in s NOT in set. */
#include“PStrLib.h”
PStrFindFNS(s, set)
unsigned char *s, *set; /* Pascal strings */
{
register int i = *s, n;
register unsigned char *setp, *sp = s;
while (--i >= 0) {
++sp;
setp = set;
n = *setp;
while (--n >= 0 && *++setp != *sp);
if (n < 0) return(sp - s);
}
return(0);
}/* Result: 0 if Not Found, else char position */
/* FILE: PStrFindFS.c
Finds first occurance in both s and set. */
#include“PStrLib.h”
PStrFindFS(s, set)
unsigned char *s, *set; /* Pascal strings */
{
register int i = *s, n;
register unsigned char *setp, *sp = s;
while (--i >= 0) {
++sp;
setp = set;
n = *setp;
while (--n >= 0 && *++setp != *sp);
if (n >= 0) return(sp - s);
}
return(0);
}/* Result: 0 if Not Found, else char position */
/* FILE: PStrFindLC.c
Finds last occurance of c in s. */
#include“PStrLib.h”
PStrFindLC(s, c)
register unsigned char *s; /* Pascal string */
register intc; /* char to find */
{
register int n = *s;
register unsigned char *sp = s + n + 1;
c &= 0xFF;
/* strips sign ext. in case caller was ‘char’ */
while (*--sp != c && --n >= 0);
return(sp - s);
}/* Result: 0 if Not Found, else char position */
/* FILE: PStrFindLS.c
Finds last occurance in both s and set. */
#include“PStrLib.h”
PStrFindLS(s, set)
unsigned char *s, *set; /* Pascal strings */
{
register int i = *s, n;
register unsigned char *setp, *sp = s + i;
while (--i >= 0) {
setp = set;
n = *setp;
while (--n >= 0 && *++setp != *sp);
if (n >= 0) return(sp - s);
--sp;
}
return(0);
}/* Result: 0 if Not Found, else char position */
/* FILE: PStrFixLen.c
Sets length of pascal string s to len by either chopping extra chars
off or by padding out with c characters. */
#include“PStrLib.h”
PStrFixLen(s, len, c)
registerunsigned char*s; /* pascal string */
register int len;/* max length is 255 */
registerint c; /* pad character */
{
register unsigned char *sp = s + *s;
register int n;
if (*s < (len &= 0xFF)) {
n = len - *s;
while (--n >= 0) *++sp = c;
}
*s = len;
}
/* FILE: PStrIns.c
Inserts src at pos of dst. */
#include“PStrLib.h”
PStrIns(src, dst, pos)
unsigned char *src; /* Pascal string */
register unsigned char *dst; /* Pascal string */
register intpos;
{
register unsigned char *s, *d;
register int len, shift;
if (--pos + *src < 256) {
len = *src;
*dst += len;
shift = *dst - pos;
s = dst + *dst;
d = ++s + len;
while (--shift >= 0)
*--d = *--s;
}
else {
len = 255 - pos;
*dst = 255;
}
s = dst + pos;
while (--len >= 0)
*++s = *++src;
}
/* FILE: PStrRep.c
Replaces count chars from pos of dst with src. */
#include“PStrLib.h”
PStrRep(dst, pos, len, src)
register char *dst, *src;/* pascal strings */
register intpos, len;
{
PStrDel(dst, pos, len);
PStrIns(src, dst, pos);
}
/* FILE: SetFont.c
Sets the txFont, txSize, txFace fields of the current GrafPort. */
#include“PStrLib.h”
SetFont(font, size, face)
intfont, size;
Style face;
{
TextFont(font);
TextSize(size);
TextFace(face);
}
/* FILE: ShowVars.c
Displays up to 10 sets of variable labels and values. */
#include“PStrLib.h”
ShowVars(count, varLabel, varType, varPtr)
intcount; /* # of {varLabel,varType,varPtr} sets */
char *varLabel; /* string label for variable */
intvarType; /* type of variable*/
char *varPtr; /* pointer to variable */
{
auto char**lh = &varLabel; /* Ptr 1st varLabel */
auto int *tp = &varType; /* Ptr to 1st varType */
auto char**vh = &varPtr; /* Ptr to 1st varPtr */
auto char*sp;
auto Str255s;
auto RectwRect;
auto WindowPtr wp, savedPort;
auto int y = 5;
if (count > 0) {
if (count > 10)
count = 10;/* max number of arg. sets */
GetPort(&savedPort);
wRect.top = 45;
wRect.left = 72;
wRect.bottom = count * 20 + wRect.top + 45;
wRect.right = 440;
wp = NewWindow(NIL, &wRect, NIL, TRUE, dBoxProc, -1L, FALSE, NIL);
SetPort(wp);
while (--count >= 0) {
if (*tp == PSTR)
sp = *vh;
else if (*tp == BOOL)
sp = **(Boolean **)vh ? “\pTRUE” : “\pFALSE”;
else {
sp = (char *)s;
Num2PStr(*tp, *vh, sp, DEC, (*tp >= CINT ? 0 : 6));
}
MoveTo(30, y += 20);
if (*lh && **lh){ /* Length varLabel > 0? */
DrawString(*lh);
DrawString(“\p = “);
}
DrawString(sp);
/*
Incr. Ptr’s 10 bytes each pass so they’ll
point to the next set of arg.s on the stack.
*/
lh = (char **)((char *)lh + 10);
tp += 5;
vh = (char **)((char *)vh + 10);
}
MoveTo(30, wRect.bottom - wRect.top - 10);
DrawString(“\pClick Mouse Button to Continue...”);
while (!Button());/* Wait for a mouse down event */
DisposeWindow(wp);
SetPort(savedPort);
}
}
