mirror of
https://github.com/nushell/nushell.git
synced 2024-10-06 10:23:49 +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 {
|
||||
r#"Use mathematical functions (average, min, max) to aggregate list of numbers or tables
|
||||
math average
|
||||
math min
|
||||
math max
|
||||
"#
|
||||
"Use mathematical functions as aggregate functions on a list of numbers or tables"
|
||||
}
|
||||
|
||||
async fn run(
|
||||
@ -97,6 +93,17 @@ mod tests {
|
||||
expected_err: None,
|
||||
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
|
||||
// TestCase {
|
||||
// description: "Invalid Mixed Values",
|
||||
|
||||
@ -20,6 +20,8 @@ pub async fn calculate(
|
||||
Err(err) => Err(err),
|
||||
}
|
||||
} 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();
|
||||
for value in values {
|
||||
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();
|
||||
for (col_name, col_vals) in column_values {
|
||||
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