# Documentation

## Using Calculon

The user interface of Calculon is deliberately simplistic. The leftmost text field is where you type in the calculations and the rightmost field will show the result of the calculation. You can use the Return key to calculate, there is no need for the mouse. Pressing Escape will quit the program.

When typing in the expression, an information field will appear with suggestions of found functions, constants and variables with similar names. You can click on the suggestions to insert them. Upon entering a valid function or constant, the same info field will show the parameters and other information associated with the keyword.

In case there was a syntax error (e.g. a missing parenthesis) or a math error (e.g. dividing by zero), an error field similar to the information field will appear. The part of the expression that caused the error will be highlighted in red.

## Expressions

Calculon is an expression evaluator which compared to a standard calculator needs less planning of the order of operators and the expression can also be edited in case of a typo. The expression is evaluated in standard order of operations. The order can be forced by using parenthesis.

It may be useful to be parenthesis paranoid and use them more than needed. Since a single expression can contain more than basic arithmetics, the order of evaluation may not be clear or in some cases the order could be undefined.

Following are examples of valid Calculon expressions:

``````1 + 1
(8 * 6 + 5) ^ (3 * 3)
1 m * 1 m
sin 45 deg``````

### Operators

#### Arithmetic operators

Operator Description Example
Subtraction 1 – 1
* Multiplication 1 * 1
/ Division 1 / 1
% Modulo, the remainder of a / b 1 % 1
^ Power 2 ^ 2
nroot Gives the nth root of x 2 nroot 4

#### Comparison operators

Comparison operators result in either zero (false) or one (true) depending on the operator and the tested values. For example, (1 = 1) + 2 equals three since 1 equals 1 (which is true or one). Comparison operators can be useful if used with the ternary operator.

Operator Description Example
< Less than 1 < 2
> Greater than 1 > 2
= Equal 1 = 2
<= Less than or equal 1 <= 2
>= Greater than or equal 1 >= 2
##### Ternary operator

The ternary construct works as follows:

`expression ? if_true : if_false`

If expression is non-zero, if_true will be evaluated. If expression is zero, if_false will be evaulated. Consider the below example:

`((2 > 7) ? 10 : (30 + 1)) + 4`

In the above case, the result will be 35 because 2 > 7 is false (zero) in which case the else part of the if is selected. Take note of the extra parentheses around the comparison operator.

### Functions and constants

Calculon has built-in functions for trigonometric, logarithmic and other basic calculations. In addition, custom user defined functions can be added. Constants can be defined as functions that don’t take any arguments.

In addition there is a special function ans that always returns the result of the previous calculation. There is a catch, though. ans only returns the result without the unit.

## Units

Calculon accepts mixed units in an expression. That is, you can add inches to metres, minutes to nanoseconds and so forth. It is not possible to add square kilometers to seconds or do other cross quantity calculations (unless there is an existing conversion between the quantities).

Specifying a unit in an expression is intuitive:

``30 m + 0.7 km``

### Unit conversions

When displaying the result, the default action is to choose the unit that gives the shortest answer. That is, Calculon cycles through all units available for the quantity. For explicit conversion purposes, it is very useful to use in to force the result unit.

``````6 km in m
(6 km + 100 m) * 2 in m``````

### Quantity conversions

Calculon can automatically convert a result for an expression if there is a conversion defined. For example, it can be very userful to automatically convert to area when a length is multiplied with length. Similarly, it is very useful to be able to divide distance with time to get velocity (as it is with calculating average speed from distance traveled and the total time used).

## Configuration files

All configuration files for Calculon are XML files that can be edited. Only the base functions provided by the standard library are hardcoded in Calculon, that is they are not defined in the configuration files (and redefinition will result in an error). All the rest including constants, units and conversions are fully customizable.