diff --git a/crates/nu-cli/src/commands/math/command.rs b/crates/nu-cli/src/commands/math/command.rs index fa726847f4..253220665d 100644 --- a/crates/nu-cli/src/commands/math/command.rs +++ b/crates/nu-cli/src/commands/math/command.rs @@ -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", diff --git a/crates/nu-cli/src/commands/math/utils.rs b/crates/nu-cli/src/commands/math/utils.rs index 39ec6198b2..0102632b36 100644 --- a/crates/nu-cli/src/commands/math/utils.rs +++ b/crates/nu-cli/src/commands/math/utils.rs @@ -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) { diff --git a/docs/commands/average.md b/docs/commands/average.md deleted file mode 100644 index 3923ae9e54..0000000000 --- a/docs/commands/average.md +++ /dev/null @@ -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 -━━━━━━━━━ - -━━━━━━━━━ -2282.727272727273 -━━━━━━━━━ -``` - -```shell -> pwd | split-row / | size | get chars | average -━━━━━━━━━ - -━━━━━━━━━ -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 -━━━━━━━━━━━━━━━━━━━ - -─────────────────── - 3239404444.000000 -━━━━━━━━━━━━━━━━━━━ -``` - - diff --git a/docs/commands/math.md b/docs/commands/math.md new file mode 100644 index 0000000000..a9eba76aa2 --- /dev/null +++ b/docs/commands/math.md @@ -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 +``` + + + +