PStrings in C
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