contrib/bc/manuals/bc/NP.1.md

   1 <!---
   2
   3 SPDX-License-Identifier: BSD-2-Clause
   4
   5 Copyright (c) 2018-2021 Gavin D. Howard and contributors.
   6
   7 Redistribution and use in source and binary forms, with or without
   8 modification, 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
  17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  21 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 POSSIBILITY OF SUCH DAMAGE.
  28
  29 -->
  30
  31 # NAME
  32
  33 bc - arbitrary-precision decimal arithmetic language and calculator
  34
  35 # SYNOPSIS
  36
  37 **bc** [**-ghilPqRsvVw**] [**-\-global-stacks**] [**-\-help**] [**-\-interactive**] [**-\-mathlib**] [**-\-no-prompt**] [**-\-no-read-prompt**] [**-\-quiet**] [**-\-standard**] [**-\-warn**] [**-\-version**] [**-e** *expr*] [**-\-expression**=*expr*...] [**-f** *file*...] [**-\-file**=*file*...] [*file*...]
  38
  39 # DESCRIPTION
  40
  41 bc(1) is an interactive processor for a language first standardized in 1991 by
  42 POSIX. (The current standard is [here][1].) The language provides unlimited
  43 precision decimal arithmetic and is somewhat C-like, but there are differences.
  44 Such differences will be noted in this document.
  45
  46 After parsing and handling options, this bc(1) reads any files given on the
  47 command line and executes them before reading from **stdin**.
  48
  49 This bc(1) is a drop-in replacement for *any* bc(1), including (and
  50 especially) the GNU bc(1). It also has many extensions and extra features beyond
  51 other implementations.
  52
  53 # OPTIONS
  54
  55 The following are the options that bc(1) accepts.
  56
  57 **-g**, **-\-global-stacks**
  58
  59 :   Turns the globals **ibase**, **obase**, **scale**, and **seed** into stacks.
  60
  61     This has the effect that a copy of the current value of all four are pushed
  62     onto a stack for every function call, as well as popped when every function
  63     returns. This means that functions can assign to any and all of those
  64     globals without worrying that the change will affect other functions.
  65     Thus, a hypothetical function named **output(x,b)** that simply printed
  66     **x** in base **b** could be written like this:
  67
  68         define void output(x, b) {
  69             obase=b
  70             x
  71         }
  72
  73     instead of like this:
  74
  75         define void output(x, b) {
  76             auto c
  77             c=obase
  78             obase=b
  79             x
  80             obase=c
  81         }
  82
  83     This makes writing functions much easier.
  84
  85     (**Note**: the function **output(x,b)** exists in the extended math library.
  86      See the **LIBRARY** section.)
  87
  88     However, since using this flag means that functions cannot set **ibase**,
  89     **obase**, **scale**, or **seed** globally, functions that are made to do so
  90     cannot work anymore. There are two possible use cases for that, and each has
  91     a solution.
  92
  93     First, if a function is called on startup to turn bc(1) into a number
  94     converter, it is possible to replace that capability with various shell
  95     aliases. Examples:
  96
  97         alias d2o="bc -e ibase=A -e obase=8"
  98         alias h2b="bc -e ibase=G -e obase=2"
  99
 100     Second, if the purpose of a function is to set **ibase**, **obase**,
 101     **scale**, or **seed** globally for any other purpose, it could be split
 102     into one to four functions (based on how many globals it sets) and each of
 103     those functions could return the desired value for a global.
 104
 105     For functions that set **seed**, the value assigned to **seed** is not
 106     propagated to parent functions. This means that the sequence of
 107     pseudo-random numbers that they see will not be the same sequence of
 108     pseudo-random numbers that any parent sees. This is only the case once
 109     **seed** has been set.
 110
 111     If a function desires to not affect the sequence of pseudo-random numbers
 112     of its parents, but wants to use the same **seed**, it can use the following
 113     line:
 114
 115         seed = seed
 116
 117     If the behavior of this option is desired for every run of bc(1), then users
 118     could make sure to define **BC_ENV_ARGS** and include this option (see the
 119     **ENVIRONMENT VARIABLES** section for more details).
 120
 121     If **-s**, **-w**, or any equivalents are used, this option is ignored.
 122
 123     This is a **non-portable extension**.
 124
 125 **-h**, **-\-help**
 126
 127 :   Prints a usage message and quits.
 128
 129 **-i**, **-\-interactive**
 130
 131 :   Forces interactive mode. (See the **INTERACTIVE MODE** section.)
 132
 133     This is a **non-portable extension**.
 134
 135 **-l**, **-\-mathlib**
 136
 137 :   Sets **scale** (see the **SYNTAX** section) to **20** and loads the included
 138     math library and the extended math library before running any code,
 139     including any expressions or files specified on the command line.
 140
 141     To learn what is in the libraries, see the **LIBRARY** section.
 142
 143 **-P**, **-\-no-prompt**
 144
 145 :   This option is a no-op.
 146
 147     This is a **non-portable extension**.
 148
 149 **-R**, **-\-no-read-prompt**
 150
 151 :   Because bc(1) was built without support for prompts, this option is a no-op.
 152
 153     This is a **non-portable extension**.
 154
 155 **-q**, **-\-quiet**
 156
 157 :   This option is for compatibility with the [GNU bc(1)][2]; it is a no-op.
 158     Without this option, GNU bc(1) prints a copyright header. This bc(1) only
 159     prints the copyright header if one or more of the **-v**, **-V**, or
 160     **-\-version** options are given.
 161
 162     This is a **non-portable extension**.
 163
 164 **-s**, **-\-standard**
 165
 166 :   Process exactly the language defined by the [standard][1] and error if any
 167     extensions are used.
 168
 169     This is a **non-portable extension**.
 170
 171 **-v**, **-V**, **-\-version**
 172
 173 :   Print the version information (copyright header) and exit.
 174
 175     This is a **non-portable extension**.
 176
 177 **-w**, **-\-warn**
 178
 179 :   Like **-s** and **-\-standard**, except that warnings (and not errors) are
 180     printed for non-standard extensions and execution continues normally.
 181
 182     This is a **non-portable extension**.
 183
 184 **-e** *expr*, **-\-expression**=*expr*
 185
 186 :   Evaluates *expr*. If multiple expressions are given, they are evaluated in
 187     order. If files are given as well (see below), the expressions and files are
 188     evaluated in the order given. This means that if a file is given before an
 189     expression, the file is read in and evaluated first.
 190
 191     If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
 192     see the **ENVIRONMENT VARIABLES** section), then after processing all
 193     expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
 194     as an argument at least once to **-f** or **-\-file**, whether on the
 195     command-line or in **BC_ENV_ARGS**. However, if any other **-e**,
 196     **-\-expression**, **-f**, or **-\-file** arguments are given after **-f-**
 197     or equivalent is given, bc(1) will give a fatal error and exit.
 198
 199     This is a **non-portable extension**.
 200
 201 **-f** *file*, **-\-file**=*file*
 202
 203 :   Reads in *file* and evaluates it, line by line, as though it were read
 204     through **stdin**. If expressions are also given (see above), the
 205     expressions are evaluated in the order given.
 206
 207     If this option is given on the command-line (i.e., not in **BC_ENV_ARGS**,
 208     see the **ENVIRONMENT VARIABLES** section), then after processing all
 209     expressions and files, bc(1) will exit, unless **-** (**stdin**) was given
 210     as an argument at least once to **-f** or **-\-file**. However, if any other
 211     **-e**, **-\-expression**, **-f**, or **-\-file** arguments are given after
 212     **-f-** or equivalent is given, bc(1) will give a fatal error and exit.
 213
 214     This is a **non-portable extension**.
 215
 216 All long options are **non-portable extensions**.
 217
 218 # STDOUT
 219
 220 Any non-error output is written to **stdout**. In addition, if history (see the
 221 **HISTORY** section) and the prompt (see the **TTY MODE** section) are enabled,
 222 both are output to **stdout**.
 223
 224 **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal
 225 error (see the **EXIT STATUS** section) if it cannot write to **stdout**, so if
 226 **stdout** is closed, as in **bc <file> >&-**, it will quit with an error. This
 227 is done so that bc(1) can report problems when **stdout** is redirected to a
 228 file.
 229
 230 If there are scripts that depend on the behavior of other bc(1) implementations,
 231 it is recommended that those scripts be changed to redirect **stdout** to
 232 **/dev/null**.
 233
 234 # STDERR
 235
 236 Any error output is written to **stderr**.
 237
 238 **Note**: Unlike other bc(1) implementations, this bc(1) will issue a fatal
 239 error (see the **EXIT STATUS** section) if it cannot write to **stderr**, so if
 240 **stderr** is closed, as in **bc <file> 2>&-**, it will quit with an error. This
 241 is done so that bc(1) can exit with an error code when **stderr** is redirected
 242 to a file.
 243
 244 If there are scripts that depend on the behavior of other bc(1) implementations,
 245 it is recommended that those scripts be changed to redirect **stderr** to
 246 **/dev/null**.
 247
 248 # SYNTAX
 249
 250 The syntax for bc(1) programs is mostly C-like, with some differences. This
 251 bc(1) follows the [POSIX standard][1], which is a much more thorough resource
 252 for the language this bc(1) accepts. This section is meant to be a summary and a
 253 listing of all the extensions to the standard.
 254
 255 In the sections below, **E** means expression, **S** means statement, and **I**
 256 means identifier.
 257
 258 Identifiers (**I**) start with a lowercase letter and can be followed by any
 259 number (up to **BC_NAME_MAX-1**) of lowercase letters (**a-z**), digits
 260 (**0-9**), and underscores (**\_**). The regex is **\[a-z\]\[a-z0-9\_\]\***.
 261 Identifiers with more than one character (letter) are a
 262 **non-portable extension**.
 263
 264 **ibase** is a global variable determining how to interpret constant numbers. It
 265 is the "input" base, or the number base used for interpreting input numbers.
 266 **ibase** is initially **10**. If the **-s** (**-\-standard**) and **-w**
 267 (**-\-warn**) flags were not given on the command line, the max allowable value
 268 for **ibase** is **36**. Otherwise, it is **16**. The min allowable value for
 269 **ibase** is **2**. The max allowable value for **ibase** can be queried in
 270 bc(1) programs with the **maxibase()** built-in function.
 271
 272 **obase** is a global variable determining how to output results. It is the
 273 "output" base, or the number base used for outputting numbers. **obase** is
 274 initially **10**. The max allowable value for **obase** is **BC_BASE_MAX** and
 275 can be queried in bc(1) programs with the **maxobase()** built-in function. The
 276 min allowable value for **obase** is **0**. If **obase** is **0**, values are
 277 output in scientific notation, and if **obase** is **1**, values are output in
 278 engineering notation. Otherwise, values are output in the specified base.
 279
 280 Outputting in scientific and engineering notations are **non-portable
 281 extensions**.
 282
 283 The *scale* of an expression is the number of digits in the result of the
 284 expression right of the decimal point, and **scale** is a global variable that
 285 sets the precision of any operations, with exceptions. **scale** is initially
 286 **0**. **scale** cannot be negative. The max allowable value for **scale** is
 287 **BC_SCALE_MAX** and can be queried in bc(1) programs with the **maxscale()**
 288 built-in function.
 289
 290 bc(1) has both *global* variables and *local* variables. All *local*
 291 variables are local to the function; they are parameters or are introduced in
 292 the **auto** list of a function (see the **FUNCTIONS** section). If a variable
 293 is accessed which is not a parameter or in the **auto** list, it is assumed to
 294 be *global*. If a parent function has a *local* variable version of a variable
 295 that a child function considers *global*, the value of that *global* variable in
 296 the child function is the value of the variable in the parent function, not the
 297 value of the actual *global* variable.
 298
 299 All of the above applies to arrays as well.
 300
 301 The value of a statement that is an expression (i.e., any of the named
 302 expressions or operands) is printed unless the lowest precedence operator is an
 303 assignment operator *and* the expression is notsurrounded by parentheses.
 304
 305 The value that is printed is also assigned to the special variable **last**. A
 306 single dot (**.**) may also be used as a synonym for **last**. These are
 307 **non-portable extensions**.
 308
 309 Either semicolons or newlines may separate statements.
 310
 311 ## Comments
 312
 313 There are two kinds of comments:
 314
 315 1.      Block comments are enclosed in **/\*** and **\*/**.
 316 2.      Line comments go from **#** until, and not including, the next newline. This
 317         is a **non-portable extension**.
 318
 319 ## Named Expressions
 320
 321 The following are named expressions in bc(1):
 322
 323 1.      Variables: **I**
 324 2.      Array Elements: **I[E]**
 325 3.      **ibase**
 326 4.      **obase**
 327 5.      **scale**
 328 6.      **seed**
 329 7.      **last** or a single dot (**.**)
 330
 331 Numbers 6 and 7 are **non-portable extensions**.
 332
 333 The meaning of **seed** is dependent on the current pseudo-random number
 334 generator but is guaranteed to not change except for new major versions.
 335
 336 The *scale* and sign of the value may be significant.
 337
 338 If a previously used **seed** value is assigned to **seed** and used again, the
 339 pseudo-random number generator is guaranteed to produce the same sequence of
 340 pseudo-random numbers as it did when the **seed** value was previously used.
 341
 342 The exact value assigned to **seed** is not guaranteed to be returned if
 343 **seed** is queried again immediately. However, if **seed** *does* return a
 344 different value, both values, when assigned to **seed**, are guaranteed to
 345 produce the same sequence of pseudo-random numbers. This means that certain
 346 values assigned to **seed** will *not* produce unique sequences of pseudo-random
 347 numbers. The value of **seed** will change after any use of the **rand()** and
 348 **irand(E)** operands (see the *Operands* subsection below), except if the
 349 parameter passed to **irand(E)** is **0**, **1**, or negative.
 350
 351 There is no limit to the length (number of significant decimal digits) or
 352 *scale* of the value that can be assigned to **seed**.
 353
 354 Variables and arrays do not interfere; users can have arrays named the same as
 355 variables. This also applies to functions (see the **FUNCTIONS** section), so a
 356 user can have a variable, array, and function that all have the same name, and
 357 they will not shadow each other, whether inside of functions or not.
 358
 359 Named expressions are required as the operand of **increment**/**decrement**
 360 operators  and as the left side of **assignment** operators (see the *Operators*
 361 subsection).
 362
 363 ## Operands
 364
 365 The following are valid operands in bc(1):
 366
 367 1.      Numbers (see the *Numbers* subsection below).
 368 2.      Array indices (**I[E]**).
 369 3.      **(E)**: The value of **E** (used to change precedence).
 370 4.      **sqrt(E)**: The square root of **E**. **E** must be non-negative.
 371 5.      **length(E)**: The number of significant decimal digits in **E**.
 372 6.      **length(I[])**: The number of elements in the array **I**. This is a
 373         **non-portable extension**.
 374 7.      **scale(E)**: The *scale* of **E**.
 375 8.      **abs(E)**: The absolute value of **E**. This is a **non-portable
 376         extension**.
 377 9.      **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
 378         a non-**void** function (see the *Void Functions* subsection of the
 379         **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
 380         **I[]**, which will automatically be turned into array references (see the
 381         *Array References* subsection of the **FUNCTIONS** section) if the
 382         corresponding parameter in the function definition is an array reference.
 383 10.     **read()**: Reads a line from **stdin** and uses that as an expression. The
 384         result of that expression is the result of the **read()** operand. This is a
 385         **non-portable extension**.
 386 11.     **maxibase()**: The max allowable **ibase**. This is a **non-portable
 387         extension**.
 388 12.     **maxobase()**: The max allowable **obase**. This is a **non-portable
 389         extension**.
 390 13.     **maxscale()**: The max allowable **scale**. This is a **non-portable
 391         extension**.
 392 14.     **rand()**: A pseudo-random integer between **0** (inclusive) and
 393         **BC_RAND_MAX** (inclusive). Using this operand will change the value of
 394         **seed**. This is a **non-portable extension**.
 395 15.     **irand(E)**: A pseudo-random integer between **0** (inclusive) and the
 396         value of **E** (exclusive). If **E** is negative or is a non-integer
 397         (**E**'s *scale* is not **0**), an error is raised, and bc(1) resets (see
 398         the **RESET** section) while **seed** remains unchanged. If **E** is larger
 399         than **BC_RAND_MAX**, the higher bound is honored by generating several
 400         pseudo-random integers, multiplying them by appropriate powers of
 401         **BC_RAND_MAX+1**, and adding them together. Thus, the size of integer that
 402         can be generated with this operand is unbounded. Using this operand will
 403         change the value of **seed**, unless the value of **E** is **0** or **1**.
 404         In that case, **0** is returned, and **seed** is *not* changed. This is a
 405         **non-portable extension**.
 406 16.     **maxrand()**: The max integer returned by **rand()**. This is a
 407         **non-portable extension**.
 408
 409 The integers generated by **rand()** and **irand(E)** are guaranteed to be as
 410 unbiased as possible, subject to the limitations of the pseudo-random number
 411 generator.
 412
 413 **Note**: The values returned by the pseudo-random number generator with
 414 **rand()** and **irand(E)** are guaranteed to *NOT* be cryptographically secure.
 415 This is a consequence of using a seeded pseudo-random number generator. However,
 416 they *are* guaranteed to be reproducible with identical **seed** values. This
 417 means that the pseudo-random values from bc(1) should only be used where a
 418 reproducible stream of pseudo-random numbers is *ESSENTIAL*. In any other case,
 419 use a non-seeded pseudo-random number generator.
 420
 421 ## Numbers
 422
 423 Numbers are strings made up of digits, uppercase letters, and at most **1**
 424 period for a radix. Numbers can have up to **BC_NUM_MAX** digits. Uppercase
 425 letters are equal to **9** + their position in the alphabet (i.e., **A** equals
 426 **10**, or **9+1**). If a digit or letter makes no sense with the current value
 427 of **ibase**, they are set to the value of the highest valid digit in **ibase**.
 428
 429 Single-character numbers (i.e., **A** alone) take the value that they would have
 430 if they were valid digits, regardless of the value of **ibase**. This means that
 431 **A** alone always equals decimal **10** and **Z** alone always equals decimal
 432 **35**.
 433
 434 In addition, bc(1) accepts numbers in scientific notation. These have the form
 435 **\<number\>e\<integer\>**. The exponent (the portion after the **e**) must be
 436 an integer. An example is **1.89237e9**, which is equal to **1892370000**.
 437 Negative exponents are also allowed, so **4.2890e-3** is equal to **0.0042890**.
 438
 439 Using scientific notation is an error or warning if the **-s** or **-w**,
 440 respectively, command-line options (or equivalents) are given.
 441
 442 **WARNING**: Both the number and the exponent in scientific notation are
 443 interpreted according to the current **ibase**, but the number is still
 444 multiplied by **10\^exponent** regardless of the current **ibase**. For example,
 445 if **ibase** is **16** and bc(1) is given the number string **FFeA**, the
 446 resulting decimal number will be **2550000000000**, and if bc(1) is given the
 447 number string **10e-4**, the resulting decimal number will be **0.0016**.
 448
 449 Accepting input as scientific notation is a **non-portable extension**.
 450
 451 ## Operators
 452
 453 The following arithmetic and logical operators can be used. They are listed in
 454 order of decreasing precedence. Operators in the same group have the same
 455 precedence.
 456
 457 **++** **-\-**
 458
 459 :   Type: Prefix and Postfix
 460
 461     Associativity: None
 462
 463     Description: **increment**, **decrement**
 464
 465 **-** **!**
 466
 467 :   Type: Prefix
 468
 469     Associativity: None
 470
 471     Description: **negation**, **boolean not**
 472
 473 **\$**
 474
 475 :   Type: Postfix
 476
 477     Associativity: None
 478
 479     Description: **truncation**
 480
 481 **\@**
 482
 483 :   Type: Binary
 484
 485     Associativity: Right
 486
 487     Description: **set precision**
 488
 489 **\^**
 490
 491 :   Type: Binary
 492
 493     Associativity: Right
 494
 495     Description: **power**
 496
 497 **\*** **/** **%**
 498
 499 :   Type: Binary
 500
 501     Associativity: Left
 502
 503     Description: **multiply**, **divide**, **modulus**
 504
 505 **+** **-**
 506
 507 :   Type: Binary
 508
 509     Associativity: Left
 510
 511     Description: **add**, **subtract**
 512
 513 **\<\<** **\>\>**
 514
 515 :   Type: Binary
 516
 517     Associativity: Left
 518
 519     Description: **shift left**, **shift right**
 520
 521 **=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=**
 522
 523 :   Type: Binary
 524
 525     Associativity: Right
 526
 527     Description: **assignment**
 528
 529 **==** **\<=** **\>=** **!=** **\<** **\>**
 530
 531 :   Type: Binary
 532
 533     Associativity: Left
 534
 535     Description: **relational**
 536
 537 **&&**
 538
 539 :   Type: Binary
 540
 541     Associativity: Left
 542
 543     Description: **boolean and**
 544
 545 **||**
 546
 547 :   Type: Binary
 548
 549     Associativity: Left
 550
 551     Description: **boolean or**
 552
 553 The operators will be described in more detail below.
 554
 555 **++** **-\-**
 556
 557 :   The prefix and postfix **increment** and **decrement** operators behave
 558     exactly like they would in C. They require a named expression (see the
 559     *Named Expressions* subsection) as an operand.
 560
 561     The prefix versions of these operators are more efficient; use them where
 562     possible.
 563
 564 **-**
 565
 566 :   The **negation** operator returns **0** if a user attempts to negate any
 567     expression with the value **0**. Otherwise, a copy of the expression with
 568     its sign flipped is returned.
 569
 570 **!**
 571
 572 :   The **boolean not** operator returns **1** if the expression is **0**, or
 573     **0** otherwise.
 574
 575     This is a **non-portable extension**.
 576
 577 **\$**
 578
 579 :   The **truncation** operator returns a copy of the given expression with all
 580     of its *scale* removed.
 581
 582     This is a **non-portable extension**.
 583
 584 **\@**
 585
 586 :   The **set precision** operator takes two expressions and returns a copy of
 587     the first with its *scale* equal to the value of the second expression. That
 588     could either mean that the number is returned without change (if the
 589     *scale* of the first expression matches the value of the second
 590     expression), extended (if it is less), or truncated (if it is more).
 591
 592     The second expression must be an integer (no *scale*) and non-negative.
 593
 594     This is a **non-portable extension**.
 595
 596 **\^**
 597
 598 :   The **power** operator (not the **exclusive or** operator, as it would be in
 599     C) takes two expressions and raises the first to the power of the value of
 600     the second. The *scale* of the result is equal to **scale**.
 601
 602     The second expression must be an integer (no *scale*), and if it is
 603     negative, the first value must be non-zero.
 604
 605 **\***
 606
 607 :   The **multiply** operator takes two expressions, multiplies them, and
 608     returns the product. If **a** is the *scale* of the first expression and
 609     **b** is the *scale* of the second expression, the *scale* of the result is
 610     equal to **min(a+b,max(scale,a,b))** where **min()** and **max()** return
 611     the obvious values.
 612
 613 **/**
 614
 615 :   The **divide** operator takes two expressions, divides them, and returns the
 616     quotient. The *scale* of the result shall be the value of **scale**.
 617
 618     The second expression must be non-zero.
 619
 620 **%**
 621
 622 :   The **modulus** operator takes two expressions, **a** and **b**, and
 623     evaluates them by 1) Computing **a/b** to current **scale** and 2) Using the
 624     result of step 1 to calculate **a-(a/b)\*b** to *scale*
 625     **max(scale+scale(b),scale(a))**.
 626
 627     The second expression must be non-zero.
 628
 629 **+**
 630
 631 :   The **add** operator takes two expressions, **a** and **b**, and returns the
 632     sum, with a *scale* equal to the max of the *scale*s of **a** and **b**.
 633
 634 **-**
 635
 636 :   The **subtract** operator takes two expressions, **a** and **b**, and
 637     returns the difference, with a *scale* equal to the max of the *scale*s of
 638     **a** and **b**.
 639
 640 **\<\<**
 641
 642 :   The **left shift** operator takes two expressions, **a** and **b**, and
 643     returns a copy of the value of **a** with its decimal point moved **b**
 644     places to the right.
 645
 646     The second expression must be an integer (no *scale*) and non-negative.
 647
 648     This is a **non-portable extension**.
 649
 650 **\>\>**
 651
 652 :   The **right shift** operator takes two expressions, **a** and **b**, and
 653     returns a copy of the value of **a** with its decimal point moved **b**
 654     places to the left.
 655
 656     The second expression must be an integer (no *scale*) and non-negative.
 657
 658     This is a **non-portable extension**.
 659
 660 **=** **\<\<=** **\>\>=** **+=** **-=** **\*=** **/=** **%=** **\^=** **\@=**
 661
 662 :   The **assignment** operators take two expressions, **a** and **b** where
 663     **a** is a named expression (see the *Named Expressions* subsection).
 664
 665     For **=**, **b** is copied and the result is assigned to **a**. For all
 666     others, **a** and **b** are applied as operands to the corresponding
 667     arithmetic operator and the result is assigned to **a**.
 668
 669     The **assignment** operators that correspond to operators that are
 670     extensions are themselves **non-portable extensions**.
 671
 672 **==** **\<=** **\>=** **!=** **\<** **\>**
 673
 674 :   The **relational** operators compare two expressions, **a** and **b**, and
 675     if the relation holds, according to C language semantics, the result is
 676     **1**. Otherwise, it is **0**.
 677
 678     Note that unlike in C, these operators have a lower precedence than the
 679     **assignment** operators, which means that **a=b\>c** is interpreted as
 680     **(a=b)\>c**.
 681
 682     Also, unlike the [standard][1] requires, these operators can appear anywhere
 683     any other expressions can be used. This allowance is a
 684     **non-portable extension**.
 685
 686 **&&**
 687
 688 :   The **boolean and** operator takes two expressions and returns **1** if both
 689     expressions are non-zero, **0** otherwise.
 690
 691     This is *not* a short-circuit operator.
 692
 693     This is a **non-portable extension**.
 694
 695 **||**
 696
 697 :   The **boolean or** operator takes two expressions and returns **1** if one
 698     of the expressions is non-zero, **0** otherwise.
 699
 700     This is *not* a short-circuit operator.
 701
 702     This is a **non-portable extension**.
 703
 704 ## Statements
 705
 706 The following items are statements:
 707
 708 1.      **E**
 709 2.      **{** **S** **;** ... **;** **S** **}**
 710 3.      **if** **(** **E** **)** **S**
 711 4.      **if** **(** **E** **)** **S** **else** **S**
 712 5.      **while** **(** **E** **)** **S**
 713 6.      **for** **(** **E** **;** **E** **;** **E** **)** **S**
 714 7.      An empty statement
 715 8.      **break**
 716 9.      **continue**
 717 10.     **quit**
 718 11.     **halt**
 719 12.     **limits**
 720 13.     A string of characters, enclosed in double quotes
 721 14.     **print** **E** **,** ... **,** **E**
 722 15.     **I()**, **I(E)**, **I(E, E)**, and so on, where **I** is an identifier for
 723         a **void** function (see the *Void Functions* subsection of the
 724         **FUNCTIONS** section). The **E** argument(s) may also be arrays of the form
 725         **I[]**, which will automatically be turned into array references (see the
 726         *Array References* subsection of the **FUNCTIONS** section) if the
 727         corresponding parameter in the function definition is an array reference.
 728
 729 Numbers 4, 9, 11, 12, 14, and 15 are **non-portable extensions**.
 730
 731 Also, as a **non-portable extension**, any or all of the expressions in the
 732 header of a for loop may be omitted. If the condition (second expression) is
 733 omitted, it is assumed to be a constant **1**.
 734
 735 The **break** statement causes a loop to stop iterating and resume execution
 736 immediately following a loop. This is only allowed in loops.
 737
 738 The **continue** statement causes a loop iteration to stop early and returns to
 739 the start of the loop, including testing the loop condition. This is only
 740 allowed in loops.
 741
 742 The **if** **else** statement does the same thing as in C.
 743
 744 The **quit** statement causes bc(1) to quit, even if it is on a branch that will
 745 not be executed (it is a compile-time command).
 746
 747 The **halt** statement causes bc(1) to quit, if it is executed. (Unlike **quit**
 748 if it is on a branch of an **if** statement that is not executed, bc(1) does not
 749 quit.)
 750
 751 The **limits** statement prints the limits that this bc(1) is subject to. This
 752 is like the **quit** statement in that it is a compile-time command.
 753
 754 An expression by itself is evaluated and printed, followed by a newline.
 755
 756 Both scientific notation and engineering notation are available for printing the
 757 results of expressions. Scientific notation is activated by assigning **0** to
 758 **obase**, and engineering notation is activated by assigning **1** to
 759 **obase**. To deactivate them, just assign a different value to **obase**.
 760
 761 Scientific notation and engineering notation are disabled if bc(1) is run with
 762 either the **-s** or **-w** command-line options (or equivalents).
 763
 764 Printing numbers in scientific notation and/or engineering notation is a
 765 **non-portable extension**.
 766
 767 ## Print Statement
 768
 769 The "expressions" in a **print** statement may also be strings. If they are, there
 770 are backslash escape sequences that are interpreted specially. What those
 771 sequences are, and what they cause to be printed, are shown below:
 772
 773 -------- -------
 774 **\\a**  **\\a**
 775 **\\b**  **\\b**
 776 **\\\\** **\\**
 777 **\\e**  **\\**
 778 **\\f**  **\\f**
 779 **\\n**  **\\n**
 780 **\\q**  **"**
 781 **\\r**  **\\r**
 782 **\\t**  **\\t**
 783 -------- -------
 784
 785 Any other character following a backslash causes the backslash and character to
 786 be printed as-is.
 787
 788 Any non-string expression in a print statement shall be assigned to **last**,
 789 like any other expression that is printed.
 790
 791 ## Order of Evaluation
 792
 793 All expressions in a statment are evaluated left to right, except as necessary
 794 to maintain order of operations. This means, for example, assuming that **i** is
 795 equal to **0**, in the expression
 796
 797     a[i++] = i++
 798
 799 the first (or 0th) element of **a** is set to **1**, and **i** is equal to **2**
 800 at the end of the expression.
 801
 802 This includes function arguments. Thus, assuming **i** is equal to **0**, this
 803 means that in the expression
 804
 805     x(i++, i++)
 806
 807 the first argument passed to **x()** is **0**, and the second argument is **1**,
 808 while **i** is equal to **2** before the function starts executing.
 809
 810 # FUNCTIONS
 811
 812 Function definitions are as follows:
 813
 814 ```
 815 define I(I,...,I){
 816         auto I,...,I
 817         S;...;S
 818         return(E)
 819 }
 820 ```
 821
 822 Any **I** in the parameter list or **auto** list may be replaced with **I[]** to
 823 make a parameter or **auto** var an array, and any **I** in the parameter list
 824 may be replaced with **\*I[]** to make a parameter an array reference. Callers
 825 of functions that take array references should not put an asterisk in the call;
 826 they must be called with just **I[]** like normal array parameters and will be
 827 automatically converted into references.
 828
 829 As a **non-portable extension**, the opening brace of a **define** statement may
 830 appear on the next line.
 831
 832 As a **non-portable extension**, the return statement may also be in one of the
 833 following forms:
 834
 835 1.      **return**
 836 2.      **return** **(** **)**
 837 3.      **return** **E**
 838
 839 The first two, or not specifying a **return** statement, is equivalent to
 840 **return (0)**, unless the function is a **void** function (see the *Void
 841 Functions* subsection below).
 842
 843 ## Void Functions
 844
 845 Functions can also be **void** functions, defined as follows:
 846
 847 ```
 848 define void I(I,...,I){
 849         auto I,...,I
 850         S;...;S
 851         return
 852 }
 853 ```
 854
 855 They can only be used as standalone expressions, where such an expression would
 856 be printed alone, except in a print statement.
 857
 858 Void functions can only use the first two **return** statements listed above.
 859 They can also omit the return statement entirely.
 860
 861 The word "void" is not treated as a keyword; it is still possible to have
 862 variables, arrays, and functions named **void**. The word "void" is only
 863 treated specially right after the **define** keyword.
 864
 865 This is a **non-portable extension**.
 866
 867 ## Array References
 868
 869 For any array in the parameter list, if the array is declared in the form
 870
 871 ```
 872 *I[]
 873 ```
 874
 875 it is a **reference**. Any changes to the array in the function are reflected,
 876 when the function returns, to the array that was passed in.
 877
 878 Other than this, all function arguments are passed by value.
 879
 880 This is a **non-portable extension**.
 881
 882 # LIBRARY
 883
 884 All of the functions below, including the functions in the extended math
 885 library (see the *Extended Library* subsection below), are available when the
 886 **-l** or **-\-mathlib** command-line flags are given, except that the extended
 887 math library is not available when the **-s** option, the **-w** option, or
 888 equivalents are given.
 889
 890 ## Standard Library
 891
 892 The [standard][1] defines the following functions for the math library:
 893
 894 **s(x)**
 895
 896 :   Returns the sine of **x**, which is assumed to be in radians.
 897
 898     This is a transcendental function (see the *Transcendental Functions*
 899     subsection below).
 900
 901 **c(x)**
 902
 903 :   Returns the cosine of **x**, which is assumed to be in radians.
 904
 905     This is a transcendental function (see the *Transcendental Functions*
 906     subsection below).
 907
 908 **a(x)**
 909
 910 :   Returns the arctangent of **x**, in radians.
 911
 912     This is a transcendental function (see the *Transcendental Functions*
 913     subsection below).
 914
 915 **l(x)**
 916
 917 :   Returns the natural logarithm of **x**.
 918
 919     This is a transcendental function (see the *Transcendental Functions*
 920     subsection below).
 921
 922 **e(x)**
 923
 924 :   Returns the mathematical constant **e** raised to the power of **x**.
 925
 926     This is a transcendental function (see the *Transcendental Functions*
 927     subsection below).
 928
 929 **j(x, n)**
 930
 931 :   Returns the bessel integer order **n** (truncated) of **x**.
 932
 933     This is a transcendental function (see the *Transcendental Functions*
 934     subsection below).
 935
 936 ## Extended Library
 937
 938 The extended library is *not* loaded when the **-s**/**-\-standard** or
 939 **-w**/**-\-warn** options are given since they are not part of the library
 940 defined by the [standard][1].
 941
 942 The extended library is a **non-portable extension**.
 943
 944 **p(x, y)**
 945
 946 :   Calculates **x** to the power of **y**, even if **y** is not an integer, and
 947     returns the result to the current **scale**.
 948
 949     It is an error if **y** is negative and **x** is **0**.
 950
 951     This is a transcendental function (see the *Transcendental Functions*
 952     subsection below).
 953
 954 **r(x, p)**
 955
 956 :   Returns **x** rounded to **p** decimal places according to the rounding mode
 957     [round half away from **0**][3].
 958
 959 **ceil(x, p)**
 960
 961 :   Returns **x** rounded to **p** decimal places according to the rounding mode
 962     [round away from **0**][6].
 963
 964 **f(x)**
 965
 966 :   Returns the factorial of the truncated absolute value of **x**.
 967
 968 **perm(n, k)**
 969
 970 :   Returns the permutation of the truncated absolute value of **n** of the
 971     truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**.
 972
 973 **comb(n, k)**
 974
 975 :   Returns the combination of the truncated absolute value of **n** of the
 976     truncated absolute value of **k**, if **k \<= n**. If not, it returns **0**.
 977
 978 **l2(x)**
 979
 980 :   Returns the logarithm base **2** of **x**.
 981
 982     This is a transcendental function (see the *Transcendental Functions*
 983     subsection below).
 984
 985 **l10(x)**
 986
 987 :   Returns the logarithm base **10** of **x**.
 988
 989     This is a transcendental function (see the *Transcendental Functions*
 990     subsection below).
 991
 992 **log(x, b)**
 993
 994 :   Returns the logarithm base **b** of **x**.
 995
 996     This is a transcendental function (see the *Transcendental Functions*
 997     subsection below).
 998
 999 **cbrt(x)**
