Welcome to the fend Manual!

fend is an arbitrary-precision unit-aware calculator. If you haven’t already, head to https://printfn.github.io/fend to use the online version, or click here to learn how to install fend on your computer.

You can check your version of fend at any time by typing version. If you are using the command-line interface, you can also run fend --version.

Table of Contents

  1. Installation
    1. Windows
    2. macOS
    3. Arch Linux
    4. NixOS / Nix package manager
    5. Pre-built binaries
    6. Install via crates.io
  2. Numbers
  3. Arithmetic
  4. Units
    1. Temperature
  5. Dice
  6. Functions and constants
  7. Number formats
  8. Strings
  9. Debug Representation
  10. Configuration
  11. Scripting
  12. Changelog

Installation

You can use fend without installing by visiting https://printfn.github.io/fend.

If you want to install the fend command-line application, you have the following options:

Windows

On Windows, you can install fend with a standard Windows installer package, which you can download here.

Alternatively you can install fend via winget:

winget install fend

Or using Chocolatey:

choco install fend

macOS

fend is available on Homebrew:

brew install fend

Arch Linux

fend is available on the AUR:

yay -Syu aur/fend-bin

You can also build it from source with:

yay -Syu aur/fend

NixOS / Nix package manager

fend is available in nixpkgs:

nix-env -iA nixpkgs.fend

Or using nix-shell:

nix-shell -p fend

Pre-built binaries

You can download the latest stable binaries for Windows, macOS and Linux here.

Binaries are available for:

Install via crates.io

If you have an up-to-date installation of Rust, you can install fend like so:

rustup update
cargo install fend

If you already have an older version of fend installed, this will automatically update to the latest version.

Once you have installed fend, you can launch an interactive REPL by typing fend in your terminal:

$ fend
> 1 ft to cm
30.48 cm
>

Numbers

You can write numbers as integers or with a decimal point. Feel free to use , or _ as a digit separator:

> 1234
1234
> 2.54
2.54
> 1,000,000
1000000

To write numbers in binary, octal or hexadecimal, add a 0b, 0o or 0x prefix:

> 0x9 + 0x2
0xb
> 0b1000_0001
0b10000001

You can write in any other base (between 2 and 36 inclusive) by writing <base>#<number>. Here is an example of senary (base 6):

> 6#100 in decimal
36
> 36 to base 6
100

There is no difference between to, as or in to convert between bases, formats or units.

You can also use e to for exponential notation, like so:

> 1e10
10000000000
> 3e8
300000000
> 1.5e-6
0.0000015
> 1E3
1000

i can be used for complex numbers:

> i * i
-1
> (2 + 3i) * i
-3 + 2i

You can specify recurring digits by writing them in parentheses, like so:

> 0.(3)
approx. 0.3333333333
> 0.(3) to fraction
1/3
> 0.0(15)
approx. 0.0151515151
> 0.0(15) to fraction
1/66

Arithmetic

fend supports the standard operators +, -, *, /, ^ and !, with the usual order of operations:

> 1 + 3 * 4
13
> 3^2
9
> (1 + 3) * 7
28
> 2pi
approx. 6.2831853071
> 5!
120

You can use = to declare variables:

> a = 1
1
> a
1
> a + 8
9
> a = 4 kg; b = 2; a * b^2
16 kg

Bitwise operators are also supported. & is used for bitwise AND, | for bitwise OR, and xor for bitwise XOR, since ^ is already used for exponentiation. Left and right bitshifts can be done with << and >>.

The operator precedence for these is the same as in C, with bitshifts having the highest precedence, followed by &, then xor, and finally | which has the lowest precedence.

> 1 & 1
1
> 0xff & 0x100
0x0
> 0xff & 0xcb
0xcb
> 0b0011 | 0b0101
0b111
> 0b0011 xor 0b0101
0b110
> 1 << 2
4
> 7 >> 1
3

These are all the supported operators:

Operators Precedence Associativity
Literals, Identifiers, Parentheses highest N/A
of right
! left
^, ** right
*, /, per, function application (e.g. sin 2), mod left
mixed fractions (e.g. 1 2/3), implicit sums (e.g. 5 feet 10 inches) N/A
+, -, to, as, in left
<<, >> left
&, and left
xor left
|, or left
\ ., :, => left
= left
; lowest left

