fish-shell/doc_src/math.txt

\section math math - Perform mathematics calculations

\subsection math-synopsis Synopsis
\fish{synopsis}
math [-sN | --scale=N] [--] EXPRESSION
\endfish

\subsection math-description Description

`math` is used to perform mathematical calculations. It is based on the MuParser library which is documented <a href="http://beltoforion.de/article.php?a=muparser&hl=en&p=features&s=idPageTop#idPageTop">here</a>. You can use bare variable names (i.e., without the dollar-sign).  The stock MuParser does not support the modulo, `%` operator but fish implements it using integer semantics.

Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis and the asterisk glob character have to be escaped.

The `math` command can evaluate multiple expressions separated by commas. The result of each expression is written on a separate line. This means you can evaluate multiple expressions and capture the results in a single invocation just like you can with commands like `string`. See the examples below.

The following options are available:

- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer and defaults to zero (rounded to the nearest integer).

\subsection return-values Return Values

If the expression is successfully evaluated the return `status` is zero (success) else one.

\subsection math-example Examples

`math 1+1` outputs 2.

`math status - 128` outputs the numerical exit status of the last command minus 128.

`math 10 / 6` outputs `1`.

`math -s0 10.0 / 6.0` outputs `1`.

`math -s3 10 / 6` outputs `1.666`.

Capture the result of three expressions: `set results (math '1+1, 5*3, 10^2')` sets `$results` to 2, 15, and 100.

\subsection math-cautions Cautions

You don't need to use `--` before the expression even if it begins with a minus sign which might otherwise be interpreted as an invalid option.

Note that the modulo operator (`x % y`) is not well defined for floating point arithmetic. Fish rounds down all floating point values to nearest int before performing the modulo operation. So `10.5 % 6.1` is `4`.

\subsection math-notes Compatibility notes

Fish 1.x and 2.x releases relied on the `bc` command for handling math expressions via the `math` command. Starting with fish 3.0.0 fish uses the MuParser library.
Update documentation display code to run roff on the client system instead of pregenerating documentation and compiling it into program binaries darcs-hash:20061117162438-ac50b-5c4c7f0bd8bf53a16e16ecfead9569e642b7160f.gz 2006-11-18 00:24:38 +08:00			`\section math math - Perform mathematics calculations`

			`\subsection math-synopsis Synopsis`
Simplify styling 2014-08-01 20:25:41 +08:00			`\fish{synopsis}`
fix `math` regression The previous change to use `argparse` for parity with every other builtin and function introduced a regression. Invocations that start with a negative number can fail because the negative value looks like an invalid flag. 2017-07-15 07:03:31 +08:00			`math [-sN \| --scale=N] [--] EXPRESSION`
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 10:37:32 +08:00			`\endfish`
Update documentation display code to run roff on the client system instead of pregenerating documentation and compiling it into program binaries darcs-hash:20061117162438-ac50b-5c4c7f0bd8bf53a16e16ecfead9569e642b7160f.gz 2006-11-18 00:24:38 +08:00
			`\subsection math-description Description`

Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			`math` is used to perform mathematical calculations. It is based on the MuParser library which is documented <a href="http://beltoforion.de/article.php?a=muparser&hl=en&p=features&s=idPageTop#idPageTop">here</a>. You can use bare variable names (i.e., without the dollar-sign). The stock MuParser does not support the modulo, `%` operator but fish implements it using integer semantics.
Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +08:00
Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			`Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis and the asterisk glob character have to be escaped.`
Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +08:00
Implement support for multiple math expressions The MuParser supports the concept of multiple expressions separated by commas. This implements support for that so that you can do things like this: set results (math '1+1, 4*2, 9^2') 2017-08-24 08:14:54 +08:00			The `math` command can evaluate multiple expressions separated by commas. The result of each expression is written on a separate line. This means you can evaluate multiple expressions and capture the results in a single invocation just like you can with commands like `string`. See the examples below.

add floating point output to `math` command This makes it easy for the user to request floating point output with the desired number of digits after the decimal point (not to be confused with significant digits). Note that this is just a thin wrapper so someone can say `math -s3 10 / 3` rather than `math "scale=3; 10 /3"`. Resolves #1643 2016-05-03 11:53:48 +08:00			`The following options are available:`

Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer and defaults to zero (rounded to the nearest integer).
add floating point output to `math` command This makes it easy for the user to request floating point output with the desired number of digits after the decimal point (not to be confused with significant digits). Note that this is just a thin wrapper so someone can say `math -s3 10 / 3` rather than `math "scale=3; 10 /3"`. Resolves #1643 2016-05-03 11:53:48 +08:00
			`\subsection return-values Return Values`

Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			If the expression is successfully evaluated the return `status` is zero (success) else one.
Extend documentation for the math function darcs-hash:20061212171037-ac50b-1b9d0f51b284925fe0fc3020774ec32bb1414ce7.gz 2006-12-13 01:10:37 +08:00
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 15:56:01 +08:00			`\subsection math-example Examples`

Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 10:37:32 +08:00			`math 1+1` outputs 2.
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 15:56:01 +08:00
Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			`math status - 128` outputs the numerical exit status of the last command minus 128.
add floating point output to `math` command This makes it easy for the user to request floating point output with the desired number of digits after the decimal point (not to be confused with significant digits). Note that this is just a thin wrapper so someone can say `math -s3 10 / 3` rather than `math "scale=3; 10 /3"`. Resolves #1643 2016-05-03 11:53:48 +08:00
			`math 10 / 6` outputs `1`.

			`math -s0 10.0 / 6.0` outputs `1`.

			`math -s3 10 / 6` outputs `1.666`.

Implement support for multiple math expressions The MuParser supports the concept of multiple expressions separated by commas. This implements support for that so that you can do things like this: set results (math '1+1, 4*2, 9^2') 2017-08-24 08:14:54 +08:00			Capture the result of three expressions: `set results (math '1+1, 5*3, 10^2')` sets `$results` to 2, 15, and 100.

add floating point output to `math` command This makes it easy for the user to request floating point output with the desired number of digits after the decimal point (not to be confused with significant digits). Note that this is just a thin wrapper so someone can say `math -s3 10 / 3` rather than `math "scale=3; 10 /3"`. Resolves #1643 2016-05-03 11:53:48 +08:00			`\subsection math-cautions Cautions`

Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			You don't need to use `--` before the expression even if it begins with a minus sign which might otherwise be interpreted as an invalid option.
fix `math` regression The previous change to use `argparse` for parity with every other builtin and function introduced a regression. Invocations that start with a negative number can fail because the negative value looks like an invalid flag. 2017-07-15 07:03:31 +08:00
Implement bare minimum builtin `math` command This is the second baby step in resolving #3157. Implement a bare minimum builtin `math` command. This is solely to ensure that fish can be built and run in the Travis build environments. This is okay since anyone running `builtin math` today is already getting an error response. Also, more work is needed to support bare var references, multiple result values, etc. 2017-08-23 10:57:30 +08:00			Note that the modulo operator (`x % y`) is not well defined for floating point arithmetic. Fish rounds down all floating point values to nearest int before performing the modulo operation. So `10.5 % 6.1` is `4`.

			`\subsection math-notes Compatibility notes`

			Fish 1.x and 2.x releases relied on the `bc` command for handling math expressions via the `math` command. Starting with fish 3.0.0 fish uses the MuParser library.