jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
knowledge/technology/applications/cli/numbat.md

1096 lines
80 KiB
Markdown
Raw Normal View History

add numbat
2024-04-10 06:39:35 +00:00
---
obj: application
repo: https://github.com/sharkdp/numbat
website: https://numbat.dev
---
# numbat
Numbat is a statically typed programming language for scientific computations
with first class support for physical dimensions and units.
## Number Notation
Numbers in Numbat can be written in the following forms:
- Integer notation
- `12345`
- `12_345` — with decimal separators
- Floating point notation
- `0.234`
- `.234` — without the leading zero
- Scientific notation
- `1.234e15`
- `1.234e+15`
- `1e-9`
- `1.0e-9`
- Non-decimal bases notation
- `0x2A` — Hexadecimal
- `0o52` — Octal
- `0b101010` — Binary
- Non-finite numbers
- `NaN` — Not a number
- `inf` — Infinity
You can use the `bin`, `oct`, `dec` and `hex` functions to convert numbers to binary, octal, decimal and hexadecimal bases, respectively. You can call those using `hex(2^16 - 1)`, or `2^16 - 1 // hex`, but they are also available as targets of the conversion operator `->/to`, so you can write expressions like:
Examples:
```
0xffee to bin
42 ot oct
2^16 - 1 to hex
```
You can also use `base(b)` to convert a number to base b:
```
0xffee to base(2)
```
## Unit Notation
Most units can be entered in the same way that they would appear in textbook calculations. They usually have a long form (meter, degrees, byte, …), a plural form (meters, degrees, bytes), and a short alias (m, °, B).
All SI-accepted units support metric prefixes (mm, cm, km, … or millimeter, centimeter, kilometer, …) and — where sensible — units allow for binary prefixes (MiB, GiB, … or mebibyte, gibibyte, …). Note that the short-form prefixes can only be used with the short version of the unit, and vice versa (that is: kmeter and kilom are not allowed, only km and kilometer).
Units can be combined using mathematical operations such as multiplication, division and exponentiation: $kg * m/s^2$, $km/h$, $m^2$, meter per second.
The following snippet shows various styles of entering units:
```
2 min + 1 s
150 cm
sin(30°)
50 mph
6 MiB
2 minutes + 1 second
150 centimeters
sin(30 degrees)
50 miles per hour
6 mebibyte
```
> Note that Numbat also allows you to define new units.
## Operations and precedence
Numbat operators and other language constructs, ordered by precedence form _high_ to _low_:
| Operation / operator | Syntax |
| ------------------------- | ------------------------------------------------ |
| square, cube, … | `x²`, `x³`, `x⁻¹`, … |
| factorial | `x!` |
| exponentiation | `x^y`, `x**y` |
| multiplication (implicit) | `x y` (_whitespace_) |
| unary negation | `-x` |
| division | `x per y` |
| division | `x / y`, `x ÷ y` |
| multiplication (explicit) | `x * y`, `x · y`, `x × y` |
| subtraction | `x - y` |
| addition | `x + y` |
| comparisons | `x < y`, `x <= y`, `x ≤ y`, … `x == y`, `x != y` |
| logical negation | `!x` |
| logical ‘and’ | `x && y` |
| logical ‘or’ | `x \| y` |
| unit conversion | `x -> y`, `x → y`, `x ➞ y`, `x to y` |
| conditionals | `if x then y else z` |
| reverse function call | `x // f` |
Note that _implicit_ multiplication has a higher precedence than division, i.e. `50 cm / 2 m` will be parsed as `50 cm / (2 m)`.
Also, note that `per`-division has a higher precedence than `/`-division. This means `1 / meter per second` will be parsed as `1 / (meter per second)`.
If in doubt, you can always look at the pretty-printing output (second line in the snippet below) to make sure that your input was parsed correctly:
```numbat
>>> 1 / meter per second
1 / (meter / second)
= 1 s/m
```
## Constants
New constants can be introduced with the `let` keyword:
```
let pipe_radius = 1 cm
let pipe_length = 10 m
let Δp = 0.1 bar
```
Definitions may contain a type annotation after the identifier (`let Δp: Pressure = 0.1 bar`). This annotation will be verified by the type checker. For more complex definitions it can be desirable to add type annotations, as it often improves readability and allows you to catch potential errors early:
```
let μ_water: DynamicViscosity = 1 mPa·s
let Q: FlowRate = π × pipe_radius^4 × Δp / (8 μ_water × pipe_length)
```
## Unit Conversion
The conversion operator `->` attempts to convert the physical quantity on its left hand side to the unit of the expression on its right hand side. This means that you can write an arbitrary expression on the right hand side — but only the unit part will be extracted. For example:
Simple unit conversion:
```
> 120 km/h -> mph
= 74.5645 mi/h
```
Expression on the right hand side:
```
> 120 m^3 -> km * m^2
= 0.12 m²·km
```
Convert x1 to the same unit as x2:
```
> let x1 = 50 km / h
> let x2 = 3 m/s -> x1
x2 = 10.8 km/h
```
## Conversion functions
The conversion operator `->` (or `to`) can not just be used for unit conversions, but also for other types of conversions. The way this is set up in Numbat is that you can call `x -> f` for any function `f` that takes a single argument of the same type as `x`.
The following functions are available for this purpose:
```
# Convert a date and time to a Unix timestamp
now() -> unixtime
# Convert a date and time to a different timezone
now() -> tz("Asia/Kathmandu")
# Convert a duration to days, hours, minutes, seconds
10 million seconds -> human
# Convert a number to its binary representation
42 -> bin
# Convert a number to its octal representation
42 -> oct
# Convert a number to its hexadecimal representation
2^31-1 -> hex
# Convert a number to a custom base
42 -> base(16)
# Convert an ASCII code point number to a character
78 -> chr
# Convert a string to upper/lower case
"numbat is awesome" -> uppercase
"vier bis elf weiße Querbänder" -> lowercase
```
Note that the `tz(…)` and `base(…)` calls above return _functions_, i.e. the right hand side of the conversion operator is still a function.
## Function definitions
Numbat comes with a large number of [predefined functions](https://numbat.dev/doc/list-functions.html), but it is also possible to add new functions. A function definition is introduced with the `fn` keyword:
```nbt
fn max_distance(v: Velocity, θ: Angle) -> Length = v² · sin(2 θ) / g0
```
This exemplary function computes the maximum distance of a projectile under the influence of Earths gravity. It takes two parameters (The initial velocity `v` and the launch angle `θ`), which are both annotated with their corresponding physical dimension (their type). The function returns a distance, and so the return type is specified as `Length`.
### Type inference
The return type annotation may be omitted, but it is often desirable to add it for better readability of the code and in order to catch potential errors.
The parameter types can also (sometimes) be omitted, in which case Numbat tries to infer their type. However, this often leads to overly generic function signatures. For example, consider the following function to compute the kinetic energy of a massive object in motion:
```nbt
fn kinetic_energy(mass, speed) = 1/2 * mass * speed^2
```
Without any type annotations, this function has an overly generic type where `mass` and `speed` can have arbitrary dimensions (and the return type is `type(mass) * type(speed)^2`). So for this case, it is probably better to add parameter and return types.
### Generic functions
Sometimes however, it _is_ useful to write generic functions. For example, consider `max(a, b)` — a function that returns the larger of the two arguments. We might want to use that function with _dimensionful_ arguments such as `max(1 m, 1 yd)`. To define such a generic function, you can introduce _type parameters_ in angle brackets:
```nbt
fn max<T>(a: T, b: T) -> T = if a > b then a else b
```
This function signature tells us that `max` takes two arguments of _arbitrary_ type `T` (but they need to match!), and returns a quantity of the same type `T`.
Note that you can perform the usual operations with type parameters, such as multiplying/dividing them with other types, or raising to rational powers. For example, consider this cube-root function
```nbt
fn cube_root<T>(x: T^3) -> T = x^(1/3)
```
that can be called with a scalar (`cube_root(8) == 2`) or a dimensionful argument (`cube_root(1 liter) == 10 cm`).
Note: `cube_root` can also be defined as `fn cube_root<T>(x: T) -> T^(1/3)`, which is equivalent to the definition above.
### Recursive functions
It is also possible to define recursive functions. In order to do so, you currently need to specify the return type — as the type signature can not (yet) be inferred otherwise.
For example, a naive recursive implementation to compute Fibonacci numbers in Numbat looks like this:
```nbt
fn fib(n: Scalar) -> Scalar =
if n ≤ 2
then 1
else fib(n - 2) + fib(n - 1)
```
## Conditionals
Numbat has `if-then-else` conditional expressions with the following syntax
```nbt
if <cond> then <expr1> else <expr2>
```
where `<cond>` is a condition that evaluates to a Boolean value, like `3 ft < 3 m`. The types of `<expr1>` and `<expr2>` need to match.
For example, you can defined a simple step function using
```nbt
fn step(x: Scalar) -> Scalar = if x < 0 then 0 else 1
```
## Date and time
Numbat supports date and time handling based on the [proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), which is the (usual) Gregorian calendar extended to dates before its introduction in 1582. Julian calendar dates are currently not supported.
A few examples of useful operations that can be performed on dates and times:
```nbt
# Which date is 40 days from now?
now() + 40 days
# Which date was 1 million seconds ago?
now() - 1 million seconds
# How many days are left until September 1st?
date("2024-11-01") - today() -> days
# What time is it in Nepal right now?
now() -> tz("Asia/Kathmandu") # use tab completion to find time zone names
# What is the local time when it is 2024-11-01 12:30:00 in Australia?
datetime("2024-11-01 12:30:00 Australia/Sydney") -> local
# What is the current UNIX timestamp?
now() -> unixtime
# What is the date corresponding to the UNIX timestamp 1707568901?
from_unixtime(1707568901)
# How long are one million seconds in days, hours, minutes, seconds
1 million seconds -> human
```
### Date and time arithmetic
The following operations are supported for `DateTime` objects:
| Left | Operator | Right | Result |
| ---------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `DateTime` | `-` | `DateTime` | Duration between the two dates as a `Time`. In `seconds`, by default. Use normal conversion for other time units. |
| `DateTime` | `+` | `Time` | New `DateTime` by adding the duration to the date |
| `DateTime` | `-` | `Time` | New `DateTime` by subtracting the duration from the date |
| `DateTime` | `->` | `tz("…")` | Converts the datetime to the specified time zone. Note that you can use tab-completion for time zone names. |
> **Warning**: You can add `years` or `months` to a given date (`now() + 3 months`), but note that the result might not be what you expect. The unit `year` is defined as the _average_ length of a year (a [tropical year](https://en.wikipedia.org/wiki/Tropical_year), to be precise), and `month` is defined as the _average_ length of a month (1/12 of a `year`). So this does not take into account the actual length of the months or the leap years. However, note that adding or subtracting “one year” or “one month” is not a well-defined operation anyway. For example, what should “one month after March 31st” be? April 30th or May 1st? If your answer is April 30th, then what is “one month after March 30th”? If your answer is May 1st, then what is “one month after April 1st”?
### Date, time, and duration functions
The following functions are available for date and time handling:
- `now() -> DateTime`: Returns the current date and time.
- `today() -> DateTime`: Returns the current date at midnight (in the local time).
- `datetime(input: String) -> DateTime`: Parses a string (date and time) into a `DateTime` object.
- `date(input: String) -> DateTime`: Parses a string (only date) into a `DateTime` object.
- `time(input: String) -> DateTime`: Parses a string (only time) into a `DateTime` object.
- `format_datetime(format: String, dt: DateTime) -> String`: Formats a `DateTime` object as a string. See [this page](https://docs.rs/chrono/latest/chrono/format/strftime/index.html#specifiers) for possible format specifiers.
- `tz(tz: String) -> Fn[(DateTime) -> DateTime]`: Returns a timezone conversion function, typically used with the conversion operator (`datetime -> tz("Europe/Berlin")`)
- `local(dt: DateTime) -> DateTime`: Timezone conversion function targeting the users local timezone (`datetime -> local`)
- `get_local_timezone() -> String`: Returns the users local timezone
- `unixtime(dt: DateTime) -> Scalar`: Converts a `DateTime` to a [UNIX timestamp](../../linux/UNIX%20Timestamp.md).
- `from_unixtime(ut: Scalar) -> DateTime`: Converts a [UNIX timestamp](../../linux/UNIX%20Timestamp.md) to a `DateTime` object.
- `human(duration: Time) -> String`: Converts a `Time` to a human-readable string in days, hours, minutes and seconds
### Date time formats
The following formats are supported by `datetime`. UTC offsets are mandatory for the RFC 3339 and RFC 2822 formats. The other formats can optionally include a time zone name or UTC offset. If no time zone is specified, the local time zone is used.
| Format | Examples |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [RFC 3339](https://tools.ietf.org/html/rfc3339) | `2024-02-10T12:30:00Z` <br>`2024-02-10T06:30:00-06:00` |
| [RFC 2822](https://tools.ietf.org/html/rfc2822) | `Sat, 10 Feb 2024 12:30:00 Z` <br>`Sat, 10 Feb 2024 06:30:00 -0600` |
| `%Y-%m-%d %H:%M:%S%.f` | `2024-02-10 12:30:00` <br>`2024-02-10 06:30:00 -0600` <br>`2024-02-10 07:30:00 US/Eastern` <br>`2024-02-10 12:30:00.123456` |
| `%Y/%m/%d %H:%M:%S%.f` | same, but with `/` separator |
| `%Y-%m-%d %H:%M` | `2024-02-10 12:30` <br>`2024-02-10 06:30 -0600` <br>`2024-02-10 07:30 US/Eastern` |
| `%Y/%m/%d %H:%M` | same, but with `/` separator |
| `%Y-%m-%d %I:%M:%S%.f %p` | `2024-02-10 12:30:00 PM` <br>`2024-02-10 06:30:00 AM -0600` <br>`2024-02-10 07:30:00 AM US/Eastern` <br>`2024-02-10 12:30:00.123456 PM` |
| `%Y/%m/%d %I:%M:%S%.f %p` | same, but with `/` separator |
| `%Y-%m-%d %I:%M %p` | `2024-02-10 12:30 PM` <br>`2024-02-10 06:30 AM -0600` <br>`2024-02-10 07:30 AM US/Eastern` |
| `%Y/%m/%d %I:%M %p` | same, but with `/` separator |
The `date` function supports the following formats. It returns a `DateTime` object with the time set to midnight in the specified timezone (or the local timezone if no timezone is specified).
| Format | Examples |
| ---------- | -------------------------------------------------------------------- |
| `%Y-%m-%d` | `2024-02-10` <br>`2024-02-10 +0100` <br>`2024-02-10 Europe/Berlin` |
| `%Y/%m/%d` | `2024/02/10` <br>`2024/02/10 +0100` <br>`2024/02/10 Europe/Berlin` |
The `time` function supports the following formats. It returns a `DateTime` object with the date set to the current date. If no timezone is specified, the local timezone is used.
| Format | Examples |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `%H:%M:%S%.f` | `12:30:00` <br>`06:30:00 -0600` <br>`07:30:00 US/Eastern` <br>`12:30:00.123456` |
| `%H:%M` | `12:30` <br>`06:30 -0600` <br>`07:30 US/Eastern` |
| `%I:%M:%S%.f %p` | `12:30:00 PM` <br>`06:30:00 AM -0600` <br>`07:30:00 AM US/Eastern` <br>`12:30:00.123456 PM` |
| `%I:%M %p` | `12:30 PM` <br>`06:30 AM -0600` <br>`07:30 AM US/Eastern` |
## Printing, testing, debugging
### Printing
Numbat has a builtin `print` procedure that can be used to print the value of an expression:
```nbt
print(2 km/h)
print(3 ft < 1 m)
```
You can also print out simple messages as strings. This is particularly useful when combined with string interpolation to print results of a computation:
```nbt
let radius: Length = sqrt(footballfield / 4 pi) -> meter
print("A football field would fit on a sphere of radius {radius}")
```
You can use almost every expression inside a string interpolation field. For example:
```nbt
print("3² + 4² = {hypot2(3, 4)}²")
let speed = 25 km/h
print("Speed of the bicycle: {speed} ({speed -> mph})")
```
Format specifiers are also supported in interpolations. For instance:
```nbt
print("{pi:0.2f}") // Prints "3.14"
```
For more information on supported format specifiers, please see [this page](https://doc.rust-lang.org/std/fmt/#formatting-parameters).
### Testing
The `assert_eq` procedure can be used to test for (approximate) equality of two quantities. This is often useful to make sure that (intermediate) results in longer calculations have a certain value, e.g. when restructuring the code. The general syntax is
```nbt
assert_eq(q1, q2)
assert_eq(q1, q2, ε)
```
where the first version tests for exact equality while the second version tests for approximate equality $|{q1}−{q2}|<ϵ$
with a specified accuracy of ϵ
. For example:
```nbt
assert_eq(2 + 3, 5)
assert_eq(1 ft × 77 in², 4 gal)
assert_eq(alpha, 1 / 137, 1e-4)
assert_eq(3.3 ft, 1 m, 1 cm)
```
There is also a plain `assert` procedure that can test any boolean condition. For example:
```nbt
assert(1 yard < 1 meter)
assert(π != 3)
```
A runtime error is thrown if an assertion fails. Otherwise, nothing happens.
### Debugging
You can use the builtin `type` procedure to see the type (or physical dimension) of a quantity:
```nbt
>>> type(g0)
Length / Time²
>>> type(2 < 3)
Bool
```
## Dimension definitions
New (physical) dimensions can be introduced with the `dimension` keyword. Similar like for units, there are base dimensions (like _length_, _time_ and _mass_) and dimensions that are derived from those base dimensions (like _momentum_, which is _mass_ · _length_ / _time_). Base dimensions are simply introduced by declaring their name:
```numbat
dimension Length
dimension Time
dimension Mass
```
Derived dimensions need to specify their relation to base dimensions (or other derived dimensions). For example:
```numbat
dimension Velocity = Length / Time
dimension Momentum = Mass * Velocity
dimension Force = Mass * Acceleration = Momentum / Time
dimension Energy = Momentum^2 / Mass = Mass * Velocity^2 = Force * Length
```
In the definition of `Force` and `Energy`, we can see that multiple _alternative definitions_ can be specified. This is entirely optional. When given, the compiler will make sure that all definitions are equivalent.
## Unit definitions
New units of measurement can be introduced with the `unit` keyword. There are two types of units: base units and derived units.
A new **base unit** can be defined by specifying the _physical dimension_ it represents. For example, in the International System of Units (SI), the _second_ is the base unit for measuring times:
```numbat
unit second: Time
```
Here, `Time` denotes the physical dimension.
**Derived units** are also introduced with the `unit` keyword. But unlike base units, they are defined through their relation to other units. For example, a _minute_ can be defined as
```numbat
unit minute: Time = 60 second
```
Here, the `: Time` annotation is optional. If a dimension is specified, it will be used to verify that the right hand side expression (`60 second`) is indeed of physical dimension `Time`. This is apparent in this simple example, but can be useful for more complicated unit definitions like
```numbat
unit farad: Capacitance = ampere^2 second^4 / (kilogram meter^2)
```
### Prefixes
If a unit may be used with metric prefixes such as `milli`/`m`, `kilo`/`k` or `mega`/`M`, we can prepend the unit definition with the `@metric_prefixes` decorator:
```numbat
@metric_prefixes
unit second: Time
```
This allows identifiers such as `millisecond` to be used in calculations. See the section below how prefixes interact with aliases.
Similarly, if a unit should be prependable with _binary_ (IEC) prefixes such as `kibi`/`Ki`, `mebi`/`Mi` or `gibi`/`Gi`, you can add the `@binary_prefixes` decorator. A unit might also allow for both metric and binary prefixes, for example:
```numbat
@binary_prefixes
@metric_prefixes
unit byte = 8 bit
```
This allows the usage of both `mebibyte` (1024² byte) as well as `megabyte` (1000² byte).
### Aliases
It is often useful to define alternative names for a unit. For example, we might want to use the plural form `seconds` or the commonly used short version `s`. We can use the `@aliases` decorator to specify them:
```numbat
@metric_prefixes
@aliases(meters, metre, metres, m: short)
unit meter: Length
```
In addition to the name, we can also specify how aliases interact with prefixes using `: long` (the default), `: short`, `: both` or `: none`. The actual unit name (`meter`) and all `long` aliases will accept the long version of prefixes (…, `milli`, `kilo`, `mega`, `giga`, …). All `short` aliases (`m` in the example above) will only accept the respective short versions of the prefixes (…, `m`, `k`, `M`, `G`, …). Aliases annotated with `: both` or `: none` accept either both long _and_ short prefixes, or none of them. The unit definition above allows all of following expressions:
```numbat
millimeter
kilometer
millimeters
kilometers
millimetre
kilometre
millimetres
kilometres
mm
km
...
```
### Ad-hoc units
It is often useful to introduce ‘fictional’ physical units (and dimensions). This comes up frequently when you want to count things. For example:
```numbat
unit book
@aliases(pages)
unit page
@aliases(words)
unit word
let words_per_book = 500 words/page × 300 pages/book
```
Note that those base unit definitions will implicitly create new dimensions which are capitalized versions of the unit names (`Book`, `Page`, `Word`). A definition like `unit book` is a shorthand for `dimension Book; unit book: Book`. Those units now allow us to count books, pages and words independently without any risk of mixing them. The `words_per_book` constant in this examples has a type of `Word / Book`.
Another example shows how we introduce a `dot` unit to do calculations with screen resolutions:
```numbat
@aliases(dots)
unit dot
unit dpi = dots / inch
# Note: a `Dot` dimension was implicitly created for us
fn inter_dot_spacing(resolution: Dot / Length) -> Length = 1 dot / resolution
inter_dot_spacing(72 dpi) -> µm # 353 µm
```
## Syntax overview
```numbat
# This is a line comment. It can span over
# multiple lines
# 1. Imports
use prelude # This is not necessary. The 'prelude'
# module will always be loaded upon startup
use units::stoney # Load a specific module
# 2. Numbers
12345 # integer notation
12_345 # optional decimal separators
0.234 # floating point notation
.234 # without the leading zero
1.234e15 # scientific notation
1.234e+15
1e-9
1.0e-9
0x2A # hexadecimal
0o52 # octal
0b101010 # binary
NaN # Not a number
inf # Infinity
# 3. Simple expressions
3 + (4 - 3) # Addition and subtraction
1920 / 16 * 9 # Multiplication, division
1920 ÷ 16 × 9 # Unicode-style, '·' is also multiplication
2 pi # Whitespace is implicit multiplication
meter per second # 'per' keyword can be used for division
2^3 # Exponentiation
2**3 # Python-style
2³ # Unicode exponents
2^-3 # Negative exponents
mod(17, 4) # Modulo
3 in -> cm # Unit conversion, can also be → or ➞
3 in to cm # Unit conversion with the 'to' keyword
cos(pi/3 + pi) # Call mathematical functions
pi/3 + pi // cos # Same, 'arg // f' is equivalent to 'f(arg)'
# The '//' operator has the lowest precedence
# which makes it very useful for interactive
# terminals (press up-arrow, and add '// f')
# 4. Constants
let n = 4 # Simple numerical constant
let q1 = 2 m/s # Right hand side can be any expression
let q2: Velocity = 2 m/s # With optional type annotation
let q3: Length / Time = 2 m/s # more complex type annotation
# 5. Function definitions
fn foo(z: Scalar) -> Scalar = 2 * z + 3 # A simple function
fn speed(len: Length, dur: Time) -> Velocity = len / dur # Two parameters
fn my_sqrt<T>(q: T^2) -> T = q^(1/2) # A generic function
fn is_non_negative(x: Scalar) -> Bool = x ≥ 0 # Returns a bool
# 6. Dimension definitions
dimension Fame # A new base dimension
dimension Deceleration = Length / Time^2 # A new derived dimension
# 7. Unit definitions
@aliases(quorks) # Optional aliases-decorator
unit quork = 0.35 meter # A new derived unit
@metric_prefixes # Optional decorator to allow 'milliclonk', etc.
@aliases(ck: short) # short aliases can be used with short prefixes (mck)
unit clonk: Time = 0.2 seconds # Optional type annotation
@metric_prefixes
@aliases(wh: short)
unit warhol: Fame # New base unit for the "Fame" dimension
unit thing # New base unit with automatically generated
# base dimension "Thing"
# 8. Conditionals
fn bump(x: Scalar) -> Scalar = # The construct 'if <cond> then <expr> else <expr>'
if x >= 0 && x <= 1 # is an expression, not a statement. It can span
then 1 # multiple lines.
else 0
# 9. Procedures
print(2 kilowarhol) # Print the value of an expression
print("hello world") # Print a message
print("value of pi = {pi}") # String interpolation
print("sqrt(10) = {sqrt(10)}") # Expressions in string interpolation
print("value of π ≈ {π:.3}") # Format specifiers
assert(1 yard < 1 meter) # Assertion
assert_eq(1 ft, 12 in) # Assert that two quantities are equal
assert_eq(1 yd, 1 m, 10 cm) # Assert that two quantities are equal, up to
# the given precision
type(2 m/s) # Print the type of an expression
```
## Predefined functions
### Utility
```nbt
fn unit_of<T>(x: T) -> T
fn value_of<T>(x: T) -> Scalar
fn is_nan<T>(x: T) -> Bool
fn is_infinite<T>(x: T) -> Bool
```
### Math
#### Basics
```nbt
fn abs<T>(x: T) -> T
fn round<T>(x: T) -> T
fn floor<T>(x: T) -> T
fn ceil<T>(x: T) -> T
fn mod<T>(a: T, b: T) -> T
fn sqrt<D>(x: D^2) -> D
fn sqr<D>(x: D) -> D^2
```
#### Exponential and logarithm
```nbt
fn exp(x: Scalar) -> Scalar
fn ln(x: Scalar) -> Scalar
fn log(x: Scalar) -> Scalar
fn log10(x: Scalar) -> Scalar
fn log2(x: Scalar) -> Scalar
```
#### Trigonometry
**Basic**:
```nbt
fn cos(x: Scalar) -> Scalar
fn sin(x: Scalar) -> Scalar
fn tan(x: Scalar) -> Scalar
fn asin(x: Scalar) -> Scalar
fn acos(x: Scalar) -> Scalar
fn atan(x: Scalar) -> Scalar
fn atan2<T>(y: T, x: T) -> Scalar
```
**Hyperbolic**:
```nbt
fn sinh(x: Scalar) -> Scalar
fn cosh(x: Scalar) -> Scalar
fn tanh(x: Scalar) -> Scalar
fn asinh(x: Scalar) -> Scalar
fn acosh(x: Scalar) -> Scalar
fn atanh(x: Scalar) -> Scalar
```
**Extra**:
```nbt
fn cot(x: Scalar) -> Scalar
fn acot(x: Scalar) -> Scalar
fn coth(x: Scalar) -> Scalar
fn acoth(x: Scalar) -> Scalar
fn secant(x: Scalar) -> Scalar
fn arcsecant(x: Scalar) -> Scalar
fn cosecant(x: Scalar) -> Scalar
fn csc(x: Scalar) -> Scalar
fn acsc(x: Scalar) -> Scalar
fn sech(x: Scalar) -> Scalar
fn asech(x: Scalar) -> Scalar
fn csch(x: Scalar) -> Scalar
fn acsch(x: Scalar) -> Scalar
```
#### Others
```nbt
fn gamma(x: Scalar) -> Scalar
```
#### Statistics
```nbt
fn mean<D>(xs: D…) -> D
fn maximum<D>(xs: D…) -> D
fn minimum<D>(xs: D…) -> D
```
#### Geometry
```nbt
fn hypot2<T>(x: T, y: T) -> T
fn hypot3<T>(x: T, y: T, z: T) -> T
fn circle_area<L>(radius: L) -> L^2
fn circle_circumference<L>(radius: L) -> L
fn sphere_area<L>(radius: L) -> L^2
fn sphere_volume<L>(radius: L) -> L^3
```
#### Algebra
```nbt
fn quadratic_equation<A2, B2>(a: A2, b: B2, c: B2²/A2) -> String
```
### Date and time
See [this page](https://numbat.dev/doc/date-and-time.html) for details.
### Physics
#### Temperature conversion
```nbt
fn from_celsius(t_celsius: Scalar) -> Temperature
fn celsius(t_kelvin: Temperature) -> Scalar
fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature
fn fahrenheit(t_kelvin: Temperature) -> Scalar
```
### Strings
```nbt
fn str_length(s: String) -> Scalar
fn str_slice(s: String, start: Scalar, end: Scalar) -> String
fn str_append(a: String, b: String) -> String
fn str_contains(haystack: String, needle: String) -> Bool
fn str_replace(s: String, pattern: String, replacement: String) -> String
fn str_repeat(a: String, n: Scalar) -> String
fn chr(n: Scalar) -> String
fn hex(n: Scalar) -> String
```
## Constants
### Mathematical
- `pi`, `π`
- `τ`
- `e`
- `golden_ratio`, `φ`
### Named numbers
**Large numbers**:
- `hundred`
- `thousand`
- `million`
- `billion`
- `trillion`
- `quadrillion`
- `quintillion`
- `googol`
**Unicode fractions**:
- `½`, `⅓`, `⅔`, `¼`, `¾`, …
**Colloquial**:
- `quarter`
- `half`
- `semi`
- `double`
- `triple`
- `dozen`
### Physics
| Description | Identifier | Dimension |
| ------------------------------------------------ | --------------------------------------- | -------------------------------------------- |
| The speed of light in vacuum | `speed_of_light`, `c` | `Velocity` |
| The Newtonian constant of gravitation | `gravitational_constant`, `G` | `Force × Length^2 / Mass^2` |
| Standard acceleration of gravity on earth | `gravity`, `g0` | `Acceleration` |
| The Planck constant | `planck_constant`, `ℎ` | `Mass × Length^2 / Time` |
| The reduced Planck constant | `h_bar`, `ℏ` | `Mass × Length^2 / Time` |
| Mass of the electron | `electron_mass` | `Mass` |
| Elementary charge (charge of the electron) | `elementary_charge`, `electron_charge` | `ElectricCharge` |
| Magnetic constant (vacuum magnetic permeability) | `magnetic_constant`, `µ0`, `mu0` | `Force / Current^2` |
| Electric constant (vacuum electric permittivity) | `electric_constant`, `ε0`, `eps0` | `Capacitance / Length` |
| Bohr magneton | `bohr_magneton`, `µ_B` | `Energy / MagneticFluxDensity` |
| Fine structure constant | `fine_structure_constant`, `alpha`, `α` | `Scalar` |
| Proton mass | `proton_mass` | `Mass` |
| Neutron mass | `neutron_mass` | `Mass` |
| Avogadro constant | `avogadro_constant`, `N_A` | `1 / AmountOfSubstance` |
| Boltzmann constant | `boltzmann_constant`, `k_B` | `Energy / Temperature` |
| Stefan-Boltzmann constant | `stefan_boltzmann_constant` | `Power / (Area × Temperature^4)` |
| Ideal gas constant | `gas_constant`, `R` | `Energy / (AmountOfSubstance × Temperature)` |
| Planck length | `planck_length` | `Length` |
| Planck mass | `planck_mass` | `Mass` |
| Planck time | `planck_time` | `Time` |
| Planck temperature | `planck_temperature` | `Temperature` |
| Planck energy | `planck_energy` | `Energy` |
| Bohr radius | `bohr_radius`, `a0` | `Length` |
| Rydberg constant | `rydberg_constant` | `Wavenumber` |
## List of supported units
All SI-accepted units support [metric prefixes](https://en.wikipedia.org/wiki/Metric_prefix) (`mm`, `cm`, `km`, … or `millimeter`, `centimeter`, `kilometer`, …) and — where sensible — units allow for [binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) (`MiB`, `GiB`, … or `mebibyte`, `gibibyte`, …).
| Dimension | Unit name | Identifier(s) |
| --------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `AbsorbedDose` | [Gray](https://en.wikipedia.org/wiki/Gray_(unit)) | `gray`, `grays`, `Gy` |
| `Activity` | [Becquerel](https://en.wikipedia.org/wiki/Becquerel) | `becquerel`, `becquerels`, `Bq` |
| `AmountOfSubstance` | [Mole](../../../science/physics/units/Mole.md) | `mol`, `mole`, `moles` |
| `Angle` | [Minute of arc](https://en.wikipedia.org/wiki/Minute_and_second_of_arc) | `arcmin`, `arcminute`, `arcminutes` |
| `Angle` | [Second of arc](https://en.wikipedia.org/wiki/Minute_and_second_of_arc) | `arcsec`, `arcsecond`, `arcseconds` |
| `Angle` | [Degree](https://en.wikipedia.org/wiki/Degree_(angle)) | `deg`, `degree`, `degrees`, `°` |
| `Angle` | [Gradian](https://en.wikipedia.org/wiki/Gradian) | `gon`, `gons`, `grad`, `grade`, `grades`, `gradian`, `gradians`, `grads` |
| `Angle` | [Radian](https://en.wikipedia.org/wiki/Radian) | `rad`, `radian`, `radians` |
| `Angle` | [Revolution](https://en.wikipedia.org/wiki/Revolution_(unit)) | `rev`, `revolution`, `revolutions` |
| `Angle` | [Turn](https://en.wikipedia.org/wiki/Turn_(geometry)) | `turn`, `turns` |
| `Area` | [Acre](https://en.wikipedia.org/wiki/Acre) | `acre`, `acres` |
| `Area` | [Are](https://en.wikipedia.org/wiki/Are_(unit)) | `are` |
| `Area` | [Barn](https://en.wikipedia.org/wiki/Barn_(unit)) | `barn`, `barns` |
| `Area` | [Football field](https://en.wikipedia.org/wiki/Football_pitch) | `footballfield` |
| `Area` | [Hectare](https://en.wikipedia.org/wiki/Hectare) | `ha`, `hectare`, `hectares` |
| `Beat` | [Beat](https://en.wikipedia.org/wiki/Beat_(music)) | `beat`, `beats` |
| `Beat / Time` | [Beats per minute](https://en.wikipedia.org/wiki/Tempo) | `bpm`, `BPM` |
| `Capacitance` | [Farad](https://en.wikipedia.org/wiki/Farad) | `F`, `farad`, `farads` |
| `CatalyticActivity` | [Katal](https://en.wikipedia.org/wiki/Katal) | `kat`, `katal`, `katals` |
| `Current` | [Ampere](https://en.wikipedia.org/wiki/Ampere) | `A`, `ampere`, `amperes` |
| `DigitalInformation` | [Bit](https://en.wikipedia.org/wiki/Bit) | `bit`, `bits` |
| `DigitalInformation` | [Byte](https://en.wikipedia.org/wiki/Byte) | `B`, `byte`, `Byte`, `bytes`, `Bytes`, `octet`, `Octet`, `octets`, `Octets` |
| `DigitalInformation / Time` | [Bits per second](https://en.wikipedia.org/wiki/Bit_per_second) | `bps` |
| `Dot` | [Dot](https://en.wikipedia.org/wiki/Dots_per_inch) | `dot`, `dots` |
| `Dot / Length` | [Dots per inch](https://en.wikipedia.org/wiki/Dots_per_inch) | `dpi` |
| `DynamicViscosity` | [Poise](https://en.wikipedia.org/wiki/Poise_(unit)) | `poise` |
| `ElectricCharge` | [Ampere-hour](https://en.wikipedia.org/wiki/Ampere_hour) | `Ah`, `amperehour` |
| `ElectricCharge` | [Coulomb](https://en.wikipedia.org/wiki/Coulomb) | `C`, `coulomb`, `coulombs` |
| `ElectricConductance` | [Siemens](https://en.wikipedia.org/wiki/Siemens_(unit)) | `S`, `siemens` |
| `ElectricResistance` | [Ohm](https://en.wikipedia.org/wiki/Ohm) | `ohm`, `ohms`, `Ω`, `Ω` |
| `Energy` | [British thermal unit](https://en.wikipedia.org/wiki/British_thermal_unit) | `BTU`, `Btu` |
| `Energy` | [Calorie](https://en.wikipedia.org/wiki/Calorie) | `cal`, `calorie`, `calories` |
| `Energy` | [Electron volt](https://en.wikipedia.org/wiki/Electronvolt) | `electronvolt`, `electronvolts`, `eV` |
| `Energy` | [Erg](https://en.wikipedia.org/wiki/Erg) | `erg`, `ergs` |
| `Energy` | [Hartree](https://en.wikipedia.org/wiki/Hartree) | `hartree`, `hartrees` |
| `Energy` | [Joule](https://en.wikipedia.org/wiki/Joule) | `J`, `joule`, `joules` |
| `Energy` | [Planck energy](https://en.wikipedia.org/wiki/Planck_energy) | `planck_energy` |
| `Energy` | [Rydberg unit of energy](https://en.wikipedia.org/wiki/Rydberg_constant) | `Ry` |
| `Energy` | [Watt-hour](https://en.wikipedia.org/wiki/Watt_hour) | `watthour`, `Wh` |
| `EquivalentDose` | [Sievert](https://en.wikipedia.org/wiki/Sievert) | `sievert`, `sieverts`, `Sv` |
| `Force` | [Dyne](https://en.wikipedia.org/wiki/Dyne) | `dyn`, `dyne` |
| `Force` | [Kilogram-force](https://en.wikipedia.org/wiki/Kilogram-force) | `kgf`, `kilogram_force` |
| `Force` | [Newton](https://en.wikipedia.org/wiki/Newton_(unit)) | `N`, `newton`, `newtons` |
| `Force` | [Ounce-force](https://en.wikipedia.org/wiki/Ounce-force) | `ounce_force`, `ozf` |
| `Force` | [Pound-force](https://en.wikipedia.org/wiki/Pound_(force)) | `lbf`, `pound_force` |
| `Force / Volume` | [Mercury](https://en.wikipedia.org/wiki/Mercury_(element)) | `Hg` |
| `Frame` | [Frame](https://en.wikipedia.org/wiki/Frame_rate) | `frame`, `frames` |
| `Frame / Time` | [Frames per second](https://en.wikipedia.org/wiki/Frame_rate) | `fps` |
| `Frequency` | [Hertz](https://en.wikipedia.org/wiki/Hertz) | `hertz`, `Hz` |
| `Frequency` | [Revolutions per minute](https://en.wikipedia.org/wiki/Revolutions_per_minute) | `rpm`, `RPM` |
| `Illuminance` | [Foot-candle](https://en.wikipedia.org/wiki/Foot-candle) | `fc`, `footcandle`, `footcandles` |
| `Illuminance` | [Lux](https://en.wikipedia.org/wiki/Lux) | `lux`, `lx` |
| `Inductance` | [Henry](https://en.wikipedia.org/wiki/Henry_(unit)) | `H`, `henries`, `henry`, `henrys` |
| `KinematicViscosity` | [Stokes](https://en.wikipedia.org/wiki/Stokes_(unit)) | `St`, `stokes` |
| `Length` | [Ångström](https://en.wikipedia.org/wiki/Angstrom) | `angstrom`, `angstroms`, `Å`, `Å` |
| `Length` | [Astronomical unit](https://en.wikipedia.org/wiki/Astronomical_unit) | `astronomicalunit`, `astronomicalunits`, `au`, `AU` |
| `Length` | [Bohr](https://en.wikipedia.org/wiki/Hartree_atomic_units) | `bohr` |
| `Length` | [Fathom](https://en.wikipedia.org/wiki/Fathom) | `fathom`, `fathoms` |
| `Length` | [Fermi](https://en.wikipedia.org/wiki/Femtometre) | `fermi` |
| `Length` | [Foot](https://en.wikipedia.org/wiki/Foot_(unit)) | `feet`, `foot`, `ft` |
| `Length` | [Furlong](https://en.wikipedia.org/wiki/Furlong) | `furlong`, `furlongs` |
| `Length` | [Inch](https://en.wikipedia.org/wiki/Inch) | `in`, `inch`, `inches` |
| `Length` | [League](https://en.wikipedia.org/wiki/League_(unit)) | `league`, `leagues` |
| `Length` | [Light-year](https://en.wikipedia.org/wiki/Light-year) | `lightyear`, `lightyears`, `ly` |
| `Length` | [Metre](../../../science/physics/units/Meter.md) | `m`, `meter`, `meters`, `metre`, `metres` |
| `Length` | [Micron](https://en.wikipedia.org/wiki/Micrometre) | `micron` |
| `Length` | [Mile](https://en.wikipedia.org/wiki/Mile) | `mi`, `mile`, `miles` |
| `Length` | [Nautical Mile](https://en.wikipedia.org/wiki/Nautical_mile) | `nautical_mile`, `nautical_miles`, `NM`, `nmi` |
| `Length` | [Parsec](https://en.wikipedia.org/wiki/Parsec) | `parsec`, `parsecs`, `pc` |
| `Length` | [Planck length](https://en.wikipedia.org/wiki/Planck_length) | `planck_length` |
| `Length` | [Rack unit](https://en.wikipedia.org/wiki/Rack_unit) | `rackunit`, `rackunits`, `RU`, `U` |
| `Length` | [US rod](https://en.wikipedia.org/wiki/Rod_(unit)) | `perch`, `rod`, `rods` |
| `Length` | [Smoot](https://en.wikipedia.org/wiki/Smoot) | `smoot` |
| `Length` | [Stoney length](https://en.wikipedia.org/wiki/Stoney_units) | `stoney_length` |
| `Length` | [Thousandth of an inch](https://en.wikipedia.org/wiki/Thousandth_of_an_inch) | `mil`, `mils`, `thou` |
| `Length` | [Yard](https://en.wikipedia.org/wiki/Yard) | `yard`, `yards`, `yd` |
| `Length / Volume` | [Miles per gallon](https://en.wikipedia.org/wiki/Fuel_economy_in_automobiles) | `mpg` |
| `Length^2` | [darcy](https://en.wikipedia.org/wiki/Darcy_(unit)) | `darcies`, `darcy`, `darcys` |
| `LuminousFlux` | [Lumen](https://en.wikipedia.org/wiki/Lumen_(unit)) | `lm`, `lumen`, `lumens` |
| `LuminousIntensity` | [Candela](../../../science/physics/units/Candela.md) | `candela`, `candelas`, `cd` |
| `MagneticFieldStrength` | [Oersted](https://en.wikipedia.org/wiki/Oersted) | `Oe`, `oersted` |
| `MagneticFlux` | [Maxwell](https://en.wikipedia.org/wiki/Maxwell_(unit)) | `maxwell`, `Mx` |
| `MagneticFlux` | [Weber](https://en.wikipedia.org/wiki/Weber_(unit)) | `Wb`, `weber`, `webers` |
| `MagneticFluxDensity` | [Gauss](https://en.wikipedia.org/wiki/Gauss_(unit)) | `gauss` |
| `MagneticFluxDensity` | [Tesla](https://en.wikipedia.org/wiki/Tesla_(unit)) | `T`, `tesla`, `teslas` |
| `Mass` | [Dalton](https://en.wikipedia.org/wiki/Dalton) | `Da`, `dalton`, `daltons` |
| `Mass` | [Firkin](https://en.wikipedia.org/wiki/Firkin_(unit)) | `firkin`, `firkins` |
| `Mass` | [Grain](https://en.wikipedia.org/wiki/Grain_(unit)) | `grain`, `grains` |
| `Mass` | [Gram](https://en.wikipedia.org/wiki/Gram) | `g`, `gram`, `gramme`, `grammes`, `grams` |
| `Mass` | [Hundredweight](https://en.wikipedia.org/wiki/Hundredweight) | `cwt`, `long_hundredweight` |
| `Mass` | [Long ton](https://en.wikipedia.org/wiki/Long_ton) | `long_ton`, `long_tons` |
| `Mass` | [Ounce](https://en.wikipedia.org/wiki/Ounce) | `ounce`, `ounces`, `oz` |
| `Mass` | [Planck mass](https://en.wikipedia.org/wiki/Planck_mass) | `planck_mass` |
| `Mass` | [Pound](https://en.wikipedia.org/wiki/Pound_(mass)) | `lb`, `lbs`, `pound`, `pounds` |
| `Mass` | [Stone](https://en.wikipedia.org/wiki/Stone_(unit)) | `stone` |
| `Mass` | [Stoney mass](https://en.wikipedia.org/wiki/Stoney_units) | `stoney_mass` |
| `Mass` | [Tonne](https://en.wikipedia.org/wiki/Tonne) | `metricton`, `ton`, `tonne`, `tonnes`, `tons` |
| `Molality` | [Molal](https://en.wikipedia.org/wiki/Molality) | `molal` |
| `Molarity` | [Molar](https://en.wikipedia.org/wiki/Molar_concentration) | `molar` |
| `Money` | [Australian dollar](https://en.wikipedia.org/wiki/Australian_dollar) | `A$`, `AUD`, `australian_dollar`, `australian_dollars` |
| `Money` | [Brazilian real](https://en.wikipedia.org/wiki/Brazilian_real) | `brazilian_real`, `brazilian_reals`, `BRL`, `R$` |
| `Money` | [Pound sterling](https://en.wikipedia.org/wiki/Pound_sterling) | `british_pound`, `GBP`, `pound_sterling`, `£` |
| `Money` | [Bulgarian lev](https://en.wikipedia.org/wiki/Bulgarian_lev) | `BGN`, `bulgarian_lev`, `bulgarian_leva` |
| `Money` | [Canadian dollar](https://en.wikipedia.org/wiki/Canadian_dollar) | `C$`, `CAD`, `canadian_dollar`, `canadian_dollars` |
| `Money` | [Czech koruna](https://en.wikipedia.org/wiki/Czech_koruna) | `czech_koruna`, `czech_korunas`, `CZK`, `Kč` |
| `Money` | [Danish krone](https://en.wikipedia.org/wiki/Danish_krone) | `danish_krone`, `danish_kroner`, `DKK` |
| `Money` | [US dollar](https://en.wikipedia.org/wiki/United_States_dollar) | `$`, `dollar`, `dollars`, `USD` |
| `Money` | [Euro](https://en.wikipedia.org/wiki/Euro) | `EUR`, `euro`, `euros`, `€` |
| `Money` | [Hong Kong dollar](https://en.wikipedia.org/wiki/Hong_Kong_dollar) | `HK$`, `HKD`, `hong_kong_dollar`, `hong_kong_dollars` |
| `Money` | [Hungarian forint](https://en.wikipedia.org/wiki/Hungarian_forint) | `Ft`, `HUF`, `hungarian_forint`, `hungarian_forints` |
| `Money` | [Icelandic króna](https://en.wikipedia.org/wiki/Icelandic_kr%C3%B3na) | `icelandic_krona`, `icelandic_kronur`, `icelandic_króna`, `icelandic_krónur`, `ISK` |
| `Money` | [Indian rupee](https://en.wikipedia.org/wiki/Indian_rupee) | `indian_rupee`, `indian_rupees`, `INR`, `₹` |
| `Money` | [Indonesian rupiah](https://en.wikipedia.org/wiki/Indonesian_rupiah) | `IDR`, `indonesian_rupiah`, `indonesian_rupiahs`, `Rp` |
| `Money` | [Israeli new shekel](https://en.wikipedia.org/wiki/Israeli_new_shekel) | `ILS`, `israeli_new_shekel`, `israeli_new_shekels`, `NIS`, `₪` |
| `Money` | [Malaysian ringgit](https://en.wikipedia.org/wiki/Malaysian_ringgit) | `malaysian_ringgit`, `malaysian_ringgits`, `MYR`, `RM` |
| `Money` | [New Zealand dollar](https://en.wikipedia.org/wiki/New_Zealand_dollar) | `new_zealand_dollar`, `new_zealand_dollars`, `NZ$`, `NZD` |
| `Money` | [Norwegian krone](https://en.wikipedia.org/wiki/Norwegian_krone) | `NOK`, `norwegian_krone`, `norwegian_kroner` |
| `Money` | [Philippine peso](https://en.wikipedia.org/wiki/Philippine_peso) | `philippine_peso`, `philippine_pesos`, `PHP`, `₱` |
| `Money` | [Polish złoty](https://en.wikipedia.org/wiki/Polish_z%C5%82oty) | `PLN`, `polish_zloty`, `polish_zlotys`, `zł` |
| `Money` | [Chinese yuan](https://en.wikipedia.org/wiki/Renminbi) | `CNY`, `renminbi`, `yuan`, `元` |
| `Money` | [Romanian leu](https://en.wikipedia.org/wiki/Romanian_leu) | `lei`, `romanian_leu`, `romanian_leus`, `RON` |
| `Money` | [Singapore dollar](https://en.wikipedia.org/wiki/Singapore_dollar) | `S$`, `SGD`, `singapore_dollar`, `singapore_dollars` |
| `Money` | [South African rand](https://en.wikipedia.org/wiki/South_African_rand) | `south_african_rand`, `ZAR` |
| `Money` | [South Korean won](https://en.wikipedia.org/wiki/South_Korean_won) | `KRW`, `south_korean_won`, `south_korean_wons`, `₩` |
| `Money` | [Swedish krona](https://en.wikipedia.org/wiki/Swedish_krona) | `SEK`, `swedish_krona`, `swedish_kronor` |
| `Money` | [Swiss franc](https://en.wikipedia.org/wiki/Swiss_franc) | `CHF`, `swiss_franc`, `swiss_francs` |
| `Money` | [Thai baht](https://en.wikipedia.org/wiki/Thai_baht) | `thai_baht`, `thai_bahts`, `THB`, `฿` |
| `Money` | [Turkish lira](https://en.wikipedia.org/wiki/Turkish_lira) | `TRY`, `turkish_lira`, `turkish_liras`, `₺` |
| `Money` | [Japanese yen](https://en.wikipedia.org/wiki/Japanese_yen) | `JPY`, `yen`, `¥`, `円` |
| `Person` | Person | `capita`, `people`, `person`, `persons` |
| `Piece` | Piece | `piece`, `pieces` |
| `Pixel` | [Pixel](https://en.wikipedia.org/wiki/Pixel) | `pixel`, `pixels`, `px` |
| `Pixel / Length` | [Pixels per inch](https://en.wikipedia.org/wiki/Pixels_per_inch) | `ppi` |
| `Power` | [Metric horsepower](https://en.wikipedia.org/wiki/Horsepower) | `horsepower`, `hp` |
| `Power` | [Watt](https://en.wikipedia.org/wiki/Watt) | `W`, `watt`, `watts` |
| `Pressure` | [Standard atmosphere](https://en.wikipedia.org/wiki/Standard_atmosphere_(unit)) | `atm`, `atmosphere`, `atmospheres` |
| `Pressure` | [Bar](https://en.wikipedia.org/wiki/Bar_(unit)) | `bar`, `bars` |
| `Pressure` | [Inch of mercury](https://en.wikipedia.org/wiki/Inch_of_mercury) | `inHg` |
| `Pressure` | [Kilopound-force per square inch](https://en.wikipedia.org/wiki/Ksi_(unit)) | `ksi`, `KSI` |
| `Pressure` | [Millimeter of mercury](https://en.wikipedia.org/wiki/Millimeter_of_mercury) | `mmHg` |
| `Pressure` | [Megapound-force per square inch](https://en.wikipedia.org/wiki/Ksi_(unit)) | `mpsi`, `MPSI` |
| `Pressure` | [Pascal](https://en.wikipedia.org/wiki/Pascal_(unit)) | `Pa`, `pascal`, `pascals` |
| `Pressure` | [Pound-force per square inch](https://en.wikipedia.org/wiki/Pounds_per_square_inch) | `psi`, `PSI` |
| `Pressure` | [Torr](https://en.wikipedia.org/wiki/Torr) | `torr` |
| `Scalar` | [Billion](https://en.wikipedia.org/wiki/Billion) | `billion` |
| `Scalar` | [Dozen](https://en.wikipedia.org/wiki/Dozen) | `dozen` |
| `Scalar` | [Hundred](https://en.wikipedia.org/wiki/100_(number)) | `hundred` |
| `Scalar` | [Million](https://en.wikipedia.org/wiki/Million) | `million` |
| `Scalar` | [Parts per billion](https://en.wikipedia.org/wiki/Parts-per_notation) | `partsperbillion`, `ppb` |
| `Scalar` | [Parts per million](https://en.wikipedia.org/wiki/Parts-per_notation) | `partspermillion`, `ppm` |
| `Scalar` | [Parts per quadrillion](https://en.wikipedia.org/wiki/Parts-per_notation) | `partsperquadrillion`, `ppq` |
| `Scalar` | [Parts per trillion](https://en.wikipedia.org/wiki/Parts-per_notation) | `partspertrillion`, `ppt` |
| `Scalar` | [Percent](https://en.wikipedia.org/wiki/Percentage) | `%`, `pct`, `percent` |
| `Scalar` | [Quadrillion](https://en.wikipedia.org/wiki/Quadrillion) | `quadrillion` |
| `Scalar` | [Quintillion](https://en.wikipedia.org/wiki/Quintillion) | `quintillion` |
| `Scalar` | [Thousand](https://en.wikipedia.org/wiki/1000_(number)) | `thousand` |
| `Scalar` | [Trillion](https://en.wikipedia.org/wiki/Trillion) | `trillion` |
| `SolidAngle` | [Steradian](https://en.wikipedia.org/wiki/Steradian) | `sr`, `steradian`, `steradians` |
| `Temperature` | [Kelvin](https://en.wikipedia.org/wiki/Kelvin) | `K`, `kelvin`, `kelvins` |
| `Temperature` | [Planck temperature](https://en.wikipedia.org/wiki/Planck_temperature) | `planck_temperature` |
| `Time` | [Century](https://en.wikipedia.org/wiki/Century) | `centuries`, `century` |
| `Time` | [Day](https://en.wikipedia.org/wiki/Day) | `d`, `day`, `days` |
| `Time` | [Decade](https://en.wikipedia.org/wiki/Decade) | `decade`, `decades` |
| `Time` | [Fortnight](https://en.wikipedia.org/wiki/Fortnight) | `fortnight`, `fortnights` |
| `Time` | [Gregorian year](https://en.wikipedia.org/wiki/Gregorian_year) | `gregorian_year`, `gregorian_years` |
| `Time` | [Hour](https://en.wikipedia.org/wiki/Hour) | `h`, `hour`, `hours`, `hr` |
| `Time` | [Julian year](https://en.wikipedia.org/wiki/Julian_year_(astronomy)) | `julian_year`, `julian_years` |
| `Time` | [Millennium](https://en.wikipedia.org/wiki/Millennium) | `millennia`, `millennium` |
| `Time` | [Minute](https://en.wikipedia.org/wiki/Minute) | `min`, `minute`, `minutes` |
| `Time` | [Month](https://en.wikipedia.org/wiki/Month) | `month`, `months` |
| `Time` | [Planck time](https://en.wikipedia.org/wiki/Planck_time) | `planck_time` |
| `Time` | [Second](https://en.wikipedia.org/wiki/Second) | `s`, `sec`, `second`, `seconds` |
| `Time` | [Sidereal day](https://en.wikipedia.org/wiki/Sidereal_time#Sidereal_day) | `sidereal_day`, `sidereal_days` |
| `Time` | [Stoney time](https://en.wikipedia.org/wiki/Stoney_units) | `stoney_time` |
| `Time` | [Week](https://en.wikipedia.org/wiki/Week) | `week`, `weeks` |
| `Time` | [Tropical year](https://en.wikipedia.org/wiki/Tropical_year) | `tropical_year`, `tropical_years`, `year`, `years`, `yr` |
| `Velocity` | [Knot](https://en.wikipedia.org/wiki/Knot_(unit)) | `kn`, `knot`, `knots`, `kt` |
| `Velocity` | [Kilometres per hour](https://en.wikipedia.org/wiki/Kilometres_per_hour) | `kph` |
| `Velocity` | [Miles per hour](https://en.wikipedia.org/wiki/Miles_per_hour) | `mph` |
| `Voltage` | [Volt](../../../science/physics/units/Volt.md) | `V`, `volt`, `volts` |
| `Volume` | [Cubic centimetre](https://en.wikipedia.org/wiki/Cubic_centimetre) | `cc`, `ccm` |
| `Volume` | [US cup](https://en.wikipedia.org/wiki/Cup_(unit)) | `cup`, `cups` |
| `Volume` | [US fluid ounce](https://en.wikipedia.org/wiki/Fluid_ounce) | `floz`, `fluidounce`, `fluidounces` |
| `Volume` | [US liquid gallon](https://en.wikipedia.org/wiki/Gallon) | `gal`, `gallon`, `gallons` |
| `Volume` | [US hogshead](https://en.wikipedia.org/wiki/Hogshead) | `hogshead`, `hogsheads` |
| `Volume` | [Imperial Bushel](https://en.wikipedia.org/wiki/Bushel#Imperial_bushel) | `imperial_bushel`, `imperial_bushels`, `UK_bu` |
| `Volume` | [Imperial Fluid Drachm](https://en.wikipedia.org/wiki/Fluid_drachm#Imperial_fluid_drachm) | `imperial_fluid_drachm`, `imperial_fluid_drachms`, `UK_fldr` |
| `Volume` | [Imperial Fluid Ounce](https://en.wikipedia.org/wiki/Fluid_ounce) | `imperial_fluidounce`, `imperial_fluidounces`, `UK_floz` |
| `Volume` | [Imperial Gallon](https://en.wikipedia.org/wiki/Gallon#Imperial_gallon) | `imperial_gallon`, `imperial_gallons`, `UK_gal` |
| `Volume` | [Imperial Gill](https://en.wikipedia.org/wiki/Gill_(unit)) | `imperial_gill`, `imperial_gills`, `UK_gi` |
| `Volume` | [Imperial Pint](https://en.wikipedia.org/wiki/Pint#Imperial_pint) | `imperial_pint`, `imperial_pints`, `UK_pt` |
| `Volume` | [Imperial Quart](https://en.wikipedia.org/wiki/Quart#Imperial_quart) | `imperial_quart`, `imperial_quarts`, `UK_qt` |
| `Volume` | [Litre](https://en.wikipedia.org/wiki/Litre) | `l`, `L`, `liter`, `liters`, `litre`, `litres` |
| `Volume` | [US liquid pint](https://en.wikipedia.org/wiki/Pint) | `pint`, `pints` |
| `Volume` | [Swimming pool](https://en.wikipedia.org/wiki/Olympic-size_swimming_pool) | `swimmingpool` |
| `Volume` | [US tablespoon](https://en.wikipedia.org/wiki/Tablespoon) | `tablespoon`, `tablespoons`, `tbsp` |
| `Volume` | [US teaspoon](https://en.wikipedia.org/wiki/Teaspoon) | `teaspoon`, `teaspoons`, `tsp` |
## Usage
### Modes
You can run the Numbat command-line application in three different modes:
| Mode | Command to run |
| ----------------------------------- | ----------------------------- |
| Start an interactive session (REPL) | `numbat` |
| Run a Numbat program | `numbat script.nbt` |
| Evaluate a single expression | `numbat -e '30 km/h -> mi/h'` |
### Command-line options
Usage: `numbat [OPTIONS] [FILE]`
| Option | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `-e, --expression <CODE>` | Evaluate a single expression. Can be specified multiple times to evaluate several expressions in sequence |
| `-i, --inspect-interactively` | Enter interactive session after running a numbat script or expression |
| `--pretty-print <WHEN>` | Whether or not to pretty-print every input expression [possible values: `always`, `never`, `auto`] |
| `--intro-banner <MODE>` | What kind of intro banner to show (if any) [possible values: `long`, `short`, `off`] |
### Interactive sessions
Interactive sessions allow you to perform a sequence of calculations. You can use the special identifiers `ans` or `_` to refer to the result of the last calculation. For example:
```numbat
>>> 60 kW h / 150 kW
= 0.4 h
>>> ans -> minutes
= 24 min
```
#### Commands
There is a set of special commands that only work in interactive mode:
| Command | Action |
| ------------------- | --------------------------------------------------------------------- |
| `list`, `ls` | List all functions, dimensions, variables and units |
| `list <what>` | Where `<what>` can be `functions`, `dimensions`, `variables`, `units` |
| `info <identifier>` | Get more information about units and variables |
| `clear` | Clear screen |
| `help`, `?` | View short help text |
| `quit`, `exit` | Quit the session |
#### Key bindings
In interactive command-line mode, you can use the following key bindings. Most importantly, `Tab` for auto-completion, arrow keys and `Ctrl-R` for browsing the command history, and `Ctrl-D` for exiting the interactive session.
| Key sequence | Action |
| ------------------ | ---------------------------------------- |
| `Tab`, `Ctrl`-`I` | Auto-completion |
| `Ctrl`-`D` | Quit |
| `Ctrl`-`L` | Clear screen |
| `Up`, `Down` | Browse command history |
| `Ctrl`-`R` | Search command history |
| `Ctrl`-`C` | Clear the current line |
| `Alt`-`Enter` | Insert newline |
| `Home`, `Ctrl`-`A` | Move cursor to the beginning of the line |
| `End`, `Ctrl`-`E` | Move cursor to the end of the line |
| `Ctrl`-`W` | Delete word leading up to cursor |
Reference in a new issue Copy permalink