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 a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.

For a description of the syntax supported by math, see the manual for the bc program. 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 have to be escaped.

The following options are available:

- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer and defaults to zero. This simply sets bc's `scale` variable to the provided value.

\subsection return-values Return Values

If invalid options or no expression is provided the return `status` is two. If the expression is invalid the  return `status` is three. If bc returns a result of `0` (literally, not `0.0` or similar variants) the return `status` is one otherwise it's zero.

\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`.

\subsection math-cautions Cautions

You should always place a `--` flag separator before the expression. 99.99% of the time you'll get the desired result without the separator. Something like `math -10.0 / 2` will fail because the negative floating point value gets treated as an invalid flag. But `math -10 / 2` will work because negative integers are special-cased.

Note that the modulo operator (`x % y`) is not well defined for floating point arithmetic. The `bc` command produces a nonsensical result rather than emit an error and fail in that case. It doesn't matter if the arguments are integers; e.g., `10 % 4`. You'll still get an incorrect result. Do not use the `-sN` flag with N greater than zero if you want sensible answers when using the modulo operator.
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`

Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +08:00			`math` is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.

			`For a description of the syntax supported by math, see the manual for the bc program. 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 have to be escaped.`

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:`

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			- `-sN` or `--scale=N` sets the scale of the result. `N` must be an integer and defaults to zero. This simply sets bc's `scale` variable to the provided value.
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`

			If invalid options or no expression is provided the return `status` is two. If the expression is invalid the return `status` is three. If bc returns a result of `0` (literally, not `0.0` or similar variants) the return `status` is one otherwise it's zero.
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
Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +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`.

			`\subsection math-cautions Cautions`

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			You should always place a `--` flag separator before the expression. 99.99% of the time you'll get the desired result without the separator. Something like `math -10.0 / 2` will fail because the negative floating point value gets treated as an invalid flag. But `math -10 / 2` will work because negative integers are special-cased.

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			Note that the modulo operator (`x % y`) is not well defined for floating point arithmetic. The `bc` command produces a nonsensical result rather than emit an error and fail in that case. It doesn't matter if the arguments are integers; e.g., `10 % 4`. You'll still get an incorrect result. Do not use the `-sN` flag with N greater than zero if you want sensible answers when using the modulo operator.