txt: ## dist_zef-lizmat-P5math.md
  [![Actions Status](https://github.com/lizmat/P5math/workflows/test/badge.svg)](https://github.com/lizmat/P5math/actions)
  
  # NAME
  
  Raku port of Perl's math built-ins
  
  # SYNOPSIS
  
  ```
  use P5math; # exports abs cos crypt exp int log rand sin sqrt
  
  ```
  
  # DESCRIPTION
  
  This module tries to mimic the behaviour of Perl's `abs`, `cos`, `crypt`, `exp`, `int`, `log`, `rand`, `sin` and `sqrt` builtins as closely as possible in the Raku Programming Language..
  
  # ORIGINAL PERL 5 DOCUMENTATION
  
  ```
  abs VALUE
  abs     Returns the absolute value of its argument. If VALUE is omitted,
          uses $_.
  
  cos EXPR
  cos     Returns the cosine of EXPR (expressed in radians). If EXPR is
          omitted, takes the cosine of $_.
  
          For the inverse cosine operation, you may use the
          "Math::Trig::acos()" function, or use this relation:
  
              sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
  
  crypt PLAINTEXT,SALT
          Creates a digest string exactly like the crypt(3) function in the
          C library (assuming that you actually have a version there that
          has not been extirpated as a potential munition).
  
          crypt() is a one-way hash function. The PLAINTEXT and SALT are
          turned into a short string, called a digest, which is returned.
          The same PLAINTEXT and SALT will always return the same string,
          but there is no (known) way to get the original PLAINTEXT from the
          hash. Small changes in the PLAINTEXT or SALT will result in large
          changes in the digest.
  
          There is no decrypt function. This function isn't all that useful
          for cryptography (for that, look for Crypt modules on your nearby
          CPAN mirror) and the name "crypt" is a bit of a misnomer. Instead
          it is primarily used to check if two pieces of text are the same
          without having to transmit or store the text itself. An example is
          checking if a correct password is given. The digest of the
          password is stored, not the password itself. The user types in a
          password that is crypt()'d with the same salt as the stored
          digest. If the two digests match, the password is correct.
  
          When verifying an existing digest string you should use the digest
          as the salt (like "crypt($plain, $digest) eq $digest"). The SALT
          used to create the digest is visible as part of the digest. This
          ensures crypt() will hash the new string with the same salt as the
          digest. This allows your code to work with the standard crypt and
          with more exotic implementations. In other words, assume nothing
          about the returned string itself nor about how many bytes of SALT
          may matter.
  
          Traditionally the result is a string of 13 bytes: two first bytes
          of the salt, followed by 11 bytes from the set "[./0-9A-Za-z]",
          and only the first eight bytes of PLAINTEXT mattered. But
          alternative hashing schemes (like MD5), higher level security
          schemes (like C2), and implementations on non-Unix platforms may
          produce different strings.
  
          When choosing a new salt create a random two character string
          whose characters come from the set "[./0-9A-Za-z]" (like "join '',
          ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]"). This set
          of characters is just a recommendation; the characters allowed in
          the salt depend solely on your system's crypt library, and Perl
          can't restrict what salts "crypt()" accepts.
  
          Here's an example that makes sure that whoever runs this program
          knows their password:
  
              $pwd = (getpwuid($<))[1];
  
              system "stty -echo";
              print "Password: ";
              chomp($word = <STDIN>);
              print "\n";
              system "stty echo";
  
              if (crypt($word, $pwd) ne $pwd) {
                  die "Sorry...\n";
              } else {
                  print "ok\n";
              }
  
          Of course, typing in your own password to whoever asks you for it
          is unwise.
  
          The crypt function is unsuitable for hashing large quantities of
          data, not least of all because you can't get the information back.
          Look at the Digest module for more robust algorithms.
  
          If using crypt() on a Unicode string (which potentially has
          characters with codepoints above 255), Perl tries to make sense of
          the situation by trying to downgrade (a copy of) the string back
          to an eight-bit byte string before calling crypt() (on that copy).
          If that works, good. If not, crypt() dies with "Wide character in
          crypt".
  
          Portability issues: "crypt" in perlport.
  
  exp EXPR
  exp     Returns me (the natural logarithm base) to the power of EXPR. If
          EXPR is omitted, gives "exp($_)".
  
  int EXPR
  int     Returns the integer portion of EXPR. If EXPR is omitted, uses $_.
          You should not use this function for rounding: one because it
          truncates towards 0, and two because machine representations of
          floating-point numbers can sometimes produce counterintuitive
          results. For example, "int(-6.725/0.025)" produces -268 rather
          than the correct -269; that's because it's really more like
          -268.99999999999994315658 instead. Usually, the "sprintf",
          "printf", or the "POSIX::floor" and "POSIX::ceil" functions will
          serve you better than will int().
  
  log EXPR
  log     Returns the natural logarithm (base e) of EXPR. If EXPR is
          omitted, returns the log of $_. To get the log of another base,
          use basic algebra: The base-N log of a number is equal to the
          natural log of that number divided by the natural log of N. For
          example:
  
              sub log10 {
                  my $n = shift;
                  return log($n)/log(10);
              }
  
          See also "exp" for the inverse operation.
  
  rand EXPR
  rand    Returns a random fractional number greater than or equal to 0 and
          less than the value of EXPR. (EXPR should be positive.) If EXPR is
          omitted, the value 1 is used. Currently EXPR with the value 0 is
          also special-cased as 1 (this was undocumented before Perl 5.8.0
          and is subject to change in future versions of Perl).
          Automatically calls "srand" unless "srand" has already been
          called. See also "srand".
  
          Apply "int()" to the value returned by "rand()" if you want random
          integers instead of random fractional numbers. For example,
  
              int(rand(10))
  
          returns a random integer between 0 and 9, inclusive.
  
          (Note: If your rand function consistently returns numbers that are
          too large or too small, then your version of Perl was probably
          compiled with the wrong number of RANDBITS.)
  
          "rand()" is not cryptographically secure. You should not rely on
          it in security-sensitive situations. As of this writing, a number
          of third-party CPAN modules offer random number generators
          intended by their authors to be cryptographically secure,
          including: Data::Entropy, Crypt::Random, Math::Random::Secure, and
          Math::TrulyRandom.
  
  sin EXPR
  sin     Returns the sine of EXPR (expressed in radians). If EXPR is
          omitted, returns sine of $_.
  
          For the inverse sine operation, you may use the "Math::Trig::asin"
          function, or use this relation:
  
              sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
  
  sqrt EXPR
  sqrt    Return the positive square root of EXPR. If EXPR is omitted, uses
          $_. Works only for non-negative operands unless you've loaded the
          "Math::Complex" module.
  
              use Math::Complex;
              print sqrt(-4);    # prints 2i
  
  ```
  
  # PORTING CAVEATS
  
  ## Can not use int()
  
  As of this writing (2020.10), it is **not** possible to actually use `int` in your code because of code generation issue caused by the fact that `int` is a built-in native type in Raku.
  
  ## crypt() not supported on all platforms
  
  The `crypt` function will return `Nil` if it is not supported by the OS.
  
  ## $\_ no longer accessible from caller's scope
  
  In future language versions of Raku, it will become impossible to access the `$_` variable of the caller's scope, because it will not have been marked as a dynamic variable. So please consider changing:
  
  ```
  cos;
  
  ```
  
  to either:
  
  ```
  cos($_);
  
  ```
  
  or, using the subroutine as a method syntax, with the prefix `.` shortcut to use that scope's `$_` as the invocant:
  
  ```
  .&cos;
  
  ```
  
  # AUTHOR
  
  Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)
  
  If you like this module, or what I’m doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!
  
  Source can be located at: <https://github.com/lizmat/P5math> . Comments and Pull Requests are welcome.
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2018, 2019, 2020, 2021, 2023 Elizabeth Mattijsen
  
  Re-imagined from Perl as part of the CPAN Butterfly Plan.
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  