1000
1001 :   Returns the cube root of **x**.
1002
1003 **root(x, n)**
1004
1005 :   Calculates the truncated value of **n**, **r**, and returns the **r**th root
1006     of **x** to the current **scale**.
1007
1008     If **r** is **0** or negative, this raises an error and causes bc(1) to
1009     reset (see the **RESET** section). It also raises an error and causes bc(1)
1010     to reset if **r** is even and **x** is negative.
1011
1012 **pi(p)**
1013
1014 :   Returns **pi** to **p** decimal places.
1015
1016     This is a transcendental function (see the *Transcendental Functions*
1017     subsection below).
1018
1019 **t(x)**
1020
1021 :   Returns the tangent of **x**, which is assumed to be in radians.
1022
1023     This is a transcendental function (see the *Transcendental Functions*
1024     subsection below).
1025
1026 **a2(y, x)**
1027
1028 :   Returns the arctangent of **y/x**, in radians. If both **y** and **x** are
1029     equal to **0**, it raises an error and causes bc(1) to reset (see the
1030     **RESET** section). Otherwise, if **x** is greater than **0**, it returns
1031     **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal
1032     to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y**
1033     is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**,
1034     and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to
1035     **0**, and **y** is less than **0**, it returns **-pi/2**.
1036
1037     This function is the same as the **atan2()** function in many programming
1038     languages.
1039
1040     This is a transcendental function (see the *Transcendental Functions*
1041     subsection below).
1042
1043 **sin(x)**
1044
1045 :   Returns the sine of **x**, which is assumed to be in radians.
1046
1047     This is an alias of **s(x)**.
1048
1049     This is a transcendental function (see the *Transcendental Functions*
1050     subsection below).
1051
1052 **cos(x)**
1053
1054 :   Returns the cosine of **x**, which is assumed to be in radians.
1055
1056     This is an alias of **c(x)**.
1057
1058     This is a transcendental function (see the *Transcendental Functions*
1059     subsection below).
1060
1061 **tan(x)**
1062
1063 :   Returns the tangent of **x**, which is assumed to be in radians.
1064
1065     If **x** is equal to **1** or **-1**, this raises an error and causes bc(1)
1066     to reset (see the **RESET** section).
1067
1068     This is an alias of **t(x)**.
1069
1070     This is a transcendental function (see the *Transcendental Functions*
1071     subsection below).
1072
1073 **atan(x)**
1074
1075 :   Returns the arctangent of **x**, in radians.
1076
1077     This is an alias of **a(x)**.
1078
1079     This is a transcendental function (see the *Transcendental Functions*
1080     subsection below).
1081
1082 **atan2(y, x)**
1083
1084 :   Returns the arctangent of **y/x**, in radians. If both **y** and **x** are
1085     equal to **0**, it raises an error and causes bc(1) to reset (see the
1086     **RESET** section). Otherwise, if **x** is greater than **0**, it returns
1087     **a(y/x)**. If **x** is less than **0**, and **y** is greater than or equal
1088     to **0**, it returns **a(y/x)+pi**. If **x** is less than **0**, and **y**
1089     is less than **0**, it returns **a(y/x)-pi**. If **x** is equal to **0**,
1090     and **y** is greater than **0**, it returns **pi/2**. If **x** is equal to
1091     **0**, and **y** is less than **0**, it returns **-pi/2**.
1092
1093     This function is the same as the **atan2()** function in many programming
1094     languages.
1095
1096     This is an alias of **a2(y, x)**.
1097
1098     This is a transcendental function (see the *Transcendental Functions*
1099     subsection below).
1100
1101 **r2d(x)**
1102
1103 :   Converts **x** from radians to degrees and returns the result.
1104
1105     This is a transcendental function (see the *Transcendental Functions*
1106     subsection below).
1107
1108 **d2r(x)**
1109
1110 :   Converts **x** from degrees to radians and returns the result.
1111
1112     This is a transcendental function (see the *Transcendental Functions*
1113     subsection below).
1114
1115 **frand(p)**
1116
1117 :   Generates a pseudo-random number between **0** (inclusive) and **1**
1118     (exclusive) with the number of decimal digits after the decimal point equal
1119     to the truncated absolute value of **p**. If **p** is not **0**, then
1120     calling this function will change the value of **seed**. If **p** is **0**,
1121     then **0** is returned, and **seed** is *not* changed.
1122
1123 **ifrand(i, p)**
1124
1125 :   Generates a pseudo-random number that is between **0** (inclusive) and the
1126     truncated absolute value of **i** (exclusive) with the number of decimal
1127     digits after the decimal point equal to the truncated absolute value of
1128     **p**. If the absolute value of **i** is greater than or equal to **2**, and
1129     **p** is not **0**, then calling this function will change the value of
1130     **seed**; otherwise, **0** is returned and **seed** is not changed.
1131
1132 **srand(x)**
1133
1134 :   Returns **x** with its sign flipped with probability **0.5**. In other
1135     words, it randomizes the sign of **x**.
1136
1137 **brand()**
1138
1139 :   Returns a random boolean value (either **0** or **1**).
1140
1141 **ubytes(x)**
1142
1143 :   Returns the numbers of unsigned integer bytes required to hold the truncated
1144     absolute value of **x**.
1145
1146 **sbytes(x)**
1147
1148 :   Returns the numbers of signed, two's-complement integer bytes required to
1149     hold the truncated value of **x**.
1150
1151 **hex(x)**
1152
1153 :   Outputs the hexadecimal (base **16**) representation of **x**.
1154
1155     This is a **void** function (see the *Void Functions* subsection of the
1156     **FUNCTIONS** section).
1157
1158 **binary(x)**
1159
1160 :   Outputs the binary (base **2**) representation of **x**.
1161
1162     This is a **void** function (see the *Void Functions* subsection of the
1163     **FUNCTIONS** section).
1164
1165 **output(x, b)**
1166
1167 :   Outputs the base **b** representation of **x**.
1168
1169     This is a **void** function (see the *Void Functions* subsection of the
1170     **FUNCTIONS** section).
1171
1172 **uint(x)**
1173
1174 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1175     unsigned integer in as few power of two bytes as possible. Both outputs are
1176     split into bytes separated by spaces.
1177
1178     If **x** is not an integer or is negative, an error message is printed
1179     instead, but bc(1) is not reset (see the **RESET** section).
1180
1181     This is a **void** function (see the *Void Functions* subsection of the
1182     **FUNCTIONS** section).
1183
1184 **int(x)**
1185
1186 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1187     two's-complement integer in as few power of two bytes as possible. Both
1188     outputs are split into bytes separated by spaces.
1189
1190     If **x** is not an integer, an error message is printed instead, but bc(1)
1191     is not reset (see the **RESET** section).
1192
1193     This is a **void** function (see the *Void Functions* subsection of the
1194     **FUNCTIONS** section).
1195
1196 **uintn(x, n)**
1197
1198 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1199     unsigned integer in **n** bytes. Both outputs are split into bytes separated
1200     by spaces.
1201
1202     If **x** is not an integer, is negative, or cannot fit into **n** bytes, an
1203     error message is printed instead, but bc(1) is not reset (see the **RESET**
1204     section).
1205
1206     This is a **void** function (see the *Void Functions* subsection of the
1207     **FUNCTIONS** section).
1208
1209 **intn(x, n)**
1210
1211 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1212     two's-complement integer in **n** bytes. Both outputs are split into bytes
1213     separated by spaces.
1214
1215     If **x** is not an integer or cannot fit into **n** bytes, an error message
1216     is printed instead, but bc(1) is not reset (see the **RESET** section).
1217
1218     This is a **void** function (see the *Void Functions* subsection of the
1219     **FUNCTIONS** section).
1220
1221 **uint8(x)**
1222
1223 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1224     unsigned integer in **1** byte. Both outputs are split into bytes separated
1225     by spaces.
1226
1227     If **x** is not an integer, is negative, or cannot fit into **1** byte, an
1228     error message is printed instead, but bc(1) is not reset (see the **RESET**
1229     section).
1230
1231     This is a **void** function (see the *Void Functions* subsection of the
1232     **FUNCTIONS** section).
1233
1234 **int8(x)**
1235
1236 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1237     two's-complement integer in **1** byte. Both outputs are split into bytes
1238     separated by spaces.
1239
1240     If **x** is not an integer or cannot fit into **1** byte, an error message
1241     is printed instead, but bc(1) is not reset (see the **RESET** section).
1242
1243     This is a **void** function (see the *Void Functions* subsection of the
1244     **FUNCTIONS** section).
1245
1246 **uint16(x)**
1247
1248 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1249     unsigned integer in **2** bytes. Both outputs are split into bytes separated
1250     by spaces.
1251
1252     If **x** is not an integer, is negative, or cannot fit into **2** bytes, an
1253     error message is printed instead, but bc(1) is not reset (see the **RESET**
1254     section).
1255
1256     This is a **void** function (see the *Void Functions* subsection of the
1257     **FUNCTIONS** section).
1258
1259 **int16(x)**
1260
1261 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1262     two's-complement integer in **2** bytes. Both outputs are split into bytes
1263     separated by spaces.
1264
1265     If **x** is not an integer or cannot fit into **2** bytes, an error message
1266     is printed instead, but bc(1) is not reset (see the **RESET** section).
1267
1268     This is a **void** function (see the *Void Functions* subsection of the
1269     **FUNCTIONS** section).
1270
1271 **uint32(x)**
1272
1273 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1274     unsigned integer in **4** bytes. Both outputs are split into bytes separated
1275     by spaces.
1276
1277     If **x** is not an integer, is negative, or cannot fit into **4** bytes, an
1278     error message is printed instead, but bc(1) is not reset (see the **RESET**
1279     section).
1280
1281     This is a **void** function (see the *Void Functions* subsection of the
1282     **FUNCTIONS** section).
1283
1284 **int32(x)**
1285
1286 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1287     two's-complement integer in **4** bytes. Both outputs are split into bytes
1288     separated by spaces.
1289
1290     If **x** is not an integer or cannot fit into **4** bytes, an error message
1291     is printed instead, but bc(1) is not reset (see the **RESET** section).
1292
1293     This is a **void** function (see the *Void Functions* subsection of the
1294     **FUNCTIONS** section).
1295
1296 **uint64(x)**
1297
1298 :   Outputs the representation, in binary and hexadecimal, of **x** as an
1299     unsigned integer in **8** bytes. Both outputs are split into bytes separated
1300     by spaces.
1301
1302     If **x** is not an integer, is negative, or cannot fit into **8** bytes, an
1303     error message is printed instead, but bc(1) is not reset (see the **RESET**
1304     section).
1305
1306     This is a **void** function (see the *Void Functions* subsection of the
1307     **FUNCTIONS** section).
1308
1309 **int64(x)**
1310
1311 :   Outputs the representation, in binary and hexadecimal, of **x** as a signed,
1312     two's-complement integer in **8** bytes. Both outputs are split into bytes
1313     separated by spaces.
1314
1315     If **x** is not an integer or cannot fit into **8** bytes, an error message
1316     is printed instead, but bc(1) is not reset (see the **RESET** section).
1317
1318     This is a **void** function (see the *Void Functions* subsection of the
1319     **FUNCTIONS** section).
1320
1321 **hex_uint(x, n)**
1322
1323 :   Outputs the representation of the truncated absolute value of **x** as an
1324     unsigned integer in hexadecimal using **n** bytes. Not all of the value will
1325     be output if **n** is too small.
1326
1327     This is a **void** function (see the *Void Functions* subsection of the
1328     **FUNCTIONS** section).
1329
1330 **binary_uint(x, n)**
1331
1332 :   Outputs the representation of the truncated absolute value of **x** as an
1333     unsigned integer in binary using **n** bytes. Not all of the value will be
1334     output if **n** is too small.
1335
1336     This is a **void** function (see the *Void Functions* subsection of the
1337     **FUNCTIONS** section).
1338
1339 **output_uint(x, n)**
1340
1341 :   Outputs the representation of the truncated absolute value of **x** as an
1342     unsigned integer in the current **obase** (see the **SYNTAX** section) using
1343     **n** bytes. Not all of the value will be output if **n** is too small.
1344
1345     This is a **void** function (see the *Void Functions* subsection of the
1346     **FUNCTIONS** section).
1347
1348 **output_byte(x, i)**
1349
1350 :   Outputs byte **i** of the truncated absolute value of **x**, where **0** is
1351     the least significant byte and **number_of_bytes - 1** is the most
1352     significant byte.
1353
1354     This is a **void** function (see the *Void Functions* subsection of the
1355     **FUNCTIONS** section).
1356
1357 ## Transcendental Functions
1358
1359 All transcendental functions can return slightly inaccurate results (up to 1
1360 [ULP][4]). This is unavoidable, and [this article][5] explains why it is
1361 impossible and unnecessary to calculate exact results for the transcendental
1362 functions.
1363
1364 Because of the possible inaccuracy, I recommend that users call those functions
1365 with the precision (**scale**) set to at least 1 higher than is necessary. If
1366 exact results are *absolutely* required, users can double the precision
1367 (**scale**) and then truncate.
1368
1369 The transcendental functions in the standard math library are:
1370
1371 * **s(x)**
1372 * **c(x)**
1373 * **a(x)**
1374 * **l(x)**
1375 * **e(x)**
1376 * **j(x, n)**
1377
1378 The transcendental functions in the extended math library are:
1379
1380 * **l2(x)**
1381 * **l10(x)**
1382 * **log(x, b)**
1383 * **pi(p)**
1384 * **t(x)**
1385 * **a2(y, x)**
1386 * **sin(x)**
1387 * **cos(x)**
1388 * **tan(x)**
1389 * **atan(x)**
1390 * **atan2(y, x)**
1391 * **r2d(x)**
1392 * **d2r(x)**
1393
1394 # RESET
1395
1396 When bc(1) encounters an error or a signal that it has a non-default handler
1397 for, it resets. This means that several things happen.
1398
1399 First, any functions that are executing are stopped and popped off the stack.
1400 The behavior is not unlike that of exceptions in programming languages. Then
1401 the execution point is set so that any code waiting to execute (after all
1402 functions returned) is skipped.
1403
1404 Thus, when bc(1) resets, it skips any remaining code waiting to be executed.
1405 Then, if it is interactive mode, and the error was not a fatal error (see the
1406 **EXIT STATUS** section), it asks for more input; otherwise, it exits with the
1407 appropriate return code.
1408
1409 Note that this reset behavior is different from the GNU bc(1), which attempts to
1410 start executing the statement right after the one that caused an error.
1411
1412 # PERFORMANCE
1413
1414 Most bc(1) implementations use **char** types to calculate the value of **1**
1415 decimal digit at a time, but that can be slow. This bc(1) does something
1416 different.
1417
1418 It uses large integers to calculate more than **1** decimal digit at a time. If
1419 built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is
1420 **64**, then each integer has **9** decimal digits. If built in an environment
1421 where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
1422 value (the number of decimal digits per large integer) is called
1423 **BC_BASE_DIGS**.
1424
1425 The actual values of **BC_LONG_BIT** and **BC_BASE_DIGS** can be queried with
1426 the **limits** statement.
1427
1428 In addition, this bc(1) uses an even larger integer for overflow checking. This
1429 integer type depends on the value of **BC_LONG_BIT**, but is always at least
1430 twice as large as the integer type used to store digits.
1431
1432 # LIMITS
1433
1434 The following are the limits on bc(1):
1435
1436 **BC_LONG_BIT**
1437
1438 :   The number of bits in the **long** type in the environment where bc(1) was
1439     built. This determines how many decimal digits can be stored in a single
1440     large integer (see the **PERFORMANCE** section).
1441
1442 **BC_BASE_DIGS**
1443
1444 :   The number of decimal digits per large integer (see the **PERFORMANCE**
1445     section). Depends on **BC_LONG_BIT**.
1446
1447 **BC_BASE_POW**
1448
1449 :   The max decimal number that each large integer can store (see
1450     **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**.
1451
1452 **BC_OVERFLOW_MAX**
1453
1454 :   The max number that the overflow type (see the **PERFORMANCE** section) can
1455     hold. Depends on **BC_LONG_BIT**.
1456
1457 **BC_BASE_MAX**
1458
1459 :   The maximum output base. Set at **BC_BASE_POW**.
1460
1461 **BC_DIM_MAX**
1462
1463 :   The maximum size of arrays. Set at **SIZE_MAX-1**.
1464
1465 **BC_SCALE_MAX**
1466
1467 :   The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**.
1468
1469 **BC_STRING_MAX**
1470
1471 :   The maximum length of strings. Set at **BC_OVERFLOW_MAX-1**.
1472
1473 **BC_NAME_MAX**
1474
1475 :   The maximum length of identifiers. Set at **BC_OVERFLOW_MAX-1**.
1476
1477 **BC_NUM_MAX**
1478
1479 :   The maximum length of a number (in decimal digits), which includes digits
1480     after the decimal point. Set at **BC_OVERFLOW_MAX-1**.
1481
1482 **BC_RAND_MAX**
1483
1484 :   The maximum integer (inclusive) returned by the **rand()** operand. Set at
1485     **2\^BC_LONG_BIT-1**.
1486
1487 Exponent
1488
1489 :   The maximum allowable exponent (positive or negative). Set at
1490     **BC_OVERFLOW_MAX**.
1491
1492 Number of vars
1493
1494 :   The maximum number of vars/arrays. Set at **SIZE_MAX-1**.
1495
1496 The actual values can be queried with the **limits** statement.
1497
1498 These limits are meant to be effectively non-existent; the limits are so large
1499 (at least on 64-bit machines) that there should not be any point at which they
1500 become a problem. In fact, memory should be exhausted before these limits should
1501 be hit.
1502
1503 # ENVIRONMENT VARIABLES
1504
1505 bc(1) recognizes the following environment variables:
1506
1507 **POSIXLY_CORRECT**
1508
1509 :   If this variable exists (no matter the contents), bc(1) behaves as if
1510     the **-s** option was given.
1511
1512 **BC_ENV_ARGS**
1513
1514 :   This is another way to give command-line arguments to bc(1). They should be
1515     in the same format as all other command-line arguments. These are always
1516     processed first, so any files given in **BC_ENV_ARGS** will be processed
1517     before arguments and files given on the command-line. This gives the user
1518     the ability to set up "standard" options and files to be used at every
1519     invocation. The most useful thing for such files to contain would be useful
1520     functions that the user might want every time bc(1) runs.
1521
1522     The code that parses **BC_ENV_ARGS** will correctly handle quoted arguments,
1523     but it does not understand escape sequences. For example, the string
1524     **"/home/gavin/some bc file.bc"** will be correctly parsed, but the string
1525     **"/home/gavin/some \"bc\" file.bc"** will include the backslashes.
1526
1527     The quote parsing will handle either kind of quotes, **'** or **"**. Thus,
1528     if you have a file with any number of single quotes in the name, you can use
1529     double quotes as the outside quotes, as in **"some 'bc' file.bc"**, and vice
1530     versa if you have a file with double quotes. However, handling a file with
1531     both kinds of quotes in **BC_ENV_ARGS** is not supported due to the
1532     complexity of the parsing, though such files are still supported on the
1533     command-line where the parsing is done by the shell.
1534
1535 **BC_LINE_LENGTH**
1536
1537 :   If this environment variable exists and contains an integer that is greater
1538     than **1** and is less than **UINT16_MAX** (**2\^16-1**), bc(1) will output
1539     lines to that length, including the backslash (**\\**). The default line
1540     length is **70**.
1541
1542 # EXIT STATUS
1543
1544 bc(1) returns the following exit statuses:
1545
1546 **0**
1547
1548 :   No error.
1549
1550 **1**
1551
1552 :   A math error occurred. This follows standard practice of using **1** for
1553     expected errors, since math errors will happen in the process of normal
1554     execution.
1555
1556     Math errors include divide by **0**, taking the square root of a negative
1557     number, using a negative number as a bound for the pseudo-random number
1558     generator, attempting to convert a negative number to a hardware integer,
1559     overflow when converting a number to a hardware integer, and attempting to
1560     use a non-integer where an integer is required.
1561
1562     Converting to a hardware integer happens for the second operand of the power
1563     (**\^**), places (**\@**), left shift (**\<\<**), and right shift (**\>\>**)
1564     operators and their corresponding assignment operators.
1565
1566 **2**
1567
1568 :   A parse error occurred.
1569
1570     Parse errors include unexpected **EOF**, using an invalid character, failing
1571     to find the end of a string or comment, using a token where it is invalid,
1572     giving an invalid expression, giving an invalid print statement, giving an
1573     invalid function definition, attempting to assign to an expression that is
1574     not a named expression (see the *Named Expressions* subsection of the
1575     **SYNTAX** section), giving an invalid **auto** list, having a duplicate
1576     **auto**/function parameter, failing to find the end of a code block,
1577     attempting to return a value from a **void** function, attempting to use a
1578     variable as a reference, and using any extensions when the option **-s** or
1579     any equivalents were given.
1580
1581 **3**
1582
1583 :   A runtime error occurred.
1584
1585     Runtime errors include assigning an invalid number to **ibase**, **obase**,
1586     or **scale**; give a bad expression to a **read()** call, calling **read()**
1587     inside of a **read()** call, type errors, passing the wrong number of
1588     arguments to functions, attempting to call an undefined function, and
1589     attempting to use a **void** function call as a value in an expression.
1590
1591 **4**
1592
1593 :   A fatal error occurred.
1594
1595     Fatal errors include memory allocation errors, I/O errors, failing to open
1596     files, attempting to use files that do not have only ASCII characters (bc(1)
1597     only accepts ASCII characters), attempting to open a directory as a file,
1598     and giving invalid command-line options.
1599
1600 The exit status **4** is special; when a fatal error occurs, bc(1) always exits
1601 and returns **4**, no matter what mode bc(1) is in.
1602
1603 The other statuses will only be returned when bc(1) is not in interactive mode
1604 (see the **INTERACTIVE MODE** section), since bc(1) resets its state (see the
1605 **RESET** section) and accepts more input when one of those errors occurs in
1606 interactive mode. This is also the case when interactive mode is forced by the
1607 **-i** flag or **-\-interactive** option.
1608
1609 These exit statuses allow bc(1) to be used in shell scripting with error
1610 checking, and its normal behavior can be forced by using the **-i** flag or
1611 **-\-interactive** option.
1612
1613 # INTERACTIVE MODE
1614
1615 Per the [standard][1], bc(1) has an interactive mode and a non-interactive mode.
1616 Interactive mode is turned on automatically when both **stdin** and **stdout**
1617 are hooked to a terminal, but the **-i** flag and **-\-interactive** option can
1618 turn it on in other cases.
1619
1620 In interactive mode, bc(1) attempts to recover from errors (see the **RESET**
1621 section), and in normal execution, flushes **stdout** as soon as execution is
1622 done for the current input.
1623
1624 # TTY MODE
1625
1626 If **stdin**, **stdout**, and **stderr** are all connected to a TTY, bc(1) turns
1627 on "TTY mode."
1628
1629 TTY mode is required for history to be enabled (see the **COMMAND LINE HISTORY**
1630 section). It is also required to enable special handling for **SIGINT** signals.
1631
1632 TTY mode is different from interactive mode because interactive mode is required
1633 in the [bc(1) specification][1], and interactive mode requires only **stdin**
1634 and **stdout** to be connected to a terminal.
1635
1636 # SIGNAL HANDLING
1637
1638 Sending a **SIGINT** will cause bc(1) to stop execution of the current input. If
1639 bc(1) is in TTY mode (see the **TTY MODE** section), it will reset (see the
1640 **RESET** section). Otherwise, it will clean up and exit.
1641
1642 Note that "current input" can mean one of two things. If bc(1) is processing
1643 input from **stdin** in TTY mode, it will ask for more input. If bc(1) is
1644 processing input from a file in TTY mode, it will stop processing the file and
1645 start processing the next file, if one exists, or ask for input from **stdin**
1646 if no other file exists.
1647
1648 This means that if a **SIGINT** is sent to bc(1) as it is executing a file, it
1649 can seem as though bc(1) did not respond to the signal since it will immediately
1650 start executing the next file. This is by design; most files that users execute
1651 when interacting with bc(1) have function definitions, which are quick to parse.
1652 If a file takes a long time to execute, there may be a bug in that file. The
1653 rest of the files could still be executed without problem, allowing the user to
1654 continue.
1655
1656 **SIGTERM** and **SIGQUIT** cause bc(1) to clean up and exit, and it uses the
1657 default handler for all other signals. The one exception is **SIGHUP**; in that
1658 case, when bc(1) is in TTY mode, a **SIGHUP** will cause bc(1) to clean up and
1659 exit.
1660
1661 # COMMAND LINE HISTORY
1662
1663 bc(1) supports interactive command-line editing. If bc(1) is in TTY mode (see
1664 the **TTY MODE** section), history is enabled. Previous lines can be recalled
1665 and edited with the arrow keys.
1666
1667 **Note**: tabs are converted to 8 spaces.
1668
1669 # SEE ALSO
1670
1671 dc(1)
1672
1673 # STANDARDS
1674
1675 bc(1) is compliant with the [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1]
1676 specification. The flags **-efghiqsvVw**, all long options, and the extensions
1677 noted above are extensions to that specification.
1678
1679 Note that the specification explicitly says that bc(1) only accepts numbers that
1680 use a period (**.**) as a radix point, regardless of the value of
1681 **LC_NUMERIC**.
1682
1683 # BUGS
1684
1685 None are known. Report bugs at https://git.yzena.com/gavin/bc.
1686
1687 # AUTHORS
1688
1689 Gavin D. Howard <gavin@yzena.com> and contributors.
1690
1691 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html
1692 [2]: https://www.gnu.org/software/bc/
1693 [3]: https://en.wikipedia.org/wiki/Rounding#Round_half_away_from_zero
1694 [4]: https://en.wikipedia.org/wiki/Unit_in_the_last_place
1695 [5]: https://people.eecs.berkeley.edu/~wkahan/LOG10HAF.TXT
1696 [6]: https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero