gno/lib/lsaneglue/README

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