| <!--- |
| |
| SPDX-License-Identifier: BSD-2-Clause |
| |
| Copyright (c) 2018-2020 Gavin D. Howard and contributors. |
| |
| Redistribution and use in source and binary forms, with or without |
| modification, are permitted provided that the following conditions are met: |
| |
| * Redistributions of source code must retain the above copyright notice, this |
| list of conditions and the following disclaimer. |
| |
| * Redistributions in binary form must reproduce the above copyright notice, |
| this list of conditions and the following disclaimer in the documentation |
| and/or other materials provided with the distribution. |
| |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
| LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| POSSIBILITY OF SUCH DAMAGE. |
| |
| --> |
| |
| # NAME |
| |
| bc - arbitrary-precision arithmetic language and calculator |
| |
| # SYNOPSIS |
| |
| **bc** [**-ghilPqsvVw**] [**--global-stacks**] [**--help**] [**--interactive**] [**--mathlib**] [**--no-prompt**] [**--quiet**] [**--standard**] [**--warn**] [**--version**] [**-e** *expr*] [**--expression**=*expr*...] [**-f** *file*...] [**-file**=*file*...] |
| [*file*...] |
| |
| # DESCRIPTION |
| |
| bc(1) is an interactive processor for a language first standardized in 1991 by |
| POSIX. (The current standard is [here][1].) The language provides unlimited |
| precision decimal arithmetic and is somewhat C-like, but there are differences. |
| Such differences will be noted in this document. |
| |
| After parsing and handling options, this bc(1) reads any files given on the |
| command line and executes them before reading from **stdin**. |
| |
| {{ A N P NP }} |
| This bc(1) is a drop-in replacement for *any* bc(1), including (and |
| especially) the GNU bc(1). It also has many extensions and extra features beyond |
| other implementations. |
| {{ end }} |
| {{ E EN EP ENP }} |
| This bc(1) is a drop-in replacement for *any* bc(1), including (and |
| especially) the GNU bc(1). |
| {{ end }} |
| |
| # OPTIONS |
| |
| The following are the options that bc(1) accepts. |
| |
| **-g**, **--global-stacks** |
| |
| {{ A H N P HN HP NP HNP }} |
| : Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks. |
| |
| This has the effect that a copy of the current value of all four are pushed |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| Turns the globals **ibase**, **obase**, and **scale** into stacks. |
| |
| This has the effect that a copy of the current value of all three are pushed |
| {{ end }} |
| onto a stack for every function call, as well as popped when every function |
| returns. This means that functions can assign to any and all of those |
| globals without worrying that the change will affect other functions. |
| Thus, a hypothetical function named **output(x,b)** that simply printed |
| **x** in base **b** could be written like this: |
| |
| define void output(x, b) { |
| obase=b |
| x |
| } |
| |
| instead of like this: |
| |
| define void output(x, b) { |
| auto c |
| c=obase |
| obase=b |
| x |
| obase=c |
| } |
| |
| This makes writing functions much easier. |
| |
| {{ A H N P HN HP NP HNP }} |
| (**Note**: the function **output(x,b)** exists in the extended math library. |
| See the **LIBRARY** section.) |
| |
| However, since using this flag means that functions cannot set **ibase**, |
| **obase**, **scale**, or **seed** globally, functions that are made to do so |
| cannot work anymore. There are two possible use cases for that, and each has |
| a solution. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| However, since using this flag means that functions cannot set **ibase**, |
| **obase**, or **scale** globally, functions that are made to do so cannot |
| work anymore. There are two possible use cases for that, and each has a |
| solution. |
| {{ end }} |
| |
| First, if a function is called on startup to turn bc(1) into a number |
| converter, it is possible to replace that capability with various shell |
| aliases. Examples: |
| |
| alias d2o="bc -e ibase=A -e obase=8" |
| alias h2b="bc -e ibase=G -e obase=2" |
| |
| {{ A H N P HN HP NP HNP }} |
| Second, if the purpose of a function is to set **ibase**, **obase**, |
| **scale**, or **seed** globally for any other purpose, it could be split |
| into one to four functions (based on how many globals it sets) and each of |
| those functions could return the desired value for a global. |
| |
| For functions that set **seed**, the value assigned to **seed** is not |
| propagated to parent functions. This means that the sequence of |
| pseudo-random numbers that they see will not be the same sequence of |
| pseudo-random numbers that any parent sees. This is only the case once |
| **seed** has been set. |
| |
| If a function desires to not affect the sequence of pseudo-random numbers |
| of its parents, but wants to use the same **seed**, it can use the following |
| line: |
| |
| seed = seed |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| Second, if the purpose of a function is to set **ibase**, **obase**, or |
| **scale** globally for any other purpose, it could be split into one to |
| three functions (based on how many globals it sets) and each of those |
| functions could return the desired value for a global. |
| {{ end }} |
| |
| If the behavior of this option is desired for every run of bc(1), then users |
| could make sure to define **BC_ENV_ARGS** and include this option (see the |
| **ENVIRONMENT VARIABLES** section for more details). |
| |
| If **-s**, **-w**, or any equivalents are used, this option is ignored. |
| |
| This is a **non-portable extension**. |
| |
| **-h**, **--help** |
| |
| : Prints a usage message and quits. |
| |
| **-i**, **--interactive** |
| |
| : Forces interactive mode. (See the **INTERACTIVE MODE** section.) |
| |
| This is a **non-portable extension**. |
| |
| **-l**, **--mathlib** |
| |
| : Sets **scale** (see the **SYNTAX** section) to **20** and loads the included |
| {{ A H N P HN HP NP HNP }} |
| math library and the extended math library before running any code, |
| including any expressions or files specified on the command line. |
| |
| To learn what is in the libraries, see the **LIBRARY** section. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| math library before running any code, including any expressions or files |
| specified on the command line. |
| |
| To learn what is in the library, see the **LIBRARY** section. |
| {{ end }} |
| |
| **-P**, **--no-prompt** |
| |
| {{ A E H N EH EN HN EHN }} |
| : Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode. |
| See the **TTY MODE** section) This is mostly for those users that do not |
| want a prompt or are not used to having them in bc(1). Most of those users |
| would want to put this option in **BC_ENV_ARGS** (see the |
| **ENVIRONMENT VARIABLES** section). |
| {{ end }} |
| {{ P EP HP NP EHP ENP HNP EHNP }} |
| : This option is a no-op. |
| {{ end }} |
| |
| This is a **non-portable extension**. |
| |
| **-q**, **--quiet** |
| |
| : This option is for compatibility with the [GNU bc(1)][2]; it is a no-op. |
| Without this option, GNU bc(1) prints a copyright header. This bc(1) only |
| prints the copyright header if one or more of the **-v**, **-V**, or |
| **--version** options are given. |
| |
| This is a **non-portable extension**. |
| |
| **-s**, **--standard** |
| |
| : Process exactly the language defined by the [standard][1] and error if any |
| extensions are used. |
| |
| This is a **non-portable extension**. |
| |
| **-v**, **-V**, **--version** |
| |
| : Print the version information (copyright header) and exit. |
| |
| This is a **non-portable extension**. |
| |
| **-w**, **--warn** |
| |
| : Like **-s** and **--standard**, except that warnings (and not errors) are |
| printed for non-standard extensions and execution continues normally. |
| |
| This is a **non-portable extension**. |
| |
| **-e** *expr*, **--expression**=*expr* |
| |
| : Evaluates *expr*. If multiple expressions are given, they are evaluated in |
| order. If files are given as well (see below), the expressions and files are |
| evaluated in the order given. This means that if a file is given before an |
| expression, the file is read in and evaluated first. |
| |
| After processing all expressions and files, bc(1) will exit, unless **-** |
| (**stdin**) was given as an argument at least once to **-f** or **--file**. |
| However, if any other **-e**, **--expression**, **-f**, or **--file** |
| arguments are given after that, bc(1) will give a fatal error and exit. |
| |
| This is a **non-portable extension**. |
| |
| **-f** *file*, **--file**=*file* |
| |
| : Reads in *file* and evaluates it, line by line, as though it were read |
| through **stdin**. If expressions are also given (see above), the |
| expressions are evaluated in the order given. |
| |
| After processing all expressions and files, bc(1) will exit, unless **-** |
| (**stdin**) was given as an argument at least once to **-f** or **--file**. |
| |
| This is a **non-portable extension**. |
| |
| All long options are **non-portable extensions**. |
| |
| # STDOUT |
| |
| Any non-error output is written to **stdout**. |
| |
| **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal |
| error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if |
| **stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This |
| is done so that bc(1) can report problems when **stdout** is redirected to a |
| file. |
| |
| If there are scripts that depend on the behavior of other bc(1) implementations, |
| it is recommended that those scripts be changed to redirect **stdout** to |
| **/dev/null**. |
| |
| # STDERR |
| |
| Any error output is written to **stderr**. |
| |
| **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal |
| error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if |
| **stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This |
| is done so that bc(1) can exit with an error code when **stderr** is redirected |
| to a file. |
| |
| If there are scripts that depend on the behavior of other bc(1) implementations, |
| it is recommended that those scripts be changed to redirect **stderr** to |
| **/dev/null**. |
| |
| # SYNTAX |
| |
| The syntax for bc(1) programs is mostly C-like, with some differences. This |
| bc(1) follows the [POSIX standard][1], which is a much more thorough resource |
| for the language this bc(1) accepts. This section is meant to be a summary and a |
| listing of all the extensions to the standard. |
| |
| In the sections below, **E** means expression, **S** means statement, and **I** |
| means identifier. |
| |
| Identifiers (**I**) start with a lowercase letter and can be followed by any |
| number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits |
| (**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***. |
| Identifiers with more than one character (letter) are a |
| **non-portable extension**. |
| |
| **ibase** is a global variable determining how to interpret constant numbers. It |
| is the "input" base, or the number base used for interpreting input numbers. |
| **ibase** is initially **10**. If the **-s** (**--standard**) and **-w** |
| (**--warn**) flags were not given on the command line, the max allowable value |
| for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for |
| **ibase** is **2**. The max allowable value for **ibase** can be queried in |
| bc(1) programs with the **maxibase()** built-in function. |
| |
| **obase** is a global variable determining how to output results. It is the |
| "output" base, or the number base used for outputting numbers. **obase** is |
| initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and |
| can be queried in bc(1) programs with the **maxobase()** built-in function. The |
| {{ A H N P HN HP NP HNP }} |
| min allowable value for **obase** is **0**. If **obase** is **0**, values are |
| output in scientific notation, and if **obase** is **1**, values are output in |
| engineering notation. Otherwise, values are output in the specified base. |
| |
| Outputting in scientific and engineering notations are **non-portable |
| extensions**. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| min allowable value for **obase** is **2**. Values are output in the specified |
| base. |
| {{ end }} |
| |
| The *scale* of an expression is the number of digits in the result of the |
| expression right of the decimal point, and **scale** is a global variable that |
| sets the precision of any operations, with exceptions. **scale** is initially |
| **0**. **scale** cannot be negative. The max allowable value for **scale** is |
| **BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()** |
| built-in function. |
| |
| bc(1) has both *global* variables and *local* variables. All *local* |
| variables are local to the function; they are parameters or are introduced in |
| the **auto** list of a function (see the **FUNCTIONS** section). If a variable |
| is accessed which is not a parameter or in the **auto** list, it is assumed to |
| be *global*. If a parent function has a *local* variable version of a variable |
| that a child function considers *global*, the value of that *global* variable in |
| the child function is the value of the variable in the parent function, not the |
| value of the actual *global* variable. |
| |
| All of the above applies to arrays as well. |
| |
| The value of a statement that is an expression (i.e., any of the named |
| expressions or operands) is printed unless the lowest precedence operator is an |
| assignment operator *and* the expression is notsurrounded by parentheses. |
| |
| The value that is printed is also assigned to the special variable **last**. A |
| single dot (**.**) may also be used as a synonym for **last**. These are |
| **non-portable extensions**. |
| |
| Either semicolons or newlines may separate statements. |
| |
| ## Comments |
| |
| There are two kinds of comments: |
| |
| 1. Block comments are enclosed in **/\*** and **\*/**. |
| 2. Line comments go from **#** until, and not including, the next newline. This |
| is a **non-portable extension**. |
| |
| ## Named Expressions |
| |
| The following are named expressions in bc(1): |
| |
| 1. Variables: **I** |
| 2. Array Elements: **I[E]** |
| 3. **ibase** |
| 4. **obase** |
| 5. **scale** |
| {{ A H N P HN HP NP HNP }} |
| 6. **seed** |
| 7. **last** or a single dot (**.**) |
| |
| Numbers 6 and 7 are **non-portable extensions**. |
| |
| The meaning of **seed** is dependent on the current pseudo-random number |
| generator but is guaranteed to not change except for new major versions. |
| |
| The *scale* and sign of the value may be significant. |
| |
| If a previously used **seed** value is assigned to **seed** and used again, the |
| pseudo-random number generator is guaranteed to produce the same sequence of |
| pseudo-random numbers as it did when the **seed** value was previously used. |
| |
| The exact value assigned to **seed** is not guaranteed to be returned if |
| **seed** is queried again immediately. However, if **seed** *does* return a |
| different value, both values, when assigned to **seed**, are guaranteed to |
| produce the same sequence of pseudo-random numbers. This means that certain |
| values assigned to **seed** will *not* produce unique sequences of pseudo-random |
| numbers. The value of **seed** will change after any use of the **rand()** and |
| **irand(E)** operands (see the *Operands* subsection below), except if the |
| parameter passed to **irand(E)** is **0**, **1**, or negative. |
| |
| There is no limit to the length (number of significant decimal digits) or |
| *scale* of the value that can be assigned to **seed**. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| 6. **last** or a single dot (**.**) |
| |
| Number 6 is a **non-portable extension**. |
| {{ end }} |
| |
| Variables and arrays do not interfere; users can have arrays named the same as |
| variables. This also applies to functions (see the **FUNCTIONS** section), so a |
| user can have a variable, array, and function that all have the same name, and |
| they will not shadow each other, whether inside of functions or not. |
| |
| Named expressions are required as the operand of **increment**/**decrement** |
| operators and as the left side of **assignment** operators (see the *Operators* |
| subsection). |
| |
| ## Operands |
| |
| The following are valid operands in bc(1): |
| |
| 1. Numbers (see the *Numbers* subsection below). |
| 2. Array indices (**I[E]**). |
| 3. **(E)**: The value of **E** (used to change precedence). |
| 4. **sqrt(E)**: The square root of **E**. **E** must be non-negative. |
| 5. **length(E)**: The number of significant decimal digits in **E**. |
| 6. **length(I[])**: The number of elements in the array **I**. This is a |
| **non-portable extension**. |
| 7. **scale(E)**: The *scale* of **E**. |
| 8. **abs(E)**: The absolute value of **E**. This is a **non-portable |
| extension**. |
| 9. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for |
| a non-**void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form |
| **I[]**, which will automatically be turned into array references (see the |
| *Array References* subsection of the **FUNCTIONS** section) if the |
| corresponding parameter in the function definition is an array reference. |
| 10. **read()**: Reads a line from **stdin** and uses that as an expression. The |
| result of that expression is the result of the **read()** operand. This is a |
| **non-portable extension**. |
| 11. **maxibase()**: The max allowable **ibase**. This is a **non-portable |
| extension**. |
| 12. **maxobase()**: The max allowable **obase**. This is a **non-portable |
| extension**. |
| 13. **maxscale()**: The max allowable **scale**. This is a **non-portable |
| extension**. |
| {{ A H N P HN HP NP HNP }} |
| 14. **rand()**: A pseudo-random integer between **0** (inclusive) and |
| **BC_RAND_MAX** (inclusive). Using this operand will change the value of |
| **seed**. This is a **non-portable extension**. |
| 15. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the |
| value of **E** (exclusive). If **E** is negative or is a non-integer |
| (**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see |
| the **RESET** section) while **seed** remains unchanged. If **E** is larger |
| than **BC_RAND_MAX**, the higher bound is honored by generating several |
| pseudo-random integers, multiplying them by appropriate powers of |
| **BC_RAND_MAX+1**, and adding them together. Thus, the size of integer that |
| can be generated with this operand is unbounded. Using this operand will |
| change the value of **seed**, unless the value of **E** is **0** or **1**. |
| In that case, **0** is returned, and **seed** is *not* changed. This is a |
| **non-portable extension**. |
| 16. **maxrand()**: The max integer returned by **rand()**. This is a |
| **non-portable extension**. |
| |
| The integers generated by **rand()** and **irand(E)** are guaranteed to be as |
| unbiased as possible, subject to the limitations of the pseudo-random number |
| generator. |
| |
| **Note**: The values returned by the pseudo-random number generator with |
| **rand()** and **irand(E)** are guaranteed to *NOT* be cryptographically secure. |
| This is a consequence of using a seeded pseudo-random number generator. However, |
| they *are* guaranteed to be reproducible with identical **seed** values. |
| {{ end }} |
| |
| ## Numbers |
| |
| Numbers are strings made up of digits, uppercase letters, and at most **1** |
| period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase |
| letters are equal to **9** + their position in the alphabet (i.e., **A** equals |
| **10**, or **9+1**). If a digit or letter makes no sense with the current value |
| of **ibase**, they are set to the value of the highest valid digit in **ibase**. |
| |
| Single-character numbers (i.e., **A** alone) take the value that they would have |
| if they were valid digits, regardless of the value of **ibase**. This means that |
| **A** alone always equals decimal **10** and **Z** alone always equals decimal |
| **35**. |
| |
| {{ A H N P HN HP NP HNP }} |
| In addition, bc(1) accepts numbers in scientific notation. These have the form |
| **\<number\>e\<integer\>**. The power (the portion after the **e**) must be an |
| integer. An example is **1.89237e9**, which is equal to **1892370000**. Negative |
| exponents are also allowed, so **4.2890e-3** is equal to **0.0042890**. |
| |
| Using scientific notation is an error or warning if the **-s** or **-w**, |
| respectively, command-line options (or equivalents) are given. |
| |
| **WARNING**: Both the number and the exponent in scientific notation are |
| interpreted according to the current **ibase**, but the number is still |
| multiplied by **10\^exponent** regardless of the current **ibase**. For example, |
| if **ibase** is **16** and bc(1) is given the number string **FFeA**, the |
| resulting decimal number will be **2550000000000**, and if bc(1) is given the |
| number string **10e-4**, the resulting decimal number will be **0.0016**. |
| |
| Accepting input as scientific notation is a **non-portable extension**. |
| {{ end }} |
| |
| ## Operators |
| |
| The following arithmetic and logical operators can be used. They are listed in |
| order of decreasing precedence. Operators in the same group have the same |
| precedence. |
| |
| **++** **--** |
| |
| : Type: Prefix and Postfix |
| |
| Associativity: None |
| |
| Description: **increment**, **decrement** |
| |
| **-** **!** |
| |
| : Type: Prefix |
| |
| Associativity: None |
| |
| Description: **negation**, **boolean not** |
| |
| {{ A H N P HN HP NP HNP }} |
| **\$** |
| |
| : Type: Postfix |
| |
| Associativity: None |
| |
| Description: **truncation** |
| |
| **\@** |
| |
| : Type: Binary |
| |
| Associativity: Right |
| |
| Description: **set precision** |
| {{ end }} |
| |
| **\^** |
| |
| : Type: Binary |
| |
| Associativity: Right |
| |
| Description: **power** |
| |
| **\*** **/** **%** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **multiply**, **divide**, **modulus** |
| |
| **+** **-** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **add**, **subtract** |
| |
| {{ A H N P HN HP NP HNP }} |
| **\<\<** **\>\>** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **shift left**, **shift right** |
| |
| **=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| **=** **+=** **-=** **\*=** **/=** **%=** **\^=** |
| {{ end }} |
| |
| : Type: Binary |
| |
| Associativity: Right |
| |
| Description: **assignment** |
| |
| **==** **\<=** **\>=** **!=** **\<** **\>** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **relational** |
| |
| **&&** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **boolean and** |
| |
| **||** |
| |
| : Type: Binary |
| |
| Associativity: Left |
| |
| Description: **boolean or** |
| |
| The operators will be described in more detail below. |
| |
| **++** **--** |
| |
| : The prefix and postfix **increment** and **decrement** operators behave |
| exactly like they would in C. They require a named expression (see the |
| *Named Expressions* subsection) as an operand. |
| |
| The prefix versions of these operators are more efficient; use them where |
| possible. |
| |
| **-** |
| |
| : The **negation** operator returns **0** if a user attempts to negate any |
| expression with the value **0**. Otherwise, a copy of the expression with |
| its sign flipped is returned. |
| |
| **!** |
| |
| : The **boolean not** operator returns **1** if the expression is **0**, or |
| **0** otherwise. |
| |
| This is a **non-portable extension**. |
| |
| {{ A H N P HN HP NP HNP }} |
| **\$** |
| |
| : The **truncation** operator returns a copy of the given expression with all |
| of its *scale* removed. |
| |
| This is a **non-portable extension**. |
| |
| **\@** |
| |
| : The **set precision** operator takes two expressions and returns a copy of |
| the first with its *scale* equal to the value of the second expression. That |
| could either mean that the number is returned without change (if the |
| *scale* of the first expression matches the value of the second |
| expression), extended (if it is less), or truncated (if it is more). |
| |
| The second expression must be an integer (no *scale*) and non-negative. |
| |
| This is a **non-portable extension**. |
| {{ end }} |
| |
| **\^** |
| |
| : The **power** operator (not the **exclusive or** operator, as it would be in |
| C) takes two expressions and raises the first to the power of the value of |
| the second. |
| |
| The second expression must be an integer (no *scale*), and if it is |
| negative, the first value must be non-zero. |
| |
| **\*** |
| |
| : The **multiply** operator takes two expressions, multiplies them, and |
| returns the product. If **a** is the *scale* of the first expression and |
| **b** is the *scale* of the second expression, the *scale* of the result is |
| equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return |
| the obvious values. |
| |
| **/** |
| |
| : The **divide** operator takes two expressions, divides them, and returns the |
| quotient. The *scale* of the result shall be the value of **scale**. |
| |
| The second expression must be non-zero. |
| |
| **%** |
| |
| : The **modulus** operator takes two expressions, **a** and **b**, and |
| evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the |
| result of step 1 to calculate **a-(a/b)\*b** to *scale* |
| **max(scale+scale(b),scale(a))**. |
| |
| The second expression must be non-zero. |
| |
| **+** |
| |
| : The **add** operator takes two expressions, **a** and **b**, and returns the |
| sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. |
| |
| **-** |
| |
| : The **subtract** operator takes two expressions, **a** and **b**, and |
| returns the difference, with a *scale* equal to the max of the *scale*s of |
| **a** and **b**. |
| |
| {{ A H N P HN HP NP HNP }} |
| **\<\<** |
| |
| : The **left shift** operator takes two expressions, **a** and **b**, and |
| returns a copy of the value of **a** with its decimal point moved **b** |
| places to the right. |
| |
| The second expression must be an integer (no *scale*) and non-negative. |
| |
| This is a **non-portable extension**. |
| |
| **\>\>** |
| |
| : The **right shift** operator takes two expressions, **a** and **b**, and |
| returns a copy of the value of **a** with its decimal point moved **b** |
| places to the left. |
| |
| The second expression must be an integer (no *scale*) and non-negative. |
| |
| This is a **non-portable extension**. |
| {{ end }} |
| |
| {{ A H N P HN HP NP HNP }} |
| **=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| **=** **+=** **-=** **\*=** **/=** **%=** **\^=** |
| {{ end }} |
| |
| : The **assignment** operators take two expressions, **a** and **b** where |
| **a** is a named expression (see the *Named Expressions* subsection). |
| |
| For **=**, **b** is copied and the result is assigned to **a**. For all |
| others, **a** and **b** are applied as operands to the corresponding |
| arithmetic operator and the result is assigned to **a**. |
| |
| {{ A H N P HN HP NP HNP }} |
| The **assignment** operators that correspond to operators that are |
| extensions are themselves **non-portable extensions**. |
| {{ end }} |
| |
| **==** **\<=** **\>=** **!=** **\<** **\>** |
| |
| : The **relational** operators compare two expressions, **a** and **b**, and |
| if the relation holds, according to C language semantics, the result is |
| **1**. Otherwise, it is **0**. |
| |
| Note that unlike in C, these operators have a lower precedence than the |
| **assignment** operators, which means that **a=b\>c** is interpreted as |
| **(a=b)\>c**. |
| |
| Also, unlike the [standard][1] requires, these operators can appear anywhere |
| any other expressions can be used. This allowance is a |
| **non-portable extension**. |
| |
| **&&** |
| |
| : The **boolean and** operator takes two expressions and returns **1** if both |
| expressions are non-zero, **0** otherwise. |
| |
| This is *not* a short-circuit operator. |
| |
| This is a **non-portable extension**. |
| |
| **||** |
| |
| : The **boolean or** operator takes two expressions and returns **1** if one |
| of the expressions is non-zero, **0** otherwise. |
| |
| This is *not* a short-circuit operator. |
| |
| This is a **non-portable extension**. |
| |
| ## Statements |
| |
| The following items are statements: |
| |
| 1. **E** |
| 2. **{** **S** **;** ... **;** **S** **}** |
| 3. **if** **(** **E** **)** **S** |
| 4. **if** **(** **E** **)** **S** **else** **S** |
| 5. **while** **(** **E** **)** **S** |
| 6. **for** **(** **E** **;** **E** **;** **E** **)** **S** |
| 7. An empty statement |
| 8. **break** |
| 9. **continue** |
| 10. **quit** |
| 11. **halt** |
| 12. **limits** |
| 13. A string of characters, enclosed in double quotes |
| 14. **print** **E** **,** ... **,** **E** |
| 15. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for |
| a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form |
| **I[]**, which will automatically be turned into array references (see the |
| *Array References* subsection of the **FUNCTIONS** section) if the |
| corresponding parameter in the function definition is an array reference. |
| |
| Numbers 4, 9, 11, 12, 14, and 15 are **non-portable extensions**. |
| |
| Also, as a **non-portable extension**, any or all of the expressions in the |
| header of a for loop may be omitted. If the condition (second expression) is |
| omitted, it is assumed to be a constant **1**. |
| |
| The **break** statement causes a loop to stop iterating and resume execution |
| immediately following a loop. This is only allowed in loops. |
| |
| The **continue** statement causes a loop iteration to stop early and returns to |
| the start of the loop, including testing the loop condition. This is only |
| allowed in loops. |
| |
| The **if** **else** statement does the same thing as in C. |
| |
| The **quit** statement causes bc(1) to quit, even if it is on a branch that will |
| not be executed (it is a compile-time command). |
| |
| The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** |
| if it is on a branch of an **if** statement that is not executed, bc(1) does not |
| quit.) |
| |
| The **limits** statement prints the limits that this bc(1) is subject to. This |
| is like the **quit** statement in that it is a compile-time command. |
| |
| An expression by itself is evaluated and printed, followed by a newline. |
| |
| {{ A H N P HN HP NP HNP }} |
| Both scientific notation and engineering notation are available for printing the |
| results of expressions. Scientific notation is activated by assigning **0** to |
| **obase**, and engineering notation is activated by assigning **1** to |
| **obase**. To deactivate them, just assign a different value to **obase**. |
| |
| Scientific notation and engineering notation are disabled if bc(1) is run with |
| either the **-s** or **-w** command-line options (or equivalents). |
| |
| Printing numbers in scientific notation and/or engineering notation is a |
| **non-portable extension**. |
| {{ end }} |
| |
| ## Print Statement |
| |
| The "expressions" in a **print** statement may also be strings. If they are, there |
| are backslash escape sequences that are interpreted specially. What those |
| sequences are, and what they cause to be printed, are shown below: |
| |
| -------- ------- |
| **\\a** **\\a** |
| **\\b** **\\b** |
| **\\\\** **\\** |
| **\\e** **\\** |
| **\\f** **\\f** |
| **\\n** **\\n** |
| **\\q** **"** |
| **\\r** **\\r** |
| **\\t** **\\t** |
| -------- ------- |
| |
| Any other character following a backslash causes the backslash and character to |
| be printed as-is. |
| |
| Any non-string expression in a print statement shall be assigned to **last**, |
| like any other expression that is printed. |
| |
| ## Order of Evaluation |
| |
| All expressions in a statment are evaluated left to right, except as necessary |
| to maintain order of operations. This means, for example, assuming that **i** is |
| equal to **0**, in the expression |
| |
| a[i++] = i++ |
| |
| the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** |
| at the end of the expression. |
| |
| This includes function arguments. Thus, assuming **i** is equal to **0**, this |
| means that in the expression |
| |
| x(i++, i++) |
| |
| the first argument passed to **x()** is **0**, and the second argument is **1**, |
| while **i** is equal to **2** before the function starts executing. |
| |
| # FUNCTIONS |
| |
| Function definitions are as follows: |
| |
| ``` |
| define I(I,...,I){ |
| auto I,...,I |
| S;...;S |
| return(E) |
| } |
| ``` |
| |
| Any **I** in the parameter list or **auto** list may be replaced with **I[]** to |
| make a parameter or **auto** var an array, and any **I** in the parameter list |
| may be replaced with **\*I[]** to make a parameter an array reference. Callers |
| of functions that take array references should not put an asterisk in the call; |
| they must be called with just **I[]** like normal array parameters and will be |
| automatically converted into references. |
| |
| As a **non-portable extension**, the opening brace of a **define** statement may |
| appear on the next line. |
| |
| As a **non-portable extension**, the return statement may also be in one of the |
| following forms: |
| |
| 1. **return** |
| 2. **return** **(** **)** |
| 3. **return** **E** |
| |
| The first two, or not specifying a **return** statement, is equivalent to |
| **return (0)**, unless the function is a **void** function (see the *Void |
| Functions* subsection below). |
| |
| ## Void Functions |
| |
| Functions can also be **void** functions, defined as follows: |
| |
| ``` |
| define void I(I,...,I){ |
| auto I,...,I |
| S;...;S |
| return |
| } |
| ``` |
| |
| They can only be used as standalone expressions, where such an expression would |
| be printed alone, except in a print statement. |
| |
| Void functions can only use the first two **return** statements listed above. |
| They can also omit the return statement entirely. |
| |
| The word "void" is not treated as a keyword; it is still possible to have |
| variables, arrays, and functions named **void**. The word "void" is only |
| treated specially right after the **define** keyword. |
| |
| This is a **non-portable extension**. |
| |
| ## Array References |
| |
| For any array in the parameter list, if the array is declared in the form |
| |
| ``` |
| *I[] |
| ``` |
| |
| it is a **reference**. Any changes to the array in the function are reflected, |
| when the function returns, to the array that was passed in. |
| |
| Other than this, all function arguments are passed by value. |
| |
| This is a **non-portable extension**. |
| |
| # LIBRARY |
| |
| {{ A H N P HN HP NP HNP }} |
| All of the functions below, including the functions in the extended math |
| library (see the *Extended Library* subsection below), are available when the |
| **-l** or **--mathlib** command-line flags are given, except that the extended |
| math library is not available when the **-s** option, the **-w** option, or |
| equivalents are given. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| All of the functions below are available when the **-l** or **--mathlib** |
| command-line flags are given. |
| {{ end }} |
| |
| ## Standard Library |
| |
| The [standard][1] defines the following functions for the math library: |
| |
| **s(x)** |
| |
| : Returns the sine of **x**, which is assumed to be in radians. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **c(x)** |
| |
| : Returns the cosine of **x**, which is assumed to be in radians. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **a(x)** |
| |
| : Returns the arctangent of **x**, in radians. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **l(x)** |
| |
| : Returns the natural logarithm of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **e(x)** |
| |
| : Returns the mathematical constant **e** raised to the power of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **j(x, n)** |
| |
| : Returns the bessel integer order **n** (truncated) of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| {{ A H N P HN HP NP HNP }} |
| ## Extended Library |
| |
| The extended library is *not* loaded when the **-s**/**--standard** or |
| **-w**/**--warn** options are given since they are not part of the library |
| defined by the [standard][1]. |
| |
| The extended library is a **non-portable extension**. |
| |
| **p(x, y)** |
| |
| : Calculates **x** to the power of **y**, even if **y** is not an integer, and |
| returns the result to the current **scale**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **r(x, p)** |
| |
| : Returns **x** rounded to **p** decimal places according to the rounding mode |
| [round half away from **0**][3]. |
| |
| **ceil(x, p)** |
| |
| : Returns **x** rounded to **p** decimal places according to the rounding mode |
| [round away from **0**][6]. |
| |
| **f(x)** |
| |
| : Returns the factorial of the truncated absolute value of **x**. |
| |
| **perm(n, k)** |
| |
| : Returns the permutation of the truncated absolute value of **n** of the |
| truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. |
| |
| **comb(n, k)** |
| |
| : Returns the combination of the truncated absolute value of **n** of the |
| truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. |
| |
| **l2(x)** |
| |
| : Returns the logarithm base **2** of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **l10(x)** |
| |
| : Returns the logarithm base **10** of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **log(x, b)** |
| |
| : Returns the logarithm base **b** of **x**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **cbrt(x)** |
| |
| : Returns the cube root of **x**. |
| |
| **root(x, n)** |
| |
| : Calculates the truncated value of **n**, **r**, and returns the **r**th root |
| of **x** to the current **scale**. |
| |
| If **r** is **0** or negative, this raises an error and causes bc(1) to |
| reset (see the **RESET** section). It also raises an error and causes bc(1) |
| to reset if **r** is even and **x** is negative. |
| |
| **pi(p)** |
| |
| : Returns **pi** to **p** decimal places. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **t(x)** |
| |
| : Returns the tangent of **x**, which is assumed to be in radians. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **a2(y, x)** |
| |
| : Returns the arctangent of **y/x**, in radians. If both **y** and **x** are |
| equal to **0**, it raises an error and causes bc(1) to reset (see the |
| **RESET** section). Otherwise, if **x** is greater than **0**, it returns |
| **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal |
| to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** |
| is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, |
| and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to |
| **0**, and **y** is less than **0**, it returns **-pi/2**. |
| |
| This function is the same as the **atan2()** function in many programming |
| languages. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **sin(x)** |
| |
| : Returns the sine of **x**, which is assumed to be in radians. |
| |
| This is an alias of **s(x)**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **cos(x)** |
| |
| : Returns the cosine of **x**, which is assumed to be in radians. |
| |
| This is an alias of **c(x)**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **tan(x)** |
| |
| : Returns the tangent of **x**, which is assumed to be in radians. |
| |
| If **x** is equal to **1** or **-1**, this raises an error and causes bc(1) |
| to reset (see the **RESET** section). |
| |
| This is an alias of **t(x)**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **atan(x)** |
| |
| : Returns the arctangent of **x**, in radians. |
| |
| This is an alias of **a(x)**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **atan2(y, x)** |
| |
| : Returns the arctangent of **y/x**, in radians. If both **y** and **x** are |
| equal to **0**, it raises an error and causes bc(1) to reset (see the |
| **RESET** section). Otherwise, if **x** is greater than **0**, it returns |
| **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal |
| to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** |
| is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, |
| and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to |
| **0**, and **y** is less than **0**, it returns **-pi/2**. |
| |
| This function is the same as the **atan2()** function in many programming |
| languages. |
| |
| This is an alias of **a2(y, x)**. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **r2d(x)** |
| |
| : Converts **x** from radians to degrees and returns the result. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **d2r(x)** |
| |
| : Converts **x** from degrees to radians and returns the result. |
| |
| This is a transcendental function (see the *Transcendental Functions* |
| subsection below). |
| |
| **frand(p)** |
| |
| : Generates a pseudo-random number between **0** (inclusive) and **1** |
| (exclusive) with the number of decimal digits after the decimal point equal |
| to the truncated absolute value of **p**. If **p** is not **0**, then |
| calling this function will change the value of **seed**. If **p** is **0**, |
| then **0** is returned, and **seed** is *not* changed. |
| |
| **ifrand(i, p)** |
| |
| : Generates a pseudo-random number that is between **0** (inclusive) and the |
| truncated absolute value of **i** (exclusive) with the number of decimal |
| digits after the decimal point equal to the truncated absolute value of |
| **p**. If the absolute value of **i** is greater than or equal to **2**, and |
| **p** is not **0**, then calling this function will change the value of |
| **seed**; otherwise, **0** is returned and **seed** is not changed. |
| |
| **srand(x)** |
| |
| : Returns **x** with its sign flipped with probability **0.5**. In other |
| words, it randomizes the sign of **x**. |
| |
| **brand()** |
| |
| : Returns a random boolean value (either **0** or **1**). |
| |
| **ubytes(x)** |
| |
| : Returns the numbers of unsigned integer bytes required to hold the truncated |
| absolute value of **x**. |
| |
| **sbytes(x)** |
| |
| : Returns the numbers of signed, two's-complement integer bytes required to |
| hold the truncated value of **x**. |
| |
| **hex(x)** |
| |
| : Outputs the hexadecimal (base **16**) representation of **x**. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **binary(x)** |
| |
| : Outputs the binary (base **2**) representation of **x**. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **output(x, b)** |
| |
| : Outputs the base **b** representation of **x**. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uint(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in as few power of two bytes as possible. Both outputs are |
| split into bytes separated by spaces. |
| |
| If **x** is not an integer or is negative, an error message is printed |
| instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **int(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in as few power of two bytes as possible. Both |
| outputs are split into bytes separated by spaces. |
| |
| If **x** is not an integer, an error message is printed instead, but bc(1) |
| is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uintn(x, n)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in **n** bytes. Both outputs are split into bytes separated |
| by spaces. |
| |
| If **x** is not an integer, is negative, or cannot fit into **n** bytes, an |
| error message is printed instead, but bc(1) is not reset (see the **RESET** |
| section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **intn(x, n)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in **n** bytes. Both outputs are split into bytes |
| separated by spaces. |
| |
| If **x** is not an integer or cannot fit into **n** bytes, an error message |
| is printed instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uint8(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in **1** byte. Both outputs are split into bytes separated |
| by spaces. |
| |
| If **x** is not an integer, is negative, or cannot fit into **1** byte, an |
| error message is printed instead, but bc(1) is not reset (see the **RESET** |
| section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **int8(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in **1** byte. Both outputs are split into bytes |
| separated by spaces. |
| |
| If **x** is not an integer or cannot fit into **1** byte, an error message |
| is printed instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uint16(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in **2** bytes. Both outputs are split into bytes separated |
| by spaces. |
| |
| If **x** is not an integer, is negative, or cannot fit into **2** bytes, an |
| error message is printed instead, but bc(1) is not reset (see the **RESET** |
| section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **int16(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in **2** bytes. Both outputs are split into bytes |
| separated by spaces. |
| |
| If **x** is not an integer or cannot fit into **2** bytes, an error message |
| is printed instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uint32(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in **4** bytes. Both outputs are split into bytes separated |
| by spaces. |
| |
| If **x** is not an integer, is negative, or cannot fit into **4** bytes, an |
| error message is printed instead, but bc(1) is not reset (see the **RESET** |
| section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **int32(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in **4** bytes. Both outputs are split into bytes |
| separated by spaces. |
| |
| If **x** is not an integer or cannot fit into **4** bytes, an error message |
| is printed instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **uint64(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as an |
| unsigned integer in **8** bytes. Both outputs are split into bytes separated |
| by spaces. |
| |
| If **x** is not an integer, is negative, or cannot fit into **8** bytes, an |
| error message is printed instead, but bc(1) is not reset (see the **RESET** |
| section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **int64(x)** |
| |
| : Outputs the representation, in binary and hexadecimal, of **x** as a signed, |
| two's-complement integer in **8** bytes. Both outputs are split into bytes |
| separated by spaces. |
| |
| If **x** is not an integer or cannot fit into **8** bytes, an error message |
| is printed instead, but bc(1) is not reset (see the **RESET** section). |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **hex_uint(x, n)** |
| |
| : Outputs the representation of the truncated absolute value of **x** as an |
| unsigned integer in hexadecimal using **n** bytes. Not all of the value will |
| be output if **n** is too small. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **binary_uint(x, n)** |
| |
| : Outputs the representation of the truncated absolute value of **x** as an |
| unsigned integer in binary using **n** bytes. Not all of the value will be |
| output if **n** is too small. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **output_uint(x, n)** |
| |
| : Outputs the representation of the truncated absolute value of **x** as an |
| unsigned integer in the current **obase** (see the **SYNTAX** section) using |
| **n** bytes. Not all of the value will be output if **n** is too small. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| |
| **output_byte(x, i)** |
| |
| : Outputs byte **i** of the truncated absolute value of **x**, where **0** is |
| the least significant byte and **number_of_bytes - 1** is the most |
| significant byte. |
| |
| This is a **void** function (see the *Void Functions* subsection of the |
| **FUNCTIONS** section). |
| {{ end }} |
| |
| ## Transcendental Functions |
| |
| All transcendental functions can return slightly inaccurate results (up to 1 |
| [ULP][4]). This is unavoidable, and [this article][5] explains why it is |
| impossible and unnecessary to calculate exact results for the transcendental |
| functions. |
| |
| Because of the possible inaccuracy, I recommend that users call those functions |
| with the precision (**scale**) set to at least 1 higher than is necessary. If |
| exact results are *absolutely* required, users can double the precision |
| (**scale**) and then truncate. |
| |
| The transcendental functions in the standard math library are: |
| |
| * **s(x)** |
| * **c(x)** |
| * **a(x)** |
| * **l(x)** |
| * **e(x)** |
| * **j(x, n)** |
| |
| {{ A H N P HN HP NP HNP }} |
| The transcendental functions in the extended math library are: |
| |
| * **l2(x)** |
| * **l10(x)** |
| * **log(x, b)** |
| * **pi(p)** |
| * **t(x)** |
| * **a2(y, x)** |
| * **sin(x)** |
| * **cos(x)** |
| * **tan(x)** |
| * **atan(x)** |
| * **atan2(y, x)** |
| * **r2d(x)** |
| * **d2r(x)** |
| {{ end }} |
| |
| # RESET |
| |
| When bc(1) encounters an error or a signal that it has a non-default handler |
| for, it resets. This means that several things happen. |
| |
| First, any functions that are executing are stopped and popped off the stack. |
| The behavior is not unlike that of exceptions in programming languages. Then |
| the execution point is set so that any code waiting to execute (after all |
| functions returned) is skipped. |
| |
| Thus, when bc(1) resets, it skips any remaining code waiting to be executed. |
| Then, if it is interactive mode, and the error was not a fatal error (see the |
| **EXIT STATUS** section), it asks for more input; otherwise, it exits with the |
| appropriate return code. |
| |
| Note that this reset behavior is different from the GNU bc(1), which attempts to |
| start executing the statement right after the one that caused an error. |
| |
| # PERFORMANCE |
| |
| Most bc(1) implementations use **char** types to calculate the value of **1** |
| decimal digit at a time, but that can be slow. This bc(1) does something |
| different. |
| |
| It uses large integers to calculate more than **1** decimal digit at a time. If |
| built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is |
| **64**, then each integer has **9** decimal digits. If built in an environment |
| where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This |
| value (the number of decimal digits per large integer) is called |
| **BC_BASE_DIGS**. |
| |
| The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with |
| the **limits** statement. |
| |
| In addition, this bc(1) uses an even larger integer for overflow checking. This |
| integer type depends on the value of **BC_LONG_BIT**, but is always at least |
| twice as large as the integer type used to store digits. |
| |
| # LIMITS |
| |
| The following are the limits on bc(1): |
| |
| **BC_LONG_BIT** |
| |
| : The number of bits in the **long** type in the environment where bc(1) was |
| built. This determines how many decimal digits can be stored in a single |
| large integer (see the **PERFORMANCE** section). |
| |
| **BC_BASE_DIGS** |
| |
| : The number of decimal digits per large integer (see the **PERFORMANCE** |
| section). Depends on **BC_LONG_BIT**. |
| |
| **BC_BASE_POW** |
| |
| : The max decimal number that each large integer can store (see |
| **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. |
| |
| **BC_OVERFLOW_MAX** |
| |
| : The max number that the overflow type (see the **PERFORMANCE** section) can |
| hold. Depends on **BC_LONG_BIT**. |
| |
| **BC_BASE_MAX** |
| |
| : The maximum output base. Set at **BC_BASE_POW**. |
| |
| **BC_DIM_MAX** |
| |
| : The maximum size of arrays. Set at **SIZE_MAX-1**. |
| |
| **BC_SCALE_MAX** |
| |
| : The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. |
| |
| **BC_STRING_MAX** |
| |
| : The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. |
| |
| **BC_NAME_MAX** |
| |
| : The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. |
| |
| **BC_NUM_MAX** |
| |
| : The maximum length of a number (in decimal digits), which includes digits |
| after the decimal point. Set at **BC_OVERFLOW_MAX-1**. |
| |
| {{ A H N P HN HP NP HNP }} |
| **BC_RAND_MAX** |
| |
| : The maximum integer (inclusive) returned by the **rand()** operand. Set at |
| **2\^BC_LONG_BIT-1**. |
| {{ end }} |
| |
| Exponent |
| |
| : The maximum allowable exponent (positive or negative). Set at |
| **BC_OVERFLOW_MAX**. |
| |
| Number of vars |
| |
| : The maximum number of vars/arrays. Set at **SIZE_MAX-1**. |
| |
| The actual values can be queried with the **limits** statement. |
| |
| These limits are meant to be effectively non-existent; the limits are so large |
| (at least on 64-bit machines) that there should not be any point at which they |
| become a problem. In fact, memory should be exhausted before these limits should |
| be hit. |
| |
| # ENVIRONMENT VARIABLES |
| |
| bc(1) recognizes the following environment variables: |
| |
| **POSIXLY_CORRECT** |
| |
| : If this variable exists (no matter the contents), bc(1) behaves as if |
| the **-s** option was given. |
| |
| **BC_ENV_ARGS** |
| |
| : This is another way to give command-line arguments to bc(1). They should be |
| in the same format as all other command-line arguments. These are always |
| processed first, so any files given in **BC_ENV_ARGS** will be processed |
| before arguments and files given on the command-line. This gives the user |
| the ability to set up "standard" options and files to be used at every |
| invocation. The most useful thing for such files to contain would be useful |
| functions that the user might want every time bc(1) runs. |
| |
| The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, |
| but it does not understand escape sequences. For example, the string |
| **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string |
| **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. |
| |
| The quote parsing will handle either kind of quotes, **'** or **"**. Thus, |
| if you have a file with any number of single quotes in the name, you can use |
| double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice |
| versa if you have a file with double quotes. However, handling a file with |
| both kinds of quotes in **BC_ENV_ARGS** is not supported due to the |
| complexity of the parsing, though such files are still supported on the |
| command-line where the parsing is done by the shell. |
| |
| **BC_LINE_LENGTH** |
| |
| : If this environment variable exists and contains an integer that is greater |
| than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output |
| lines to that length, including the backslash (**\\**). The default line |
| length is **70**. |
| |
| # EXIT STATUS |
| |
| bc(1) returns the following exit statuses: |
| |
| **0** |
| |
| : No error. |
| |
| **1** |
| |
| : A math error occurred. This follows standard practice of using **1** for |
| expected errors, since math errors will happen in the process of normal |
| execution. |
| |
| {{ A H N P HN HP NP HNP }} |
| Math errors include divide by **0**, taking the square root of a negative |
| number, using a negative number as a bound for the pseudo-random number |
| generator, attempting to convert a negative number to a hardware integer, |
| overflow when converting a number to a hardware integer, and attempting to |
| use a non-integer where an integer is required. |
| |
| Converting to a hardware integer happens for the second operand of the power |
| (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**) |
| operators and their corresponding assignment operators. |
| {{ end }} |
| {{ E EH EN EP EHN EHP ENP EHNP }} |
| Math errors include divide by **0**, taking the square root of a negative |
| number, attempting to convert a negative number to a hardware integer, |
| overflow when converting a number to a hardware integer, and attempting to |
| use a non-integer where an integer is required. |
| |
| Converting to a hardware integer happens for the second operand of the power |
| (**\^**) operator and the corresponding assignment operator. |
| {{ end }} |
| |
| **2** |
| |
| : A parse error occurred. |
| |
| Parse errors include unexpected **EOF**, using an invalid character, failing |
| to find the end of a string or comment, using a token where it is invalid, |
| giving an invalid expression, giving an invalid print statement, giving an |
| invalid function definition, attempting to assign to an expression that is |
| not a named expression (see the *Named Expressions* subsection of the |
| **SYNTAX** section), giving an invalid **auto** list, having a duplicate |
| **auto**/function parameter, failing to find the end of a code block, |
| attempting to return a value from a **void** function, attempting to use a |
| variable as a reference, and using any extensions when the option **-s** or |
| any equivalents were given. |
| |
| **3** |
| |
| : A runtime error occurred. |
| |
| Runtime errors include assigning an invalid number to **ibase**, **obase**, |
| or **scale**; give a bad expression to a **read()** call, calling **read()** |
| inside of a **read()** call, type errors, passing the wrong number of |
| arguments to functions, attempting to call an undefined function, and |
| attempting to use a **void** function call as a value in an expression. |
| |
| **4** |
| |
| : A fatal error occurred. |
| |
| Fatal errors include memory allocation errors, I/O errors, failing to open |
| files, attempting to use files that do not have only ASCII characters (bc(1) |
| only accepts ASCII characters), attempting to open a directory as a file, |
| and giving invalid command-line options. |
| |
| The exit status **4** is special; when a fatal error occurs, bc(1) always exits |
| and returns **4**, no matter what mode bc(1) is in. |
| |
| The other statuses will only be returned when bc(1) is not in interactive mode |
| (see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the |
| **RESET** section) and accepts more input when one of those errors occurs in |
| interactive mode. This is also the case when interactive mode is forced by the |
| **-i** flag or **--interactive** option. |
| |
| These exit statuses allow bc(1) to be used in shell scripting with error |
| checking, and its normal behavior can be forced by using the **-i** flag or |
| **--interactive** option. |
| |
| # INTERACTIVE MODE |
| |
| Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode. |
| Interactive mode is turned on automatically when both **stdin** and **stdout** |
| are hooked to a terminal, but the **-i** flag and **--interactive** option can |
| turn it on in other cases. |
| |
| In interactive mode, bc(1) attempts to recover from errors (see the **RESET** |
| section), and in normal execution, flushes **stdout** as soon as execution is |
| done for the current input. |
| |
| # TTY MODE |
| |
| If **stdin**, **stdout**, and **stderr** are all connected to a TTY, bc(1) turns |
| on "TTY mode." |
| |
| {{ A E N P EN EP NP ENP }} |
| TTY mode is required for history to be enabled (see the **COMMAND LINE HISTORY** |
| section). It is also required to enable special handling for **SIGINT** signals. |
| {{ end }} |
| |
| {{ A E H N EH EN HN EHN }} |
| The prompt is enabled in TTY mode. |
| {{ end }} |
| |
| TTY mode is different from interactive mode because interactive mode is required |
| in the [bc(1) specification][1], and interactive mode requires only **stdin** |
| and **stdout** to be connected to a terminal. |
| |
| # SIGNAL HANDLING |
| |
| Sending a **SIGINT** will cause bc(1) to stop execution of the current input. If |
| bc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the |
| **RESET** section). Otherwise, it will clean up and exit. |
| |
| Note that "current input" can mean one of two things. If bc(1) is processing |
| input from **stdin** in TTY mode, it will ask for more input. If bc(1) is |
| processing input from a file in TTY mode, it will stop processing the file and |
| start processing the next file, if one exists, or ask for input from **stdin** |
| if no other file exists. |
| |
| This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it |
| can seem as though bc(1) did not respond to the signal since it will immediately |
| start executing the next file. This is by design; most files that users execute |
| when interacting with bc(1) have function definitions, which are quick to parse. |
| If a file takes a long time to execute, there may be a bug in that file. The |
| rest of the files could still be executed without problem, allowing the user to |
| continue. |
| |
| **SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the |
| {{ A E N P EN EP NP ENP }} |
| default handler for all other signals. The one exception is **SIGHUP**; in that |
| case, when bc(1) is in TTY mode, a **SIGHUP** will cause bc(1) to clean up and |
| exit. |
| {{ end }} |
| {{ H EH HN HP EHN EHP HNP EHNP }} |
| default handler for all other signals. |
| {{ end }} |
| |
| {{ A E N P EN EP NP ENP }} |
| # COMMAND LINE HISTORY |
| |
| bc(1) supports interactive command-line editing. If bc(1) is in TTY mode (see |
| the **TTY MODE** section), history is enabled. Previous lines can be recalled |
| and edited with the arrow keys. |
| |
| **Note**: tabs are converted to 8 spaces. |
| {{ end }} |
| |
| {{ A E H P EH EP HP EHP }} |
| # LOCALES |
| |
| This bc(1) ships with support for adding error messages for different locales |
| and thus, supports **LC_MESSAGES**. |
| {{ end }} |
| |
| # SEE ALSO |
| |
| dc(1) |
| |
| # STANDARDS |
| |
| bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] |
| specification. The flags **-efghiqsvVw**, all long options, and the extensions |
| noted above are extensions to that specification. |
| |
| Note that the specification explicitly says that bc(1) only accepts numbers that |
| use a period (**.**) as a radix point, regardless of the value of |
| **LC_NUMERIC**. |
| |
| {{ A E H P EH EP HP EHP }} |
| This bc(1) supports error messages for different locales, and thus, it supports |
| **LC_MESSAGES**. |
| {{ end }} |
| |
| # BUGS |
| |
| None are known. Report bugs at https://git.yzena.com/gavin/bc. |
| |
| # AUTHORS |
| |
| Gavin D. Howard <yzena.tech@gmail.com> and contributors. |
| |
| [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html |
| [2]: https://www.gnu.org/software/bc/ |
| [3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero |
| [4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place |
| [5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT |
| [6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero |