mirror of
https://github.com/nushell/nushell.git
synced 2025-04-09 21:28:55 +02:00
Math Documentation (#1982)
* Adding math docs * Add some comments to calculate * Remove redudant message Message already shows up in subcommands list * Added not working example Accidentantly * Remove table
This commit is contained in:
Arash Outadi
GitHub
parent
d7b1480ad0
commit
bd7ac0d48e
@ -16,11 +16,7 @@ impl WholeStreamCommand for Command {
|
|||||||
}
|
}
|
||||||
|
|
||||||
fn usage(&self) -> &str {
|
fn usage(&self) -> &str {
|
||||||
r#"Use mathematical functions (average, min, max) to aggregate list of numbers or tables
|
"Use mathematical functions as aggregate functions on a list of numbers or tables"
|
||||||
math average
|
|
||||||
math min
|
|
||||||
math max
|
|
||||||
"#
|
|
||||||
}
|
}
|
||||||
|
|
||||||
async fn run(
|
async fn run(
|
||||||
@ -97,6 +93,17 @@ mod tests {
|
|||||||
expected_err: None,
|
expected_err: None,
|
||||||
expected_res: vec![Ok(decimal(-5)), Ok(decimal(-13.5)), Ok(int(10))],
|
expected_res: vec![Ok(decimal(-5)), Ok(decimal(-13.5)), Ok(int(10))],
|
||||||
},
|
},
|
||||||
|
// TODO-Uncomment once I figure out how to structure tables
|
||||||
|
// TestCase {
|
||||||
|
// description: "Tables",
|
||||||
|
// values: vec![
|
||||||
|
// table(&vec![int(3), int(4), int(4)]),
|
||||||
|
// table(&vec![int(3), int(4), int(4)]),
|
||||||
|
// table(&vec![int(3), int(4), int(4)]),
|
||||||
|
// ],
|
||||||
|
// expected_err: None,
|
||||||
|
// expected_res: vec![Ok(decimal(-5)), Ok(decimal(-13.5)), Ok(int(10))],
|
||||||
|
// },
|
||||||
// TODO-Uncomment once Issue: https://github.com/nushell/nushell/issues/1883 is resolved
|
// TODO-Uncomment once Issue: https://github.com/nushell/nushell/issues/1883 is resolved
|
||||||
// TestCase {
|
// TestCase {
|
||||||
// description: "Invalid Mixed Values",
|
// description: "Invalid Mixed Values",
|
||||||
|
|||||||
@ -20,6 +20,8 @@ pub async fn calculate(
|
|||||||
Err(err) => Err(err),
|
Err(err) => Err(err),
|
||||||
}
|
}
|
||||||
} else {
|
} else {
|
||||||
|
// If we are not dealing with Primitives, then perhaps we are dealing with a table
|
||||||
|
// Create a key for each column name
|
||||||
let mut column_values = IndexMap::new();
|
let mut column_values = IndexMap::new();
|
||||||
for value in values {
|
for value in values {
|
||||||
if let UntaggedValue::Row(row_dict) = value.value {
|
if let UntaggedValue::Row(row_dict) = value.value {
|
||||||
@ -31,7 +33,7 @@ pub async fn calculate(
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
// The mathematical function operates over the columns of the table
|
||||||
let mut column_totals = IndexMap::new();
|
let mut column_totals = IndexMap::new();
|
||||||
for (col_name, col_vals) in column_values {
|
for (col_name, col_vals) in column_values {
|
||||||
match mf(&col_vals, &name) {
|
match mf(&col_vals, &name) {
|
||||||
|
|||||||
@ -1,45 +0,0 @@
|
|||||||
# average
|
|
||||||
Calculate the average of values in a column.
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
> ls | get size | average
|
|
||||||
━━━━━━━━━
|
|
||||||
<value>
|
|
||||||
━━━━━━━━━
|
|
||||||
2282.727272727273
|
|
||||||
━━━━━━━━━
|
|
||||||
```
|
|
||||||
|
|
||||||
```shell
|
|
||||||
> pwd | split-row / | size | get chars | average
|
|
||||||
━━━━━━━━━
|
|
||||||
<value>
|
|
||||||
━━━━━━━━━
|
|
||||||
5.250000000000000
|
|
||||||
━━━━━━━━━
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that average only works for integer and byte values. If the shell doesn't recognize the values in a column as one of those types, it will return an error.
|
|
||||||
One way to solve this is to convert each row to an integer when possible and then pipe the result to `average`
|
|
||||||
|
|
||||||
```shell
|
|
||||||
> open tests/fixtures/formats/caco3_plastics.csv | get tariff_item | average
|
|
||||||
error: Unrecognized type in stream: Primitive(String("2509000000"))
|
|
||||||
- shell:1:0
|
|
||||||
1 | open tests/fixtures/formats/caco3_plastics.csv | get tariff_item | average
|
|
||||||
| ^^^^ source
|
|
||||||
```
|
|
||||||
|
|
||||||
```shell
|
|
||||||
> open tests/fixtures/formats/caco3_plastics.csv | get tariff_item | str --to-int | average
|
|
||||||
━━━━━━━━━━━━━━━━━━━
|
|
||||||
<value>
|
|
||||||
───────────────────
|
|
||||||
3239404444.000000
|
|
||||||
━━━━━━━━━━━━━━━━━━━
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
108
docs/commands/math.md
Normal file
108
docs/commands/math.md
Normal file
@ -0,0 +1,108 @@
|
|||||||
|
# math
|
||||||
|
Mathematical functions that generally only operate on a list of numbers (integers, decimals, bytes) and tables.
|
||||||
|
Currently the following functions are implemented:
|
||||||
|
`math average` Get the average of a list of number
|
||||||
|
`math min` Get the minimum of a list of numbers
|
||||||
|
`math max` Get the maximum of a list of numbers
|
||||||
|
|
||||||
|
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)
|
||||||
|
```shell
|
||||||
|
> 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 average
|
||||||
|
───┬────────
|
||||||
|
0 │ 6.5 KB
|
||||||
|
───┴────────
|
||||||
|
|
||||||
|
> ls | get size | math min
|
||||||
|
───┬─────
|
||||||
|
0 │ 0 B
|
||||||
|
───┴─────
|
||||||
|
> ls | get size | math max
|
||||||
|
───┬──────────
|
||||||
|
0 │ 106.3 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
|
||||||
|
```shell
|
||||||
|
> pwd | split row / | size
|
||||||
|
───┬───────┬───────┬───────┬────────────
|
||||||
|
# │ lines │ words │ chars │ max length
|
||||||
|
───┼───────┼───────┼───────┼────────────
|
||||||
|
0 │ 0 │ 1 │ 5 │ 5
|
||||||
|
1 │ 0 │ 1 │ 7 │ 7
|
||||||
|
2 │ 0 │ 1 │ 9 │ 9
|
||||||
|
3 │ 0 │ 1 │ 7 │ 7
|
||||||
|
───┴───────┴───────┴───────┴────────────
|
||||||
|
|
||||||
|
> pwd | split row / | size | math max
|
||||||
|
───────────┬───
|
||||||
|
lines │ 0
|
||||||
|
words │ 1
|
||||||
|
chars │ 9
|
||||||
|
max length │ 9
|
||||||
|
────────────┴───
|
||||||
|
|
||||||
|
> pwd | split row / | size | math average
|
||||||
|
────────────┬────────
|
||||||
|
lines │ 0.0000
|
||||||
|
words │ 1.0000
|
||||||
|
chars │ 7.0000
|
||||||
|
max length │ 7.0000
|
||||||
|
────────────┴────────
|
||||||
|
```
|
||||||
|
|
||||||
|
## Errors
|
||||||
|
`math` functions are aggregation functions so empty lists are invalid
|
||||||
|
```shell
|
||||||
|
> echo [] | math average
|
||||||
|
error: Error: Unexpected: Cannot perform aggregate math operation on empty data
|
||||||
|
```
|
||||||
|
|
||||||
|
Note `math` functions only work on list of numbers (integers, decimals, bytes) and tables of numbers, if any other types are piped into the function
|
||||||
|
then unexpected results can occur.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
> echo [1 2 a ] | math average
|
||||||
|
0
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user