The most recent calculation result is stored in a special variable _ (or ans):

> 5 * 10
50
> _ + 5
55
> _ * 2
110
> ans * 2
220

Units

fend supports many units, such as kg, lb, N, lightyear, etc. You can interchangeably use to, as and in to convert between units.

> 5'10" to cm
177.8 cm
> 1 mile to km
1.609344 km
> 1 GiB to bytes
1073741824 bytes
> 1m to kg
Error: cannot convert from m to kg: units are incompatible

Temperature

Temperature units are handled differently to other units, because celsius (°C) and fahrenheit (°F) don’t start at zero. Namely, absolute zero (0 kelvin) corresponds to -273.15 °C or -459.67 °F. This means that conversions between °C, °F and kelvin (K) need to differentiate between converting absolute temperatures and differences of temperatures.

If you use the to keyword to convert a plain temperature explicitly, fend will perform an absolute conversion. Here are some examples:

> 0 °C to °F
32 °F
> 100 °C to °F
212 °F
> 0 kelvin to °F
-459.67 °F

If, on the other hand, you add or subtract values with different temperature scales, fend performs relative conversions, like so:

> 0 °C + 1 kelvin
1 °C
> 0 kelvin + 9°F
5 kelvin

Additionally, conversions between more complex units (such as joules per degree celsius, i.e. J / °C) will always be relative:

> 100 J/K to J/°C
100 J / °C
> 100 J/K to J/°F
approx. 55.5555555555 J / °F

Dice

fend has support for D&D-style dice syntax. For example, d6 refers to a standard 6-sided die.

> roll d6
4
> roll d20 # 20-sided die
17
> roll 2d6 # sum of two 6-sided dice
7
> 2d6 # view the probability distribution
  2:  2.78%  #####
  3:  5.56%  ##########
  4:  8.33%  ###############
  5: 11.11%  ####################
  6: 13.89%  #########################
  7: 16.67%  ##############################
  8: 13.89%  #########################
  9: 11.11%  ####################
 10:  8.33%  ###############
 11:  5.56%  ##########
 12:  2.78%  #####
> roll(d20 + d6 + 4) # arithmetic operations
14

Functions and constants

fend has a number of predefined functions:

Here are some examples of these functions:

> sin(1°)
approx. 0.0174524064
> asin 1
approx. 1.5707963267
> exp 2
approx. 7.3890560989
> abs (1 + i)
approx. 1.4142135619

Many constants are available, including:

You can define your own lambda functions using either \ ., : or =>:

> \x.x
\x.x
> (\x.x) 5
5
> (\x.2x) 5
10
> (x: x to lb to 2 dp) (60 kg)
132.27 lbs

The notation λx.x is also supported.

Even the Y Combinator can be defined as \f.(\x.f (x x)) \x.f(x x).

Number formats

fend supports a few different output formats. It tries to choose an appropriate format automatically based on the given number, but you can change it using the to operator. These are the currently supported formats:

Strings

fend supports string literals, which can be enclosed in either single or double quotes. Strings are always encoded in UTF-8. Either type supports all the same escape sequences, which are as follows:

\\    backslash (\)
\"    double quote (")
\'    single quote (')
\a    bell (0x07)
\b    backspace (0x08)
\e    escape (0x1b)
\f    form feed (0x0c)
\n    line feed (0x0a)
\r    carriage return (0x0d)
\t    (horizontal) tab (0x09)
\v    vertical tab (0x0b)
\x    ASCII escape sequence, e.g. \x7e for '~'
\u    Unicode escape sequence, e.g. \u{3c0} for 'π'
\^    ASCII control character escape sequence,
          e.g. \^H for backspace (0x08)
\z    This causes fend to ignore any following whitespace characters

Here are some examples of using strings:

> "This is pi: \u{3c0}"
This is pi: π
> 'pi = ' + (pi to string)
pi = approx. 3.1415926535
> 'A' to codepoint
0x41

Debug Representation

You can see the debug representation of a value in fend by writing @debug at the start of your calculation. For example, you can type:

> @debug 1+1
2 (unitless) (base 10, auto, simplifiable)

Configuration

The CLI version of fend supports a configuration file.

The location of this file differs based on your operating system:

You can always confirm the path that fend uses by typing help. You can also see the default configuration file that fend uses by running fend --default-config.

You can override the config path location using the environment variable FEND_CONFIG_DIR.

fend stores its history file in $HOME/.local/state/fend/history by default, although this can be overridden with the FEND_STATE_DIR environment variable.

Cache data is stored in $HOME/.cache/fend by default. This can be overridden with the FEND_CACHE_DIR environment variable.

These are the configuration options currently available, along with their default values:

# Choose whether or not colors should be enabled. Possible
# values are 'never', 'auto' (default) or 'always'
enable-colors = 'auto'

# Maximum number of calculations to store in fend's
# history file
max-history-size = 1000

# The characters that are shown as the prompt when
# using fend interactively
prompt = '> '

# Change 'C' and 'F' to refer to coulomb and farad
# instead of degrees celsius and degrees fahrenheit
coulomb-and-farad = false

# What to do if this configuration file contains unknown
# settings. These are the possible values:
#  * 'warn': print a warning on startup if there are any
#            unknown config settings (default)
#  * 'ignore': ignore any unknown configuration settings
unknown-settings = 'warn'

# This section controls the colors that are used by
# fend. Make sure the `enable-colors` setting is
# turned on for this to work.
#
# Color options:
#   foreground: the foreground color to use
#   bold:       whether or not to show text in bold font
#   underline:  whether or not to underline text
#
# Valid colors are:
#   * 'black', 'red', 'green', 'yellow', 'blue',
#       'magenta', 'cyan' or 'white'
#   * '256:n' (where `n` is a number between 0 and 255).
#
[colors]
number = {}
string = {}
identifier = { foreground = 'white' }
keyword = { foreground = 'blue', bold = true }
built-in-function = { foreground = 'blue', bold = true }
date = {}
other = {}

Scripting

You can use fend programmatically using pipes or command-line arguments:

$ echo "sin (pi/4)" | fend
approx. 0.7071067811
$ fend "sqrt 2"
approx. 1.4142135619

The return code is 0 on success, or 1 if an error occurs during evaluation.

You can also specify filenames directly on the command-line, like this:

$ cat calculation.txt
16^2
$ fend calculation.txt
256

By default, fend will automatically try to read in files, or fall back to evaluating expressions. This behavior can be overridden with these command-line options:

For example:

$ cat calculation.txt
16^2
$ fend calculation.txt
256
$ fend -f calculation.txt
256
$ fend -e calculation.txt
Error: unknown identifier 'calculation.txt'

Or:

$ fend 1+1
2
$ fend -f 1+1
Error: No such file or directory (os error 2)
$ fend -e 1+1
2

-f and -e can be specified multiple times, in which case fend will evaluate each specified expression one after the other. Any variables defined in earlier expressions can be used by later expressions:

$ fend -e "a = 5" -e "2a"
10

Changelog

v1.1.2 (2022-10-31)

v1.1.1 (2022-09-23)

v1.1.0 (2022-09-22)

v1.0.5 (2022-08-14)

v1.0.4 (2022-07-22)

v1.0.3 (2022-06-07)

v1.0.2 (2022-06-01)

v1.0.1 (2022-03-19)

v1.0.0 (2022-03-12)

v0.1.29 (2022-02-23)

v0.1.28 (2022-02-12)

v0.1.27 (2021-11-02)

v0.1.26 (2021-09-27)

v0.1.25 (2021-09-27)

v0.1.24 (2021-08-09)

v0.1.23 (2021-08-06)

v0.1.22 (2021-07-29)

v0.1.21 (2021-07-11)

v0.1.20 (2021-06-29)

v0.1.19 (2021-06-29)

v0.1.18 (2021-06-28)

v0.1.17 (2021-06-08)

v0.1.16 (2021-05-21)

v0.1.15 (2021-05-20)

v0.1.14 (2021-02-14)

v0.1.13 (2021-01-20)

v0.1.12 (2020-11-27)

This build was only released on NPM.

v0.1.11 (2020-11-27)

v0.1.10 (2020-11-23)

v0.1.9 (2020-11-06)

v0.1.8 (2020-11-06)

v0.1.7 (2020-10-14)

v0.1.6 (2020-10-05)

v0.1.5 (2020-09-29)

v0.1.4 (2020-09-15)

v0.1.3 (2020-09-05)

v0.1.2 (2020-09-02)

v0.1.1 (2020-09-01)

v0.1.0 (2020-08-31)

Initial release: