********** THE 83-BASIC LIBRARY **********
               version 2.0
           by Daniel J. Bishop
           danb2k@hotmail.com

'Notepad users:
'Good time to turn on Word Wrap

*** Files Included ***

README.TXT -- this file
__xxxxx.83p -- 65 TI-BASIC subroutines, as described below
     The underscores in the filenames become thetas on the calculator.

*** Symbols used in this file ****

-> = the STO key
\L\ = start of list name (LIST\OPS\B)
\theta\ = theta ([ALPHA][3])
     The function names all start with thetas so they'll be at the bottom of the PRGM list.
?= possible value (as in rand ?= .543)  Used in the random number examples.

*** Function Calls ***

Calls to 83-Basic Library functions are as follows

{parameter list} -> \L\PARAM
prgm\theta\\theta\FUNC

FUNC should be replaced by the name of the function.  The return value(s) for the function will be stored in the list RET.

For example, the following code is equivalent to C++'s C = A % B
{A,B} -> \L\PARAM
prgm\theta\\theta\MOD
\L\RET(1) -> C

If you need to save the parameters and local variables for the current subprogram, use this:

prgm\theta\\theta\LPUSH
prgm\theta\\theta\PPUSH
{parameter list} -> \L\PARAM
prgm\theta\\theta\FUNC
prgm\theta\\theta\PPOP
prgm\theta\\theta\LPOP

The order of the statements is important.  Because this kind of function call uses so much code, it is preferable to your programs in a way that doesn't require LOCAL and PARAM to be preserved after a call to another function.

In the examples, the function calls will be written as:

function_name(PARAM)=RET

This is usually easier to understand than the actual function call.  However, it is not TI_BASIC syntax.  Do not use it in a program.

*** Copyright Information ***

You may use these functions in your programs and distribute them without paying me any fees, as long as the documentation for your program clearly indicates the author of these functions.

*** Stack Functions ***

Notes: Start your main program with {0} -> \L\STACK
For more info on stacks, ask an asm programmer.
The other functions in this library don't use stack functions.

LPOP: pops list LOCAL from STACK
LPUSH: pushes list LOCAL onto STACK
PPOP: pops list PARAM from STACK
PPUSH: pushes list PARAM onto STACK

*** Trig Functions ***

Note: All trig functions can have multiple parameters.
Remember that answers depend on mode (deg/rad).

ACOT
param={x}
returns: the inverse cotangent of x
example: acot(1)=45

ACSC
param={x}
returns: the inverse cosecant of x
example: acsc(2)=30

ASEC
param={x}
returns: the inverse secant of x
example: asec(2)=60

COT
param={theta}
returns: the cotangent of theta
example: cot(90)=0

CSC
param={theta}
returns: the cosecant of theta
example: csc(30)=2

SEC
param={theta}
returns: the secant of theta
example: sec(60)=2

*** Other Triangle Functions ***

ISTRI
param={a,b,c}
returns: 1 if sides a, b, and c can form a triangle; 0 otherwise
examples:
     istri(3,4,5)=1
     istri(3,4,8)=0

TAREA
param={a,b,c}
returns: area of a triangle with sides a, b, and c
     does not check triangle inequality: use ISTRI
examples:
     tarea(3,4,5)=6
     tarea(6,7,8)=20.33316257

*** Hyperbolic Functions ***

ACSCH
param={x}
returns: the inverse hyperbolic cosecant of x
example: acsch(1)=.881373587

ASECH
param={x}
returns: the inverse hyperbolic secant of x
example: asech(1)=0

ATANH
param={x}
returns: the inverse hyperbolic tangent of x
example: atanh(2)=.5493061443

COTH
param={x}
returns: the hyperbolic cotangent of x
example: coth(1)=1.313035285

CSCH
param={x}
returns: the hyperbolic cosecant of x
example: csch(1)=.8509181282

SECH
param={x}
returns: the hyperbolic secant of x
example: sech(1)=.6480542737

*** More Angle Functions ***

DD2DMS
param={theta}
returns: theta in DMS notation
example: dd2dms(12.3456)={12,20,44.16}

DMS2DD
param={degrees,minutes,seconds}
returns: angle in decimal notation
example: dms2dd(12,20,44.16)=12.3456

POLAR
param={x,y}
returns: polar coordinates {r,theta}
example: polar(1,1)={1.414213562,45}

RECT
param={r,theta}
returns: point in rectangular coordinates (x,y)
example: rect(1,90)={0,1}

*** Date Functions ***

DWKSTR
param={day}: 0 <= day <= 6
returns: string representation of day of week stored in Str1
examples:
     dwkstr(0)="SUNDAY"
     dwkstr(1)="MONDAY"
     dwkstr(6)="SATURDAY"

JULIAN
param={year,month,day}
returns: Julian date
examples:
     julian(2000,1,1)=2000.001
     julian(1995,2,10)=1995.041

LEAPYR
param={year}
returns: 1 is year is leap year, 0 otherwise
examples:
     leapyr(2000)=1
     leapyr(1995)=0
     leapyr(2004,2005,2006)={1,0,0}

