1<!--- 2 3SPDX-License-Identifier: BSD-2-Clause 4 5Copyright (c) 2018-2024 Gavin D. Howard and contributors. 6 7Redistribution and use in source and binary forms, with or without 8modification, are permitted provided that the following conditions are met: 9 10* Redistributions of source code must retain the above copyright notice, this 11 list of conditions and the following disclaimer. 12 13* Redistributions in binary form must reproduce the above copyright notice, 14 this list of conditions and the following disclaimer in the documentation 15 and/or other materials provided with the distribution. 16 17THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 21LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27POSSIBILITY OF SUCH DAMAGE. 28 29--> 30 31# NAME 32 33bc - arbitrary-precision decimal arithmetic language and calculator 34 35# SYNOPSIS 36 37**bc** [**-cCghilPqRsvVw**] [**-\-digit-clamp**] [**-\-no-digit-clamp**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...] [**-I** *ibase*] [**-\-ibase**=*ibase*] [**-O** *obase*] [**-\-obase**=*obase*] [**-S** *scale*] [**-\-scale**=*scale*] [**-E** *seed*] [**-\-seed**=*seed*] 38 39# DESCRIPTION 40 41bc(1) is an interactive processor for a language first standardized in 1991 by 42POSIX. (See the **STANDARDS** section.) The language provides unlimited 43precision decimal arithmetic and is somewhat C-like, but there are differences. 44Such differences will be noted in this document. 45 46After parsing and handling options, this bc(1) reads any files given on the 47command line and executes them before reading from **stdin**. 48 49This bc(1) is a drop-in replacement for *any* bc(1), including (and 50especially) the GNU bc(1). It also has many extensions and extra features beyond 51other implementations. 52 53**Note**: If running this bc(1) on *any* script meant for another bc(1) gives a 54parse error, it is probably because a word this bc(1) reserves as a keyword is 55used as the name of a function, variable, or array. To fix that, use the 56command-line option **-r** *keyword*, where *keyword* is the keyword that is 57used as a name in the script. For more information, see the **OPTIONS** section. 58 59If parsing scripts meant for other bc(1) implementations still does not work, 60that is a bug and should be reported. See the **BUGS** section. 61 62# OPTIONS 63 64The following are the options that bc(1) accepts. 65 66**-C**, **-\-no-digit-clamp** 67 68: Disables clamping of digits greater than or equal to the current **ibase** 69 when parsing numbers. 70 71 This means that the value added to a number from a digit is always that 72 digit's value multiplied by the value of ibase raised to the power of the 73 digit's position, which starts from 0 at the least significant digit. 74 75 If this and/or the **-c** or **-\-digit-clamp** options are given multiple 76 times, the last one given is used. 77 78 This option overrides the **BC_DIGIT_CLAMP** environment variable (see the 79 **ENVIRONMENT VARIABLES** section) and the default, which can be queried 80 with the **-h** or **-\-help** options. 81 82 This is a **non-portable extension**. 83 84**-c**, **-\-digit-clamp** 85 86: Enables clamping of digits greater than or equal to the current **ibase** 87 when parsing numbers. 88 89 This means that digits that the value added to a number from a digit that is 90 greater than or equal to the ibase is the value of ibase minus 1 all 91 multiplied by the value of ibase raised to the power of the digit's 92 position, which starts from 0 at the least significant digit. 93 94 If this and/or the **-C** or **-\-no-digit-clamp** options are given 95 multiple times, the last one given is used. 96 97 This option overrides the **BC_DIGIT_CLAMP** environment variable (see the 98 **ENVIRONMENT VARIABLES** section) and the default, which can be queried 99 with the **-h** or **-\-help** options. 100 101 This is a **non-portable extension**. 102 103**-E** *seed*, **-\-seed**=*seed* 104 105: Sets the builtin variable **seed** to the value *seed* assuming that *seed* 106 is in base 10. It is a fatal error if *seed* is not a valid number. 107 108 If multiple instances of this option are given, the last is used. 109 110 This is a **non-portable extension**. 111 112**-e** *expr*, **-\-expression**=*expr* 113 114: Evaluates *expr*. If multiple expressions are given, they are evaluated in 115 order. If files are given as well (see the **-f** and **-\-file** options), 116 the expressions and files are evaluated in the order given. This means that 117 if a file is given before an expression, the file is read in and evaluated 118 first. 119 120 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**, 121 see the **ENVIRONMENT VARIABLES** section), then after processing all 122 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given 123 as an argument at least once to **-f** or **-\-file**, whether on the 124 command-line or in **BC_ENV_ARGS**. However, if any other **-e**, 125 **-\-expression**, **-f**, or **-\-file** arguments are given after **-f-** 126 or equivalent is given, bc(1) will give a fatal error and exit. 127 128 This is a **non-portable extension**. 129 130**-f** *file*, **-\-file**=*file* 131 132: Reads in *file* and evaluates it, line by line, as though it were read 133 through **stdin**. If expressions are also given (see the **-e** and 134 **-\-expression** options), the expressions are evaluated in the order 135 given. 136 137 If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**, 138 see the **ENVIRONMENT VARIABLES** section), then after processing all 139 expressions and files, bc(1) will exit, unless **-** (**stdin**) was given 140 as an argument at least once to **-f** or **-\-file**. However, if any other 141 **-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after 142 **-f-** or equivalent is given, bc(1) will give a fatal error and exit. 143 144 This is a **non-portable extension**. 145 146**-g**, **-\-global-stacks** 147 148: Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks. 149 150 This has the effect that a copy of the current value of all four are pushed 151 onto a stack for every function call, as well as popped when every function 152 returns. This means that functions can assign to any and all of those 153 globals without worrying that the change will affect other functions. 154 Thus, a hypothetical function named **output(x,b)** that simply printed 155 **x** in base **b** could be written like this: 156 157 define void output(x, b) { 158 obase=b 159 x 160 } 161 162 instead of like this: 163 164 define void output(x, b) { 165 auto c 166 c=obase 167 obase=b 168 x 169 obase=c 170 } 171 172 This makes writing functions much easier. 173 174 (**Note**: the function **output(x,b)** exists in the extended math library. 175 See the **LIBRARY** section.) 176 177 However, since using this flag means that functions cannot set **ibase**, 178 **obase**, **scale**, or **seed** globally, functions that are made to do so 179 cannot work anymore. There are two possible use cases for that, and each has 180 a solution. 181 182 First, if a function is called on startup to turn bc(1) into a number 183 converter, it is possible to replace that capability with various shell 184 aliases. Examples: 185 186 alias d2o="bc -e ibase=A -e obase=8" 187 alias h2b="bc -e ibase=G -e obase=2" 188 189 Second, if the purpose of a function is to set **ibase**, **obase**, 190 **scale**, or **seed** globally for any other purpose, it could be split 191 into one to four functions (based on how many globals it sets) and each of 192 those functions could return the desired value for a global. 193 194 For functions that set **seed**, the value assigned to **seed** is not 195 propagated to parent functions. This means that the sequence of 196 pseudo-random numbers that they see will not be the same sequence of 197 pseudo-random numbers that any parent sees. This is only the case once 198 **seed** has been set. 199 200 If a function desires to not affect the sequence of pseudo-random numbers 201 of its parents, but wants to use the same **seed**, it can use the following 202 line: 203 204 seed = seed 205 206 If the behavior of this option is desired for every run of bc(1), then users 207 could make sure to define **BC_ENV_ARGS** and include this option (see the 208 **ENVIRONMENT VARIABLES** section for more details). 209 210 If **-s**, **-w**, or any equivalents are used, this option is ignored. 211 212 This is a **non-portable extension**. 213 214**-h**, **-\-help** 215 216: Prints a usage message and exits. 217 218**-I** *ibase*, **-\-ibase**=*ibase* 219 220: Sets the builtin variable **ibase** to the value *ibase* assuming that 221 *ibase* is in base 10. It is a fatal error if *ibase* is not a valid number. 222 223 If multiple instances of this option are given, the last is used. 224 225 This is a **non-portable extension**. 226 227**-i**, **-\-interactive** 228 229: Forces interactive mode. (See the **INTERACTIVE MODE** section.) 230 231 This is a **non-portable extension**. 232 233**-L**, **-\-no-line-length** 234 235: Disables line length checking and prints numbers without backslashes and 236 newlines. In other words, this option sets **BC_LINE_LENGTH** to **0** (see 237 the **ENVIRONMENT VARIABLES** section). 238 239 This is a **non-portable extension**. 240 241**-l**, **-\-mathlib** 242 243: Sets **scale** (see the **SYNTAX** section) to **20** and loads the included 244 math library and the extended math library before running any code, 245 including any expressions or files specified on the command line. 246 247 To learn what is in the libraries, see the **LIBRARY** section. 248 249**-O** *obase*, **-\-obase**=*obase* 250 251: Sets the builtin variable **obase** to the value *obase* assuming that 252 *obase* is in base 10. It is a fatal error if *obase* is not a valid number. 253 254 If multiple instances of this option are given, the last is used. 255 256 This is a **non-portable extension**. 257 258**-P**, **-\-no-prompt** 259 260: Disables the prompt in TTY mode. (The prompt is only enabled in TTY mode. 261 See the **TTY MODE** section.) This is mostly for those users that do not 262 want a prompt or are not used to having them in bc(1). Most of those users 263 would want to put this option in **BC_ENV_ARGS** (see the 264 **ENVIRONMENT VARIABLES** section). 265 266 These options override the **BC_PROMPT** and **BC_TTY_MODE** environment 267 variables (see the **ENVIRONMENT VARIABLES** section). 268 269 This is a **non-portable extension**. 270 271**-q**, **-\-quiet** 272 273: This option is for compatibility with the GNU bc(1) 274 (https://www.gnu.org/software/bc/); it is a no-op. Without this option, GNU 275 bc(1) prints a copyright header. This bc(1) only prints the copyright header 276 if one or more of the **-v**, **-V**, or **-\-version** options are given 277 unless the **BC_BANNER** environment variable is set and contains a non-zero 278 integer or if this bc(1) was built with the header displayed by default. If 279 *any* of that is the case, then this option *does* prevent bc(1) from 280 printing the header. 281 282 This is a **non-portable extension**. 283 284**-R**, **-\-no-read-prompt** 285 286: Disables the read prompt in TTY mode. (The read prompt is only enabled in 287 TTY mode. See the **TTY MODE** section.) This is mostly for those users that 288 do not want a read prompt or are not used to having them in bc(1). Most of 289 those users would want to put this option in **BC_ENV_ARGS** (see the 290 **ENVIRONMENT VARIABLES** section). This option is also useful in hash bang 291 lines of bc(1) scripts that prompt for user input. 292 293 This option does not disable the regular prompt because the read prompt is 294 only used when the **read()** built-in function is called. 295 296 These options *do* override the **BC_PROMPT** and **BC_TTY_MODE** 297 environment variables (see the **ENVIRONMENT VARIABLES** section), but only 298 for the read prompt. 299 300 This is a **non-portable extension**. 301 302**-r** *keyword*, **-\-redefine**=*keyword* 303 304: Redefines *keyword* in order to allow it to be used as a function, variable, 305 or array name. This is useful when this bc(1) gives parse errors when 306 parsing scripts meant for other bc(1) implementations. 307 308 The keywords this bc(1) allows to be redefined are: 309 310 * **abs** 311 * **asciify** 312 * **continue** 313 * **divmod** 314 * **else** 315 * **halt** 316 * **irand** 317 * **last** 318 * **limits** 319 * **maxibase** 320 * **maxobase** 321 * **maxrand** 322 * **maxscale** 323 * **modexp** 324 * **print** 325 * **rand** 326 * **read** 327 * **seed** 328 * **stream** 329 330 If any of those keywords are used as a function, variable, or array name in 331 a script, use this option with the keyword as the argument. If multiple are 332 used, use this option for all of them; it can be used multiple times. 333 334 Keywords are *not* redefined when parsing the builtin math library (see the 335 **LIBRARY** section). 336 337 It is a fatal error to redefine keywords mandated by the POSIX standard (see 338 the **STANDARDS** section). It is a fatal error to attempt to redefine words 339 that this bc(1) does not reserve as keywords. 340 341**-S** *scale*, **-\-scale**=*scale* 342 343: Sets the builtin variable **scale** to the value *scale* assuming that 344 *scale* is in base 10. It is a fatal error if *scale* is not a valid number. 345 346 If multiple instances of this option are given, the last is used. 347 348 This is a **non-portable extension**. 349 350**-s**, **-\-standard** 351 352: Process exactly the language defined by the standard (see the **STANDARDS** 353 section) and error if any extensions are used. 354 355 This is a **non-portable extension**. 356 357**-v**, **-V**, **-\-version** 358 359: Print the version information (copyright header) and exits. 360 361 This is a **non-portable extension**. 362 363**-w**, **-\-warn** 364 365: Like **-s** and **-\-standard**, except that warnings (and not errors) are 366 printed for non-standard extensions and execution continues normally. 367 368 This is a **non-portable extension**. 369 370**-z**, **-\-leading-zeroes** 371 372: Makes bc(1) print all numbers greater than **-1** and less than **1**, and 373 not equal to **0**, with a leading zero. 374 375 This can be set for individual numbers with the **plz(x)**, **plznl(x)**, 376 **pnlz(x)**, and **pnlznl(x)** functions in the extended math library (see 377 the **LIBRARY** section). 378 379 This is a **non-portable extension**. 380 381All long options are **non-portable extensions**. 382 383# STDIN 384 385If no files or expressions are given by the **-f**, **-\-file**, **-e**, or 386**-\-expression** options, then bc(1) reads from **stdin**. 387 388However, there are a few caveats to this. 389 390First, **stdin** is evaluated a line at a time. The only exception to this is if 391the parse cannot complete. That means that starting a string without ending it 392or starting a function, **if** statement, or loop without ending it will also 393cause bc(1) to not execute. 394 395Second, after an **if** statement, bc(1) doesn't know if an **else** statement 396will follow, so it will not execute until it knows there will not be an **else** 397statement. 398 399# STDOUT 400 401Any non-error output is written to **stdout**. In addition, if history (see the 402**HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled, 403both are output to **stdout**. 404 405**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 406error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if 407**stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This 408is done so that bc(1) can report problems when **stdout** is redirected to a 409file. 410 411If there are scripts that depend on the behavior of other bc(1) implementations, 412it is recommended that those scripts be changed to redirect **stdout** to 413**/dev/null**. 414 415# STDERR 416 417Any error output is written to **stderr**. 418 419**Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal 420error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if 421**stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This 422is done so that bc(1) can exit with an error code when **stderr** is redirected 423to a file. 424 425If there are scripts that depend on the behavior of other bc(1) implementations, 426it is recommended that those scripts be changed to redirect **stderr** to 427**/dev/null**. 428 429# SYNTAX 430 431The syntax for bc(1) programs is mostly C-like, with some differences. This 432bc(1) follows the POSIX standard (see the **STANDARDS** section), which is a 433much more thorough resource for the language this bc(1) accepts. This section is 434meant to be a summary and a listing of all the extensions to the standard. 435 436In the sections below, **E** means expression, **S** means statement, and **I** 437means identifier. 438 439Identifiers (**I**) start with a lowercase letter and can be followed by any 440number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits 441(**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***. 442Identifiers with more than one character (letter) are a 443**non-portable extension**. 444 445**ibase** is a global variable determining how to interpret constant numbers. It 446is the "input" base, or the number base used for interpreting input numbers. 447**ibase** is initially **10**. If the **-s** (**-\-standard**) and **-w** 448(**-\-warn**) flags were not given on the command line, the max allowable value 449for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for 450**ibase** is **2**. The max allowable value for **ibase** can be queried in 451bc(1) programs with the **maxibase()** built-in function. 452 453**obase** is a global variable determining how to output results. It is the 454"output" base, or the number base used for outputting numbers. **obase** is 455initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and 456can be queried in bc(1) programs with the **maxobase()** built-in function. The 457min allowable value for **obase** is **0**. If **obase** is **0**, values are 458output in scientific notation, and if **obase** is **1**, values are output in 459engineering notation. Otherwise, values are output in the specified base. 460 461Outputting in scientific and engineering notations are **non-portable 462extensions**. 463 464The *scale* of an expression is the number of digits in the result of the 465expression right of the decimal point, and **scale** is a global variable that 466sets the precision of any operations, with exceptions. **scale** is initially 467**0**. **scale** cannot be negative. The max allowable value for **scale** is 468**BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()** 469built-in function. 470 471bc(1) has both *global* variables and *local* variables. All *local* 472variables are local to the function; they are parameters or are introduced in 473the **auto** list of a function (see the **FUNCTIONS** section). If a variable 474is accessed which is not a parameter or in the **auto** list, it is assumed to 475be *global*. If a parent function has a *local* variable version of a variable 476that a child function considers *global*, the value of that *global* variable in 477the child function is the value of the variable in the parent function, not the 478value of the actual *global* variable. 479 480All of the above applies to arrays as well. 481 482The value of a statement that is an expression (i.e., any of the named 483expressions or operands) is printed unless the lowest precedence operator is an 484assignment operator *and* the expression is notsurrounded by parentheses. 485 486The value that is printed is also assigned to the special variable **last**. A 487single dot (**.**) may also be used as a synonym for **last**. These are 488**non-portable extensions**. 489 490Either semicolons or newlines may separate statements. 491 492## Comments 493 494There are two kinds of comments: 495 4961. Block comments are enclosed in **/\*** and **\*/**. 4972. Line comments go from **#** until, and not including, the next newline. This 498 is a **non-portable extension**. 499 500## Named Expressions 501 502The following are named expressions in bc(1): 503 5041. Variables: **I** 5052. Array Elements: **I[E]** 5063. **ibase** 5074. **obase** 5085. **scale** 5096. **seed** 5107. **last** or a single dot (**.**) 511 512Numbers 6 and 7 are **non-portable extensions**. 513 514The meaning of **seed** is dependent on the current pseudo-random number 515generator but is guaranteed to not change except for new major versions. 516 517The *scale* and sign of the value may be significant. 518 519If a previously used **seed** value is assigned to **seed** and used again, the 520pseudo-random number generator is guaranteed to produce the same sequence of 521pseudo-random numbers as it did when the **seed** value was previously used. 522 523The exact value assigned to **seed** is not guaranteed to be returned if 524**seed** is queried again immediately. However, if **seed** *does* return a 525different value, both values, when assigned to **seed**, are guaranteed to 526produce the same sequence of pseudo-random numbers. This means that certain 527values assigned to **seed** will *not* produce unique sequences of pseudo-random 528numbers. The value of **seed** will change after any use of the **rand()** and 529**irand(E)** operands (see the *Operands* subsection below), except if the 530parameter passed to **irand(E)** is **0**, **1**, or negative. 531 532There is no limit to the length (number of significant decimal digits) or 533*scale* of the value that can be assigned to **seed**. 534 535Variables and arrays do not interfere; users can have arrays named the same as 536variables. This also applies to functions (see the **FUNCTIONS** section), so a 537user can have a variable, array, and function that all have the same name, and 538they will not shadow each other, whether inside of functions or not. 539 540Named expressions are required as the operand of **increment**/**decrement** 541operators and as the left side of **assignment** operators (see the *Operators* 542subsection). 543 544## Operands 545 546The following are valid operands in bc(1): 547 5481. Numbers (see the *Numbers* subsection below). 5492. Array indices (**I[E]**). 5503. **(E)**: The value of **E** (used to change precedence). 5514. **sqrt(E)**: The square root of **E**. **E** must be non-negative. 5525. **length(E)**: The number of significant decimal digits in **E**. Returns 553 **1** for **0** with no decimal places. If given a string, the length of the 554 string is returned. Passing a string to **length(E)** is a **non-portable 555 extension**. 5566. **length(I[])**: The number of elements in the array **I**. This is a 557 **non-portable extension**. 5587. **scale(E)**: The *scale* of **E**. 5598. **abs(E)**: The absolute value of **E**. This is a **non-portable 560 extension**. 5619. **is_number(E)**: **1** if the given argument is a number, **0** if it is a 562 string. This is a **non-portable extension**. 56310. **is_string(E)**: **1** if the given argument is a string, **0** if it is a 564 number. This is a **non-portable extension**. 56511. **modexp(E, E, E)**: Modular exponentiation, where the first expression is 566 the base, the second is the exponent, and the third is the modulus. All 567 three values must be integers. The second argument must be non-negative. The 568 third argument must be non-zero. This is a **non-portable extension**. 56911. **divmod(E, E, I[])**: Division and modulus in one operation. This is for 570 optimization. The first expression is the dividend, and the second is the 571 divisor, which must be non-zero. The return value is the quotient, and the 572 modulus is stored in index **0** of the provided array (the last argument). 573 This is a **non-portable extension**. 57412. **asciify(E)**: If **E** is a string, returns a string that is the first 575 letter of its argument. If it is a number, calculates the number mod **256** 576 and returns that number as a one-character string. This is a **non-portable 577 extension**. 57813. **asciify(I[])**: A string that is made up of the characters that would 579 result from running **asciify(E)** on each element of the array identified 580 by the argument. This allows creating multi-character strings and storing 581 them. This is a **non-portable extension**. 58214. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 583 a non-**void** function (see the *Void Functions* subsection of the 584 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 585 **I[]**, which will automatically be turned into array references (see the 586 *Array References* subsection of the **FUNCTIONS** section) if the 587 corresponding parameter in the function definition is an array reference. 58815. **read()**: Reads a line from **stdin** and uses that as an expression. The 589 result of that expression is the result of the **read()** operand. This is a 590 **non-portable extension**. 59116. **maxibase()**: The max allowable **ibase**. This is a **non-portable 592 extension**. 59317. **maxobase()**: The max allowable **obase**. This is a **non-portable 594 extension**. 59518. **maxscale()**: The max allowable **scale**. This is a **non-portable 596 extension**. 59719. **line_length()**: The line length set with **BC_LINE_LENGTH** (see the 598 **ENVIRONMENT VARIABLES** section). This is a **non-portable extension**. 59920. **global_stacks()**: **0** if global stacks are not enabled with the **-g** 600 or **-\-global-stacks** options, non-zero otherwise. See the **OPTIONS** 601 section. This is a **non-portable extension**. 60221. **leading_zero()**: **0** if leading zeroes are not enabled with the **-z** 603 or **--leading-zeroes** options, non-zero otherwise. See the **OPTIONS** 604 section. This is a **non-portable extension**. 60522. **rand()**: A pseudo-random integer between **0** (inclusive) and 606 **BC_RAND_MAX** (inclusive). Using this operand will change the value of 607 **seed**. This is a **non-portable extension**. 60823. **irand(E)**: A pseudo-random integer between **0** (inclusive) and the 609 value of **E** (exclusive). If **E** is negative or is a non-integer 610 (**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see 611 the **RESET** section) while **seed** remains unchanged. If **E** is larger 612 than **BC_RAND_MAX**, the higher bound is honored by generating several 613 pseudo-random integers, multiplying them by appropriate powers of 614 **BC_RAND_MAX+1**, and adding them together. Thus, the size of integer that 615 can be generated with this operand is unbounded. Using this operand will 616 change the value of **seed**, unless the value of **E** is **0** or **1**. 617 In that case, **0** is returned, and **seed** is *not* changed. This is a 618 **non-portable extension**. 61924. **maxrand()**: The max integer returned by **rand()**. This is a 620 **non-portable extension**. 621 622The integers generated by **rand()** and **irand(E)** are guaranteed to be as 623unbiased as possible, subject to the limitations of the pseudo-random number 624generator. 625 626**Note**: The values returned by the pseudo-random number generator with 627**rand()** and **irand(E)** are guaranteed to *NOT* be cryptographically secure. 628This is a consequence of using a seeded pseudo-random number generator. However, 629they *are* guaranteed to be reproducible with identical **seed** values. This 630means that the pseudo-random values from bc(1) should only be used where a 631reproducible stream of pseudo-random numbers is *ESSENTIAL*. In any other case, 632use a non-seeded pseudo-random number generator. 633 634## Numbers 635 636Numbers are strings made up of digits, uppercase letters, and at most **1** 637period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase 638letters are equal to **9** plus their position in the alphabet, starting from 639**1** (i.e., **A** equals **10**, or **9+1**). 640 641If a digit or letter makes no sense with the current value of **ibase** (i.e., 642they are greater than or equal to the current value of **ibase**), then the 643behavior depends on the existence of the **-c**/**-\-digit-clamp** or 644**-C**/**-\-no-digit-clamp** options (see the **OPTIONS** section), the 645existence and setting of the **BC_DIGIT_CLAMP** environment variable (see the 646**ENVIRONMENT VARIABLES** section), or the default, which can be queried with 647the **-h**/**-\-help** option. 648 649If clamping is off, then digits or letters that are greater than or equal to the 650current value of **ibase** are not changed. Instead, their given value is 651multiplied by the appropriate power of **ibase** and added into the number. This 652means that, with an **ibase** of **3**, the number **AB** is equal to 653**3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or **41**. 654 655If clamping is on, then digits or letters that are greater than or equal to the 656current value of **ibase** are set to the value of the highest valid digit in 657**ibase** before being multiplied by the appropriate power of **ibase** and 658added into the number. This means that, with an **ibase** of **3**, the number 659**AB** is equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus **2**, 660or **8**. 661 662There is one exception to clamping: single-character numbers (i.e., **A** 663alone). Such numbers are never clamped and always take the value they would have 664in the highest possible **ibase**. This means that **A** alone always equals 665decimal **10** and **Z** alone always equals decimal **35**. This behavior is 666mandated by the standard (see the STANDARDS section) and is meant to provide an 667easy way to set the current **ibase** (with the **i** command) regardless of the 668current value of **ibase**. 669 670If clamping is on, and the clamped value of a character is needed, use a leading 671zero, i.e., for **A**, use **0A**. 672 673In addition, bc(1) accepts numbers in scientific notation. These have the form 674**\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be 675an integer. An example is **1.89237e9**, which is equal to **1892370000**. 676Negative exponents are also allowed, so **4.2890e-3** is equal to **0.0042890**. 677 678Using scientific notation is an error or warning if the **-s** or **-w**, 679respectively, command-line options (or equivalents) are given. 680 681**WARNING**: Both the number and the exponent in scientific notation are 682interpreted according to the current **ibase**, but the number is still 683multiplied by **10\^exponent** regardless of the current **ibase**. For example, 684if **ibase** is **16** and bc(1) is given the number string **FFeA**, the 685resulting decimal number will be **2550000000000**, and if bc(1) is given the 686number string **10e-4**, the resulting decimal number will be **0.0016**. 687 688Accepting input as scientific notation is a **non-portable extension**. 689 690## Operators 691 692The following arithmetic and logical operators can be used. They are listed in 693order of decreasing precedence. Operators in the same group have the same 694precedence. 695 696**++** **-\-** 697 698: Type: Prefix and Postfix 699 700 Associativity: None 701 702 Description: **increment**, **decrement** 703 704**-** **!** 705 706: Type: Prefix 707 708 Associativity: None 709 710 Description: **negation**, **boolean not** 711 712**\$** 713 714: Type: Postfix 715 716 Associativity: None 717 718 Description: **truncation** 719 720**\@** 721 722: Type: Binary 723 724 Associativity: Right 725 726 Description: **set precision** 727 728**\^** 729 730: Type: Binary 731 732 Associativity: Right 733 734 Description: **power** 735 736**\*** **/** **%** 737 738: Type: Binary 739 740 Associativity: Left 741 742 Description: **multiply**, **divide**, **modulus** 743 744**+** **-** 745 746: Type: Binary 747 748 Associativity: Left 749 750 Description: **add**, **subtract** 751 752**\<\<** **\>\>** 753 754: Type: Binary 755 756 Associativity: Left 757 758 Description: **shift left**, **shift right** 759 760**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 761 762: Type: Binary 763 764 Associativity: Right 765 766 Description: **assignment** 767 768**==** **\<=** **\>=** **!=** **\<** **\>** 769 770: Type: Binary 771 772 Associativity: Left 773 774 Description: **relational** 775 776**&&** 777 778: Type: Binary 779 780 Associativity: Left 781 782 Description: **boolean and** 783 784**||** 785 786: Type: Binary 787 788 Associativity: Left 789 790 Description: **boolean or** 791 792The operators will be described in more detail below. 793 794**++** **-\-** 795 796: The prefix and postfix **increment** and **decrement** operators behave 797 exactly like they would in C. They require a named expression (see the 798 *Named Expressions* subsection) as an operand. 799 800 The prefix versions of these operators are more efficient; use them where 801 possible. 802 803**-** 804 805: The **negation** operator returns **0** if a user attempts to negate any 806 expression with the value **0**. Otherwise, a copy of the expression with 807 its sign flipped is returned. 808 809**!** 810 811: The **boolean not** operator returns **1** if the expression is **0**, or 812 **0** otherwise. 813 814 **Warning**: This operator has a **different precedence** than the 815 equivalent operator in GNU bc(1) and other bc(1) implementations! 816 817 This is a **non-portable extension**. 818 819**\$** 820 821: The **truncation** operator returns a copy of the given expression with all 822 of its *scale* removed. 823 824 This is a **non-portable extension**. 825 826**\@** 827 828: The **set precision** operator takes two expressions and returns a copy of 829 the first with its *scale* equal to the value of the second expression. That 830 could either mean that the number is returned without change (if the 831 *scale* of the first expression matches the value of the second 832 expression), extended (if it is less), or truncated (if it is more). 833 834 The second expression must be an integer (no *scale*) and non-negative. 835 836 This is a **non-portable extension**. 837 838**\^** 839 840: The **power** operator (not the **exclusive or** operator, as it would be in 841 C) takes two expressions and raises the first to the power of the value of 842 the second. The *scale* of the result is equal to **scale**. 843 844 The second expression must be an integer (no *scale*), and if it is 845 negative, the first value must be non-zero. 846 847**\*** 848 849: The **multiply** operator takes two expressions, multiplies them, and 850 returns the product. If **a** is the *scale* of the first expression and 851 **b** is the *scale* of the second expression, the *scale* of the result is 852 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return 853 the obvious values. 854 855**/** 856 857: The **divide** operator takes two expressions, divides them, and returns the 858 quotient. The *scale* of the result shall be the value of **scale**. 859 860 The second expression must be non-zero. 861 862**%** 863 864: The **modulus** operator takes two expressions, **a** and **b**, and 865 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the 866 result of step 1 to calculate **a-(a/b)\*b** to *scale* 867 **max(scale+scale(b),scale(a))**. 868 869 The second expression must be non-zero. 870 871**+** 872 873: The **add** operator takes two expressions, **a** and **b**, and returns the 874 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. 875 876**-** 877 878: The **subtract** operator takes two expressions, **a** and **b**, and 879 returns the difference, with a *scale* equal to the max of the *scale*s of 880 **a** and **b**. 881 882**\<\<** 883 884: The **left shift** operator takes two expressions, **a** and **b**, and 885 returns a copy of the value of **a** with its decimal point moved **b** 886 places to the right. 887 888 The second expression must be an integer (no *scale*) and non-negative. 889 890 This is a **non-portable extension**. 891 892**\>\>** 893 894: The **right shift** operator takes two expressions, **a** and **b**, and 895 returns a copy of the value of **a** with its decimal point moved **b** 896 places to the left. 897 898 The second expression must be an integer (no *scale*) and non-negative. 899 900 This is a **non-portable extension**. 901 902**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 903 904: The **assignment** operators take two expressions, **a** and **b** where 905 **a** is a named expression (see the *Named Expressions* subsection). 906 907 For **=**, **b** is copied and the result is assigned to **a**. For all 908 others, **a** and **b** are applied as operands to the corresponding 909 arithmetic operator and the result is assigned to **a**. 910 911 The **assignment** operators that correspond to operators that are 912 extensions are themselves **non-portable extensions**. 913 914**==** **\<=** **\>=** **!=** **\<** **\>** 915 916: The **relational** operators compare two expressions, **a** and **b**, and 917 if the relation holds, according to C language semantics, the result is 918 **1**. Otherwise, it is **0**. 919 920 Note that unlike in C, these operators have a lower precedence than the 921 **assignment** operators, which means that **a=b\>c** is interpreted as 922 **(a=b)\>c**. 923 924 Also, unlike the standard (see the **STANDARDS** section) requires, these 925 operators can appear anywhere any other expressions can be used. This 926 allowance is a **non-portable extension**. 927 928**&&** 929 930: The **boolean and** operator takes two expressions and returns **1** if both 931 expressions are non-zero, **0** otherwise. 932 933 This is *not* a short-circuit operator. 934 935 This is a **non-portable extension**. 936 937**||** 938 939: The **boolean or** operator takes two expressions and returns **1** if one 940 of the expressions is non-zero, **0** otherwise. 941 942 This is *not* a short-circuit operator. 943 944 This is a **non-portable extension**. 945 946## Statements 947 948The following items are statements: 949 9501. **E** 9512. **{** **S** **;** ... **;** **S** **}** 9523. **if** **(** **E** **)** **S** 9534. **if** **(** **E** **)** **S** **else** **S** 9545. **while** **(** **E** **)** **S** 9556. **for** **(** **E** **;** **E** **;** **E** **)** **S** 9567. An empty statement 9578. **break** 9589. **continue** 95910. **quit** 96011. **halt** 96112. **limits** 96213. A string of characters, enclosed in double quotes 96314. **print** **E** **,** ... **,** **E** 96415. **stream** **E** **,** ... **,** **E** 96516. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 966 a **void** function (see the *Void Functions* subsection of the 967 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 968 **I[]**, which will automatically be turned into array references (see the 969 *Array References* subsection of the **FUNCTIONS** section) if the 970 corresponding parameter in the function definition is an array reference. 971 972Numbers 4, 9, 11, 12, 14, 15, and 16 are **non-portable extensions**. 973 974Also, as a **non-portable extension**, any or all of the expressions in the 975header of a for loop may be omitted. If the condition (second expression) is 976omitted, it is assumed to be a constant **1**. 977 978The **break** statement causes a loop to stop iterating and resume execution 979immediately following a loop. This is only allowed in loops. 980 981The **continue** statement causes a loop iteration to stop early and returns to 982the start of the loop, including testing the loop condition. This is only 983allowed in loops. 984 985The **if** **else** statement does the same thing as in C. 986 987The **quit** statement causes bc(1) to quit, even if it is on a branch that will 988not be executed (it is a compile-time command). 989 990**Warning**: The behavior of this bc(1) on **quit** is slightly different from 991other bc(1) implementations. Other bc(1) implementations will exit as soon as 992they finish parsing the line that a **quit** command is on. This bc(1) will 993execute any completed and executable statements that occur before the **quit** 994statement before exiting. 995 996In other words, for the bc(1) code below: 997 998 for (i = 0; i < 3; ++i) i; quit 999 1000Other bc(1) implementations will print nothing, and this bc(1) will print **0**, 1001**1**, and **2** on successive lines before exiting. 1002 1003The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** 1004if it is on a branch of an **if** statement that is not executed, bc(1) does not 1005quit.) 1006 1007The **limits** statement prints the limits that this bc(1) is subject to. This 1008is like the **quit** statement in that it is a compile-time command. 1009 1010An expression by itself is evaluated and printed, followed by a newline. 1011 1012Both scientific notation and engineering notation are available for printing the 1013results of expressions. Scientific notation is activated by assigning **0** to 1014**obase**, and engineering notation is activated by assigning **1** to 1015**obase**. To deactivate them, just assign a different value to **obase**. 1016 1017Scientific notation and engineering notation are disabled if bc(1) is run with 1018either the **-s** or **-w** command-line options (or equivalents). 1019 1020Printing numbers in scientific notation and/or engineering notation is a 1021**non-portable extension**. 1022 1023## Strings 1024 1025If strings appear as a statement by themselves, they are printed without a 1026trailing newline. 1027 1028In addition to appearing as a lone statement by themselves, strings can be 1029assigned to variables and array elements. They can also be passed to functions 1030in variable parameters. 1031 1032If any statement that expects a string is given a variable that had a string 1033assigned to it, the statement acts as though it had received a string. 1034 1035If any math operation is attempted on a string or a variable or array element 1036that has been assigned a string, an error is raised, and bc(1) resets (see the 1037**RESET** section). 1038 1039Assigning strings to variables and array elements and passing them to functions 1040are **non-portable extensions**. 1041 1042## Print Statement 1043 1044The "expressions" in a **print** statement may also be strings. If they are, there 1045are backslash escape sequences that are interpreted specially. What those 1046sequences are, and what they cause to be printed, are shown below: 1047 1048**\\a**: **\\a** 1049 1050**\\b**: **\\b** 1051 1052**\\\\**: **\\** 1053 1054**\\e**: **\\** 1055 1056**\\f**: **\\f** 1057 1058**\\n**: **\\n** 1059 1060**\\q**: **"** 1061 1062**\\r**: **\\r** 1063 1064**\\t**: **\\t** 1065 1066Any other character following a backslash causes the backslash and character to 1067be printed as-is. 1068 1069Any non-string expression in a print statement shall be assigned to **last**, 1070like any other expression that is printed. 1071 1072## Stream Statement 1073 1074The expressions in a **stream** statement may also be strings. 1075 1076If a **stream** statement is given a string, it prints the string as though the 1077string had appeared as its own statement. In other words, the **stream** 1078statement prints strings normally, without a newline. 1079 1080If a **stream** statement is given a number, a copy of it is truncated and its 1081absolute value is calculated. The result is then printed as though **obase** is 1082**256** and each digit is interpreted as an 8-bit ASCII character, making it a 1083byte stream. 1084 1085## Order of Evaluation 1086 1087All expressions in a statment are evaluated left to right, except as necessary 1088to maintain order of operations. This means, for example, assuming that **i** is 1089equal to **0**, in the expression 1090 1091 a[i++] = i++ 1092 1093the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** 1094at the end of the expression. 1095 1096This includes function arguments. Thus, assuming **i** is equal to **0**, this 1097means that in the expression 1098 1099 x(i++, i++) 1100 1101the first argument passed to **x()** is **0**, and the second argument is **1**, 1102while **i** is equal to **2** before the function starts executing. 1103 1104# FUNCTIONS 1105 1106Function definitions are as follows: 1107 1108``` 1109define I(I,...,I){ 1110 auto I,...,I 1111 S;...;S 1112 return(E) 1113} 1114``` 1115 1116Any **I** in the parameter list or **auto** list may be replaced with **I[]** to 1117make a parameter or **auto** var an array, and any **I** in the parameter list 1118may be replaced with **\*I[]** to make a parameter an array reference. Callers 1119of functions that take array references should not put an asterisk in the call; 1120they must be called with just **I[]** like normal array parameters and will be 1121automatically converted into references. 1122 1123As a **non-portable extension**, the opening brace of a **define** statement may 1124appear on the next line. 1125 1126As a **non-portable extension**, the return statement may also be in one of the 1127following forms: 1128 11291. **return** 11302. **return** **(** **)** 11313. **return** **E** 1132 1133The first two, or not specifying a **return** statement, is equivalent to 1134**return (0)**, unless the function is a **void** function (see the *Void 1135Functions* subsection below). 1136 1137## Void Functions 1138 1139Functions can also be **void** functions, defined as follows: 1140 1141``` 1142define void I(I,...,I){ 1143 auto I,...,I 1144 S;...;S 1145 return 1146} 1147``` 1148 1149They can only be used as standalone expressions, where such an expression would 1150be printed alone, except in a print statement. 1151 1152Void functions can only use the first two **return** statements listed above. 1153They can also omit the return statement entirely. 1154 1155The word "void" is not treated as a keyword; it is still possible to have 1156variables, arrays, and functions named **void**. The word "void" is only 1157treated specially right after the **define** keyword. 1158 1159This is a **non-portable extension**. 1160 1161## Array References 1162 1163For any array in the parameter list, if the array is declared in the form 1164 1165``` 1166*I[] 1167``` 1168 1169it is a **reference**. Any changes to the array in the function are reflected, 1170when the function returns, to the array that was passed in. 1171 1172Other than this, all function arguments are passed by value. 1173 1174This is a **non-portable extension**. 1175 1176# LIBRARY 1177 1178All of the functions below, including the functions in the extended math 1179library (see the *Extended Library* subsection below), are available when the 1180**-l** or **-\-mathlib** command-line flags are given, except that the extended 1181math library is not available when the **-s** option, the **-w** option, or 1182equivalents are given. 1183 1184## Standard Library 1185 1186The standard (see the **STANDARDS** section) defines the following functions for 1187the math library: 1188 1189**s(x)** 1190 1191: Returns the sine of **x**, which is assumed to be in radians. 1192 1193 This is a transcendental function (see the *Transcendental Functions* 1194 subsection below). 1195 1196**c(x)** 1197 1198: Returns the cosine of **x**, which is assumed to be in radians. 1199 1200 This is a transcendental function (see the *Transcendental Functions* 1201 subsection below). 1202 1203**a(x)** 1204 1205: Returns the arctangent of **x**, in radians. 1206 1207 This is a transcendental function (see the *Transcendental Functions* 1208 subsection below). 1209 1210**l(x)** 1211 1212: Returns the natural logarithm of **x**. 1213 1214 This is a transcendental function (see the *Transcendental Functions* 1215 subsection below). 1216 1217**e(x)** 1218 1219: Returns the mathematical constant **e** raised to the power of **x**. 1220 1221 This is a transcendental function (see the *Transcendental Functions* 1222 subsection below). 1223 1224**j(x, n)** 1225 1226: Returns the bessel integer order **n** (truncated) of **x**. 1227 1228 This is a transcendental function (see the *Transcendental Functions* 1229 subsection below). 1230 1231## Extended Library 1232 1233The extended library is *not* loaded when the **-s**/**-\-standard** or 1234**-w**/**-\-warn** options are given since they are not part of the library 1235defined by the standard (see the **STANDARDS** section). 1236 1237The extended library is a **non-portable extension**. 1238 1239**p(x, y)** 1240 1241: Calculates **x** to the power of **y**, even if **y** is not an integer, and 1242 returns the result to the current **scale**. 1243 1244 It is an error if **y** is negative and **x** is **0**. 1245 1246 This is a transcendental function (see the *Transcendental Functions* 1247 subsection below). 1248 1249**r(x, p)** 1250 1251: Returns **x** rounded to **p** decimal places according to the rounding mode 1252 round half away from **0** 1253 (https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero). 1254 1255**ceil(x, p)** 1256 1257: Returns **x** rounded to **p** decimal places according to the rounding mode 1258 round away from **0** 1259 (https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero). 1260 1261**f(x)** 1262 1263: Returns the factorial of the truncated absolute value of **x**. 1264 1265**max(a, b)** 1266 1267: Returns **a** if **a** is greater than **b**; otherwise, returns **b**. 1268 1269**min(a, b)** 1270 1271: Returns **a** if **a** is less than **b**; otherwise, returns **b**. 1272 1273**perm(n, k)** 1274 1275: Returns the permutation of the truncated absolute value of **n** of the 1276 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1277 1278**comb(n, k)** 1279 1280: Returns the combination of the truncated absolute value of **n** of the 1281 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1282 1283**fib(n)** 1284 1285: Returns the Fibonacci number of the truncated absolute value of **n**. 1286 1287**l2(x)** 1288 1289: Returns the logarithm base **2** of **x**. 1290 1291 This is a transcendental function (see the *Transcendental Functions* 1292 subsection below). 1293 1294**l10(x)** 1295 1296: Returns the logarithm base **10** of **x**. 1297 1298 This is a transcendental function (see the *Transcendental Functions* 1299 subsection below). 1300 1301**log(x, b)** 1302 1303: Returns the logarithm base **b** of **x**. 1304 1305 This is a transcendental function (see the *Transcendental Functions* 1306 subsection below). 1307 1308**cbrt(x)** 1309 1310: Returns the cube root of **x**. 1311 1312**root(x, n)** 1313 1314: Calculates the truncated value of **n**, **r**, and returns the **r**th root 1315 of **x** to the current **scale**. 1316 1317 If **r** is **0** or negative, this raises an error and causes bc(1) to 1318 reset (see the **RESET** section). It also raises an error and causes bc(1) 1319 to reset if **r** is even and **x** is negative. 1320 1321**gcd(a, b)** 1322 1323: Returns the greatest common divisor (factor) of the truncated absolute value 1324 of **a** and the truncated absolute value of **b**. 1325 1326**lcm(a, b)** 1327 1328: Returns the least common multiple of the truncated absolute value of **a** 1329 and the truncated absolute value of **b**. 1330 1331**pi(p)** 1332 1333: Returns **pi** to **p** decimal places. 1334 1335 This is a transcendental function (see the *Transcendental Functions* 1336 subsection below). 1337 1338**t(x)** 1339 1340: Returns the tangent of **x**, which is assumed to be in radians. 1341 1342 This is a transcendental function (see the *Transcendental Functions* 1343 subsection below). 1344 1345**a2(y, x)** 1346 1347: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1348 equal to **0**, it raises an error and causes bc(1) to reset (see the 1349 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1350 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1351 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1352 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1353 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1354 **0**, and **y** is less than **0**, it returns **-pi/2**. 1355 1356 This function is the same as the **atan2()** function in many programming 1357 languages. 1358 1359 This is a transcendental function (see the *Transcendental Functions* 1360 subsection below). 1361 1362**sin(x)** 1363 1364: Returns the sine of **x**, which is assumed to be in radians. 1365 1366 This is an alias of **s(x)**. 1367 1368 This is a transcendental function (see the *Transcendental Functions* 1369 subsection below). 1370 1371**cos(x)** 1372 1373: Returns the cosine of **x**, which is assumed to be in radians. 1374 1375 This is an alias of **c(x)**. 1376 1377 This is a transcendental function (see the *Transcendental Functions* 1378 subsection below). 1379 1380**tan(x)** 1381 1382: Returns the tangent of **x**, which is assumed to be in radians. 1383 1384 If **x** is equal to **1** or **-1**, this raises an error and causes bc(1) 1385 to reset (see the **RESET** section). 1386 1387 This is an alias of **t(x)**. 1388 1389 This is a transcendental function (see the *Transcendental Functions* 1390 subsection below). 1391 1392**atan(x)** 1393 1394: Returns the arctangent of **x**, in radians. 1395 1396 This is an alias of **a(x)**. 1397 1398 This is a transcendental function (see the *Transcendental Functions* 1399 subsection below). 1400 1401**atan2(y, x)** 1402 1403: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1404 equal to **0**, it raises an error and causes bc(1) to reset (see the 1405 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1406 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1407 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1408 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1409 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1410 **0**, and **y** is less than **0**, it returns **-pi/2**. 1411 1412 This function is the same as the **atan2()** function in many programming 1413 languages. 1414 1415 This is an alias of **a2(y, x)**. 1416 1417 This is a transcendental function (see the *Transcendental Functions* 1418 subsection below). 1419 1420**r2d(x)** 1421 1422: Converts **x** from radians to degrees and returns the result. 1423 1424 This is a transcendental function (see the *Transcendental Functions* 1425 subsection below). 1426 1427**d2r(x)** 1428 1429: Converts **x** from degrees to radians and returns the result. 1430 1431 This is a transcendental function (see the *Transcendental Functions* 1432 subsection below). 1433 1434**frand(p)** 1435 1436: Generates a pseudo-random number between **0** (inclusive) and **1** 1437 (exclusive) with the number of decimal digits after the decimal point equal 1438 to the truncated absolute value of **p**. If **p** is not **0**, then 1439 calling this function will change the value of **seed**. If **p** is **0**, 1440 then **0** is returned, and **seed** is *not* changed. 1441 1442**ifrand(i, p)** 1443 1444: Generates a pseudo-random number that is between **0** (inclusive) and the 1445 truncated absolute value of **i** (exclusive) with the number of decimal 1446 digits after the decimal point equal to the truncated absolute value of 1447 **p**. If the absolute value of **i** is greater than or equal to **2**, and 1448 **p** is not **0**, then calling this function will change the value of 1449 **seed**; otherwise, **0** is returned, and **seed** is not changed. 1450 1451**i2rand(a, b)** 1452 1453: Takes the truncated value of **a** and **b** and uses them as inclusive 1454 bounds to enerate a pseudo-random integer. If the difference of the 1455 truncated values of **a** and **b** is **0**, then the truncated value is 1456 returned, and **seed** is *not* changed. Otherwise, this function will 1457 change the value of **seed**. 1458 1459**srand(x)** 1460 1461: Returns **x** with its sign flipped with probability **0.5**. In other 1462 words, it randomizes the sign of **x**. 1463 1464**brand()** 1465 1466: Returns a random boolean value (either **0** or **1**). 1467 1468**band(a, b)** 1469 1470: Takes the truncated absolute value of both **a** and **b** and calculates 1471 and returns the result of the bitwise **and** operation between them. 1472 1473 If you want to use signed two's complement arguments, use **s2u(x)** to 1474 convert. 1475 1476**bor(a, b)** 1477 1478: Takes the truncated absolute value of both **a** and **b** and calculates 1479 and returns the result of the bitwise **or** operation between them. 1480 1481 If you want to use signed two's complement arguments, use **s2u(x)** to 1482 convert. 1483 1484**bxor(a, b)** 1485 1486: Takes the truncated absolute value of both **a** and **b** and calculates 1487 and returns the result of the bitwise **xor** operation between them. 1488 1489 If you want to use signed two's complement arguments, use **s2u(x)** to 1490 convert. 1491 1492**bshl(a, b)** 1493 1494: Takes the truncated absolute value of both **a** and **b** and calculates 1495 and returns the result of **a** bit-shifted left by **b** places. 1496 1497 If you want to use signed two's complement arguments, use **s2u(x)** to 1498 convert. 1499 1500**bshr(a, b)** 1501 1502: Takes the truncated absolute value of both **a** and **b** and calculates 1503 and returns the truncated result of **a** bit-shifted right by **b** places. 1504 1505 If you want to use signed two's complement arguments, use **s2u(x)** to 1506 convert. 1507 1508**bnotn(x, n)** 1509 1510: Takes the truncated absolute value of **x** and does a bitwise not as though 1511 it has the same number of bytes as the truncated absolute value of **n**. 1512 1513 If you want to a use signed two's complement argument, use **s2u(x)** to 1514 convert. 1515 1516**bnot8(x)** 1517 1518: Does a bitwise not of the truncated absolute value of **x** as though it has 1519 **8** binary digits (**1** unsigned byte). 1520 1521 If you want to a use signed two's complement argument, use **s2u(x)** to 1522 convert. 1523 1524**bnot16(x)** 1525 1526: Does a bitwise not of the truncated absolute value of **x** as though it has 1527 **16** binary digits (**2** unsigned bytes). 1528 1529 If you want to a use signed two's complement argument, use **s2u(x)** to 1530 convert. 1531 1532**bnot32(x)** 1533 1534: Does a bitwise not of the truncated absolute value of **x** as though it has 1535 **32** binary digits (**4** unsigned bytes). 1536 1537 If you want to a use signed two's complement argument, use **s2u(x)** to 1538 convert. 1539 1540**bnot64(x)** 1541 1542: Does a bitwise not of the truncated absolute value of **x** as though it has 1543 **64** binary digits (**8** unsigned bytes). 1544 1545 If you want to a use signed two's complement argument, use **s2u(x)** to 1546 convert. 1547 1548**bnot(x)** 1549 1550: Does a bitwise not of the truncated absolute value of **x** as though it has 1551 the minimum number of power of two unsigned bytes. 1552 1553 If you want to a use signed two's complement argument, use **s2u(x)** to 1554 convert. 1555 1556**brevn(x, n)** 1557 1558: Runs a bit reversal on the truncated absolute value of **x** as though it 1559 has the same number of 8-bit bytes as the truncated absolute value of **n**. 1560 1561 If you want to a use signed two's complement argument, use **s2u(x)** to 1562 convert. 1563 1564**brev8(x)** 1565 1566: Runs a bit reversal on the truncated absolute value of **x** as though it 1567 has 8 binary digits (**1** unsigned byte). 1568 1569 If you want to a use signed two's complement argument, use **s2u(x)** to 1570 convert. 1571 1572**brev16(x)** 1573 1574: Runs a bit reversal on the truncated absolute value of **x** as though it 1575 has 16 binary digits (**2** unsigned bytes). 1576 1577 If you want to a use signed two's complement argument, use **s2u(x)** to 1578 convert. 1579 1580**brev32(x)** 1581 1582: Runs a bit reversal on the truncated absolute value of **x** as though it 1583 has 32 binary digits (**4** unsigned bytes). 1584 1585 If you want to a use signed two's complement argument, use **s2u(x)** to 1586 convert. 1587 1588**brev64(x)** 1589 1590: Runs a bit reversal on the truncated absolute value of **x** as though it 1591 has 64 binary digits (**8** unsigned bytes). 1592 1593 If you want to a use signed two's complement argument, use **s2u(x)** to 1594 convert. 1595 1596**brev(x)** 1597 1598: Runs a bit reversal on the truncated absolute value of **x** as though it 1599 has the minimum number of power of two unsigned bytes. 1600 1601 If you want to a use signed two's complement argument, use **s2u(x)** to 1602 convert. 1603 1604**broln(x, p, n)** 1605 1606: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1607 though it has the same number of unsigned 8-bit bytes as the truncated 1608 absolute value of **n**, by the number of places equal to the truncated 1609 absolute value of **p** modded by the **2** to the power of the number of 1610 binary digits in **n** 8-bit bytes. 1611 1612 If you want to a use signed two's complement argument, use **s2u(x)** to 1613 convert. 1614 1615**brol8(x, p)** 1616 1617: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1618 though it has **8** binary digits (**1** unsigned byte), by the number of 1619 places equal to the truncated absolute value of **p** modded by **2** to the 1620 power of **8**. 1621 1622 If you want to a use signed two's complement argument, use **s2u(x)** to 1623 convert. 1624 1625**brol16(x, p)** 1626 1627: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1628 though it has **16** binary digits (**2** unsigned bytes), by the number of 1629 places equal to the truncated absolute value of **p** modded by **2** to the 1630 power of **16**. 1631 1632 If you want to a use signed two's complement argument, use **s2u(x)** to 1633 convert. 1634 1635**brol32(x, p)** 1636 1637: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1638 though it has **32** binary digits (**4** unsigned bytes), by the number of 1639 places equal to the truncated absolute value of **p** modded by **2** to the 1640 power of **32**. 1641 1642 If you want to a use signed two's complement argument, use **s2u(x)** to 1643 convert. 1644 1645**brol64(x, p)** 1646 1647: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1648 though it has **64** binary digits (**8** unsigned bytes), by the number of 1649 places equal to the truncated absolute value of **p** modded by **2** to the 1650 power of **64**. 1651 1652 If you want to a use signed two's complement argument, use **s2u(x)** to 1653 convert. 1654 1655**brol(x, p)** 1656 1657: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1658 though it has the minimum number of power of two unsigned 8-bit bytes, by 1659 the number of places equal to the truncated absolute value of **p** modded 1660 by 2 to the power of the number of binary digits in the minimum number of 1661 8-bit bytes. 1662 1663 If you want to a use signed two's complement argument, use **s2u(x)** to 1664 convert. 1665 1666**brorn(x, p, n)** 1667 1668: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1669 though it has the same number of unsigned 8-bit bytes as the truncated 1670 absolute value of **n**, by the number of places equal to the truncated 1671 absolute value of **p** modded by the **2** to the power of the number of 1672 binary digits in **n** 8-bit bytes. 1673 1674 If you want to a use signed two's complement argument, use **s2u(x)** to 1675 convert. 1676 1677**bror8(x, p)** 1678 1679: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1680 though it has **8** binary digits (**1** unsigned byte), by the number of 1681 places equal to the truncated absolute value of **p** modded by **2** to the 1682 power of **8**. 1683 1684 If you want to a use signed two's complement argument, use **s2u(x)** to 1685 convert. 1686 1687**bror16(x, p)** 1688 1689: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1690 though it has **16** binary digits (**2** unsigned bytes), by the number of 1691 places equal to the truncated absolute value of **p** modded by **2** to the 1692 power of **16**. 1693 1694 If you want to a use signed two's complement argument, use **s2u(x)** to 1695 convert. 1696 1697**bror32(x, p)** 1698 1699: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1700 though it has **32** binary digits (**2** unsigned bytes), by the number of 1701 places equal to the truncated absolute value of **p** modded by **2** to the 1702 power of **32**. 1703 1704 If you want to a use signed two's complement argument, use **s2u(x)** to 1705 convert. 1706 1707**bror64(x, p)** 1708 1709: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1710 though it has **64** binary digits (**2** unsigned bytes), by the number of 1711 places equal to the truncated absolute value of **p** modded by **2** to the 1712 power of **64**. 1713 1714 If you want to a use signed two's complement argument, use **s2u(x)** to 1715 convert. 1716 1717**bror(x, p)** 1718 1719: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1720 though it has the minimum number of power of two unsigned 8-bit bytes, by 1721 the number of places equal to the truncated absolute value of **p** modded 1722 by 2 to the power of the number of binary digits in the minimum number of 1723 8-bit bytes. 1724 1725 If you want to a use signed two's complement argument, use **s2u(x)** to 1726 convert. 1727 1728**bmodn(x, n)** 1729 1730: Returns the modulus of the truncated absolute value of **x** by **2** to the 1731 power of the multiplication of the truncated absolute value of **n** and 1732 **8**. 1733 1734 If you want to a use signed two's complement argument, use **s2u(x)** to 1735 convert. 1736 1737**bmod8(x, n)** 1738 1739: Returns the modulus of the truncated absolute value of **x** by **2** to the 1740 power of **8**. 1741 1742 If you want to a use signed two's complement argument, use **s2u(x)** to 1743 convert. 1744 1745**bmod16(x, n)** 1746 1747: Returns the modulus of the truncated absolute value of **x** by **2** to the 1748 power of **16**. 1749 1750 If you want to a use signed two's complement argument, use **s2u(x)** to 1751 convert. 1752 1753**bmod32(x, n)** 1754 1755: Returns the modulus of the truncated absolute value of **x** by **2** to the 1756 power of **32**. 1757 1758 If you want to a use signed two's complement argument, use **s2u(x)** to 1759 convert. 1760 1761**bmod64(x, n)** 1762 1763: Returns the modulus of the truncated absolute value of **x** by **2** to the 1764 power of **64**. 1765 1766 If you want to a use signed two's complement argument, use **s2u(x)** to 1767 convert. 1768 1769**bunrev(t)** 1770 1771: Assumes **t** is a bitwise-reversed number with an extra set bit one place 1772 more significant than the real most significant bit (which was the least 1773 significant bit in the original number). This number is reversed and 1774 returned without the extra set bit. 1775 1776 This function is used to implement other bitwise functions; it is not meant 1777 to be used by users, but it can be. 1778 1779**plz(x)** 1780 1781: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1782 it is printed with a leading zero, regardless of the use of the **-z** 1783 option (see the **OPTIONS** section) and without a trailing newline. 1784 1785 Otherwise, **x** is printed normally, without a trailing newline. 1786 1787**plznl(x)** 1788 1789: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1790 it is printed with a leading zero, regardless of the use of the **-z** 1791 option (see the **OPTIONS** section) and with a trailing newline. 1792 1793 Otherwise, **x** is printed normally, with a trailing newline. 1794 1795**pnlz(x)** 1796 1797: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1798 it is printed without a leading zero, regardless of the use of the **-z** 1799 option (see the **OPTIONS** section) and without a trailing newline. 1800 1801 Otherwise, **x** is printed normally, without a trailing newline. 1802 1803**pnlznl(x)** 1804 1805: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1806 it is printed without a leading zero, regardless of the use of the **-z** 1807 option (see the **OPTIONS** section) and with a trailing newline. 1808 1809 Otherwise, **x** is printed normally, with a trailing newline. 1810 1811**ubytes(x)** 1812 1813: Returns the numbers of unsigned integer bytes required to hold the truncated 1814 absolute value of **x**. 1815 1816**sbytes(x)** 1817 1818: Returns the numbers of signed, two's-complement integer bytes required to 1819 hold the truncated value of **x**. 1820 1821**s2u(x)** 1822 1823: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1824 what **x** would be as a 2's-complement signed integer and returns the 1825 non-negative integer that would have the same representation in binary. 1826 1827**s2un(x,n)** 1828 1829: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1830 what **x** would be as a 2's-complement signed integer with **n** bytes and 1831 returns the non-negative integer that would have the same representation in 1832 binary. If **x** cannot fit into **n** 2's-complement signed bytes, it is 1833 truncated to fit. 1834 1835**hex(x)** 1836 1837: Outputs the hexadecimal (base **16**) representation of **x**. 1838 1839 This is a **void** function (see the *Void Functions* subsection of the 1840 **FUNCTIONS** section). 1841 1842**binary(x)** 1843 1844: Outputs the binary (base **2**) representation of **x**. 1845 1846 This is a **void** function (see the *Void Functions* subsection of the 1847 **FUNCTIONS** section). 1848 1849**output(x, b)** 1850 1851: Outputs the base **b** representation of **x**. 1852 1853 This is a **void** function (see the *Void Functions* subsection of the 1854 **FUNCTIONS** section). 1855 1856**uint(x)** 1857 1858: Outputs the representation, in binary and hexadecimal, of **x** as an 1859 unsigned integer in as few power of two bytes as possible. Both outputs are 1860 split into bytes separated by spaces. 1861 1862 If **x** is not an integer or is negative, an error message is printed 1863 instead, but bc(1) is not reset (see the **RESET** section). 1864 1865 This is a **void** function (see the *Void Functions* subsection of the 1866 **FUNCTIONS** section). 1867 1868**int(x)** 1869 1870: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1871 two's-complement integer in as few power of two bytes as possible. Both 1872 outputs are split into bytes separated by spaces. 1873 1874 If **x** is not an integer, an error message is printed instead, but bc(1) 1875 is not reset (see the **RESET** section). 1876 1877 This is a **void** function (see the *Void Functions* subsection of the 1878 **FUNCTIONS** section). 1879 1880**uintn(x, n)** 1881 1882: Outputs the representation, in binary and hexadecimal, of **x** as an 1883 unsigned integer in **n** bytes. Both outputs are split into bytes separated 1884 by spaces. 1885 1886 If **x** is not an integer, is negative, or cannot fit into **n** bytes, an 1887 error message is printed instead, but bc(1) is not reset (see the **RESET** 1888 section). 1889 1890 This is a **void** function (see the *Void Functions* subsection of the 1891 **FUNCTIONS** section). 1892 1893**intn(x, n)** 1894 1895: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1896 two's-complement integer in **n** bytes. Both outputs are split into bytes 1897 separated by spaces. 1898 1899 If **x** is not an integer or cannot fit into **n** bytes, an error message 1900 is printed instead, but bc(1) is not reset (see the **RESET** section). 1901 1902 This is a **void** function (see the *Void Functions* subsection of the 1903 **FUNCTIONS** section). 1904 1905**uint8(x)** 1906 1907: Outputs the representation, in binary and hexadecimal, of **x** as an 1908 unsigned integer in **1** byte. Both outputs are split into bytes separated 1909 by spaces. 1910 1911 If **x** is not an integer, is negative, or cannot fit into **1** byte, an 1912 error message is printed instead, but bc(1) is not reset (see the **RESET** 1913 section). 1914 1915 This is a **void** function (see the *Void Functions* subsection of the 1916 **FUNCTIONS** section). 1917 1918**int8(x)** 1919 1920: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1921 two's-complement integer in **1** byte. Both outputs are split into bytes 1922 separated by spaces. 1923 1924 If **x** is not an integer or cannot fit into **1** byte, an error message 1925 is printed instead, but bc(1) is not reset (see the **RESET** section). 1926 1927 This is a **void** function (see the *Void Functions* subsection of the 1928 **FUNCTIONS** section). 1929 1930**uint16(x)** 1931 1932: Outputs the representation, in binary and hexadecimal, of **x** as an 1933 unsigned integer in **2** bytes. Both outputs are split into bytes separated 1934 by spaces. 1935 1936 If **x** is not an integer, is negative, or cannot fit into **2** bytes, an 1937 error message is printed instead, but bc(1) is not reset (see the **RESET** 1938 section). 1939 1940 This is a **void** function (see the *Void Functions* subsection of the 1941 **FUNCTIONS** section). 1942 1943**int16(x)** 1944 1945: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1946 two's-complement integer in **2** bytes. Both outputs are split into bytes 1947 separated by spaces. 1948 1949 If **x** is not an integer or cannot fit into **2** bytes, an error message 1950 is printed instead, but bc(1) is not reset (see the **RESET** section). 1951 1952 This is a **void** function (see the *Void Functions* subsection of the 1953 **FUNCTIONS** section). 1954 1955**uint32(x)** 1956 1957: Outputs the representation, in binary and hexadecimal, of **x** as an 1958 unsigned integer in **4** bytes. Both outputs are split into bytes separated 1959 by spaces. 1960 1961 If **x** is not an integer, is negative, or cannot fit into **4** bytes, an 1962 error message is printed instead, but bc(1) is not reset (see the **RESET** 1963 section). 1964 1965 This is a **void** function (see the *Void Functions* subsection of the 1966 **FUNCTIONS** section). 1967 1968**int32(x)** 1969 1970: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1971 two's-complement integer in **4** bytes. Both outputs are split into bytes 1972 separated by spaces. 1973 1974 If **x** is not an integer or cannot fit into **4** bytes, an error message 1975 is printed instead, but bc(1) is not reset (see the **RESET** section). 1976 1977 This is a **void** function (see the *Void Functions* subsection of the 1978 **FUNCTIONS** section). 1979 1980**uint64(x)** 1981 1982: Outputs the representation, in binary and hexadecimal, of **x** as an 1983 unsigned integer in **8** bytes. Both outputs are split into bytes separated 1984 by spaces. 1985 1986 If **x** is not an integer, is negative, or cannot fit into **8** bytes, an 1987 error message is printed instead, but bc(1) is not reset (see the **RESET** 1988 section). 1989 1990 This is a **void** function (see the *Void Functions* subsection of the 1991 **FUNCTIONS** section). 1992 1993**int64(x)** 1994 1995: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1996 two's-complement integer in **8** bytes. Both outputs are split into bytes 1997 separated by spaces. 1998 1999 If **x** is not an integer or cannot fit into **8** bytes, an error message 2000 is printed instead, but bc(1) is not reset (see the **RESET** section). 2001 2002 This is a **void** function (see the *Void Functions* subsection of the 2003 **FUNCTIONS** section). 2004 2005**hex_uint(x, n)** 2006 2007: Outputs the representation of the truncated absolute value of **x** as an 2008 unsigned integer in hexadecimal using **n** bytes. Not all of the value will 2009 be output if **n** is too small. 2010 2011 This is a **void** function (see the *Void Functions* subsection of the 2012 **FUNCTIONS** section). 2013 2014**binary_uint(x, n)** 2015 2016: Outputs the representation of the truncated absolute value of **x** as an 2017 unsigned integer in binary using **n** bytes. Not all of the value will be 2018 output if **n** is too small. 2019 2020 This is a **void** function (see the *Void Functions* subsection of the 2021 **FUNCTIONS** section). 2022 2023**output_uint(x, n)** 2024 2025: Outputs the representation of the truncated absolute value of **x** as an 2026 unsigned integer in the current **obase** (see the **SYNTAX** section) using 2027 **n** bytes. Not all of the value will be output if **n** is too small. 2028 2029 This is a **void** function (see the *Void Functions* subsection of the 2030 **FUNCTIONS** section). 2031 2032**output_byte(x, i)** 2033 2034: Outputs byte **i** of the truncated absolute value of **x**, where **0** is 2035 the least significant byte and **number_of_bytes - 1** is the most 2036 significant byte. 2037 2038 This is a **void** function (see the *Void Functions* subsection of the 2039 **FUNCTIONS** section). 2040 2041## Transcendental Functions 2042 2043All transcendental functions can return slightly inaccurate results, up to 1 ULP 2044(https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and 2045the article at https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT explains 2046why it is impossible and unnecessary to calculate exact results for the 2047transcendental functions. 2048 2049Because of the possible inaccuracy, I recommend that users call those functions 2050with the precision (**scale**) set to at least 1 higher than is necessary. If 2051exact results are *absolutely* required, users can double the precision 2052(**scale**) and then truncate. 2053 2054The transcendental functions in the standard math library are: 2055 2056* **s(x)** 2057* **c(x)** 2058* **a(x)** 2059* **l(x)** 2060* **e(x)** 2061* **j(x, n)** 2062 2063The transcendental functions in the extended math library are: 2064 2065* **l2(x)** 2066* **l10(x)** 2067* **log(x, b)** 2068* **pi(p)** 2069* **t(x)** 2070* **a2(y, x)** 2071* **sin(x)** 2072* **cos(x)** 2073* **tan(x)** 2074* **atan(x)** 2075* **atan2(y, x)** 2076* **r2d(x)** 2077* **d2r(x)** 2078 2079# RESET 2080 2081When bc(1) encounters an error or a signal that it has a non-default handler 2082for, it resets. This means that several things happen. 2083 2084First, any functions that are executing are stopped and popped off the stack. 2085The behavior is not unlike that of exceptions in programming languages. Then 2086the execution point is set so that any code waiting to execute (after all 2087functions returned) is skipped. 2088 2089Thus, when bc(1) resets, it skips any remaining code waiting to be executed. 2090Then, if it is interactive mode, and the error was not a fatal error (see the 2091**EXIT STATUS** section), it asks for more input; otherwise, it exits with the 2092appropriate return code. 2093 2094Note that this reset behavior is different from the GNU bc(1), which attempts to 2095start executing the statement right after the one that caused an error. 2096 2097# PERFORMANCE 2098 2099Most bc(1) implementations use **char** types to calculate the value of **1** 2100decimal digit at a time, but that can be slow. This bc(1) does something 2101different. 2102 2103It uses large integers to calculate more than **1** decimal digit at a time. If 2104built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is 2105**64**, then each integer has **9** decimal digits. If built in an environment 2106where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 2107value (the number of decimal digits per large integer) is called 2108**BC_BASE_DIGS**. 2109 2110The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with 2111the **limits** statement. 2112 2113In addition, this bc(1) uses an even larger integer for overflow checking. This 2114integer type depends on the value of **BC_LONG_BIT**, but is always at least 2115twice as large as the integer type used to store digits. 2116 2117# LIMITS 2118 2119The following are the limits on bc(1): 2120 2121**BC_LONG_BIT** 2122 2123: The number of bits in the **long** type in the environment where bc(1) was 2124 built. This determines how many decimal digits can be stored in a single 2125 large integer (see the **PERFORMANCE** section). 2126 2127**BC_BASE_DIGS** 2128 2129: The number of decimal digits per large integer (see the **PERFORMANCE** 2130 section). Depends on **BC_LONG_BIT**. 2131 2132**BC_BASE_POW** 2133 2134: The max decimal number that each large integer can store (see 2135 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. 2136 2137**BC_OVERFLOW_MAX** 2138 2139: The max number that the overflow type (see the **PERFORMANCE** section) can 2140 hold. Depends on **BC_LONG_BIT**. 2141 2142**BC_BASE_MAX** 2143 2144: The maximum output base. Set at **BC_BASE_POW**. 2145 2146**BC_DIM_MAX** 2147 2148: The maximum size of arrays. Set at **SIZE_MAX-1**. 2149 2150**BC_SCALE_MAX** 2151 2152: The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. 2153 2154**BC_STRING_MAX** 2155 2156: The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. 2157 2158**BC_NAME_MAX** 2159 2160: The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. 2161 2162**BC_NUM_MAX** 2163 2164: The maximum length of a number (in decimal digits), which includes digits 2165 after the decimal point. Set at **BC_OVERFLOW_MAX-1**. 2166 2167**BC_RAND_MAX** 2168 2169: The maximum integer (inclusive) returned by the **rand()** operand. Set at 2170 **2\^BC_LONG_BIT-1**. 2171 2172Exponent 2173 2174: The maximum allowable exponent (positive or negative). Set at 2175 **BC_OVERFLOW_MAX**. 2176 2177Number of vars 2178 2179: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 2180 2181The actual values can be queried with the **limits** statement. 2182 2183These limits are meant to be effectively non-existent; the limits are so large 2184(at least on 64-bit machines) that there should not be any point at which they 2185become a problem. In fact, memory should be exhausted before these limits should 2186be hit. 2187 2188# ENVIRONMENT VARIABLES 2189 2190As **non-portable extensions**, bc(1) recognizes the following environment 2191variables: 2192 2193**POSIXLY_CORRECT** 2194 2195: If this variable exists (no matter the contents), bc(1) behaves as if 2196 the **-s** option was given. 2197 2198**BC_ENV_ARGS** 2199 2200: This is another way to give command-line arguments to bc(1). They should be 2201 in the same format as all other command-line arguments. These are always 2202 processed first, so any files given in **BC_ENV_ARGS** will be processed 2203 before arguments and files given on the command-line. This gives the user 2204 the ability to set up "standard" options and files to be used at every 2205 invocation. The most useful thing for such files to contain would be useful 2206 functions that the user might want every time bc(1) runs. 2207 2208 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, 2209 but it does not understand escape sequences. For example, the string 2210 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string 2211 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. 2212 2213 The quote parsing will handle either kind of quotes, **'** or **"**. Thus, 2214 if you have a file with any number of single quotes in the name, you can use 2215 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice 2216 versa if you have a file with double quotes. However, handling a file with 2217 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the 2218 complexity of the parsing, though such files are still supported on the 2219 command-line where the parsing is done by the shell. 2220 2221**BC_LINE_LENGTH** 2222 2223: If this environment variable exists and contains an integer that is greater 2224 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output 2225 lines to that length, including the backslash (**\\**). The default line 2226 length is **70**. 2227 2228 The special value of **0** will disable line length checking and print 2229 numbers without regard to line length and without backslashes and newlines. 2230 2231**BC_BANNER** 2232 2233: If this environment variable exists and contains an integer, then a non-zero 2234 value activates the copyright banner when bc(1) is in interactive mode, 2235 while zero deactivates it. 2236 2237 If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2238 then this environment variable has no effect because bc(1) does not print 2239 the banner when not in interactive mode. 2240 2241 This environment variable overrides the default, which can be queried with 2242 the **-h** or **-\-help** options. 2243 2244**BC_SIGINT_RESET** 2245 2246: If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2247 then this environment variable has no effect because bc(1) exits on 2248 **SIGINT** when not in interactive mode. 2249 2250 However, when bc(1) is in interactive mode, then if this environment 2251 variable exists and contains an integer, a non-zero value makes bc(1) reset 2252 on **SIGINT**, rather than exit, and zero makes bc(1) exit. If this 2253 environment variable exists and is *not* an integer, then bc(1) will exit on 2254 **SIGINT**. 2255 2256 This environment variable overrides the default, which can be queried with 2257 the **-h** or **-\-help** options. 2258 2259**BC_TTY_MODE** 2260 2261: If TTY mode is *not* available (see the **TTY MODE** section), then this 2262 environment variable has no effect. 2263 2264 However, when TTY mode is available, then if this environment variable 2265 exists and contains an integer, then a non-zero value makes bc(1) use TTY 2266 mode, and zero makes bc(1) not use TTY mode. 2267 2268 This environment variable overrides the default, which can be queried with 2269 the **-h** or **-\-help** options. 2270 2271**BC_PROMPT** 2272 2273: If TTY mode is *not* available (see the **TTY MODE** section), then this 2274 environment variable has no effect. 2275 2276 However, when TTY mode is available, then if this environment variable 2277 exists and contains an integer, a non-zero value makes bc(1) use a prompt, 2278 and zero or a non-integer makes bc(1) not use a prompt. If this environment 2279 variable does not exist and **BC_TTY_MODE** does, then the value of the 2280 **BC_TTY_MODE** environment variable is used. 2281 2282 This environment variable and the **BC_TTY_MODE** environment variable 2283 override the default, which can be queried with the **-h** or **-\-help** 2284 options. 2285 2286**BC_EXPR_EXIT** 2287 2288: If any expressions or expression files are given on the command-line with 2289 **-e**, **-\-expression**, **-f**, or **-\-file**, then if this environment 2290 variable exists and contains an integer, a non-zero value makes bc(1) exit 2291 after executing the expressions and expression files, and a zero value makes 2292 bc(1) not exit. 2293 2294 This environment variable overrides the default, which can be queried with 2295 the **-h** or **-\-help** options. 2296 2297**BC_DIGIT_CLAMP** 2298 2299: When parsing numbers and if this environment variable exists and contains an 2300 integer, a non-zero value makes bc(1) clamp digits that are greater than or 2301 equal to the current **ibase** so that all such digits are considered equal 2302 to the **ibase** minus 1, and a zero value disables such clamping so that 2303 those digits are always equal to their value, which is multiplied by the 2304 power of the **ibase**. 2305 2306 This never applies to single-digit numbers, as per the standard (see the 2307 **STANDARDS** section). 2308 2309 This environment variable overrides the default, which can be queried with 2310 the **-h** or **-\-help** options. 2311 2312# EXIT STATUS 2313 2314bc(1) returns the following exit statuses: 2315 2316**0** 2317 2318: No error. 2319 2320**1** 2321 2322: A math error occurred. This follows standard practice of using **1** for 2323 expected errors, since math errors will happen in the process of normal 2324 execution. 2325 2326 Math errors include divide by **0**, taking the square root of a negative 2327 number, using a negative number as a bound for the pseudo-random number 2328 generator, attempting to convert a negative number to a hardware integer, 2329 overflow when converting a number to a hardware integer, overflow when 2330 calculating the size of a number, and attempting to use a non-integer where 2331 an integer is required. 2332 2333 Converting to a hardware integer happens for the second operand of the power 2334 (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**) 2335 operators and their corresponding assignment operators. 2336 2337**2** 2338 2339: A parse error occurred. 2340 2341 Parse errors include unexpected **EOF**, using an invalid character, failing 2342 to find the end of a string or comment, using a token where it is invalid, 2343 giving an invalid expression, giving an invalid print statement, giving an 2344 invalid function definition, attempting to assign to an expression that is 2345 not a named expression (see the *Named Expressions* subsection of the 2346 **SYNTAX** section), giving an invalid **auto** list, having a duplicate 2347 **auto**/function parameter, failing to find the end of a code block, 2348 attempting to return a value from a **void** function, attempting to use a 2349 variable as a reference, and using any extensions when the option **-s** or 2350 any equivalents were given. 2351 2352**3** 2353 2354: A runtime error occurred. 2355 2356 Runtime errors include assigning an invalid number to any global (**ibase**, 2357 **obase**, or **scale**), giving a bad expression to a **read()** call, 2358 calling **read()** inside of a **read()** call, type errors, passing the 2359 wrong number of arguments to functions, attempting to call an undefined 2360 function, and attempting to use a **void** function call as a value in an 2361 expression. 2362 2363**4** 2364 2365: A fatal error occurred. 2366 2367 Fatal errors include memory allocation errors, I/O errors, failing to open 2368 files, attempting to use files that do not have only ASCII characters (bc(1) 2369 only accepts ASCII characters), attempting to open a directory as a file, 2370 and giving invalid command-line options. 2371 2372The exit status **4** is special; when a fatal error occurs, bc(1) always exits 2373and returns **4**, no matter what mode bc(1) is in. 2374 2375The other statuses will only be returned when bc(1) is not in interactive mode 2376(see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the 2377**RESET** section) and accepts more input when one of those errors occurs in 2378interactive mode. This is also the case when interactive mode is forced by the 2379**-i** flag or **-\-interactive** option. 2380 2381These exit statuses allow bc(1) to be used in shell scripting with error 2382checking, and its normal behavior can be forced by using the **-i** flag or 2383**-\-interactive** option. 2384 2385# INTERACTIVE MODE 2386 2387Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode 2388and a non-interactive mode. Interactive mode is turned on automatically when 2389both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and 2390**-\-interactive** option can turn it on in other situations. 2391 2392In interactive mode, bc(1) attempts to recover from errors (see the **RESET** 2393section), and in normal execution, flushes **stdout** as soon as execution is 2394done for the current input. bc(1) may also reset on **SIGINT** instead of exit, 2395depending on the contents of, or default for, the **BC_SIGINT_RESET** 2396environment variable (see the **ENVIRONMENT VARIABLES** section). 2397 2398# TTY MODE 2399 2400If **stdin**, **stdout**, and **stderr** are all connected to a TTY, then "TTY 2401mode" is considered to be available, and thus, bc(1) can turn on TTY mode, 2402subject to some settings. 2403 2404If there is the environment variable **BC_TTY_MODE** in the environment (see the 2405**ENVIRONMENT VARIABLES** section), then if that environment variable contains a 2406non-zero integer, bc(1) will turn on TTY mode when **stdin**, **stdout**, and 2407**stderr** are all connected to a TTY. If the **BC_TTY_MODE** environment 2408variable exists but is *not* a non-zero integer, then bc(1) will not turn TTY 2409mode on. 2410 2411If the environment variable **BC_TTY_MODE** does *not* exist, the default 2412setting is used. The default setting can be queried with the **-h** or 2413**-\-help** options. 2414 2415TTY mode is different from interactive mode because interactive mode is required 2416in the bc(1) standard (see the **STANDARDS** section), and interactive mode 2417requires only **stdin** and **stdout** to be connected to a terminal. 2418 2419## Command-Line History 2420 2421Command-line history is only enabled if TTY mode is, i.e., that **stdin**, 2422**stdout**, and **stderr** are connected to a TTY and the **BC_TTY_MODE** 2423environment variable (see the **ENVIRONMENT VARIABLES** section) and its default 2424do not disable TTY mode. See the **COMMAND LINE HISTORY** section for more 2425information. 2426 2427## Prompt 2428 2429If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it 2430can be turned on or off with an environment variable: **BC_PROMPT** (see the 2431**ENVIRONMENT VARIABLES** section). 2432 2433If the environment variable **BC_PROMPT** exists and is a non-zero integer, then 2434the prompt is turned on when **stdin**, **stdout**, and **stderr** are connected 2435to a TTY and the **-P** and **-\-no-prompt** options were not used. The read 2436prompt will be turned on under the same conditions, except that the **-R** and 2437**-\-no-read-prompt** options must also not be used. 2438 2439However, if **BC_PROMPT** does not exist, the prompt can be enabled or disabled 2440with the **BC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt** 2441options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT 2442VARIABLES** and **OPTIONS** sections for more details. 2443 2444# SIGNAL HANDLING 2445 2446Sending a **SIGINT** will cause bc(1) to do one of two things. 2447 2448If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or 2449the **BC_SIGINT_RESET** environment variable (see the **ENVIRONMENT VARIABLES** 2450section), or its default, is either not an integer or it is zero, bc(1) will 2451exit. 2452 2453However, if bc(1) is in interactive mode, and the **BC_SIGINT_RESET** or its 2454default is an integer and non-zero, then bc(1) will stop executing the current 2455input and reset (see the **RESET** section) upon receiving a **SIGINT**. 2456 2457Note that "current input" can mean one of two things. If bc(1) is processing 2458input from **stdin** in interactive mode, it will ask for more input. If bc(1) 2459is processing input from a file in interactive mode, it will stop processing the 2460file and start processing the next file, if one exists, or ask for input from 2461**stdin** if no other file exists. 2462 2463This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it 2464can seem as though bc(1) did not respond to the signal since it will immediately 2465start executing the next file. This is by design; most files that users execute 2466when interacting with bc(1) have function definitions, which are quick to parse. 2467If a file takes a long time to execute, there may be a bug in that file. The 2468rest of the files could still be executed without problem, allowing the user to 2469continue. 2470 2471**SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the 2472default handler for all other signals. The one exception is **SIGHUP**; in that 2473case, and only when bc(1) is in TTY mode (see the **TTY MODE** section), a 2474**SIGHUP** will cause bc(1) to clean up and exit. 2475 2476# COMMAND LINE HISTORY 2477 2478bc(1) supports interactive command-line editing. 2479 2480If bc(1) can be in TTY mode (see the **TTY MODE** section), history can be 2481enabled. This means that command-line history can only be enabled when 2482**stdin**, **stdout**, and **stderr** are all connected to a TTY. 2483 2484Like TTY mode itself, it can be turned on or off with the environment variable 2485**BC_TTY_MODE** (see the **ENVIRONMENT VARIABLES** section). 2486 2487If history is enabled, previous lines can be recalled and edited with the arrow 2488keys. 2489 2490**Note**: tabs are converted to 8 spaces. 2491 2492# SEE ALSO 2493 2494dc(1) 2495 2496# STANDARDS 2497 2498bc(1) is compliant with the IEEE Std 1003.1-2017 (“POSIX.1-2017”) specification 2499at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The 2500flags **-efghiqsvVw**, all long options, and the extensions noted above are 2501extensions to that specification. 2502 2503In addition, the behavior of the **quit** implements an interpretation of that 2504specification that is different from all known implementations. For more 2505information see the **Statements** subsection of the **SYNTAX** section. 2506 2507Note that the specification explicitly says that bc(1) only accepts numbers that 2508use a period (**.**) as a radix point, regardless of the value of 2509**LC_NUMERIC**. 2510 2511# BUGS 2512 2513Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit** 2514statement. 2515 2516No other bugs are known. Report bugs at https://git.gavinhoward.com/gavin/bc . 2517 2518# AUTHORS 2519 2520Gavin D. Howard <gavin@gavinhoward.com> and contributors. 2521