nushell/docs/commands/math.md
Shaurya Shubham ffe3e2c16b
Rename calc to math eval and allow it to optionally take an expression as an argument (#2195)
* Rename `calc` to `math eval` and allow it to optionally take the expression as an argument

* Moved calc tests to math eval
Also added 2 tests and changed 1 test

* Move calc docs to math eval
2020-07-18 16:11:19 +12:00

5.0 KiB

math

Mathematical functions that generally only operate on a list of numbers (integers, decimals, bytes) and tables. Currently the following functions are implemented:

  • math avg: Finds the average of a list of numbers or tables
  • math eval: Evaluates a list of math expressions into numbers
  • math min: Finds the minimum within a list of numbers or tables
  • math max: Finds the maximum within a list of numbers or tables
  • math median: Finds the median of a list of numbers or tables
  • math sum: Finds the sum of a list of numbers or tables

However, the mathematical functions like min and max are more permissive and also work on Dates.

Examples

To get the average of the file sizes in a directory, simply pipe the size column from the ls command to the average command.

List of Numbers (Integers, Decimals, Bytes)

> ls
 #  │ name               │ type │ size     │ modified
────┼────────────────────┼──────┼──────────┼─────────────
  0 │ CODE_OF_CONDUCT.md │ File │   3.4 KB │ 4 days ago
  1 │ CONTRIBUTING.md    │ File │   1.3 KB │ 4 days ago
  2 │ Cargo.lock         │ File │ 106.3 KB │ 6 mins ago
  3 │ Cargo.toml         │ File │   4.6 KB │ 3 days ago
  4 │ LICENSE            │ File │   1.1 KB │ 4 days ago
  5 │ Makefile.toml      │ File │    449 B │ 4 days ago
  6 │ README.md          │ File │  16.0 KB │ 6 mins ago
  7 │ TODO.md            │ File │      0 B │ 6 mins ago
  8 │ assets             │ Dir  │    128 B │ 4 days ago
  9 │ build.rs           │ File │     78 B │ 4 days ago
 10 │ crates             │ Dir  │    672 B │ 3 days ago
 11 │ debian             │ Dir  │    352 B │ 4 days ago
 12 │ docker             │ Dir  │    288 B │ 4 days ago
 13 │ docs               │ Dir  │    160 B │ 4 days ago
 14 │ features.toml      │ File │    632 B │ 4 days ago
 15 │ images             │ Dir  │    160 B │ 4 days ago
 16 │ justfile           │ File │    234 B │ 3 days ago
 17 │ rustfmt.toml       │ File │     16 B │ 4 days ago
 18 │ src                │ Dir  │    128 B │ 4 days ago
 19 │ target             │ Dir  │    192 B │ 8 hours ago
 20 │ tests              │ Dir  │    192 B │ 4 days ago
> ls | get size | math avg
───┬────────
 # │
───┼────────
 0 │ 7.2 KB
───┴────────
> ls | get size | math min
───┬─────
 # │
───┼─────
 00 B
───┴─────
> ls | get size | math max
───┬──────────
 # │
───┼──────────
 0 │ 113.6 KB
───┴──────────
> ls | get size | math median
───┬───────
 # │
───┼───────
 0320 B
───┴───────
> ls | get size | math sum
───┬──────────
 # │
───┼──────────
 0 │ 143.6 KB
───┴──────────

Dates

> ls | get modified | math min
2020-06-09 17:25:51.798743222 UTC
> ls | get modified | math max
2020-06-14 05:49:59.637449186 UT

Operations on tables

>  pwd | split row / | size
───┬───────┬───────┬───────┬────────────
 # │ lines │ words │ chars │ max length
───┼───────┼───────┼───────┼────────────
 00155
 1011111
 2011111
 30144
 4021212
 50177
───┴───────┴───────┴───────┴────────────
> pwd | split row / | size | math max
────────────┬────
 lines      │ 0
 words      │ 2
 chars      │ 12
 max length │ 12
────────────┴────
> pwd | split row / | size | math avg
────────────┬────────
 lines      │ 0.0000
 words      │ 1.1666
 chars      │ 8.3333
 max length │ 8.3333
────────────┴────────

To get the sum of the characters that make up your present working directory.

> pwd | split row / | size | get chars | math sum
50

Errors

math functions are aggregation functions so empty lists are invalid

> echo [] | math avg
error: Error: Unexpected: Cannot perform aggregate math operation on empty data