gno/lib/lsaneglue/README
gdr-ftp f3bea84880 - changed the location where the macro source files are expected to be
found to reflect the directories now recommended in the FAQ.
- added a resource fork with an rVersion.
- use catrez instead of copyfork
- make 'install' and 'release' targets consistent with the rest of
  the GNO builds.
1998-02-08 03:16:55 +00:00

246 lines
7.1 KiB
Plaintext

SANE Glue Code for ORCA/C 2.1 or later
Written in 1997 by Soenke Behrens
Legal Stuff
===========
This library and the accompanying source code are hereby placed
into the Public Domain. There is no warranty, express or implied,
on the performance of the library or source code. The author is not
liable for any damage that may occur as a direct or indirect result
of using the library or source code.
Installation
============
In GNO/ME, run "dmake install".
This will copy a changed sane.h to /usr/include and the library
lsaneglue to 13.
If, on your system, includes are kept in a different directory (say
13/orcacdefs), either copy the files manually or edit the file
"makefile" to use a different path.
In ORCA/Shell, copy the changed include file and the library
manually.
Afterwards, use a directory ordering utility such as ProSel-16
to make sure lsaneglue comes _before_ ORCALIB.
Documentation, Use
==================
lsaneglue is a library that contains code to let you call
SANE functions directly from ORCA/C. To avoid namespace
conflicts with math.h, it was necessary to change sane.h.
Thus, all SANE functions are now prefixed with "s_" (e.g.
"annuity" became "s_annuity", and "sin" became "s_sin").
This lets you choose easily between the SANE and ISO/C
implementations of the same function.
Below you will find a brief overview over the functions in
lsaneglue. This overview does not replace, however, proper
documentation. To fully understand SANE, you will need the
"Apple Numerics Manual, 2nd Edition" by Apple Computer, Inc.,
ISBN 0-201-17738-2, published by Addison-Wesley Publishing
Company, Inc.
SANE is also introduced in the "Apple IIgs Toolbox Reference,
Volume 2", Chapter 18.
I find the functions to control the SANE environment (rounding
direction, halts &c.), the functions to spot NaNs (classification
functions) as well as the functions that give you a good pi, NaN
and INF particularly useful.
Brief SANE function overview
============================
There is one function in lsaneglue that has nothing to do with
SANE:
int findfpcp(void);
This function will find an FPE or NC card and return the slot number
(or -1 if card not found). You can use the output of this function
for the ORCA/C setfpeslot(), which is used when having ORCA/C
create code for the FPE/NC directly (#pragma float 1 1).
Now for the SANE interface functions.
I will give the prototype of the function, and a one-line description
on the following line. Page numbers refer to Apple Numerics Manual.
NB: Use the file "sane.h" itself as reference for constants used
to set/test exceptions, rounding direction, rounding precision,
number classes, ordering relations, formatting styles and NAN codes.
void s_num2dec(DecForm *f, extended x, Decimal *d);
Convert x to SANE decimal record. Pg 28
extended s_dec2num(Decimal *d);
Convert SANE decimal record to extended. Pg 28f
void s_str2dec(char *s, short *ix, Decimal *d, short *vp);
Convert string s to SANE decimal record. Pg 30f
void s_dec2str(DecForm *f, Decimal *d, char *s);
Convert SANE decimal record d to string. Pg 31ff
extended s_fabs(extended x);
Get the absolute of x (make sign positive). Pg 49
extended s_fneg(extended x);
Reverse sign of x. Pg 49
extended s_remainder(extended x, extended y, short *quo);
Get the remainder of x and y. Pg 46f
extended s_sqrt(extended x);
Compute square root of x. Pg 46
extended s_rint(extended x);
Round x to integer in current rounding direction. Pg 47
extended s_scalb(short n, extended x);
Return (x times 2^n). Pg 50
extended s_logb(extended x);
Compute binary exponent of normalized x. Pg 50
extended s_copysign(extended x, extended y);
Return y with sign of x. Pg 49
extended s_nextfloat(extended x, extended y);
Return next float number after x in direction of y. Pg 50
extended s_nextdouble(extended x, extended y);
Return next double number after x in direction of y. Pg 50
extended s_nextextended(extended x, extended y);
Return next extended number after x in direction of y. Pg 50
extended s_log2(extended x);
Return base-2 logarithm of x. Pg 62
extended s_log(extended x);
Return base-e (natural) logarithm of x. Pg 62
extended s_log1(extended x);
Return base-e (natural) logarithm of (x+1). Pg 62
extended s_exp2(extended x);
Return base-2 exponantial of x (2^x). Pg 63f
extended s_exp(extended x);
Return base-e (natural) exponantial of x (x^e). Pg 63f
extended s_exp1(extended x);
Return base-e (natural) exponantial of x, minus 1 (x^e - 1). Pg 63f
extended s_power(extended x, extended y);
Return x^y. Pg 63f
extended s_ipower(extended x, short i);
Return x^i. Pg 63f
extended s_compound(extended r, extended n);
Compute compound (1+r)^n. Pg 64f
extended s_annuity(extended r, extended n);
Compute annuity (1-(1+r)^n)/r. Pg 65
extended s_tan(extended x);
Return tangent of x. Pg 67f
extended s_sin(extended x);
Return sine of x. Pg 67
extended s_cos(extended x);
Return cosine of x. Pg 67
extended s_atan(extended x);
Return arctangent of x. Pg 67f
extended s_randomx(extended *x);
Return pseudorandom integer value with seed x. Pg 67
numclass s_classfloat(extended x);
Return classification of float x. Pg 44
numclass s_classdouble(extended x);
Return classification of double x. Pg 44
numclass s_classcomp(extended x);
Return classification of comp x. Pg 44
numclass s_classextended(extended);
Return classification of extended x. Pg 44
int s_signnum(extended x);
Return sign of x: 0 if positive, 1 if negative. Pg 44
void s_setexception(exception e, long b);
Clear or set SANE exceptions. Pg 54ff
long s_testexception(exception e);
Check whether SANE exception is currently set. Pg 54ff
void s_sethalt(exception e, long b);
Clear or set SANE exception halts. Pg 54ff
long s_testhalt(exception e);
Check whether SANE exception halt is currently set. Pg 54ff
void s_setround(rounddir r);
Set SANE rounding direction. Pg 52f
rounddir s_getround(void);
Get SANE rounding direction. Pg 52f
void s_setprecision(roundpre p);
Set SANE rounding precision. Pg 53
roundpre s_getprecision(void);
Get SANE rounding precision. Pg 53
void s_setenvironment(environment e);
Set SANE environment word. Pg 57
void s_getenvironment(environment *e);
Get SANE environment word. Pg 57
void s_procentry(environment *e);
Save SANE environment word, then default it. Pg 57
void s_procexit(environment e);
Restore SANE environment word, then signal exceptions. Pg 57
haltvector s_gethaltvector(void);
Get SANE halt vector. Pg 54
void s_sethaltvector(haltvector v);
Set SANE halt vector. Pg 54
relop s_relation(extended x, extended y);
Return relation of x to y. Pg 49
extended s_nan(unsigned char c);
Return NaN(c).
extended s_inf(void);
Return +INF (Infinity).
extended s_pi(void);
Return pi constant (3.141592653589793238512808959)
Errors in SANE toolkit
======================
The fclass functions should return the sign of the passed number
in n-bit and Y. They do not report the sign at all, though, which
has to be considered a bug. s_signnum() has been rewritten to not
rely on fclassx any more.
Soenke Behrens
September 1997
sbehrens@bigfoot.com