MONSTR
param={month}: 1 <= month <= 12
returns: string representation of month
examples:
     monstr(1)="JANUARY"
     monstr(2)="FEBRUARY"
     monstr(12)="DECEMBER"

RD
param={year,month,day} OR {Julian_date}
returns: rata die (days since 1 January A.D. 1)
examples:
     rd(1995,2,10)=728334
     rd(2000.001)=730120
notes:
     1. This function requires the JULIAN function.
     2. day of week = rd mod 7
     3. days between dates = rd2 - rd1
        For example, 730120-728334=1786, so 1 Jan. 2000 was 1786
        days after 10 Feb. 1995.

WKDAY
param={year,month,day} OR {Julian_date}
returns: day of week
     0 = Sunday
     1 = Monday
     2 = Tuesday
     3 = Wednesday
     4 = Thursday
     5 = Friday
     6 = Saturday
examples:
     wkday(1995,2,10)=5     '10 Feb. 1995 was a Friday
     wkday(2000.001)=6      'New Year's Day 2000 was Saturday
note: uses JULIAN and MOD functions

***  Random-number Functions ***

DICE
param={num_rolls} OR {num_rolls,high}
returns: A list of num_rolls random numbers between 1 and high.
     high=6 if not specified
examples:
     dice(10) ?= {3,5,5,6,3,4,3,1,6}
     dice(4,8) ?= {1,1,3,1,4,4,1,3}

RAND
param={n}
returns: A list of n random numbers between 0 and 1
example:
     rand(3) ?= {.1531048432,.4136222925,.1567457195}

SHUFFL
param=any list
returns: the elements of the list in random order
example:
     shuffl(1,2,3,4,5) ?= {2,5,1,3,4}

*** Stats Functions ***

FCTRL
param={n}
returns: n! in scientific notation -- {mantissa,exponent}
examples:
     fctrl(5)={1.2,2}
     fctrl(100)={9.332621545,157}
note: very slow for large values of n

GMEAN
param=any list of positive numbers
returns: geometric mean of the list -- log gmean=mean(log x)
examples:
     gmean(1,100)=10
     gmean(1,3,9,27,81)=9

HMEAN
param=any list of nonzero numbers
returns: harmonic mean of the list -- 1/hmean=mean(1/x)
examples:
     hmean(2,4)=2.666666667
     hmean(1,2,3)=1.636363636

INVT
param={p,df}
returns: t such that tcdf(-inf,t,df)=p
examples:
     invt(.5,1)=0
     invt(.95,24)=1.710882023

RANK
param=any list
returns: a list of the ranks, in order, of the list elements
     1 = lowest value, 2 = second-lowest value, etc.
examples:
     rank(100,10)={2,1}
     rank(10,100)={1,2}
     rank(10,8,3,9,4)={5,3,1,4,2}
     rank(8,2,4,1,5,7)={6,2,3,1,4,5}
note: does not work correctly for tied values          

SUMSQ
param={x1,x2,...}
returns: sum of x
examples:
     sumsq(1,2)=5
     sumsq(3,4)=25
     sumsq(1,2,3,4,5,6,7)=140     

ZSCORE
param={x,mu,sigma}
returns: z-score for x
examples:
     zscore(1500,1000,200)=2.5
     zscore(2,0,1)=2

*** Bit Functions ***

Note: all parameters must be integers between 0 and 65535, inclusive

BAND
param={a,b}
returns: equivalent to C's (a & b)
examples:
     band(5,6)=4
          // 0000000000000101 & 0000000000000110 = 0000000000000100
     band(61872,10674)=8624
          // 1111000110110000 & 0010100110110010 = 0010000110110000

BNOT
param={n}
returns: equivalent to C's ~n
examples:
     bnot(5)=65530
          // ~0000000000000101 = 1111111111111010
     bnot(61872)=3663
          // ~1111000110110000 = 0000111001001111

BOR
param={a,b}
returns: equivalent to C's (a | b)
examples:
     bor(5,6)=7
          // 0000000000000101 | 0000000000000110 = 0000000000000111
     bor(61872,10674)=63922
          // 1111000110110000 | 0010100110110010 = 1111100110110010

BSHL
param={n,p}
returns: n's bits shifted left p positions, modulo 65536
examples:
     bshl(5,3)=40
         // 0000000000000101 shl 3 = 0000000000101000
     bshl(61872,2)=50880
         // 1111000110110000 shl 2 = 1100011011000000

BSHR
param={n,p}
returns: n's bits shifted right p positions, truncated
examples:
     bshr(5,3)=0
          // 101 is "pushed off the end", so only 0's are left
     bshr(61872,2)=15468
          // 1111000110110000 shr 2 = 0011110001101100

BXOR
param={a,b}
returns: eauivalent to C's (a ^ b)
examples:
     bxor(5,6)=3
          // 0000000000000101 ^ 0000000000000110 = 0000000000000011
     bxor(61872,10674)=55298
          // 1111000110110000 ^ 0010100110110010 = 1101100000000010

