1<!--- 2 3SPDX-License-Identifier: BSD-2-Clause 4 5Copyright (c) 2018-2023 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 This is a **non-portable extension**. 885 886{{ A H N HN }} 887**\$** 888 889: The **truncation** operator returns a copy of the given expression with all 890 of its *scale* removed. 891 892 This is a **non-portable extension**. 893 894**\@** 895 896: The **set precision** operator takes two expressions and returns a copy of 897 the first with its *scale* equal to the value of the second expression. That 898 could either mean that the number is returned without change (if the 899 *scale* of the first expression matches the value of the second 900 expression), extended (if it is less), or truncated (if it is more). 901 902 The second expression must be an integer (no *scale*) and non-negative. 903 904 This is a **non-portable extension**. 905{{ end }} 906 907**\^** 908 909: The **power** operator (not the **exclusive or** operator, as it would be in 910 C) takes two expressions and raises the first to the power of the value of 911 the second. The *scale* of the result is equal to **scale**. 912 913 The second expression must be an integer (no *scale*), and if it is 914 negative, the first value must be non-zero. 915 916**\*** 917 918: The **multiply** operator takes two expressions, multiplies them, and 919 returns the product. If **a** is the *scale* of the first expression and 920 **b** is the *scale* of the second expression, the *scale* of the result is 921 equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return 922 the obvious values. 923 924**/** 925 926: The **divide** operator takes two expressions, divides them, and returns the 927 quotient. The *scale* of the result shall be the value of **scale**. 928 929 The second expression must be non-zero. 930 931**%** 932 933: The **modulus** operator takes two expressions, **a** and **b**, and 934 evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the 935 result of step 1 to calculate **a-(a/b)\*b** to *scale* 936 **max(scale+scale(b),scale(a))**. 937 938 The second expression must be non-zero. 939 940**+** 941 942: The **add** operator takes two expressions, **a** and **b**, and returns the 943 sum, with a *scale* equal to the max of the *scale*s of **a** and **b**. 944 945**-** 946 947: The **subtract** operator takes two expressions, **a** and **b**, and 948 returns the difference, with a *scale* equal to the max of the *scale*s of 949 **a** and **b**. 950 951{{ A H N HN }} 952**\<\<** 953 954: The **left shift** operator takes two expressions, **a** and **b**, and 955 returns a copy of the value of **a** with its decimal point moved **b** 956 places to the right. 957 958 The second expression must be an integer (no *scale*) and non-negative. 959 960 This is a **non-portable extension**. 961 962**\>\>** 963 964: The **right shift** operator takes two expressions, **a** and **b**, and 965 returns a copy of the value of **a** with its decimal point moved **b** 966 places to the left. 967 968 The second expression must be an integer (no *scale*) and non-negative. 969 970 This is a **non-portable extension**. 971{{ end }} 972 973{{ A H N HN }} 974**=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=** 975{{ end }} 976{{ E EH EN EHN }} 977**=** **+=** **-=** **\*=** **/=** **%=** **\^=** 978{{ end }} 979 980: The **assignment** operators take two expressions, **a** and **b** where 981 **a** is a named expression (see the *Named Expressions* subsection). 982 983 For **=**, **b** is copied and the result is assigned to **a**. For all 984 others, **a** and **b** are applied as operands to the corresponding 985 arithmetic operator and the result is assigned to **a**. 986 987{{ A H N HN }} 988 The **assignment** operators that correspond to operators that are 989 extensions are themselves **non-portable extensions**. 990{{ end }} 991 992**==** **\<=** **\>=** **!=** **\<** **\>** 993 994: The **relational** operators compare two expressions, **a** and **b**, and 995 if the relation holds, according to C language semantics, the result is 996 **1**. Otherwise, it is **0**. 997 998 Note that unlike in C, these operators have a lower precedence than the 999 **assignment** operators, which means that **a=b\>c** is interpreted as 1000 **(a=b)\>c**. 1001 1002 Also, unlike the standard (see the **STANDARDS** section) requires, these 1003 operators can appear anywhere any other expressions can be used. This 1004 allowance is a **non-portable extension**. 1005 1006**&&** 1007 1008: The **boolean and** operator takes two expressions and returns **1** if both 1009 expressions are non-zero, **0** otherwise. 1010 1011 This is *not* a short-circuit operator. 1012 1013 This is a **non-portable extension**. 1014 1015**||** 1016 1017: The **boolean or** operator takes two expressions and returns **1** if one 1018 of the expressions is non-zero, **0** otherwise. 1019 1020 This is *not* a short-circuit operator. 1021 1022 This is a **non-portable extension**. 1023 1024## Statements 1025 1026The following items are statements: 1027 10281. **E** 10292. **{** **S** **;** ... **;** **S** **}** 10303. **if** **(** **E** **)** **S** 10314. **if** **(** **E** **)** **S** **else** **S** 10325. **while** **(** **E** **)** **S** 10336. **for** **(** **E** **;** **E** **;** **E** **)** **S** 10347. An empty statement 10358. **break** 10369. **continue** 103710. **quit** 103811. **halt** 103912. **limits** 104013. A string of characters, enclosed in double quotes 104114. **print** **E** **,** ... **,** **E** 104215. **stream** **E** **,** ... **,** **E** 104316. **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for 1044 a **void** function (see the *Void Functions* subsection of the 1045 **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form 1046 **I[]**, which will automatically be turned into array references (see the 1047 *Array References* subsection of the **FUNCTIONS** section) if the 1048 corresponding parameter in the function definition is an array reference. 1049 1050Numbers 4, 9, 11, 12, 14, 15, and 16 are **non-portable extensions**. 1051 1052Also, as a **non-portable extension**, any or all of the expressions in the 1053header of a for loop may be omitted. If the condition (second expression) is 1054omitted, it is assumed to be a constant **1**. 1055 1056The **break** statement causes a loop to stop iterating and resume execution 1057immediately following a loop. This is only allowed in loops. 1058 1059The **continue** statement causes a loop iteration to stop early and returns to 1060the start of the loop, including testing the loop condition. This is only 1061allowed in loops. 1062 1063The **if** **else** statement does the same thing as in C. 1064 1065The **quit** statement causes bc(1) to quit, even if it is on a branch that will 1066not be executed (it is a compile-time command). 1067 1068**Warning**: The behavior of this bc(1) on **quit** is slightly different from 1069other bc(1) implementations. Other bc(1) implementations will exit as soon as 1070they finish parsing the line that a **quit** command is on. This bc(1) will 1071execute any completed and executable statements that occur before the **quit** 1072statement before exiting. 1073 1074In other words, for the bc(1) code below: 1075 1076 for (i = 0; i < 3; ++i) i; quit 1077 1078Other bc(1) implementations will print nothing, and this bc(1) will print **0**, 1079**1**, and **2** on successive lines before exiting. 1080 1081The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit** 1082if it is on a branch of an **if** statement that is not executed, bc(1) does not 1083quit.) 1084 1085The **limits** statement prints the limits that this bc(1) is subject to. This 1086is like the **quit** statement in that it is a compile-time command. 1087 1088An expression by itself is evaluated and printed, followed by a newline. 1089 1090{{ A H N HN }} 1091Both scientific notation and engineering notation are available for printing the 1092results of expressions. Scientific notation is activated by assigning **0** to 1093**obase**, and engineering notation is activated by assigning **1** to 1094**obase**. To deactivate them, just assign a different value to **obase**. 1095 1096Scientific notation and engineering notation are disabled if bc(1) is run with 1097either the **-s** or **-w** command-line options (or equivalents). 1098 1099Printing numbers in scientific notation and/or engineering notation is a 1100**non-portable extension**. 1101{{ end }} 1102 1103## Strings 1104 1105If strings appear as a statement by themselves, they are printed without a 1106trailing newline. 1107 1108In addition to appearing as a lone statement by themselves, strings can be 1109assigned to variables and array elements. They can also be passed to functions 1110in variable parameters. 1111 1112If any statement that expects a string is given a variable that had a string 1113assigned to it, the statement acts as though it had received a string. 1114 1115If any math operation is attempted on a string or a variable or array element 1116that has been assigned a string, an error is raised, and bc(1) resets (see the 1117**RESET** section). 1118 1119Assigning strings to variables and array elements and passing them to functions 1120are **non-portable extensions**. 1121 1122## Print Statement 1123 1124The "expressions" in a **print** statement may also be strings. If they are, there 1125are backslash escape sequences that are interpreted specially. What those 1126sequences are, and what they cause to be printed, are shown below: 1127 1128**\\a**: **\\a** 1129 1130**\\b**: **\\b** 1131 1132**\\\\**: **\\** 1133 1134**\\e**: **\\** 1135 1136**\\f**: **\\f** 1137 1138**\\n**: **\\n** 1139 1140**\\q**: **"** 1141 1142**\\r**: **\\r** 1143 1144**\\t**: **\\t** 1145 1146Any other character following a backslash causes the backslash and character to 1147be printed as-is. 1148 1149Any non-string expression in a print statement shall be assigned to **last**, 1150like any other expression that is printed. 1151 1152## Stream Statement 1153 1154The "expressions in a **stream** statement may also be strings. 1155 1156If a **stream** statement is given a string, it prints the string as though the 1157string had appeared as its own statement. In other words, the **stream** 1158statement prints strings normally, without a newline. 1159 1160If a **stream** statement is given a number, a copy of it is truncated and its 1161absolute value is calculated. The result is then printed as though **obase** is 1162**256** and each digit is interpreted as an 8-bit ASCII character, making it a 1163byte stream. 1164 1165## Order of Evaluation 1166 1167All expressions in a statment are evaluated left to right, except as necessary 1168to maintain order of operations. This means, for example, assuming that **i** is 1169equal to **0**, in the expression 1170 1171 a[i++] = i++ 1172 1173the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2** 1174at the end of the expression. 1175 1176This includes function arguments. Thus, assuming **i** is equal to **0**, this 1177means that in the expression 1178 1179 x(i++, i++) 1180 1181the first argument passed to **x()** is **0**, and the second argument is **1**, 1182while **i** is equal to **2** before the function starts executing. 1183 1184# FUNCTIONS 1185 1186Function definitions are as follows: 1187 1188``` 1189define I(I,...,I){ 1190 auto I,...,I 1191 S;...;S 1192 return(E) 1193} 1194``` 1195 1196Any **I** in the parameter list or **auto** list may be replaced with **I[]** to 1197make a parameter or **auto** var an array, and any **I** in the parameter list 1198may be replaced with **\*I[]** to make a parameter an array reference. Callers 1199of functions that take array references should not put an asterisk in the call; 1200they must be called with just **I[]** like normal array parameters and will be 1201automatically converted into references. 1202 1203As a **non-portable extension**, the opening brace of a **define** statement may 1204appear on the next line. 1205 1206As a **non-portable extension**, the return statement may also be in one of the 1207following forms: 1208 12091. **return** 12102. **return** **(** **)** 12113. **return** **E** 1212 1213The first two, or not specifying a **return** statement, is equivalent to 1214**return (0)**, unless the function is a **void** function (see the *Void 1215Functions* subsection below). 1216 1217## Void Functions 1218 1219Functions can also be **void** functions, defined as follows: 1220 1221``` 1222define void I(I,...,I){ 1223 auto I,...,I 1224 S;...;S 1225 return 1226} 1227``` 1228 1229They can only be used as standalone expressions, where such an expression would 1230be printed alone, except in a print statement. 1231 1232Void functions can only use the first two **return** statements listed above. 1233They can also omit the return statement entirely. 1234 1235The word "void" is not treated as a keyword; it is still possible to have 1236variables, arrays, and functions named **void**. The word "void" is only 1237treated specially right after the **define** keyword. 1238 1239This is a **non-portable extension**. 1240 1241## Array References 1242 1243For any array in the parameter list, if the array is declared in the form 1244 1245``` 1246*I[] 1247``` 1248 1249it is a **reference**. Any changes to the array in the function are reflected, 1250when the function returns, to the array that was passed in. 1251 1252Other than this, all function arguments are passed by value. 1253 1254This is a **non-portable extension**. 1255 1256# LIBRARY 1257 1258{{ A H N HN }} 1259All of the functions below, including the functions in the extended math 1260library (see the *Extended Library* subsection below), are available when the 1261**-l** or **-\-mathlib** command-line flags are given, except that the extended 1262math library is not available when the **-s** option, the **-w** option, or 1263equivalents are given. 1264{{ end }} 1265{{ E EH EN EHN }} 1266All of the functions below are available when the **-l** or **-\-mathlib** 1267command-line flags are given. 1268{{ end }} 1269 1270## Standard Library 1271 1272The standard (see the **STANDARDS** section) defines the following functions for 1273the math library: 1274 1275**s(x)** 1276 1277: Returns the sine of **x**, which is assumed to be in radians. 1278 1279 This is a transcendental function (see the *Transcendental Functions* 1280 subsection below). 1281 1282**c(x)** 1283 1284: Returns the cosine of **x**, which is assumed to be in radians. 1285 1286 This is a transcendental function (see the *Transcendental Functions* 1287 subsection below). 1288 1289**a(x)** 1290 1291: Returns the arctangent of **x**, in radians. 1292 1293 This is a transcendental function (see the *Transcendental Functions* 1294 subsection below). 1295 1296**l(x)** 1297 1298: Returns the natural logarithm of **x**. 1299 1300 This is a transcendental function (see the *Transcendental Functions* 1301 subsection below). 1302 1303**e(x)** 1304 1305: Returns the mathematical constant **e** raised to the power of **x**. 1306 1307 This is a transcendental function (see the *Transcendental Functions* 1308 subsection below). 1309 1310**j(x, n)** 1311 1312: Returns the bessel integer order **n** (truncated) of **x**. 1313 1314 This is a transcendental function (see the *Transcendental Functions* 1315 subsection below). 1316 1317{{ A H N HN }} 1318## Extended Library 1319 1320The extended library is *not* loaded when the **-s**/**-\-standard** or 1321**-w**/**-\-warn** options are given since they are not part of the library 1322defined by the standard (see the **STANDARDS** section). 1323 1324The extended library is a **non-portable extension**. 1325 1326**p(x, y)** 1327 1328: Calculates **x** to the power of **y**, even if **y** is not an integer, and 1329 returns the result to the current **scale**. 1330 1331 It is an error if **y** is negative and **x** is **0**. 1332 1333 This is a transcendental function (see the *Transcendental Functions* 1334 subsection below). 1335 1336**r(x, p)** 1337 1338: Returns **x** rounded to **p** decimal places according to the rounding mode 1339 round half away from **0** 1340 (https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero). 1341 1342**ceil(x, p)** 1343 1344: Returns **x** rounded to **p** decimal places according to the rounding mode 1345 round away from **0** 1346 (https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero). 1347 1348**f(x)** 1349 1350: Returns the factorial of the truncated absolute value of **x**. 1351 1352**perm(n, k)** 1353 1354: Returns the permutation of the truncated absolute value of **n** of the 1355 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1356 1357**comb(n, k)** 1358 1359: Returns the combination of the truncated absolute value of **n** of the 1360 truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**. 1361 1362**fib(n)** 1363 1364: Returns the Fibonacci number of the truncated absolute value of **n**. 1365 1366**l2(x)** 1367 1368: Returns the logarithm base **2** of **x**. 1369 1370 This is a transcendental function (see the *Transcendental Functions* 1371 subsection below). 1372 1373**l10(x)** 1374 1375: Returns the logarithm base **10** of **x**. 1376 1377 This is a transcendental function (see the *Transcendental Functions* 1378 subsection below). 1379 1380**log(x, b)** 1381 1382: Returns the logarithm base **b** of **x**. 1383 1384 This is a transcendental function (see the *Transcendental Functions* 1385 subsection below). 1386 1387**cbrt(x)** 1388 1389: Returns the cube root of **x**. 1390 1391**root(x, n)** 1392 1393: Calculates the truncated value of **n**, **r**, and returns the **r**th root 1394 of **x** to the current **scale**. 1395 1396 If **r** is **0** or negative, this raises an error and causes bc(1) to 1397 reset (see the **RESET** section). It also raises an error and causes bc(1) 1398 to reset if **r** is even and **x** is negative. 1399 1400**gcd(a, b)** 1401 1402: Returns the greatest common divisor (factor) of the truncated absolute value 1403 of **a** and the truncated absolute value of **b**. 1404 1405**lcm(a, b)** 1406 1407: Returns the least common multiple of the truncated absolute value of **a** 1408 and the truncated absolute value of **b**. 1409 1410**pi(p)** 1411 1412: Returns **pi** to **p** decimal places. 1413 1414 This is a transcendental function (see the *Transcendental Functions* 1415 subsection below). 1416 1417**t(x)** 1418 1419: Returns the tangent of **x**, which is assumed to be in radians. 1420 1421 This is a transcendental function (see the *Transcendental Functions* 1422 subsection below). 1423 1424**a2(y, x)** 1425 1426: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1427 equal to **0**, it raises an error and causes bc(1) to reset (see the 1428 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1429 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1430 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1431 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1432 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1433 **0**, and **y** is less than **0**, it returns **-pi/2**. 1434 1435 This function is the same as the **atan2()** function in many programming 1436 languages. 1437 1438 This is a transcendental function (see the *Transcendental Functions* 1439 subsection below). 1440 1441**sin(x)** 1442 1443: Returns the sine of **x**, which is assumed to be in radians. 1444 1445 This is an alias of **s(x)**. 1446 1447 This is a transcendental function (see the *Transcendental Functions* 1448 subsection below). 1449 1450**cos(x)** 1451 1452: Returns the cosine of **x**, which is assumed to be in radians. 1453 1454 This is an alias of **c(x)**. 1455 1456 This is a transcendental function (see the *Transcendental Functions* 1457 subsection below). 1458 1459**tan(x)** 1460 1461: Returns the tangent of **x**, which is assumed to be in radians. 1462 1463 If **x** is equal to **1** or **-1**, this raises an error and causes bc(1) 1464 to reset (see the **RESET** section). 1465 1466 This is an alias of **t(x)**. 1467 1468 This is a transcendental function (see the *Transcendental Functions* 1469 subsection below). 1470 1471**atan(x)** 1472 1473: Returns the arctangent of **x**, in radians. 1474 1475 This is an alias of **a(x)**. 1476 1477 This is a transcendental function (see the *Transcendental Functions* 1478 subsection below). 1479 1480**atan2(y, x)** 1481 1482: Returns the arctangent of **y/x**, in radians. If both **y** and **x** are 1483 equal to **0**, it raises an error and causes bc(1) to reset (see the 1484 **RESET** section). Otherwise, if **x** is greater than **0**, it returns 1485 **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal 1486 to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y** 1487 is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**, 1488 and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to 1489 **0**, and **y** is less than **0**, it returns **-pi/2**. 1490 1491 This function is the same as the **atan2()** function in many programming 1492 languages. 1493 1494 This is an alias of **a2(y, x)**. 1495 1496 This is a transcendental function (see the *Transcendental Functions* 1497 subsection below). 1498 1499**r2d(x)** 1500 1501: Converts **x** from radians to degrees and returns the result. 1502 1503 This is a transcendental function (see the *Transcendental Functions* 1504 subsection below). 1505 1506**d2r(x)** 1507 1508: Converts **x** from degrees to radians and returns the result. 1509 1510 This is a transcendental function (see the *Transcendental Functions* 1511 subsection below). 1512 1513**frand(p)** 1514 1515: Generates a pseudo-random number between **0** (inclusive) and **1** 1516 (exclusive) with the number of decimal digits after the decimal point equal 1517 to the truncated absolute value of **p**. If **p** is not **0**, then 1518 calling this function will change the value of **seed**. If **p** is **0**, 1519 then **0** is returned, and **seed** is *not* changed. 1520 1521**ifrand(i, p)** 1522 1523: Generates a pseudo-random number that is between **0** (inclusive) and the 1524 truncated absolute value of **i** (exclusive) with the number of decimal 1525 digits after the decimal point equal to the truncated absolute value of 1526 **p**. If the absolute value of **i** is greater than or equal to **2**, and 1527 **p** is not **0**, then calling this function will change the value of 1528 **seed**; otherwise, **0** is returned and **seed** is not changed. 1529 1530**srand(x)** 1531 1532: Returns **x** with its sign flipped with probability **0.5**. In other 1533 words, it randomizes the sign of **x**. 1534 1535**brand()** 1536 1537: Returns a random boolean value (either **0** or **1**). 1538 1539**band(a, b)** 1540 1541: Takes the truncated absolute value of both **a** and **b** and calculates 1542 and returns the result of the bitwise **and** operation between them. 1543 1544 If you want to use signed two's complement arguments, use **s2u(x)** to 1545 convert. 1546 1547**bor(a, b)** 1548 1549: Takes the truncated absolute value of both **a** and **b** and calculates 1550 and returns the result of the bitwise **or** operation between them. 1551 1552 If you want to use signed two's complement arguments, use **s2u(x)** to 1553 convert. 1554 1555**bxor(a, b)** 1556 1557: Takes the truncated absolute value of both **a** and **b** and calculates 1558 and returns the result of the bitwise **xor** operation between them. 1559 1560 If you want to use signed two's complement arguments, use **s2u(x)** to 1561 convert. 1562 1563**bshl(a, b)** 1564 1565: Takes the truncated absolute value of both **a** and **b** and calculates 1566 and returns the result of **a** bit-shifted left by **b** places. 1567 1568 If you want to use signed two's complement arguments, use **s2u(x)** to 1569 convert. 1570 1571**bshr(a, b)** 1572 1573: Takes the truncated absolute value of both **a** and **b** and calculates 1574 and returns the truncated result of **a** bit-shifted right by **b** places. 1575 1576 If you want to use signed two's complement arguments, use **s2u(x)** to 1577 convert. 1578 1579**bnotn(x, n)** 1580 1581: Takes the truncated absolute value of **x** and does a bitwise not as though 1582 it has the same number of bytes as the truncated absolute value of **n**. 1583 1584 If you want to a use signed two's complement argument, use **s2u(x)** to 1585 convert. 1586 1587**bnot8(x)** 1588 1589: Does a bitwise not of the truncated absolute value of **x** as though it has 1590 **8** binary digits (1 unsigned byte). 1591 1592 If you want to a use signed two's complement argument, use **s2u(x)** to 1593 convert. 1594 1595**bnot16(x)** 1596 1597: Does a bitwise not of the truncated absolute value of **x** as though it has 1598 **16** binary digits (2 unsigned bytes). 1599 1600 If you want to a use signed two's complement argument, use **s2u(x)** to 1601 convert. 1602 1603**bnot32(x)** 1604 1605: Does a bitwise not of the truncated absolute value of **x** as though it has 1606 **32** binary digits (4 unsigned bytes). 1607 1608 If you want to a use signed two's complement argument, use **s2u(x)** to 1609 convert. 1610 1611**bnot64(x)** 1612 1613: Does a bitwise not of the truncated absolute value of **x** as though it has 1614 **64** binary digits (8 unsigned bytes). 1615 1616 If you want to a use signed two's complement argument, use **s2u(x)** to 1617 convert. 1618 1619**bnot(x)** 1620 1621: Does a bitwise not of the truncated absolute value of **x** as though it has 1622 the minimum number of power of two unsigned bytes. 1623 1624 If you want to a use signed two's complement argument, use **s2u(x)** to 1625 convert. 1626 1627**brevn(x, n)** 1628 1629: Runs a bit reversal on the truncated absolute value of **x** as though it 1630 has the same number of 8-bit bytes as the truncated absolute value of **n**. 1631 1632 If you want to a use signed two's complement argument, use **s2u(x)** to 1633 convert. 1634 1635**brev8(x)** 1636 1637: Runs a bit reversal on the truncated absolute value of **x** as though it 1638 has 8 binary digits (1 unsigned byte). 1639 1640 If you want to a use signed two's complement argument, use **s2u(x)** to 1641 convert. 1642 1643**brev16(x)** 1644 1645: Runs a bit reversal on the truncated absolute value of **x** as though it 1646 has 16 binary digits (2 unsigned bytes). 1647 1648 If you want to a use signed two's complement argument, use **s2u(x)** to 1649 convert. 1650 1651**brev32(x)** 1652 1653: Runs a bit reversal on the truncated absolute value of **x** as though it 1654 has 32 binary digits (4 unsigned bytes). 1655 1656 If you want to a use signed two's complement argument, use **s2u(x)** to 1657 convert. 1658 1659**brev64(x)** 1660 1661: Runs a bit reversal on the truncated absolute value of **x** as though it 1662 has 64 binary digits (8 unsigned bytes). 1663 1664 If you want to a use signed two's complement argument, use **s2u(x)** to 1665 convert. 1666 1667**brev(x)** 1668 1669: Runs a bit reversal on the truncated absolute value of **x** as though it 1670 has the minimum number of power of two unsigned bytes. 1671 1672 If you want to a use signed two's complement argument, use **s2u(x)** to 1673 convert. 1674 1675**broln(x, p, n)** 1676 1677: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1678 though it has the same number of unsigned 8-bit bytes as the truncated 1679 absolute value of **n**, by the number of places equal to the truncated 1680 absolute value of **p** modded by the **2** to the power of the number of 1681 binary digits in **n** 8-bit bytes. 1682 1683 If you want to a use signed two's complement argument, use **s2u(x)** to 1684 convert. 1685 1686**brol8(x, p)** 1687 1688: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1689 though it has **8** binary digits (**1** unsigned byte), by the number of 1690 places equal to the truncated absolute value of **p** modded by **2** to the 1691 power of **8**. 1692 1693 If you want to a use signed two's complement argument, use **s2u(x)** to 1694 convert. 1695 1696**brol16(x, p)** 1697 1698: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1699 though it has **16** binary digits (**2** unsigned bytes), by the number of 1700 places equal to the truncated absolute value of **p** modded by **2** to the 1701 power of **16**. 1702 1703 If you want to a use signed two's complement argument, use **s2u(x)** to 1704 convert. 1705 1706**brol32(x, p)** 1707 1708: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1709 though it has **32** binary digits (**2** unsigned bytes), by the number of 1710 places equal to the truncated absolute value of **p** modded by **2** to the 1711 power of **32**. 1712 1713 If you want to a use signed two's complement argument, use **s2u(x)** to 1714 convert. 1715 1716**brol64(x, p)** 1717 1718: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1719 though it has **64** binary digits (**2** unsigned bytes), by the number of 1720 places equal to the truncated absolute value of **p** modded by **2** to the 1721 power of **64**. 1722 1723 If you want to a use signed two's complement argument, use **s2u(x)** to 1724 convert. 1725 1726**brol(x, p)** 1727 1728: Does a left bitwise rotatation of the truncated absolute value of **x**, as 1729 though it has the minimum number of power of two unsigned 8-bit bytes, by 1730 the number of places equal to the truncated absolute value of **p** modded 1731 by 2 to the power of the number of binary digits in the minimum number of 1732 8-bit bytes. 1733 1734 If you want to a use signed two's complement argument, use **s2u(x)** to 1735 convert. 1736 1737**brorn(x, p, n)** 1738 1739: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1740 though it has the same number of unsigned 8-bit bytes as the truncated 1741 absolute value of **n**, by the number of places equal to the truncated 1742 absolute value of **p** modded by the **2** to the power of the number of 1743 binary digits in **n** 8-bit bytes. 1744 1745 If you want to a use signed two's complement argument, use **s2u(x)** to 1746 convert. 1747 1748**bror8(x, p)** 1749 1750: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1751 though it has **8** binary digits (**1** unsigned byte), by the number of 1752 places equal to the truncated absolute value of **p** modded by **2** to the 1753 power of **8**. 1754 1755 If you want to a use signed two's complement argument, use **s2u(x)** to 1756 convert. 1757 1758**bror16(x, p)** 1759 1760: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1761 though it has **16** binary digits (**2** unsigned bytes), by the number of 1762 places equal to the truncated absolute value of **p** modded by **2** to the 1763 power of **16**. 1764 1765 If you want to a use signed two's complement argument, use **s2u(x)** to 1766 convert. 1767 1768**bror32(x, p)** 1769 1770: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1771 though it has **32** binary digits (**2** unsigned bytes), by the number of 1772 places equal to the truncated absolute value of **p** modded by **2** to the 1773 power of **32**. 1774 1775 If you want to a use signed two's complement argument, use **s2u(x)** to 1776 convert. 1777 1778**bror64(x, p)** 1779 1780: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1781 though it has **64** binary digits (**2** unsigned bytes), by the number of 1782 places equal to the truncated absolute value of **p** modded by **2** to the 1783 power of **64**. 1784 1785 If you want to a use signed two's complement argument, use **s2u(x)** to 1786 convert. 1787 1788**bror(x, p)** 1789 1790: Does a right bitwise rotatation of the truncated absolute value of **x**, as 1791 though it has the minimum number of power of two unsigned 8-bit bytes, by 1792 the number of places equal to the truncated absolute value of **p** modded 1793 by 2 to the power of the number of binary digits in the minimum number of 1794 8-bit bytes. 1795 1796 If you want to a use signed two's complement argument, use **s2u(x)** to 1797 convert. 1798 1799**bmodn(x, n)** 1800 1801: Returns the modulus of the truncated absolute value of **x** by **2** to the 1802 power of the multiplication of the truncated absolute value of **n** and 1803 **8**. 1804 1805 If you want to a use signed two's complement argument, use **s2u(x)** to 1806 convert. 1807 1808**bmod8(x, n)** 1809 1810: Returns the modulus of the truncated absolute value of **x** by **2** to the 1811 power of **8**. 1812 1813 If you want to a use signed two's complement argument, use **s2u(x)** to 1814 convert. 1815 1816**bmod16(x, n)** 1817 1818: Returns the modulus of the truncated absolute value of **x** by **2** to the 1819 power of **16**. 1820 1821 If you want to a use signed two's complement argument, use **s2u(x)** to 1822 convert. 1823 1824**bmod32(x, n)** 1825 1826: Returns the modulus of the truncated absolute value of **x** by **2** to the 1827 power of **32**. 1828 1829 If you want to a use signed two's complement argument, use **s2u(x)** to 1830 convert. 1831 1832**bmod64(x, n)** 1833 1834: Returns the modulus of the truncated absolute value of **x** by **2** to the 1835 power of **64**. 1836 1837 If you want to a use signed two's complement argument, use **s2u(x)** to 1838 convert. 1839 1840**bunrev(t)** 1841 1842: Assumes **t** is a bitwise-reversed number with an extra set bit one place 1843 more significant than the real most significant bit (which was the least 1844 significant bit in the original number). This number is reversed and 1845 returned without the extra set bit. 1846 1847 This function is used to implement other bitwise functions; it is not meant 1848 to be used by users, but it can be. 1849 1850**plz(x)** 1851 1852: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1853 it is printed with a leading zero, regardless of the use of the **-z** 1854 option (see the **OPTIONS** section) and without a trailing newline. 1855 1856 Otherwise, **x** is printed normally, without a trailing newline. 1857 1858**plznl(x)** 1859 1860: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1861 it is printed with a leading zero, regardless of the use of the **-z** 1862 option (see the **OPTIONS** section) and with a trailing newline. 1863 1864 Otherwise, **x** is printed normally, with a trailing newline. 1865 1866**pnlz(x)** 1867 1868: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1869 it is printed without a leading zero, regardless of the use of the **-z** 1870 option (see the **OPTIONS** section) and without a trailing newline. 1871 1872 Otherwise, **x** is printed normally, without a trailing newline. 1873 1874**pnlznl(x)** 1875 1876: If **x** is not equal to **0** and greater that **-1** and less than **1**, 1877 it is printed without a leading zero, regardless of the use of the **-z** 1878 option (see the **OPTIONS** section) and with a trailing newline. 1879 1880 Otherwise, **x** is printed normally, with a trailing newline. 1881 1882**ubytes(x)** 1883 1884: Returns the numbers of unsigned integer bytes required to hold the truncated 1885 absolute value of **x**. 1886 1887**sbytes(x)** 1888 1889: Returns the numbers of signed, two's-complement integer bytes required to 1890 hold the truncated value of **x**. 1891 1892**s2u(x)** 1893 1894: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1895 what **x** would be as a 2's-complement signed integer and returns the 1896 non-negative integer that would have the same representation in binary. 1897 1898**s2un(x,n)** 1899 1900: Returns **x** if it is non-negative. If it *is* negative, then it calculates 1901 what **x** would be as a 2's-complement signed integer with **n** bytes and 1902 returns the non-negative integer that would have the same representation in 1903 binary. If **x** cannot fit into **n** 2's-complement signed bytes, it is 1904 truncated to fit. 1905 1906**hex(x)** 1907 1908: Outputs the hexadecimal (base **16**) representation of **x**. 1909 1910 This is a **void** function (see the *Void Functions* subsection of the 1911 **FUNCTIONS** section). 1912 1913**binary(x)** 1914 1915: Outputs the binary (base **2**) representation of **x**. 1916 1917 This is a **void** function (see the *Void Functions* subsection of the 1918 **FUNCTIONS** section). 1919 1920**output(x, b)** 1921 1922: Outputs the base **b** representation of **x**. 1923 1924 This is a **void** function (see the *Void Functions* subsection of the 1925 **FUNCTIONS** section). 1926 1927**uint(x)** 1928 1929: Outputs the representation, in binary and hexadecimal, of **x** as an 1930 unsigned integer in as few power of two bytes as possible. Both outputs are 1931 split into bytes separated by spaces. 1932 1933 If **x** is not an integer or is negative, an error message is printed 1934 instead, but bc(1) is not reset (see the **RESET** section). 1935 1936 This is a **void** function (see the *Void Functions* subsection of the 1937 **FUNCTIONS** section). 1938 1939**int(x)** 1940 1941: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1942 two's-complement integer in as few power of two bytes as possible. Both 1943 outputs are split into bytes separated by spaces. 1944 1945 If **x** is not an integer, an error message is printed instead, but bc(1) 1946 is not reset (see the **RESET** section). 1947 1948 This is a **void** function (see the *Void Functions* subsection of the 1949 **FUNCTIONS** section). 1950 1951**uintn(x, n)** 1952 1953: Outputs the representation, in binary and hexadecimal, of **x** as an 1954 unsigned integer in **n** bytes. Both outputs are split into bytes separated 1955 by spaces. 1956 1957 If **x** is not an integer, is negative, or cannot fit into **n** bytes, an 1958 error message is printed instead, but bc(1) is not reset (see the **RESET** 1959 section). 1960 1961 This is a **void** function (see the *Void Functions* subsection of the 1962 **FUNCTIONS** section). 1963 1964**intn(x, n)** 1965 1966: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1967 two's-complement integer in **n** bytes. Both outputs are split into bytes 1968 separated by spaces. 1969 1970 If **x** is not an integer or cannot fit into **n** bytes, an error message 1971 is printed instead, but bc(1) is not reset (see the **RESET** section). 1972 1973 This is a **void** function (see the *Void Functions* subsection of the 1974 **FUNCTIONS** section). 1975 1976**uint8(x)** 1977 1978: Outputs the representation, in binary and hexadecimal, of **x** as an 1979 unsigned integer in **1** byte. Both outputs are split into bytes separated 1980 by spaces. 1981 1982 If **x** is not an integer, is negative, or cannot fit into **1** byte, an 1983 error message is printed instead, but bc(1) is not reset (see the **RESET** 1984 section). 1985 1986 This is a **void** function (see the *Void Functions* subsection of the 1987 **FUNCTIONS** section). 1988 1989**int8(x)** 1990 1991: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 1992 two's-complement integer in **1** byte. Both outputs are split into bytes 1993 separated by spaces. 1994 1995 If **x** is not an integer or cannot fit into **1** byte, an error message 1996 is printed instead, but bc(1) is not reset (see the **RESET** section). 1997 1998 This is a **void** function (see the *Void Functions* subsection of the 1999 **FUNCTIONS** section). 2000 2001**uint16(x)** 2002 2003: Outputs the representation, in binary and hexadecimal, of **x** as an 2004 unsigned integer in **2** bytes. Both outputs are split into bytes separated 2005 by spaces. 2006 2007 If **x** is not an integer, is negative, or cannot fit into **2** bytes, an 2008 error message is printed instead, but bc(1) is not reset (see the **RESET** 2009 section). 2010 2011 This is a **void** function (see the *Void Functions* subsection of the 2012 **FUNCTIONS** section). 2013 2014**int16(x)** 2015 2016: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 2017 two's-complement integer in **2** bytes. Both outputs are split into bytes 2018 separated by spaces. 2019 2020 If **x** is not an integer or cannot fit into **2** bytes, an error message 2021 is printed instead, but bc(1) is not reset (see the **RESET** section). 2022 2023 This is a **void** function (see the *Void Functions* subsection of the 2024 **FUNCTIONS** section). 2025 2026**uint32(x)** 2027 2028: Outputs the representation, in binary and hexadecimal, of **x** as an 2029 unsigned integer in **4** bytes. Both outputs are split into bytes separated 2030 by spaces. 2031 2032 If **x** is not an integer, is negative, or cannot fit into **4** bytes, an 2033 error message is printed instead, but bc(1) is not reset (see the **RESET** 2034 section). 2035 2036 This is a **void** function (see the *Void Functions* subsection of the 2037 **FUNCTIONS** section). 2038 2039**int32(x)** 2040 2041: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 2042 two's-complement integer in **4** bytes. Both outputs are split into bytes 2043 separated by spaces. 2044 2045 If **x** is not an integer or cannot fit into **4** bytes, an error message 2046 is printed instead, but bc(1) is not reset (see the **RESET** section). 2047 2048 This is a **void** function (see the *Void Functions* subsection of the 2049 **FUNCTIONS** section). 2050 2051**uint64(x)** 2052 2053: Outputs the representation, in binary and hexadecimal, of **x** as an 2054 unsigned integer in **8** bytes. Both outputs are split into bytes separated 2055 by spaces. 2056 2057 If **x** is not an integer, is negative, or cannot fit into **8** bytes, an 2058 error message is printed instead, but bc(1) is not reset (see the **RESET** 2059 section). 2060 2061 This is a **void** function (see the *Void Functions* subsection of the 2062 **FUNCTIONS** section). 2063 2064**int64(x)** 2065 2066: Outputs the representation, in binary and hexadecimal, of **x** as a signed, 2067 two's-complement integer in **8** bytes. Both outputs are split into bytes 2068 separated by spaces. 2069 2070 If **x** is not an integer or cannot fit into **8** bytes, an error message 2071 is printed instead, but bc(1) is not reset (see the **RESET** section). 2072 2073 This is a **void** function (see the *Void Functions* subsection of the 2074 **FUNCTIONS** section). 2075 2076**hex_uint(x, n)** 2077 2078: Outputs the representation of the truncated absolute value of **x** as an 2079 unsigned integer in hexadecimal using **n** bytes. Not all of the value will 2080 be output if **n** is too small. 2081 2082 This is a **void** function (see the *Void Functions* subsection of the 2083 **FUNCTIONS** section). 2084 2085**binary_uint(x, n)** 2086 2087: Outputs the representation of the truncated absolute value of **x** as an 2088 unsigned integer in binary using **n** bytes. Not all of the value will be 2089 output if **n** is too small. 2090 2091 This is a **void** function (see the *Void Functions* subsection of the 2092 **FUNCTIONS** section). 2093 2094**output_uint(x, n)** 2095 2096: Outputs the representation of the truncated absolute value of **x** as an 2097 unsigned integer in the current **obase** (see the **SYNTAX** section) using 2098 **n** bytes. Not all of the value will be output if **n** is too small. 2099 2100 This is a **void** function (see the *Void Functions* subsection of the 2101 **FUNCTIONS** section). 2102 2103**output_byte(x, i)** 2104 2105: Outputs byte **i** of the truncated absolute value of **x**, where **0** is 2106 the least significant byte and **number_of_bytes - 1** is the most 2107 significant byte. 2108 2109 This is a **void** function (see the *Void Functions* subsection of the 2110 **FUNCTIONS** section). 2111{{ end }} 2112 2113## Transcendental Functions 2114 2115All transcendental functions can return slightly inaccurate results, up to 1 ULP 2116(https://en.wikipedia.org/wiki/Unit_in_the_last_place). This is unavoidable, and 2117the article at https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT explains 2118why it is impossible and unnecessary to calculate exact results for the 2119transcendental functions. 2120 2121Because of the possible inaccuracy, I recommend that users call those functions 2122with the precision (**scale**) set to at least 1 higher than is necessary. If 2123exact results are *absolutely* required, users can double the precision 2124(**scale**) and then truncate. 2125 2126The transcendental functions in the standard math library are: 2127 2128* **s(x)** 2129* **c(x)** 2130* **a(x)** 2131* **l(x)** 2132* **e(x)** 2133* **j(x, n)** 2134 2135{{ A H N HN }} 2136The transcendental functions in the extended math library are: 2137 2138* **l2(x)** 2139* **l10(x)** 2140* **log(x, b)** 2141* **pi(p)** 2142* **t(x)** 2143* **a2(y, x)** 2144* **sin(x)** 2145* **cos(x)** 2146* **tan(x)** 2147* **atan(x)** 2148* **atan2(y, x)** 2149* **r2d(x)** 2150* **d2r(x)** 2151{{ end }} 2152 2153# RESET 2154 2155When bc(1) encounters an error or a signal that it has a non-default handler 2156for, it resets. This means that several things happen. 2157 2158First, any functions that are executing are stopped and popped off the stack. 2159The behavior is not unlike that of exceptions in programming languages. Then 2160the execution point is set so that any code waiting to execute (after all 2161functions returned) is skipped. 2162 2163Thus, when bc(1) resets, it skips any remaining code waiting to be executed. 2164Then, if it is interactive mode, and the error was not a fatal error (see the 2165**EXIT STATUS** section), it asks for more input; otherwise, it exits with the 2166appropriate return code. 2167 2168Note that this reset behavior is different from the GNU bc(1), which attempts to 2169start executing the statement right after the one that caused an error. 2170 2171# PERFORMANCE 2172 2173Most bc(1) implementations use **char** types to calculate the value of **1** 2174decimal digit at a time, but that can be slow. This bc(1) does something 2175different. 2176 2177It uses large integers to calculate more than **1** decimal digit at a time. If 2178built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is 2179**64**, then each integer has **9** decimal digits. If built in an environment 2180where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 2181value (the number of decimal digits per large integer) is called 2182**BC_BASE_DIGS**. 2183 2184The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with 2185the **limits** statement. 2186 2187In addition, this bc(1) uses an even larger integer for overflow checking. This 2188integer type depends on the value of **BC_LONG_BIT**, but is always at least 2189twice as large as the integer type used to store digits. 2190 2191# LIMITS 2192 2193The following are the limits on bc(1): 2194 2195**BC_LONG_BIT** 2196 2197: The number of bits in the **long** type in the environment where bc(1) was 2198 built. This determines how many decimal digits can be stored in a single 2199 large integer (see the **PERFORMANCE** section). 2200 2201**BC_BASE_DIGS** 2202 2203: The number of decimal digits per large integer (see the **PERFORMANCE** 2204 section). Depends on **BC_LONG_BIT**. 2205 2206**BC_BASE_POW** 2207 2208: The max decimal number that each large integer can store (see 2209 **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**. 2210 2211**BC_OVERFLOW_MAX** 2212 2213: The max number that the overflow type (see the **PERFORMANCE** section) can 2214 hold. Depends on **BC_LONG_BIT**. 2215 2216**BC_BASE_MAX** 2217 2218: The maximum output base. Set at **BC_BASE_POW**. 2219 2220**BC_DIM_MAX** 2221 2222: The maximum size of arrays. Set at **SIZE_MAX-1**. 2223 2224**BC_SCALE_MAX** 2225 2226: The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**. 2227 2228**BC_STRING_MAX** 2229 2230: The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**. 2231 2232**BC_NAME_MAX** 2233 2234: The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**. 2235 2236**BC_NUM_MAX** 2237 2238: The maximum length of a number (in decimal digits), which includes digits 2239 after the decimal point. Set at **BC_OVERFLOW_MAX-1**. 2240 2241{{ A H N HN }} 2242**BC_RAND_MAX** 2243 2244: The maximum integer (inclusive) returned by the **rand()** operand. Set at 2245 **2\^BC_LONG_BIT-1**. 2246{{ end }} 2247 2248Exponent 2249 2250: The maximum allowable exponent (positive or negative). Set at 2251 **BC_OVERFLOW_MAX**. 2252 2253Number of vars 2254 2255: The maximum number of vars/arrays. Set at **SIZE_MAX-1**. 2256 2257The actual values can be queried with the **limits** statement. 2258 2259These limits are meant to be effectively non-existent; the limits are so large 2260(at least on 64-bit machines) that there should not be any point at which they 2261become a problem. In fact, memory should be exhausted before these limits should 2262be hit. 2263 2264# ENVIRONMENT VARIABLES 2265 2266As **non-portable extensions**, bc(1) recognizes the following environment 2267variables: 2268 2269**POSIXLY_CORRECT** 2270 2271: If this variable exists (no matter the contents), bc(1) behaves as if 2272 the **-s** option was given. 2273 2274**BC_ENV_ARGS** 2275 2276: This is another way to give command-line arguments to bc(1). They should be 2277 in the same format as all other command-line arguments. These are always 2278 processed first, so any files given in **BC_ENV_ARGS** will be processed 2279 before arguments and files given on the command-line. This gives the user 2280 the ability to set up "standard" options and files to be used at every 2281 invocation. The most useful thing for such files to contain would be useful 2282 functions that the user might want every time bc(1) runs. 2283 2284 The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments, 2285 but it does not understand escape sequences. For example, the string 2286 **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string 2287 **"/home/gavin/some \"bc\" file.bc"** will include the backslashes. 2288 2289 The quote parsing will handle either kind of quotes, **'** or **"**. Thus, 2290 if you have a file with any number of single quotes in the name, you can use 2291 double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice 2292 versa if you have a file with double quotes. However, handling a file with 2293 both kinds of quotes in **BC_ENV_ARGS** is not supported due to the 2294 complexity of the parsing, though such files are still supported on the 2295 command-line where the parsing is done by the shell. 2296 2297**BC_LINE_LENGTH** 2298 2299: If this environment variable exists and contains an integer that is greater 2300 than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output 2301 lines to that length, including the backslash (**\\**). The default line 2302 length is **70**. 2303 2304 The special value of **0** will disable line length checking and print 2305 numbers without regard to line length and without backslashes and newlines. 2306 2307**BC_BANNER** 2308 2309: If this environment variable exists and contains an integer, then a non-zero 2310 value activates the copyright banner when bc(1) is in interactive mode, 2311 while zero deactivates it. 2312 2313 If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2314 then this environment variable has no effect because bc(1) does not print 2315 the banner when not in interactive mode. 2316 2317 This environment variable overrides the default, which can be queried with 2318 the **-h** or **-\-help** options. 2319 2320**BC_SIGINT_RESET** 2321 2322: If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), 2323 then this environment variable has no effect because bc(1) exits on 2324 **SIGINT** when not in interactive mode. 2325 2326 However, when bc(1) is in interactive mode, then if this environment 2327 variable exists and contains an integer, a non-zero value makes bc(1) reset 2328 on **SIGINT**, rather than exit, and zero makes bc(1) exit. If this 2329 environment variable exists and is *not* an integer, then bc(1) will exit on 2330 **SIGINT**. 2331 2332 This environment variable overrides the default, which can be queried with 2333 the **-h** or **-\-help** options. 2334 2335**BC_TTY_MODE** 2336 2337: If TTY mode is *not* available (see the **TTY MODE** section), then this 2338 environment variable has no effect. 2339 2340 However, when TTY mode is available, then if this environment variable 2341 exists and contains an integer, then a non-zero value makes bc(1) use TTY 2342 mode, and zero makes bc(1) not use TTY mode. 2343 2344 This environment variable overrides the default, which can be queried with 2345 the **-h** or **-\-help** options. 2346 2347**BC_PROMPT** 2348 2349: If TTY mode is *not* available (see the **TTY MODE** section), then this 2350 environment variable has no effect. 2351 2352 However, when TTY mode is available, then if this environment variable 2353 exists and contains an integer, a non-zero value makes bc(1) use a prompt, 2354 and zero or a non-integer makes bc(1) not use a prompt. If this environment 2355 variable does not exist and **BC_TTY_MODE** does, then the value of the 2356 **BC_TTY_MODE** environment variable is used. 2357 2358 This environment variable and the **BC_TTY_MODE** environment variable 2359 override the default, which can be queried with the **-h** or **-\-help** 2360 options. 2361 2362**BC_EXPR_EXIT** 2363 2364: If any expressions or expression files are given on the command-line with 2365 **-e**, **-\-expression**, **-f**, or **-\-file**, then if this environment 2366 variable exists and contains an integer, a non-zero value makes bc(1) exit 2367 after executing the expressions and expression files, and a zero value makes 2368 bc(1) not exit. 2369 2370 This environment variable overrides the default, which can be queried with 2371 the **-h** or **-\-help** options. 2372 2373**BC_DIGIT_CLAMP** 2374 2375: When parsing numbers and if this environment variable exists and contains an 2376 integer, a non-zero value makes bc(1) clamp digits that are greater than or 2377 equal to the current **ibase** so that all such digits are considered equal 2378 to the **ibase** minus 1, and a zero value disables such clamping so that 2379 those digits are always equal to their value, which is multiplied by the 2380 power of the **ibase**. 2381 2382 This never applies to single-digit numbers, as per the standard (see the 2383 **STANDARDS** section). 2384 2385 This environment variable overrides the default, which can be queried with 2386 the **-h** or **-\-help** options. 2387 2388# EXIT STATUS 2389 2390bc(1) returns the following exit statuses: 2391 2392**0** 2393 2394: No error. 2395 2396**1** 2397 2398: A math error occurred. This follows standard practice of using **1** for 2399 expected errors, since math errors will happen in the process of normal 2400 execution. 2401 2402 Math errors include divide by **0**, taking the square root of a negative 2403{{ A H N HN }} 2404 number, using a negative number as a bound for the pseudo-random number 2405 generator, attempting to convert a negative number to a hardware integer, 2406 overflow when converting a number to a hardware integer, overflow when 2407 calculating the size of a number, and attempting to use a non-integer where 2408 an integer is required. 2409 2410 Converting to a hardware integer happens for the second operand of the power 2411 (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**) 2412 operators and their corresponding assignment operators. 2413{{ end }} 2414{{ E EH EN EHN }} 2415 number, attempting to convert a negative number to a hardware integer, 2416 overflow when converting a number to a hardware integer, overflow when 2417 calculating the size of a number, and attempting to use a non-integer where 2418 an integer is required. 2419 2420 Converting to a hardware integer happens for the second operand of the power 2421 (**\^**) operator and the corresponding assignment operator. 2422{{ end }} 2423 2424**2** 2425 2426: A parse error occurred. 2427 2428 Parse errors include unexpected **EOF**, using an invalid character, failing 2429 to find the end of a string or comment, using a token where it is invalid, 2430 giving an invalid expression, giving an invalid print statement, giving an 2431 invalid function definition, attempting to assign to an expression that is 2432 not a named expression (see the *Named Expressions* subsection of the 2433 **SYNTAX** section), giving an invalid **auto** list, having a duplicate 2434 **auto**/function parameter, failing to find the end of a code block, 2435 attempting to return a value from a **void** function, attempting to use a 2436 variable as a reference, and using any extensions when the option **-s** or 2437 any equivalents were given. 2438 2439**3** 2440 2441: A runtime error occurred. 2442 2443 Runtime errors include assigning an invalid number to any global (**ibase**, 2444 **obase**, or **scale**), giving a bad expression to a **read()** call, 2445 calling **read()** inside of a **read()** call, type errors, passing the 2446 wrong number of arguments to functions, attempting to call an undefined 2447 function, and attempting to use a **void** function call as a value in an 2448 expression. 2449 2450**4** 2451 2452: A fatal error occurred. 2453 2454 Fatal errors include memory allocation errors, I/O errors, failing to open 2455 files, attempting to use files that do not have only ASCII characters (bc(1) 2456 only accepts ASCII characters), attempting to open a directory as a file, 2457 and giving invalid command-line options. 2458 2459The exit status **4** is special; when a fatal error occurs, bc(1) always exits 2460and returns **4**, no matter what mode bc(1) is in. 2461 2462The other statuses will only be returned when bc(1) is not in interactive mode 2463(see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the 2464**RESET** section) and accepts more input when one of those errors occurs in 2465interactive mode. This is also the case when interactive mode is forced by the 2466**-i** flag or **-\-interactive** option. 2467 2468These exit statuses allow bc(1) to be used in shell scripting with error 2469checking, and its normal behavior can be forced by using the **-i** flag or 2470**-\-interactive** option. 2471 2472# INTERACTIVE MODE 2473 2474Per the standard (see the **STANDARDS** section), bc(1) has an interactive mode 2475and a non-interactive mode. Interactive mode is turned on automatically when 2476both **stdin** and **stdout** are hooked to a terminal, but the **-i** flag and 2477**-\-interactive** option can turn it on in other situations. 2478 2479In interactive mode, bc(1) attempts to recover from errors (see the **RESET** 2480section), and in normal execution, flushes **stdout** as soon as execution is 2481done for the current input. bc(1) may also reset on **SIGINT** instead of exit, 2482depending on the contents of, or default for, the **BC_SIGINT_RESET** 2483environment variable (see the **ENVIRONMENT VARIABLES** section). 2484 2485# TTY MODE 2486 2487If **stdin**, **stdout**, and **stderr** are all connected to a TTY, then "TTY 2488mode" is considered to be available, and thus, bc(1) can turn on TTY mode, 2489subject to some settings. 2490 2491If there is the environment variable **BC_TTY_MODE** in the environment (see the 2492**ENVIRONMENT VARIABLES** section), then if that environment variable contains a 2493non-zero integer, bc(1) will turn on TTY mode when **stdin**, **stdout**, and 2494**stderr** are all connected to a TTY. If the **BC_TTY_MODE** environment 2495variable exists but is *not* a non-zero integer, then bc(1) will not turn TTY 2496mode on. 2497 2498If the environment variable **BC_TTY_MODE** does *not* exist, the default 2499setting is used. The default setting can be queried with the **-h** or 2500**-\-help** options. 2501 2502TTY mode is different from interactive mode because interactive mode is required 2503in the bc(1) standard (see the **STANDARDS** section), and interactive mode 2504requires only **stdin** and **stdout** to be connected to a terminal. 2505 2506{{ A E N EN }} 2507## Command-Line History 2508 2509Command-line history is only enabled if TTY mode is, i.e., that **stdin**, 2510**stdout**, and **stderr** are connected to a TTY and the **BC_TTY_MODE** 2511environment variable (see the **ENVIRONMENT VARIABLES** section) and its default 2512do not disable TTY mode. See the **COMMAND LINE HISTORY** section for more 2513information. 2514{{ end }} 2515 2516## Prompt 2517 2518If TTY mode is available, then a prompt can be enabled. Like TTY mode itself, it 2519can be turned on or off with an environment variable: **BC_PROMPT** (see the 2520**ENVIRONMENT VARIABLES** section). 2521 2522If the environment variable **BC_PROMPT** exists and is a non-zero integer, then 2523the prompt is turned on when **stdin**, **stdout**, and **stderr** are connected 2524to a TTY and the **-P** and **-\-no-prompt** options were not used. The read 2525prompt will be turned on under the same conditions, except that the **-R** and 2526**-\-no-read-prompt** options must also not be used. 2527 2528However, if **BC_PROMPT** does not exist, the prompt can be enabled or disabled 2529with the **BC_TTY_MODE** environment variable, the **-P** and **-\-no-prompt** 2530options, and the **-R** and **-\-no-read-prompt** options. See the **ENVIRONMENT 2531VARIABLES** and **OPTIONS** sections for more details. 2532 2533# SIGNAL HANDLING 2534 2535Sending a **SIGINT** will cause bc(1) to do one of two things. 2536 2537If bc(1) is not in interactive mode (see the **INTERACTIVE MODE** section), or 2538the **BC_SIGINT_RESET** environment variable (see the **ENVIRONMENT VARIABLES** 2539section), or its default, is either not an integer or it is zero, bc(1) will 2540exit. 2541 2542However, if bc(1) is in interactive mode, and the **BC_SIGINT_RESET** or its 2543default is an integer and non-zero, then bc(1) will stop executing the current 2544input and reset (see the **RESET** section) upon receiving a **SIGINT**. 2545 2546Note that "current input" can mean one of two things. If bc(1) is processing 2547input from **stdin** in interactive mode, it will ask for more input. If bc(1) 2548is processing input from a file in interactive mode, it will stop processing the 2549file and start processing the next file, if one exists, or ask for input from 2550**stdin** if no other file exists. 2551 2552This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it 2553can seem as though bc(1) did not respond to the signal since it will immediately 2554start executing the next file. This is by design; most files that users execute 2555when interacting with bc(1) have function definitions, which are quick to parse. 2556If a file takes a long time to execute, there may be a bug in that file. The 2557rest of the files could still be executed without problem, allowing the user to 2558continue. 2559 2560**SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the 2561{{ A E N EN }} 2562default handler for all other signals. The one exception is **SIGHUP**; in that 2563case, and only when bc(1) is in TTY mode (see the **TTY MODE** section), a 2564**SIGHUP** will cause bc(1) to clean up and exit. 2565{{ end }} 2566{{ H EH HN EHN }} 2567default handler for all other signals. 2568{{ end }} 2569 2570{{ A E N EN }} 2571# COMMAND LINE HISTORY 2572 2573bc(1) supports interactive command-line editing. 2574 2575If bc(1) can be in TTY mode (see the **TTY MODE** section), history can be 2576enabled. This means that command-line history can only be enabled when 2577**stdin**, **stdout**, and **stderr** are all connected to a TTY. 2578 2579Like TTY mode itself, it can be turned on or off with the environment variable 2580**BC_TTY_MODE** (see the **ENVIRONMENT VARIABLES** section). 2581 2582If history is enabled, previous lines can be recalled and edited with the arrow 2583keys. 2584 2585**Note**: tabs are converted to 8 spaces. 2586{{ end }} 2587 2588{{ A E H EH }} 2589# LOCALES 2590 2591This bc(1) ships with support for adding error messages for different locales 2592and thus, supports **LC_MESSAGES**. 2593{{ end }} 2594 2595# SEE ALSO 2596 2597dc(1) 2598 2599# STANDARDS 2600 2601bc(1) is compliant with the IEEE Std 1003.1-2017 (“POSIX.1-2017”) specification 2602at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html . The 2603flags **-efghiqsvVw**, all long options, and the extensions noted above are 2604extensions to that specification. 2605 2606In addition, the behavior of the **quit** implements an interpretation of that 2607specification that is different from all known implementations. For more 2608information see the **Statements** subsection of the **SYNTAX** section. 2609 2610Note that the specification explicitly says that bc(1) only accepts numbers that 2611use a period (**.**) as a radix point, regardless of the value of 2612**LC_NUMERIC**. 2613 2614{{ A E H EH }} 2615This bc(1) supports error messages for different locales, and thus, it supports 2616**LC_MESSAGES**. 2617{{ end }} 2618 2619# BUGS 2620 2621Before version **6.1.0**, this bc(1) had incorrect behavior for the **quit** 2622statement. 2623 2624No other bugs are known. Report bugs at https://git.gavinhoward.com/gavin/bc . 2625 2626# AUTHORS 2627 2628Gavin D. Howard <gavin@gavinhoward.com> and contributors. 2629