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