1 % API
   2 
   3 # Builtins
   4 
   5 # Num
   6 ## Num.1_PI
   7 
   8 ```tomo
   9 Num.1_PI : Num
  10 ```
  11 
  12 The constant $\frac{1}{\pi}$.
  13 
  14 ## Num.2_PI
  15 
  16 ```tomo
  17 Num.2_PI : Num
  18 ```
  19 
  20 The constant $2 \times \pi$.
  21 
  22 ## Num.2_SQRTPI
  23 
  24 ```tomo
  25 Num.2_SQRTPI : Num
  26 ```
  27 
  28 The constant $2 \times \sqrt{\pi}$.
  29 
  30 ## Num.E
  31 
  32 ```tomo
  33 Num.E : Num
  34 ```
  35 
  36 The base of the natural logarithm ($e$).
  37 
  38 ## Num.INF
  39 
  40 ```tomo
  41 Num.INF : Num
  42 ```
  43 
  44 Positive infinity.
  45 
  46 ## Num.LN10
  47 
  48 ```tomo
  49 Num.LN10 : Num
  50 ```
  51 
  52 The natural logarithm of 10.
  53 
  54 ## Num.LN2
  55 
  56 ```tomo
  57 Num.LN2 : Num
  58 ```
  59 
  60 The natural logarithm of 2.
  61 
  62 ## Num.LOG2E
  63 
  64 ```tomo
  65 Num.LOG2E : Num
  66 ```
  67 
  68 The base 2 logarithm of $e$
  69 
  70 ## Num.PI
  71 
  72 ```tomo
  73 Num.PI : Num
  74 ```
  75 
  76 Pi ($\pi$).
  77 
  78 ## Num.PI_2
  79 
  80 ```tomo
  81 Num.PI_2 : Num
  82 ```
  83 
  84 $\frac{\pi}{2}$
  85 
  86 ## Num.PI_4
  87 
  88 ```tomo
  89 Num.PI_4 : Num
  90 ```
  91 
  92 $\frac{\pi}{4}$
  93 
  94 ## Num.SQRT1_2
  95 
  96 ```tomo
  97 Num.SQRT1_2 : Num
  98 ```
  99 
 100 $\sqrt{\frac{1}{2}}$
 101 
 102 ## Num.SQRT2
 103 
 104 ```tomo
 105 Num.SQRT2 : Num
 106 ```
 107 
 108 $\sqrt{2}$
 109 
 110 ## Num.TAU
 111 
 112 ```tomo
 113 Num.TAU : Num
 114 ```
 115 
 116 Tau ($2 \times \pi$)
 117 
 118 ## Num.abs
 119 
 120 ```tomo
 121 Num.abs : func(n: Num -> Num)
 122 ```
 123 
 124 Calculates the absolute value of a number.
 125 
 126 Argument | Type | Description | Default
 127 ---------|------|-------------|---------
 128 n | `Num` | The number whose absolute value is to be computed.  | -
 129 
 130 **Return:** The absolute value of `n`.
 131 
 132 
 133 **Example:**
 134 ```tomo
 135 assert (-3.5).abs() == 3.5
 136 
 137 ```
 138 ## Num.acos
 139 
 140 ```tomo
 141 Num.acos : func(x: Num -> Num)
 142 ```
 143 
 144 Computes the arc cosine of a number.
 145 
 146 Argument | Type | Description | Default
 147 ---------|------|-------------|---------
 148 x | `Num` | The number for which the arc cosine is to be calculated.  | -
 149 
 150 **Return:** The arc cosine of `x` in radians.
 151 
 152 
 153 **Example:**
 154 ```tomo
 155 assert (0.0).acos().near(1.5707963267948966)
 156 
 157 ```
 158 ## Num.acosh
 159 
 160 ```tomo
 161 Num.acosh : func(x: Num -> Num)
 162 ```
 163 
 164 Computes the inverse hyperbolic cosine of a number.
 165 
 166 Argument | Type | Description | Default
 167 ---------|------|-------------|---------
 168 x | `Num` | The number for which the inverse hyperbolic cosine is to be calculated.  | -
 169 
 170 **Return:** The inverse hyperbolic cosine of `x`.
 171 
 172 
 173 **Example:**
 174 ```tomo
 175 assert (1.0).acosh() == 0
 176 
 177 ```
 178 ## Num.asin
 179 
 180 ```tomo
 181 Num.asin : func(x: Num -> Num)
 182 ```
 183 
 184 Computes the arc sine of a number.
 185 
 186 Argument | Type | Description | Default
 187 ---------|------|-------------|---------
 188 x | `Num` | The number for which the arc sine is to be calculated.  | -
 189 
 190 **Return:** The arc sine of `x` in radians.
 191 
 192 
 193 **Example:**
 194 ```tomo
 195 assert (0.5).asin().near(0.5235987755982989)
 196 
 197 ```
 198 ## Num.asinh
 199 
 200 ```tomo
 201 Num.asinh : func(x: Num -> Num)
 202 ```
 203 
 204 Computes the inverse hyperbolic sine of a number.
 205 
 206 Argument | Type | Description | Default
 207 ---------|------|-------------|---------
 208 x | `Num` | The number for which the inverse hyperbolic sine is to be calculated.  | -
 209 
 210 **Return:** The inverse hyperbolic sine of `x`.
 211 
 212 
 213 **Example:**
 214 ```tomo
 215 assert (0.0).asinh() == 0
 216 
 217 ```
 218 ## Num.atan
 219 
 220 ```tomo
 221 Num.atan : func(x: Num -> Num)
 222 ```
 223 
 224 Computes the arc tangent of a number.
 225 
 226 Argument | Type | Description | Default
 227 ---------|------|-------------|---------
 228 x | `Num` | The number for which the arc tangent is to be calculated.  | -
 229 
 230 **Return:** The arc tangent of `x` in radians.
 231 
 232 
 233 **Example:**
 234 ```tomo
 235 assert (1.0).atan().near(0.7853981633974483)
 236 
 237 ```
 238 ## Num.atan2
 239 
 240 ```tomo
 241 Num.atan2 : func(x: Num, y: Num -> Num)
 242 ```
 243 
 244 Computes the arc tangent of the quotient of two numbers.
 245 
 246 Argument | Type | Description | Default
 247 ---------|------|-------------|---------
 248 x | `Num` | The numerator.  | -
 249 y | `Num` | The denominator.  | -
 250 
 251 **Return:** The arc tangent of `x/y` in radians.
 252 
 253 
 254 **Example:**
 255 ```tomo
 256 assert Num.atan2(1, 1).near(0.7853981633974483)
 257 
 258 ```
 259 ## Num.atanh
 260 
 261 ```tomo
 262 Num.atanh : func(x: Num -> Num)
 263 ```
 264 
 265 Computes the inverse hyperbolic tangent of a number.
 266 
 267 Argument | Type | Description | Default
 268 ---------|------|-------------|---------
 269 x | `Num` | The number for which the inverse hyperbolic tangent is to be calculated.  | -
 270 
 271 **Return:** The inverse hyperbolic tangent of `x`.
 272 
 273 
 274 **Example:**
 275 ```tomo
 276 assert (0.5).atanh().near(0.5493061443340549)
 277 
 278 ```
 279 ## Num.cbrt
 280 
 281 ```tomo
 282 Num.cbrt : func(x: Num -> Num)
 283 ```
 284 
 285 Computes the cube root of a number.
 286 
 287 Argument | Type | Description | Default
 288 ---------|------|-------------|---------
 289 x | `Num` | The number for which the cube root is to be calculated.  | -
 290 
 291 **Return:** The cube root of `x`.
 292 
 293 
 294 **Example:**
 295 ```tomo
 296 assert (27.0).cbrt() == 3
 297 
 298 ```
 299 ## Num.ceil
 300 
 301 ```tomo
 302 Num.ceil : func(x: Num -> Num)
 303 ```
 304 
 305 Rounds a number up to the nearest integer.
 306 
 307 Argument | Type | Description | Default
 308 ---------|------|-------------|---------
 309 x | `Num` | The number to be rounded up.  | -
 310 
 311 **Return:** The smallest integer greater than or equal to `x`.
 312 
 313 
 314 **Example:**
 315 ```tomo
 316 assert (3.2).ceil() == 4
 317 
 318 ```
 319 ## Num.clamped
 320 
 321 ```tomo
 322 Num.clamped : func(x: Num, low: Num, high: Num -> Num)
 323 ```
 324 
 325 Returns the given number clamped between two values so that it is within that range.
 326 
 327 Argument | Type | Description | Default
 328 ---------|------|-------------|---------
 329 x | `Num` | The number to clamp.  | -
 330 low | `Num` | The lowest value the result can take.  | -
 331 high | `Num` | The highest value the result can take.  | -
 332 
 333 **Return:** The first argument clamped between the other two arguments.
 334 
 335 
 336 **Example:**
 337 ```tomo
 338 assert (2.5).clamped(5.5, 10.5) == 5.5
 339 
 340 ```
 341 ## Num.copysign
 342 
 343 ```tomo
 344 Num.copysign : func(x: Num, y: Num -> Num)
 345 ```
 346 
 347 Copies the sign of one number to another.
 348 
 349 Argument | Type | Description | Default
 350 ---------|------|-------------|---------
 351 x | `Num` | The number whose magnitude will be copied.  | -
 352 y | `Num` | The number whose sign will be copied.  | -
 353 
 354 **Return:** A number with the magnitude of `x` and the sign of `y`.
 355 
 356 
 357 **Example:**
 358 ```tomo
 359 assert (3.0).copysign(-1) == -3
 360 
 361 ```
 362 ## Num.cos
 363 
 364 ```tomo
 365 Num.cos : func(x: Num -> Num)
 366 ```
 367 
 368 Computes the cosine of a number (angle in radians).
 369 
 370 Argument | Type | Description | Default
 371 ---------|------|-------------|---------
 372 x | `Num` | The angle in radians.  | -
 373 
 374 **Return:** The cosine of `x`.
 375 
 376 
 377 **Example:**
 378 ```tomo
 379 assert (0.0).cos() == 1
 380 
 381 ```
 382 ## Num.cosh
 383 
 384 ```tomo
 385 Num.cosh : func(x: Num -> Num)
 386 ```
 387 
 388 Computes the hyperbolic cosine of a number.
 389 
 390 Argument | Type | Description | Default
 391 ---------|------|-------------|---------
 392 x | `Num` | The number for which the hyperbolic cosine is to be calculated.  | -
 393 
 394 **Return:** The hyperbolic cosine of `x`.
 395 
 396 
 397 **Example:**
 398 ```tomo
 399 assert (0.0).cosh() == 1
 400 
 401 ```
 402 ## Num.erf
 403 
 404 ```tomo
 405 Num.erf : func(x: Num -> Num)
 406 ```
 407 
 408 Computes the error function of a number.
 409 
 410 Argument | Type | Description | Default
 411 ---------|------|-------------|---------
 412 x | `Num` | The number for which the error function is to be calculated.  | -
 413 
 414 **Return:** The error function of `x`.
 415 
 416 
 417 **Example:**
 418 ```tomo
 419 assert (0.0).erf() == 0
 420 
 421 ```
 422 ## Num.erfc
 423 
 424 ```tomo
 425 Num.erfc : func(x: Num -> Num)
 426 ```
 427 
 428 Computes the complementary error function of a number.
 429 
 430 Argument | Type | Description | Default
 431 ---------|------|-------------|---------
 432 x | `Num` | The number for which the complementary error function is to be calculated.  | -
 433 
 434 **Return:** The complementary error function of `x`.
 435 
 436 
 437 **Example:**
 438 ```tomo
 439 assert (0.0).erfc() == 1
 440 
 441 ```
 442 ## Num.exp
 443 
 444 ```tomo
 445 Num.exp : func(x: Num -> Num)
 446 ```
 447 
 448 Computes the exponential function $e^x$ for a number.
 449 
 450 Argument | Type | Description | Default
 451 ---------|------|-------------|---------
 452 x | `Num` | The exponent.  | -
 453 
 454 **Return:** The value of $e^x$.
 455 
 456 
 457 **Example:**
 458 ```tomo
 459 assert (1.0).exp().near(2.718281828459045)
 460 
 461 ```
 462 ## Num.exp2
 463 
 464 ```tomo
 465 Num.exp2 : func(x: Num -> Num)
 466 ```
 467 
 468 Computes $2^x$ for a number.
 469 
 470 Argument | Type | Description | Default
 471 ---------|------|-------------|---------
 472 x | `Num` | The exponent.  | -
 473 
 474 **Return:** The value of $2^x$.
 475 
 476 
 477 **Example:**
 478 ```tomo
 479 assert (3.0).exp2() == 8
 480 
 481 ```
 482 ## Num.expm1
 483 
 484 ```tomo
 485 Num.expm1 : func(x: Num -> Num)
 486 ```
 487 
 488 Computes $e^x - 1$ for a number.
 489 
 490 Argument | Type | Description | Default
 491 ---------|------|-------------|---------
 492 x | `Num` | The exponent.  | -
 493 
 494 **Return:** The value of $e^x - 1$.
 495 
 496 
 497 **Example:**
 498 ```tomo
 499 assert (1.0).expm1().near(1.7182818284590453)
 500 
 501 ```
 502 ## Num.fdim
 503 
 504 ```tomo
 505 Num.fdim : func(x: Num, y: Num -> Num)
 506 ```
 507 
 508 Computes the positive difference between two numbers.
 509 
 510 Argument | Type | Description | Default
 511 ---------|------|-------------|---------
 512 x | `Num` | The first number.  | -
 513 y | `Num` | The second number.  | -
 514 
 515 **Return:** The positive difference $\max(0, x - y)$.
 516 
 517 
 518 **Example:**
 519 ```tomo
 520 assert (5.0).fdim(3) == 2
 521 
 522 ```
 523 ## Num.floor
 524 
 525 ```tomo
 526 Num.floor : func(x: Num -> Num)
 527 ```
 528 
 529 Rounds a number down to the nearest integer.
 530 
 531 Argument | Type | Description | Default
 532 ---------|------|-------------|---------
 533 x | `Num` | The number to be rounded down.  | -
 534 
 535 **Return:** The largest integer less than or equal to `x`.
 536 
 537 
 538 **Example:**
 539 ```tomo
 540 assert (3.7).floor() == 3
 541 
 542 ```
 543 ## Num.hypot
 544 
 545 ```tomo
 546 Num.hypot : func(x: Num, y: Num -> Num)
 547 ```
 548 
 549 Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers.
 550 
 551 Argument | Type | Description | Default
 552 ---------|------|-------------|---------
 553 x | `Num` | The first number.  | -
 554 y | `Num` | The second number.  | -
 555 
 556 **Return:** The Euclidean norm of `x` and `y`.
 557 
 558 
 559 **Example:**
 560 ```tomo
 561 assert Num.hypot(3, 4) == 5
 562 
 563 ```
 564 ## Num.is_between
 565 
 566 ```tomo
 567 Num.is_between : func(x: Num, low: Num, high: Num -> Bool)
 568 ```
 569 
 570 Determines if a number is between two numbers (inclusive).
 571 
 572 Argument | Type | Description | Default
 573 ---------|------|-------------|---------
 574 x | `Num` | The integer to be checked.  | -
 575 low | `Num` | One end of the range to check (inclusive).  | -
 576 high | `Num` | The other end of the range to check (inclusive).  | -
 577 
 578 **Return:** `yes` if `a <= x and x <= b` or `b <= x and x <= a`, otherwise `no`
 579 
 580 
 581 **Example:**
 582 ```tomo
 583 assert (7.5).is_between(1, 10) == yes
 584 assert (7.5).is_between(10, 1) == yes
 585 assert (7.5).is_between(100, 200) == no
 586 assert (7.5).is_between(1, 7.5) == yes
 587 
 588 ```
 589 ## Num.isfinite
 590 
 591 ```tomo
 592 Num.isfinite : func(n: Num -> Bool)
 593 ```
 594 
 595 Checks if a number is finite.
 596 
 597 Argument | Type | Description | Default
 598 ---------|------|-------------|---------
 599 n | `Num` | The number to be checked.  | -
 600 
 601 **Return:** `yes` if `n` is finite, `no` otherwise.
 602 
 603 
 604 **Example:**
 605 ```tomo
 606 assert (1.0).isfinite() == yes
 607 assert Num.INF.isfinite() == no
 608 
 609 ```
 610 ## Num.isinf
 611 
 612 ```tomo
 613 Num.isinf : func(n: Num -> Bool)
 614 ```
 615 
 616 Checks if a number is infinite.
 617 
 618 Argument | Type | Description | Default
 619 ---------|------|-------------|---------
 620 n | `Num` | The number to be checked.  | -
 621 
 622 **Return:** `yes` if `n` is infinite, `no` otherwise.
 623 
 624 
 625 **Example:**
 626 ```tomo
 627 assert Num.INF.isinf() == yes
 628 assert (1.0).isinf() == no
 629 
 630 ```
 631 ## Num.j0
 632 
 633 ```tomo
 634 Num.j0 : func(x: Num -> Num)
 635 ```
 636 
 637 Computes the Bessel function of the first kind of order 0.
 638 
 639 Argument | Type | Description | Default
 640 ---------|------|-------------|---------
 641 x | `Num` | The number for which the Bessel function is to be calculated.  | -
 642 
 643 **Return:** The Bessel function of the first kind of order 0 of `x`.
 644 
 645 
 646 **Example:**
 647 ```tomo
 648 assert (0.0).j0() == 1
 649 
 650 ```
 651 ## Num.j1
 652 
 653 ```tomo
 654 Num.j1 : func(x: Num -> Num)
 655 ```
 656 
 657 Computes the Bessel function of the first kind of order 1.
 658 
 659 Argument | Type | Description | Default
 660 ---------|------|-------------|---------
 661 x | `Num` | The number for which the Bessel function is to be calculated.  | -
 662 
 663 **Return:** The Bessel function of the first kind of order 1 of `x`.
 664 
 665 
 666 **Example:**
 667 ```tomo
 668 assert (0.0).j1() == 0
 669 
 670 ```
 671 ## Num.log
 672 
 673 ```tomo
 674 Num.log : func(x: Num -> Num)
 675 ```
 676 
 677 Computes the natural logarithm (base $e$) of a number.
 678 
 679 Argument | Type | Description | Default
 680 ---------|------|-------------|---------
 681 x | `Num` | The number for which the natural logarithm is to be calculated.  | -
 682 
 683 **Return:** The natural logarithm of `x`.
 684 
 685 
 686 **Example:**
 687 ```tomo
 688 assert Num.E.log() == 1
 689 
 690 ```
 691 ## Num.log10
 692 
 693 ```tomo
 694 Num.log10 : func(x: Num -> Num)
 695 ```
 696 
 697 Computes the base-10 logarithm of a number.
 698 
 699 Argument | Type | Description | Default
 700 ---------|------|-------------|---------
 701 x | `Num` | The number for which the base-10 logarithm is to be calculated.  | -
 702 
 703 **Return:** The base-10 logarithm of `x`.
 704 
 705 
 706 **Example:**
 707 ```tomo
 708 assert (100.0).log10() == 2
 709 
 710 ```
 711 ## Num.log1p
 712 
 713 ```tomo
 714 Num.log1p : func(x: Num -> Num)
 715 ```
 716 
 717 Computes $\log(1 + x)$ for a number.
 718 
 719 Argument | Type | Description | Default
 720 ---------|------|-------------|---------
 721 x | `Num` | The number for which $\log(1 + x)$ is to be calculated.  | -
 722 
 723 **Return:** The value of $\log(1 + x)$.
 724 
 725 
 726 **Example:**
 727 ```tomo
 728 assert (1.0).log1p().near(0.6931471805599453)
 729 
 730 ```
 731 ## Num.log2
 732 
 733 ```tomo
 734 Num.log2 : func(x: Num -> Num)
 735 ```
 736 
 737 Computes the base-2 logarithm of a number.
 738 
 739 Argument | Type | Description | Default
 740 ---------|------|-------------|---------
 741 x | `Num` | The number for which the base-2 logarithm is to be calculated.  | -
 742 
 743 **Return:** The base-2 logarithm of `x`.
 744 
 745 
 746 **Example:**
 747 ```tomo
 748 assert (8.0).log2() == 3
 749 
 750 ```
 751 ## Num.logb
 752 
 753 ```tomo
 754 Num.logb : func(x: Num -> Num)
 755 ```
 756 
 757 Computes the binary exponent (base-2 logarithm) of a number.
 758 
 759 Argument | Type | Description | Default
 760 ---------|------|-------------|---------
 761 x | `Num` | The number for which the binary exponent is to be calculated.  | -
 762 
 763 **Return:** The binary exponent of `x`.
 764 
 765 
 766 **Example:**
 767 ```tomo
 768 assert (8.0).logb() == 3
 769 
 770 ```
 771 ## Num.mix
 772 
 773 ```tomo
 774 Num.mix : func(amount: Num, x: Num, y: Num -> Num)
 775 ```
 776 
 777 Interpolates between two numbers based on a given amount.
 778 
 779 Argument | Type | Description | Default
 780 ---------|------|-------------|---------
 781 amount | `Num` | The interpolation factor (between `0` and `1`).  | -
 782 x | `Num` | The starting number.  | -
 783 y | `Num` | The ending number.  | -
 784 
 785 **Return:** The interpolated number between `x` and `y` based on `amount`.
 786 
 787 
 788 **Example:**
 789 ```tomo
 790 assert (0.5).mix(10, 20) == 15
 791 assert (0.25).mix(10, 20) == 12.5
 792 
 793 ```
 794 ## Num.near
 795 
 796 ```tomo
 797 Num.near : func(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)
 798 ```
 799 
 800 Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other.
 801 
 802 Argument | Type | Description | Default
 803 ---------|------|-------------|---------
 804 x | `Num` | The first number.  | -
 805 y | `Num` | The second number.  | -
 806 ratio | `Num` | The relative tolerance. Default is `1e-9`.  | `1e-9`
 807 min_epsilon | `Num` | The absolute tolerance. Default is `1e-9`.  | `1e-9`
 808 
 809 **Return:** `yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise.
 810 
 811 
 812 **Example:**
 813 ```tomo
 814 assert (1.0).near(1.000000001) == yes
 815 assert (100.0).near(110, ratio=0.1) == yes
 816 assert (5.0).near(5.1, min_epsilon=0.1) == yes
 817 
 818 ```
 819 ## Num.nextafter
 820 
 821 ```tomo
 822 Num.nextafter : func(x: Num, y: Num -> Num)
 823 ```
 824 
 825 Computes the next representable value after a given number towards a specified direction.
 826 
 827 Argument | Type | Description | Default
 828 ---------|------|-------------|---------
 829 x | `Num` | The starting number.  | -
 830 y | `Num` | The direction towards which to find the next representable value.  | -
 831 
 832 **Return:** The next representable value after `x` in the direction of `y`.
 833 
 834 
 835 **Example:**
 836 ```tomo
 837 assert (1.0).nextafter(1.1) == 1.0000000000000002
 838 
 839 ```
 840 ## Num.parse
 841 
 842 ```tomo
 843 Num.parse : func(text: Text, remainder: &Text? = none -> Num?)
 844 ```
 845 
 846 Converts a text representation of a number into a floating-point number.
 847 
 848 Argument | Type | Description | Default
 849 ---------|------|-------------|---------
 850 text | `Text` | The text containing the number.  | -
 851 remainder | `&Text?` | If non-none, this argument will be set to the remainder of the text after the matching part. If none, parsing will only succeed if the entire text matches.  | `none`
 852 
 853 **Return:** The number represented by the text or `none` if the entire text can't be parsed as a number.
 854 
 855 
 856 **Example:**
 857 ```tomo
 858 assert Num.parse("3.14") == 3.14
 859 assert Num.parse("1e3") == 1000
 860 assert Num.parse("1.5junk") == none
 861 remainder : Text
 862 assert Num.parse("1.5junk", &remainder) == 1.5
 863 assert remainder == "junk"
 864 
 865 ```
 866 ## Num.percent
 867 
 868 ```tomo
 869 Num.percent : func(n: Num, precision: Num = 0.01 -> Text)
 870 ```
 871 
 872 Convert a number into a percentage text with a percent sign.
 873 
 874 Argument | Type | Description | Default
 875 ---------|------|-------------|---------
 876 n | `Num` | The number to be converted to a percent.  | -
 877 precision | `Num` | Round the percentage to this precision level.  | `0.01`
 878 
 879 **Return:** A text representation of the number as a percentage with a percent sign.
 880 
 881 
 882 **Example:**
 883 ```tomo
 884 assert (0.5).percent() == "50%"
 885 assert (1./3.).percent(2) == "34%"
 886 assert (1./3.).percent(precision=0.0001) == "33.3333%"
 887 assert (1./3.).percent(precision=10.) == "30%"
 888 
 889 ```
 890 ## Num.rint
 891 
 892 ```tomo
 893 Num.rint : func(x: Num -> Num)
 894 ```
 895 
 896 Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
 897 
 898 Argument | Type | Description | Default
 899 ---------|------|-------------|---------
 900 x | `Num` | The number to be rounded.  | -
 901 
 902 **Return:** The nearest integer value of `x`.
 903 
 904 
 905 **Example:**
 906 ```tomo
 907 assert (3.5).rint() == 4
 908 assert (2.5).rint() == 2
 909 
 910 ```
 911 ## Num.round
 912 
 913 ```tomo
 914 Num.round : func(x: Num -> Num)
 915 ```
 916 
 917 Rounds a number to the nearest whole number integer.
 918 
 919 Argument | Type | Description | Default
 920 ---------|------|-------------|---------
 921 x | `Num` | The number to be rounded.  | -
 922 
 923 **Return:** The nearest integer value of `x`.
 924 
 925 
 926 **Example:**
 927 ```tomo
 928 assert (2.3).round() == 2
 929 assert (2.7).round() == 3
 930 
 931 ```
 932 ## Num.significand
 933 
 934 ```tomo
 935 Num.significand : func(x: Num -> Num)
 936 ```
 937 
 938 Extracts the significand (or mantissa) of a number.
 939 
 940 Argument | Type | Description | Default
 941 ---------|------|-------------|---------
 942 x | `Num` | The number from which to extract the significand.  | -
 943 
 944 **Return:** The significand of `x`.
 945 
 946 
 947 **Example:**
 948 ```tomo
 949 assert (1234.567).significand() == 1.2056318359375
 950 
 951 ```
 952 ## Num.sin
 953 
 954 ```tomo
 955 Num.sin : func(x: Num -> Num)
 956 ```
 957 
 958 Computes the sine of a number (angle in radians).
 959 
 960 Argument | Type | Description | Default
 961 ---------|------|-------------|---------
 962 x | `Num` | The angle in radians.  | -
 963 
 964 **Return:** The sine of `x`.
 965 
 966 
 967 **Example:**
 968 ```tomo
 969 assert (0.0).sin() == 0
 970 
 971 ```
 972 ## Num.sinh
 973 
 974 ```tomo
 975 Num.sinh : func(x: Num -> Num)
 976 ```
 977 
 978 Computes the hyperbolic sine of a number.
 979 
 980 Argument | Type | Description | Default
 981 ---------|------|-------------|---------
 982 x | `Num` | The number for which the hyperbolic sine is to be calculated.  | -
 983 
 984 **Return:** The hyperbolic sine of `x`.
 985 
 986 
 987 **Example:**
 988 ```tomo
 989 assert (0.0).sinh() == 0
 990 
 991 ```
 992 ## Num.sqrt
 993 
 994 ```tomo
 995 Num.sqrt : func(x: Num -> Num)
 996 ```
 997 
 998 Computes the square root of a number.
 999 
1000 Argument | Type | Description | Default
1001 ---------|------|-------------|---------
1002 x | `Num` | The number for which the square root is to be calculated.  | -
1003 
1004 **Return:** The square root of `x`.
1005 
1006 
1007 **Example:**
1008 ```tomo
1009 assert (16.0).sqrt() == 4
1010 
1011 ```
1012 ## Num.tan
1013 
1014 ```tomo
1015 Num.tan : func(x: Num -> Num)
1016 ```
1017 
1018 Computes the tangent of a number (angle in radians).
1019 
1020 Argument | Type | Description | Default
1021 ---------|------|-------------|---------
1022 x | `Num` | The angle in radians.  | -
1023 
1024 **Return:** The tangent of `x`.
1025 
1026 
1027 **Example:**
1028 ```tomo
1029 assert (0.0).tan() == 0
1030 
1031 ```
1032 ## Num.tanh
1033 
1034 ```tomo
1035 Num.tanh : func(x: Num -> Num)
1036 ```
1037 
1038 Computes the hyperbolic tangent of a number.
1039 
1040 Argument | Type | Description | Default
1041 ---------|------|-------------|---------
1042 x | `Num` | The number for which the hyperbolic tangent is to be calculated.  | -
1043 
1044 **Return:** The hyperbolic tangent of `x`.
1045 
1046 
1047 **Example:**
1048 ```tomo
1049 assert (0.0).tanh() == 0
1050 
1051 ```
1052 ## Num.tgamma
1053 
1054 ```tomo
1055 Num.tgamma : func(x: Num -> Num)
1056 ```
1057 
1058 Computes the gamma function of a number.
1059 
1060 Argument | Type | Description | Default
1061 ---------|------|-------------|---------
1062 x | `Num` | The number for which the gamma function is to be calculated.  | -
1063 
1064 **Return:** The gamma function of `x`.
1065 
1066 
1067 **Example:**
1068 ```tomo
1069 assert (1.0).tgamma() == 1
1070 
1071 ```
1072 ## Num.trunc
1073 
1074 ```tomo
1075 Num.trunc : func(x: Num -> Num)
1076 ```
1077 
1078 Truncates a number to the nearest integer towards zero.
1079 
1080 Argument | Type | Description | Default
1081 ---------|------|-------------|---------
1082 x | `Num` | The number to be truncated.  | -
1083 
1084 **Return:** The integer part of `x` towards zero.
1085 
1086 
1087 **Example:**
1088 ```tomo
1089 assert (3.7).trunc() == 3
1090 assert (-3.7).trunc() == -3
1091 
1092 ```
1093 ## Num.with_precision
1094 
1095 ```tomo
1096 Num.with_precision : func(n: Num, precision: Num -> Num)
1097 ```
1098 
1099 Round a number to the given precision level (specified as `10`, `.1`, `.001` etc).
1100 
1101 Argument | Type | Description | Default
1102 ---------|------|-------------|---------
1103 n | `Num` | The number to be rounded to a given precision.  | -
1104 precision | `Num` | The precision to which the number should be rounded.  | -
1105 
1106 **Return:** The number, rounded to the given precision level.
1107 
1108 
1109 **Example:**
1110 ```tomo
1111 assert (0.1234567).with_precision(0.01) == 0.12
1112 assert (123456.).with_precision(100) == 123500
1113 assert (1234567.).with_precision(5) == 1234565
1114 
1115 ```
1116 ## Num.y0
1117 
1118 ```tomo
1119 Num.y0 : func(x: Num -> Num)
1120 ```
1121 
1122 Computes the Bessel function of the second kind of order 0.
1123 
1124 Argument | Type | Description | Default
1125 ---------|------|-------------|---------
1126 x | `Num` | The number for which the Bessel function is to be calculated.  | -
1127 
1128 **Return:** The Bessel function of the second kind of order 0 of `x`.
1129 
1130 
1131 **Example:**
1132 ```tomo
1133 assert (1.0).y0().near(0.08825696421567698)
1134 
1135 ```
1136 ## Num.y1
1137 
1138 ```tomo
1139 Num.y1 : func(x: Num -> Num)
1140 ```
1141 
1142 Computes the Bessel function of the second kind of order 1.
1143 
1144 Argument | Type | Description | Default
1145 ---------|------|-------------|---------
1146 x | `Num` | The number for which the Bessel function is to be calculated.  | -
1147 
1148 **Return:** The Bessel function of the second kind of order 1 of `x`.
1149 
1150 
1151 **Example:**
1152 ```tomo
1153 assert (1.0).y1().near(-0.7812128213002887)
1154 
1155 ```