
Calc builtin functions
(as of version 2.12.4.8)
Builtin functions
There is a large number of builtin functions. Many of the
functions work on several types of arguments, whereas some only
work for the correct types (e.g., numbers or strings). In the
following description, this is indicated by whether or not the
description refers to values or numbers. This display is generated
by the 'show builtin' command.
Name Args Description
abs 12 absolute value within accuracy b
access 12 determine accessibility of file a for mode b
acos 12 arccosine of a within accuracy b
acosh 12 inverse hyperbolic cosine of a within accuracy b
acot 12 arccotangent of a within accuracy b
acoth 12 inverse hyperbolic cotangent of a within accuracy b
acsc 12 arccosecant of a within accuracy b
acsch 12 inverse csch of a within accuracy b
agd 12 inverse gudermannian function
append 1+ append values to end of list
appr 13 approximate a by multiple of b using rounding c
arg 12 argument (the angle) of complex number
argv 01 calc argc or argv string
asec 12 arcsecant of a within accuracy b
asech 12 inverse hyperbolic secant of a within accuracy b
asin 12 arcsine of a within accuracy b
asinh 12 inverse hyperbolic sine of a within accuracy b
assoc 0 create new association array
atan 12 arctangent of a within accuracy b
atan2 23 angle to point (b,a) within accuracy c
atanh 12 inverse hyperbolic tangent of a within accuracy b
avg 0+ arithmetic mean of values
base 01 set default output base
base2 01 set default secondary output base
bernoulli 1 Bernoulli number for index a
bit 2 whether bit b in value a is set
blk 03 block with or without name, octet number, chunksize
blkcpy 25 copy value to/from a block: blkcpy(d,s,len,di,si)
blkfree 1 free all storage from a named block
blocks 01 named block with specified index, or null value
bround 13 round value a to b number of binary places
btrunc 12 truncate a to b number of binary places
calc_tty 0 set tty for interactivity
calclevel 0 current calculation level
calcpath 0 current CALCPATH search path value
catalan 1 catalan number for index a
ceil 1 smallest integer greater than or equal to number
cfappr 13 approximate a within accuracy b using
continued fractions
cfsim 12 simplify number using continued fractions
char 1 character corresponding to integer value
cmdbuf 0 command buffer
cmp 2 compare values returning 1, 0, or 1
comb 2 combinatorial number a!/b!(ab)!
config 12 set or read configuration value
conj 1 complex conjugate of value
copy 25 copy value to/from a block: copy(s,d,len,si,di)
cos 12 cosine of value a within accuracy b
cosh 12 hyperbolic cosine of a within accuracy b
cot 12 cotangent of a within accuracy b
coth 12 hyperbolic cotangent of a within accuracy b
count 2 count listr/matrix elements satisfying some condition
cp 2 cross product of two vectors
csc 12 cosecant of a within accuracy b
csch 12 hyperbolic cosecant of a within accuracy b
ctime 0 date and time as string
custom 0+ custom builtin function interface
delete 2 delete element from list a at position b
den 1 denominator of fraction
det 1 determinant of matrix
digit 23 digit at specified decimal place of number
digits 12 number of digits in base b representation of a
display 01 number of decimal digits for displaying numbers
dp 2 dot product of two vectors
epsilon 01 set or read allowed error for real calculations
errcount 01 set or read error count
errmax 01 set or read maximum for error count
errno 01 set or read calc_errno
error 01 generate error value
estr 1 exact text string representation of value
euler 1 Euler number
eval 1 evaluate expression from string to value
exp 12 exponential of value a within accuracy b
factor 13 lowest prime factor < b of a, return c if error
fcnt 2 count of times one number divides another
fib 1 Fibonacci number F(n)
forall 2 do function for all elements of list or matrix
frem 2 number with all occurrences of factor removed
fact 1 factorial
fclose 0+ close file
feof 1 whether EOF reached for file
ferror 1 whether error occurred for file
fflush 0+ flush output to file(s)
fgetc 1 read next char from file
fgetfield 1 read next whitespace delimited field from file
fgetfile 1 read to end of file
fgetline 1 read next line from file, newline removed
fgets 1 read next line from file, newline is kept
fgetstr 1 read next nullterminated string from file, null
character is kept
files 01 return opened file or max number of opened files
floor 1 greatest integer less than or equal to number
fopen 2 open file name a in mode b
fpathopen 23 open file name a in mode b, search for a along
CALCPATH or path c
fprintf 2+ print formatted output to opened file
fputc 2 write a character to a file
fputs 2+ write one or more strings to a file
fputstr 2+ write one or more nullterminated strings to a file
free 0+ free listed or all global variables
freebernoulli 0 free stored Bernoulli numbers
freeeuler 0 free stored Euler numbers
freeglobals 0 free all global and visible static variables
freeredc 0 free redc data cache
freestatics 0 free all unscoped static variables
freopen 23 reopen a file stream to a named file
fscan 2+ scan a file for assignments to one or
more variables
fscanf 2+ formatted scan of a file for assignment to one
or more variables
fseek 23 seek to position b (offset from c) in file a
fsize 1 return the size of the file
ftell 1 return the file position
frac 1 fractional part of value
gcd 1+ greatest common divisor
gcdrem 2 a divided repeatedly by gcd with b
gd 12 gudermannian function
getenv 1 value of environment variable (or NULL)
hash 1+ return nonnegative hash value for one or
more values
head 2 return list of specified number at head of a list
highbit 1 high bit number in base 2 representation
hmean 0+ harmonic mean of values
hnrmod 4 v mod h*2^n+r, h>0, n>0, r = 1, 0 or 1
hypot 23 hypotenuse of right triangle within accuracy c
ilog 2 integral log of a to integral base b
ilog10 1 integral log of a number base 10
ilog2 1 integral log of a number base 2
im 1 imaginary part of complex number
indices 2 indices of a specified assoc or mat value
inputlevel 0 current input depth
insert 2+ insert values c ... into list a at position b
int 1 integer part of value
inverse 1 multiplicative inverse of value
iroot 2 integer b'th root of a
isassoc 1 whether a value is an association
isatty 1 whether a file is a tty
isblk 1 whether a value is a block
isconfig 1 whether a value is a config state
isdefined 1 whether a string names a function
iserror 1 where a value is an error
iseven 1 whether a value is an even integer
isfile 1 whether a value is a file
ishash 1 whether a value is a hash state
isident 1 returns 1 if identity matrix
isint 1 whether a value is an integer
islist 1 whether a value is a list
ismat 1 whether a value is a matrix
ismult 2 whether a is a multiple of b
isnull 1 whether a value is the null value
isnum 1 whether a value is a number
isobj 1 whether a value is an object
isobjtype 1 whether a string names an object type
isodd 1 whether a value is an odd integer
isoctet 1 whether a value is an octet
isprime 12 whether a is a small prime, return b if error
isptr 1 whether a value is a pointer
isqrt 1 integer part of square root
isrand 1 whether a value is a additive 55 state
israndom 1 whether a value is a Blum state
isreal 1 whether a value is a real number
isrel 2 whether two numbers are relatively prime
isstr 1 whether a value is a string
issimple 1 whether value is a simple type
issq 1 whether or not number is a square
istype 2 whether the type of a is same as the type of b
jacobi 2 1 => a is not quadratic residue mod b
1 => b is composite, or a is quad residue of b
join 1+ join one or more lists into one list
lcm 1+ least common multiple
lcmfact 1 lcm of all integers up till number
lfactor 2 lowest prime factor of a in first b primes
links 1 links to number or string value
list 0+ create list of specified values
ln 12 natural logarithm of value a within accuracy b
log 12 base 10 logarithm of value a within accuracy b
lowbit 1 low bit number in base 2 representation
ltol 12 legtoleg of unit right triangle (sqrt(1  a^2))
makelist 1 create a list with a null elements
matdim 1 number of dimensions of matrix
matfill 23 fill matrix with value b (value c on diagonal)
matmax 2 maximum index of matrix a dim b
matmin 2 minimum index of matrix a dim b
matsum 1 sum the numeric values in a matrix
mattrace 1 return the trace of a square matrix
mattrans 1 transpose of matrix
max 0+ maximum value
memsize 1 number of octets used by the value, including overhead
meq 3 whether a and b are equal modulo c
min 0+ minimum value
minv 2 inverse of a modulo b
mmin 2 a mod b value with smallest abs value
mne 3 whether a and b are not equal modulo c
mod 23 residue of a modulo b, rounding type c
modify 2 modify elements of a list or matrix
name 1 name assigned to block or file
near 23 sign of (abs(ab)  c)
newerror 01 create new error type with message a
nextcand 15 smallest value == d mod e > a, ptest(a,b,c) true
nextprime 12 return next small prime, return b if err
norm 1 norm of a value (square of absolute value)
null 0+ null value
num 1 numerator of fraction
ord 1 integer corresponding to character value
param 1 value of parameter n (or parameter count if n
is zero)
perm 2 permutation number a!/(ab)!
prevcand 15 largest value == d mod e < a, ptest(a,b,c) true
prevprime 12 return previous small prime, return b if err
pfact 1 product of primes up till number
pi 01 value of pi accurate to within epsilon
pix 12 number of primes <= a < 2^32, return b if error
places 12 places after "decimal" point (1 if infinite)
pmod 3 mod of a power (a ^ b (mod c))
polar 23 complex value of polar coordinate (a * exp(b*1i))
poly 1+ evaluates a polynomial given its coefficients
or coefficientlist
pop 1 pop value from front of list
popcnt 12 number of bits in a that match b (or 1)
power 23 value a raised to the power b within accuracy c
protect 13 read or set protection level for variable
ptest 13 probabilistic primality test
printf 1+ print formatted output to stdout
prompt 1 prompt for input line using value a
push 1+ push values onto front of list
putenv 12 define an environment variable
quo 23 integer quotient of a by b, rounding type c
quomod 45 set c and d to quotient and remainder of a
divided by b
rand 02 additive 55 random number [0,2^64), [0,a), or [a,b)
randbit 01 additive 55 random number [0,2^a)
random 02 BlumBlumShub random number [0,2^64), [0,a), or [a,b)
randombit 01 BlumBlumSub random number [0,2^a)
randperm 1 random permutation of a list or matrix
rcin 2 convert normal number a to REDC number mod b
rcmul 3 multiply REDC numbers a and b mod c
rcout 2 convert REDC number a mod b to normal number
rcpow 3 raise REDC number a to power b mod c
rcsq 2 square REDC number a mod b
re 1 real part of complex number
remove 1 remove value from end of list
reverse 1 reverse a copy of a matrix or list
rewind 0+ rewind file(s)
rm 1+ remove file(s), f turns off nosuchfile errors
root 23 value a taken to the b'th root within accuracy c
round 13 round value a to b number of decimal places
rsearch 24 reverse search matrix or list for value b
starting at index c
runtime 0 user and kernel mode cpu time in seconds
saveval 1 set flag for saving values
scale 2 scale value up or down by a power of two
scan 1+ scan standard input for assignment to one
or more variables
scanf 2+ formatted scan of standard input for assignment
to variables
search 24 search matrix or list for value b starting
at index c
sec 12 sec of a within accuracy b
sech 12 hyperbolic secant of a within accuracy b
seed 0 return a 64 bit seed for a psuedorandom generator
segment 23 specified segment of specified list
select 2 form sublist of selected elements from list
setbit 23 set specified bit in string
sgn 1 sign of value (1, 0, 1)
sha1 0+ Secure Hash Algorithm (SHS1 FIPS Pub 1801)
sin 12 sine of value a within accuracy b
sinh 12 hyperbolic sine of a within accuracy b
size 1 total number of elements in value
sizeof 1 number of octets used to hold the value
sleep 01 suspend operation for a seconds
sort 1 sort a copy of a matrix or list
sqrt 13 square root of value a within accuracy b
srand 01 seed the rand() function
srandom 04 seed the random() function
ssq 1+ sum of squares of values
stoponerror 01 assign value to stoponerror flag
str 1 simple value converted to string
strcat 1+ concatenate strings together
strcmp 2 compare two strings
strcpy 2 copy string to string
strerror 01 string describing error type
strlen 1 length of string
strncmp 3 compare strings a, b to c characters
strncpy 3 copy up to c characters from string to string
strpos 2 index of first occurrence of b in a
strprintf 1+ return formatted output as a string
strscan 2+ scan a string for assignments to one or more variables
strscanf 2+ formatted scan of string for assignments to variables
substr 3 substring of a from position b for c chars
sum 0+ sum of list or object sums and/or other terms
swap 2 swap values of variables a and b (can be dangerous)
system 1 call Unix command
systime 0 kernel mode cpu time in seconds
tail 2 retain list of specified number at tail of list
tan 12 tangent of a within accuracy b
tanh 12 hyperbolic tangent of a within accuracy b
test 1 test that value is nonzero
time 0 number of seconds since 00:00:00 1 Jan 1970 UTC
trunc 12 truncate a to b number of decimal places
ungetc 2 unget char read from file
usertime 0 user mode cpu time in seconds
version 0 calc version string
xor 1+ logical xor
The config function sets or reads the value of a configuration
parameter. The first argument is a string which names the parameter
to be set or read. If only one argument is given, then the current
value of the named parameter is returned. If two arguments are given,
then the named parameter is set to the value of the second argument,
and the old value of the parameter is returned. Therefore you can
change a parameter and restore its old value later. The possible
parameters are explained in the next section.
The scale function multiplies or divides a number by a power of 2.
This is used for fractional calculations, unlike the << and >>
operators, which are only defined for integers. For example,
scale(6, 3) is 3/4.
The quomod function is used to obtain both the quotient and remainder
of a division in one operation. The first two arguments a and b are
the numbers to be divided. The last two arguments c and d are two
variables which will be assigned the quotient and remainder. For
nonnegative arguments, the results are equivalent to computing a//b
and a%b. If a is negative and the remainder is nonzero, then the
quotient will be one less than a//b. This makes the following three
properties always hold: The quotient c is always an integer. The
remainder d is always 0 <= d < b. The equation a = b * c + d always
holds. This function returns 0 if there is no remainder, and 1 if
there is a remainder. For examples, quomod(10, 3, x, y) sets x to 3,
y to 1, and returns the value 1, and quomod(4, 3.14159, x, y) sets x
to 2, y to 2.28318, and returns the value 1.
The eval function accepts a string argument and evaluates the
expression represented by the string and returns its value.
The expression can include function calls and variable references.
For example, eval("fact(3) + 7") returns 13. When combined with
the prompt function, this allows the calculator to read values from
the user. For example, x=eval(prompt("Number: ")) sets x to the
value input by the user.
The digit and bit functions return individual digits of a number,
either in base 10 or in base 2, where the lowest digit of a number
is at digit position 0. For example, digit(5678, 3) is 5, and
bit(0b1000100, 2) is 1. Negative digit positions indicate places
to the right of the decimal or binary point, so that for example,
digit(3.456, 1) is 4.
The ptest builtin is a primality testing function. The
1st argument is the suspected prime to be tested. The
absolute value of the 2nd argument is an iteration count.
If ptest is called with only 2 args, the 3rd argument is
assumed to be 0. If ptest is called with only 1 arg, the
2nd argument is assumed to be 1. Thus, the following
calls are equivalent:
ptest(a)
ptest(a,1)
ptest(a,1,0)
Normally ptest performs a some checks to determine if the
value is divisable by some trivial prime. If the 2nd
argument is < 0, then the trivial check is omitted.
For example, ptest(a,10) performs the same work as:
ptest(a,3) (7 tests without trivial check)
ptest(a,7,3) (3 more tests without the trivial check)
The ptest function returns 0 if the number is definitely not
prime, and 1 is the number is probably prime. The chance
of a number which is probably prime being actually composite
is less than 1/4 raised to the power of the iteration count.
For example, for a random number p, ptest(p, 10) incorrectly
returns 1 less than once in every million numbers, and you
will probably never find a number where ptest(p, 20) gives
the wrong answer.
The first 3 args of nextcand and prevcand functions are the same
arguments as ptest. But unlike ptest, nextcand and prevcand return
the next and previous values for which ptest is true.
For example, nextcand(2^1000) returns 2^1000+297 because
2^1000+297 is the smallest value x > 2^1000 for which
ptest(x,1) is true. And for example, prevcand(2^311,10,5)
returns 2147483629 (2^3119) because 2^3119 is the largest
value y < 2^311 for which ptest(y,10,5) is true.
The nextcand and prevcand functions also have a 5 argument form:
nextcand(num, count, skip, modval, modulus)
prevcand(num, count, skip, modval, modulus)
return the smallest (or largest) value ans > num (or < num) that
is also == modval % modulus for which ptest(ans,count,skip) is true.
The builtins nextprime(x) and prevprime(x) return the
next and previous primes with respect to x respectively.
As of this release, x must be < 2^32. With one argument, they
will return an error if x is out of range. With two arguments,
they will not generate an error but instead will return y.
The builtin function pix(x) returns the number of primes <= x.
As of this release, x must be < 2^32. With one argument, pix(x)
will return an error if x is out of range. With two arguments,
pix(x,y) will not generate an error but instead will return y.
The builtin function factor may be used to search for the
smallest factor of a given number. The call factor(x,y)
will attempt to find the smallest factor of x < min(x,y).
As of this release, y must be < 2^32. If y is omitted, y
is assumed to be 2^321.
If x < 0, factor(x,y) will return 1. If no factor <
min(x,y) is found, factor(x,y) will return 1. In all other
cases, factor(x,y) will return the smallest prime factor
of x. Note except for the case when abs(x) == 1, factor(x,y)
will not return x.
If factor is called with y that is too large, or if x or y
is not an integer, calc will report an error. If a 3rd argument
is given, factor will return that value instead. For example,
factor(1/2,b,c) will return c instead of issuing an error.
The builtin lfactor(x,y) searches a number of primes instead
of below a limit. As of this release, y must be <= 203280221
(y <= pix(2^321)). In all other cases, lfactor is operates
in the same way as factor.
If lfactor is called with y that is too large, or if x or y
is not an integer, calc will report an error. If a 3rd argument
is given, lfactor will return that value instead. For example,
lfactor(1/2,b,c) will return c instead of issuing an error.
The lfactor function is slower than factor. If possible factor
should be used instead of lfactor.
The builtin isprime(x) will attempt to determine if x is prime.
As of this release, x must be < 2^32. With one argument, isprime(x)
will return an error if x is out of range. With two arguments,
isprime(x,y) will not generate an error but instead will return y.
The functions rcin, rcmul, rcout, rcpow, and rcsq are used to
perform modular arithmetic calculations for large odd numbers
faster than the usual methods. To do this, you first use the
rcin function to convert all input values into numbers which are
in a format called REDC format. Then you use rcmul, rcsq, and
rcpow to multiply such numbers together to produce results also
in REDC format. Finally, you use rcout to convert a number in
REDC format back to a normal number. The addition, subtraction,
negation, and equality comparison between REDC numbers are done
using the normal modular methods. For example, to calculate the
value 13 * 17 + 1 (mod 11), you could use:
p = 11;
t1 = rcin(13, p);
t2 = rcin(17, p);
t3 = rcin(1, p);
t4 = rcmul(t1, t2, p);
t5 = (t4 + t3) % p;
answer = rcout(t5, p);
The swap function exchanges the values of two variables without
performing copies. For example, after:
x = 17;
y = 19;
swap(x, y);
then x is 19 and y is 17. This function should not be used to
swap a value which is contained within another one. If this is
done, then some memory will be lost. For example, the following
should not be done:
mat x[5];
swap(x, x[0]);
The hash function returns a relatively small nonnegative integer
for one or more input values. The hash values should not be used
across runs of the calculator, since the algorithms used to generate
the hash value may change with different versions of the calculator.
The base function allows one to specify how numbers should be
printed. The base function provides a numeric shorthand to the
config("mode") interface. With no args, base() will return the
current mode. With 1 arg, base(val) will set the mode according to
the arg and return the previous mode.
The following convention is used to declare modes:
base config
value string
2 "binary" binary fractions
8 "octal" octal fractions
10 "real" decimal floating point
16 "hex" hexadecimal fractions
10 "int" decimal integer
1/3 "frac" decimal fractions
1e20 "exp" decimal exponential
For convenience, any noninteger value is assumed to mean "frac",
and any integer >= 2^64 is assumed to mean "exp".