*** Summation of j^k ***

TRINUM
param={n}
returns: the nth triangular number
examples:
     trinum(4)=10
     trinum(0,1,2,3)={0,1,3,6}

SUMX2
param={n}
returns: sum of j^2 for j = 0 to n
examples:
     sumx2(4)=30
     sumx2(0,1,2,3)={0,1,5,14}

SUMX3
param={n}
returns: sum of j^3 for j = 0 to n
examples:
     sumx3(4)=100
     sumx3(0,1,2,3)={0,1,9,36}

SUMX4
param={n}
returns: sum of j^4 for j = 0 to n
examples:
     sumx4(4)=354
     sumx4(0,1,2,3)={0,1,17,98}

*** Polynomial Functions ***

DISCR
param={a,b,c}
returns: b-4ac
examples:
     discr(1,1,-1)=5
     discr(1,0,-4)=16

PNEVAL
param={constant,x_coef,x_squared_coef,x_cubed_coef,...}
returns: P(x) evaluated at X
examples: assume that X=2
     pneval(3,2,1)=11     // 3 + 2*2^1 + 1*2^2
     pneval(1,1,1,1,1)=31 // 1 + 1*2^1 + 1*2^2 + 1*2^3 + 1*2^4

PNDER
param={constant,x_coef,x_squared_coef,x_cubed_coef,...}
returns: coefficients of dy/dx
examples:
     pnder(3,2,1)={4,3}
     pnder(1,1,1,1,1)={1,2,3,4}

QUAD
param={a,b,c}
returns: solutions to equation ax+bx+c=0
examples:
     quad(1,1,-1)={-.6180339887,1.618033989}
     quad(1,0,-4)={-2,2}
note: causes error if a=0

*** Miscellaneous Functions ***

ALPHA
param=any list of integers 1-26, inclusive
returns: letters represented by list elements stored in Str1
examples:
     alpha(1,2,3)="ABC"
     alpha(20,9)="TI"
     alpha(8,5,12,12,15)="HELLO"

CEIL
param={x}
returns: smallest integer greater than or equal to x
examples:
     ceil(3.14159)=4
     ceil(3)=3
     ceil(-2.7)=-2
     ceil(2.7183,1.414)={3,2}

DIGIT
param={n}
returns: digits of n in reverse order
examples:
     digit(210)={0,1,2}
     digit(41883)={3,8,8,1,4}

GCF
param=any list of integers
returns: greatest common factor of all elements in the list
examples:
     gcf(48,120)=24
     gcf(12,2000)=4
     gcf(30,45,60,90)=15

MOD
param={a,b}
returns: remainder when a is divided by b
examples:
     mod(100,12)=4
     mod(15,7)=1

RED1
param=any list of positive numbers
returns: reduced so that lowest value is 1
examples:
    red1(12,4,16)={3,1,4}
    red1(2,3,4)={1,1.5,2}

REDI
param=any list of positive integers
returns: reduced to lowest integer values
examples:
    redi(24,36)={2,3}
    redi(30,45,60,90}={2,3,4,6}
note: uses GCF function

REV
param=any list
returns: list elements in reverse order
examples:
     rev(1,2,3)={3,2,1}
     rev(4,7,4,8)={8,4,7,4}

ROUND
param={a,b}
returns: a rounded to the nearest multiple of b
examples:
     round(1990,1000)=2000
     round(68,5)=70
     round(pi,.01)=3.14

SIGN
param={x}
returns: -1 if x<0, 0 if x=0, 1 if x>0
examples:
     sign(0)=0
     sign(3)=1
     sign(-2)=-1
     sign(-30,20,-40,0)={-1,1,-1,0}

STR
param={x}
returns: string representation of x is stored in Str1
examples:
     str(123)="123"
     str(pi)="3.1415926535898"
note: all internally-stored digits will be stored in Str1

TDBL
param={rate}
returns: time it takes for an amount increasing at rate% to double
examples:
     tdbl(3.25)=21.67233176
     tdbl(4.5)=15.74730184

WINDOW
param={0,Xmin,Xmax,Ymin,Ymax} OR {0,Xmin,Xmax,Ymin,Ymax,Xscl,Yscl} OR
      {1,center_x,center_y,delta_x,delta_y} OR {1,center_x,center_y,delta_x,delta_y,Xscl,Ycsl}
returns: nothing
examples: (the following are both equivalent to ZDecimal)
     window(0,-4.7,4.7,-3.1,3.1,1,1}
     window(1,0,0,.1,.1,1,1}

*** Adding Your Own Functions ***

To add another function, simply create a new program whose name starts with 2 thetas.  Remember: \L\PARAM is for parameters and \L\RET is for return values.  Use no other variable except X and \L\LOCAL.  If you use LOCAL, be sure to include the line

DelVar \L\LOCAL

to the end of the program to remove leftover local variables.

*** Questions?  Comments?  Suggestions? ***

Please e-mail me at danb2k@hotmail.com