Comments

Scripts can be made executable and evaluated without invoking ised explicitly. This is done by including declaration

#!/usr/local/bin/ised --f

in the first line of the script. This line is obviously treated as comment.

In apply-to-file mode, comments and blank lines are preserved in input, but don't count as active lines and therefore don't increment line counter. If a file contains mixed data, it can still be processed line-by-line if non-numerical data is commented out.

Arrays and Separators

Output to terminal and history is suppressed by semicolon ; which can occur any number of times in every line (putting it at the end suppreses all output, but still evaluates memory operations, if they're present).

Examples:

{1 2 {3 4} 5,6} = {1 2 3 4 5 6}

{1 2+3 4 5*6+7} = {1 5 4 37}

1 5 1+1 = {1 5 2}

Array Constructors

[n]

generates sequence 0..n-1

[n1 n2]

generates sequence n1..n2 with increment 1. If n2<n1, sequence is descending.

[n1 m1..mi n2]

generates sequence between n1, n2, but with cycling increments, given as m1..mi.

Example: [0 1 2 10]={0 1 3 4 6 7 9}

(x)

repeats number x. This way parentheses can be used for evaluation precedence or for function arguments in scalar context.

(x n)

generates array of n repetitions of number x.

(x m1..mi n)

generates sequence of length n, starting at x with cycling increments m1..mi.

If n is negative, the increments are used |n| times, so for i increments, the output sequence has |n|*i+1 elements.

Examples:

(0 1 2 10)={0 1 3 4 6 7 9 10 12 13}

(0 [1 5] -1)={0 1 3 6 10 15}

{x1..xi}

array grouping

Component-wise Operators

x:+y x:-y x:*y x:/y x:%y x:^y

result is an array, where each component is e.g. a sum (or other binary operations above) of corresponding components of x and y. In case of different lengths of arrays, smaller length is used. Operations coresponding to above operators are: addition, substraction, multiplication, division, modulo, exponentiation. Note that modulo works for both integer and non-integer values. Modulo always satisfies this equation: i{x/dy}*y+x%y=x

Scalar-producing Operators

@+x

returns sum of components of x.

@*x

returns product of components of x.

x+*y

returns a result of alternating addition and subtraction, in the form ((x_0+y_0)*x_1+y_1)*x_2+y_2+...

If x is shorter than y, the elements of x are cyclically reused from the beginning of the array. If y is shorter than x, it is padded with zeroes. This way, a scalar x can be used to evaluate a polynomial with unit leading coefficient.

gcd lcm

return greatest common divisor and least common multiple of the numbers in the array, respectively. If the array includes noninteger numbers, a warning is issued and an empty array is returned. The result of gcd is negative if an odd number of the array are negative.

avg var

return linear average and variance (mean square dispersion). avg{x} is shorter notation for @+x/d#x and doesn't require inputting the array twice or storing it in memory.

Example: avg{0 1.5 3}={1.5}

nrm x y

returns generalized x-norm of vector y. If x is a vector, the result contains all specified norms. x=2 corresponds to Pythagoras' theorem, which is available also as operator @=.

Examples:

nrm2{1 1 1}={sqrt3}

nrm{1 3}{1 1}={2. cbrt2}

Function Maps

sin cos tan atn asn acs abs exp sqt cbt log

evaluates a function on every element of array, e.g. sin{1 2 3}={sin1 sin2 sin3}. Functions corresponding to above operators are sine, cosine, tangent, arc tangent, arc sine, arc cosine, magnitude, exponential, square root, cubic root, natural logarithm. Long operators atan asin acos sqrt cbrt are also valid. Exponential function is also available as e^, but has a lower precedence (the same as the operator ^). The unary / prefix is also a function map: /x=1.0/x.

x!

evaluates factorial on every element of array x. For floating point values it evaluates gamma(x+1). For negative integers, it returns 1.

r f i d

prefixes that modify values of array elements.

ran

randomizes elements of array. For integers, it returns random integers strictly smaller than given value. For floating values it returns real numbers.

phi

calculates the Euler totient function for positive integers. The nonpositive and noninteger values are skipped.

bj x y by x y

applies x-th Bessel function of first/second kind to array y. x should be one or more integers. Floating point values are cast to integers and a warning is issued.

Tensor Operators

x+y x-y x*y x/y x%y x^y

evaluate corresponding operations on every possible pair between elements of x and y. Most useful when one of the arguments is a scalar. Beware, the division operator / acts as an unary operator (inversion) when it has no left operand, or has a space on the left, but not on the right. For instance, /3 is equivalent to 1.0/3.

Examples:

{1 2 3 4}*{1 -1}={1 -1 2 -2 3 -3 4 -4}

{2 3 -5}*2={4 6 -10}

xey

operator for exponential notation. Useful mostly in scalar context, e.g. 1.3e-5, but can be used in general for evaluating exponential notation for all combinations.

xcy

evaluates binomial symbol (x over y). It supports floating point values.

Example: 3c{0 1 2 3}={1 3 3 1}

Polynomial Operators

x++y x--y

polynomial addition and substraction. This is similar to operators :+ :-, but the length of output array is equal to length of the larger array.

x**y

computes product of two polynomials. It terms of arrays, this evaluates to the convolution of x and y.

x//y x%%y

computes quotient and remainder in long polynomial division. Returned arrays always contain floating point values, regardless the input. Leading zeroes are trimmed from the output.

px x y

evaluates polynomial x in points, given in array y.

pd x

computes derivative of polynomial x. Equivalent to {x<<-1}:*[1 #x].

pz x

returns all real roots of polynomial x. Resulting array is not guaranteed to be sorted in any way.

This operator uses Sturm's sequence to isolate the roots, and proceeds with Newton-Raphson iteration. It works quite well for well-behaved polynomials. Accuracy is questionable if there are roots with multiplicity 3 or higher.

The algorithms outputs warning messages if the accuracy is questionable, or if the iteration fails to converge to a result.

zp x

is the inverse of the pz operator. It takes the set of roots and returns the minimal polynomial with given roots, with the leading coefficient normalized to 1.

pzzp should return the same array as on the input, up to a reordering of elements (excepting the numerical errors in root finding, especially if there are multiple roots). Conversely, zppz does not necessarily return the initial array, as it ignores the normalization factor and irreducible factors that don't have any real roots.

F x

returns the prime factorization of x. If x has many components, the factors are concatenated in a way that makes the product of the output array equal to the product of the input array. That makes the negative integer to produce an additional -1 factor, while floating point input numbers stay intact.

Vector Operators

x@:y

returns dot product of vectors x and y. In case of different array lengths, overhead is discarded.

x@^y

returns cross product of vectors x and y, if the vectors are three-dimensional. In general case, it returns components z_i=x_{i+1}*y_{i+2}-x_{i+2}*y_{i+1}.

This generalization is useful for polygon geometry. For polygon with coordinates {x_i,y_i}, the area of the polygon is 0.5*@+{x@^y}. Similar formulas exist for polygon center and other expressions.

@!x

normalizes vector x.

@=x

returns length of vector x. Shoter notation of general norm: {@=x}={nrm2x}.

Set Operators

x&y

returns elements that are in both x and y.

x|y

concatenates arrays x and y. Produces the same result as {x y}.

[deprecated] This operator is an unnecessary waste of notation. It should have had the interleaving effect, now represented by Y.

x\y

returns elements of x that are not present in y.

x|&y

is the xor operation on arrays. Returns elements, present in only one of the arrays.

xYy

interleaves the arrays x and y.

~x

reverses order of array x.

Sx

sorts array in ascending order.

#x

returns number of elements in array.

#_xy

counts occurences of elements of x in y. This is selective variant of # operator.

Example: #_{0 1 4}{1 2 3 4 4 1}={0 2 2}

#__xy

distributes elements of y into a histogram where elements of x divide the real numbers into bins. The size of the output is one element more than the size of x. The first bin extends from negative infinity to the first element of x and the last extends to the positive infinity. x is expected to be in ascending order.

?x

returns indices of nonzero elements of x. Only integer zero counts as zero.

This operator is intended for use with index operator (_), to select elements that satisfy some logical test. For example, x_?{x<1000} returns only elements, smaller than 1000.

To skip an entire array if it doesn't satisfy a condition, use ? operator in combination with +. For example, x+?{#x==3} prints x only if its length equals 3. This functionality relies on the fact that tensor summation with empty array returns empty array.

?_x y

returns the indices of elements of x in the array y. If the element is found more than once, only the first index is returned. If the element is not present in y, a value -1 is returned.

S_x

returns the indices that would sort the array x. It's always true that Sx=x_S_x.

x=y

returns 1 if arrays are equal, 0 otherwise.

Element Selection Operators

x<<y

for positive values of y, returns first y values of x (as unix utility head). For negative values, it returns everything except first y values. If y is an array, it concatenates all results. y should be array of integers. Useful for array cycling: {1 2 3 4}<<{-2 2}={3 4 1 2}.

x>>y

same as above, except it works from the back of the array.

x_y

returns elements of x at indices y. It interpolates for noninteger indices and wraps around for indices out of range.

U P N O E I D X

conditional selectors. Return elements that satisfy a certain condition.

min max

return the smallest and the largest component of the array respectively.

Zx

`zilch` returns an empty array. This operator is useful for suppressing output from functions with side-effects, such as the @ operator.

Constants

pi

returns 3.14159265358979323846264

deg

returns the value of angular degree in radians, 0.017453292519943295769

emc

returns Euler-Mascheroni constant, 0.57721566490153286

pm mp

plus/minus and minus/plus constants. They output arrays {1,-1} and {-1,1} respectively. They can be used to compute results of multivalued formulas simultaneously, for example quadratic equation.

Memory Operators

Named variables can be used instead of integer enumeration with the use of backticks.

@xy

puts array y into memory slots, enumerated by elements of x. x should be integers. Floating point numbers are cast to integers and warning is issued.

$x

concatenates arrays found at memory slots, enumerated by x. For negative values, it returns array from history instead of memory, $-1 being most recent entry. x should be integers.

@`<name>`y

puts array y into the memory slot, represented by the given <name>.

$`<name>`

retrieves the variable, named by the given <name>.

ised manages memory as hashed map, so a memory position can be every positive integer. Saving array to slot $100 doesn't allocate any more memory than saving to slot $1. Results are added to history for input lines from files (--f option) or interactive mode, unless the line terminates with a semicolon. Negative slots are reserved for internal use by the named variable system and are not accessible by direct dereference. Instead, history is accessed by the negative arguments of the $ operator.

Comparison and Equality operators

For boolean analysis of resulting arrays, use multiplication for and operator and summation for or operator. Incorporating additional operators for this functionality would be redundant, as the result is equivalent. But beware, multiplication and summation have higher precedence than comparison operators, so use grouping operator {} to achieve desirable effect.

x:<y x:>y x:<=y x:>=y x:==y x:<>y

Comparison and equality, evaluated component-wise. Result is an array with size of the shorter of the input arrays.

x<y x>y x<=y x>=y x==y x<>y

Same as above, but evaluated on every possible pair of values. Size of the output array is product of input sizes (see Tensor operators for details and example).

Function definitions

The functions may include memory manipulation, which makes them as versatile as functions in any programming language. They can be designed as procedures ignoring input and output and operate on memory, plain-old-functions that take an argument and return a result, or any combination of both.

{:expression:}

Function declaration. The expression is parsed, stored into the function memory and its unique id is returned. The id is guarranteed to be nonzero. The returned id may be stored in memory and used later. Within the function, operator x is used to refer to the function's argument. The function is not evaluated at this point.

f::x

Function evaluation. f is an array of function ids, which are applied sequentially to the array x, left-to-right. It should be understood as composition of function; the result from the previous function is passed to the next as its argument.

f:::x

Function iteration. Array of function ids f is evaluated repeatedly on the argument x. The iteration stops when the argument no longer changes or maximum number of iterations is reached. The maximum number of iterations is 65536 by default, but can be queried and changed using system call Q{105 ...} (see the section on system calls). This operator can be emulated by the ordinary function evaluation and system call for setting the instruction pointer, Q{103 ...}, but the implementation is quite complex. As functional iteration until convergence is common in math, this operator is a valuable shortcut.

f@::x

Function map. Array of function ids f is evaluated on each element of the array x. This is meant to allow creation of user functions that don't have to handle the array nature of the argument themselves.

x

This operator evaluates to the argument supplied to the function. In case of nested functions, it refers to the innermost function's argument. Outside a function, it has the value of the current line (when used with --l or --x), or invalid otherwise.

The function evaluation operator (::) is enough to implement all basic control structures. ised is therefore a Turing complete language.

function call:

{fun}::{arg}

conditional execution (if-statement):

{{false-fun true-fun}_{condition}}::{arg}

switch statement:

{{fun1 fun2 fun3 fun4 ...}_switch}::{arg}

static repetition (for-statement):

(fun n)::{arg}

recursion:

{@mem {:do-something-with $mem::x :}}::{arg} The implementation of the function must be carefully devised, otherwise the execution might get stuck in an infinite recursion.

general loop (while-statement):

{ body-fun jump-test }::{arg}

Such simple implementation has the loop contents in body-fun and implements jump-fun such that its argument unchanged, but sets the program counter to zero if a condition is met. The program counter is set via system call operator Q{103 n} where n is simply which function in left-hand side of the operator :: is evaluated next. For example, { {:x+1:} {:x Q{103 -{x>10}}:} }::{arg} increments the argument by one until it becomes greater than 10. In that case, the system call sets the program counter to -1, which is out of range and the evaluation stops.

More complex flow control is possible, as the operator Q{103 n} can be used exactly like a goto statement. Q{102} can be used to find the current program counter and calculate relative jumps.

System calls

Example: use ised --l load_file '$1 Q{$1>3}' to output the specified file, but terminate as soon as it encounters a number greater than 3.

The system call ids are available as named variables, specified between the backticks as `<name>`. For instance, a call Q{`EXIT` 42} terminates the program with a return value of 42.

The list of system call numbers and names:

0 [NOP]: no-op

1 [EXIT]: exit

Exits with return value 0 or the value specified as an optional argument.

100 [BREAK]: break

Interrupts the loading of files by commands --f, --l, --a or --x and aborts evaluation of the current line.

101 [CONT]: continue

Aborts evaluation of the current line and proceeds to the next line in the file.

102 [PC]: get program counter

Returns the index of currently evaluated function in innermost evaluation operator ::.

103 [PCSET]: set program counter

Sets the index of next evaluated function in innermost operator ::. If argument is out of bounds, it terminates the evaluation. If without arguments, it does nothing.

104 [STACKDEPTH]: get stack depth

Return the number of nested functions around the call. If not in a function, it returns 0.

105 [MAXITER]: get/set iteration limit

Without argument, the iteration limit for operator ::: is returned. With argument, it is changed to the given (nonnegative) value.

1000 [HISTORY_COUNT]: get history count

Returns the number of history entries, or -1 if history is disabled.

1001 [HISTORY_ENABLE]: disable history

Disables remembering previous results or enables it, if called with a nonzero argument.

1002 [HISTORY_CLEAR]: clear history

Clears the history.

2000 [MEM_INDEX]: get/set indexing memory slot

Without arguments, it sets the memory slot where current line number is stored (default is 0). With argument, it sets it.

2001 [MEM_INPUT]: get/set input memory slot

Same as 2000, but for the memory slot where the current input line is stored (default 1).

2002 [MEM_OFFSET]: get/set file loading offset

Same as 2000, but for the memory slot where --a continues loading lines to. At startup, this is 0 so the first memory slot filled is $1 and is advanced with each loaded line.

2003 [MEM_CLEAR]: delete from memory

Clear entire contents of memory if called without arguments. The optional argument is a list of memory slots to delete.

2004 [MEM_LIST]: get memory list

Lists the occupied memory slots.

2050 [FUN_CLEAR]: delete function

Clears all the functions if called without arguments. The optional argument is a list of function ids to delete.

2051 [FUN_LIST]: get function list

Lists the occupied function ids.

3000 [VERSION]: ised version

Returns the array, containing the version number {major,minor,revision}.

3001 [SIZEOF_INT]: int size

Returns the size of integer type in bytes.

3002 [SIZEOF_FLOAT]: float size

Returns the size of float type in bytes.

3003 [DEBUG]: debug level

Returns the debugging level, set at compile-time.

3004 [READLINE_STATUS]: readline status

Returns the array indicating if various libreadline functionalities are enabled (use --v for details).

3005 [OVERFLOW_STATUS]: overflow enabled

Returns 1 if overflow handling was enabled at compile-time and 0 otherwise.

5000 [TIME]: system time

Returns unix time in seconds if called without arguments. The arguments can be list of values, which specify the time fields to output:

For instance, a call Q{`TIME` `TIME.YEAR` `TIME.MONTH` `TIME.DAY`} may return the array {2013 10 31}.

5001 [PROCESS_TIME]: process time

Returns array containing real time, user time and system time in seconds.

5002 [SLEEP]: sleep

Sleep for the amount of seconds specified in the argument.

5050 [PID]: pid

Return the PID of this process.