=encoding utf8
=head1 NAME
POSIX::1003::Math - POSIX handling time
=head1 INHERITANCE
POSIX::1003::Math
is a POSIX::1003::Module
=head1 SYNOPSIS
use POSIX::1003::Math qw/ceil floor sqrt/;
print ceil 3.14;
print sqrt floor 4.9;
=head1 DESCRIPTION
B<Be aware> that math in Perl has unclear precission! Be aware that the
math library often provides many variations of these functions... it is
hard to determine which one is used. Probably, Math::Trig will serve
you better. Or PDL for real number crunchers.
B<Be warned> that these functions do not have an obligatory scalar
parameter, but only an optional parameter (defaults to C<$_>). This
means that they have the lowest (is list) priority.
See L<documentation in base class|POSIX::1003::Module/"DESCRIPTION">.
=head1 METHODS
See L<documentation in base class|POSIX::1003::Module/"METHODS">.
=over 4
=item POSIX::1003::Math-E<gt>B<exampleValue>(NAME)
See L<POSIX::1003::Module/"METHODS">
=item $obj-E<gt>B<import>()
See L<POSIX::1003::Module/"METHODS">
=back
=head1 FUNCTIONS
=head2 Standard POSIX via this module (via POSIX.xs)
Like the built-in sin, cos, and sqrt, the EXPR defaults to C<$_> and
there is a scalar context (missing from POSIX.pm).
=over 4
=item B<acos>(EXPR)
=item B<asin>(EXPR)
=item B<atan>(EXPR)
=item B<ceil>(EXPR)
=item B<cosh>(EXPR)
=item B<div>(NUMER, DENOM)
Devide NUMER by DENOminator. The result is a list of two: quotient and
remainder. Implemented in Perl for completeness, currently not with the
speed of XS.
my ($quotient, $remainder) = div($number, $denom);
=item B<floor>(EXPR)
=item B<fmod>(EXPR, EXPR)
=item B<frexp>(EXPR)
=item B<ldexp>(EXPR)
=item B<log10>(EXPR)
=item B<modf>(EXPR, EXPR)
=item B<pow>(EXPR1, EXPR2)
Returns C<EXPR1 ** EXPR2>
=item B<rint>(NUMBER)
Round to the closest integer. Implemented in Perl for completeness.
=item B<sinh>(EXPR)
=item B<tan>(EXPR)
=item B<tanh>(EXPR)
=back
=head2 Standard POSIX, using CORE
A small set of mathematical functions are available in Perl CORE,
without the need to load this module. But if you do import them,
it simply gets ignored.
=over 4
=item B<abs>([EXPR])
=item B<atan2>(EXPR, EXPR)
=item B<cos>([EXPR])
=item B<exp>([EXPR])
=item B<log>([EXPR])
=item B<rand>([EXPR])
=item B<sin>([EXPR])
=item B<sqrt>([EXPR])
=item B<srand>([EXPR])
=back
=head2 Numeric conversions
All C<strto*>, C<atof>, C<atoi> and friends functions are usually
not needed in Perl programs: the integer and float types are at their
largest size, so when a string is used in numeric context it will get
converted automatically. Still, POSIX.xs does provide a few of those
functions, which are sometimes more accurate in number parsing for
large numbers.
All three provided functions treat errors the same way. Truly
POSIX-compliant systems set C<$ERRNO> ($!) to indicate a translation
error, so clear C<$!> before calling strto*. Non-compliant systems
may not check for overflow, and therefore will never set C<$!>.
To parse a string C<$str> as a floating point number use
$! = 0;
($num, $n_unparsed) = strtod($str);
if($str eq '' || $n_unparsed != 0 || $!) {
die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
}
# When you do not care about handling errors, you can do
$num = strtod($str);
$num = $str + 0; # same: Perl auto-converts
=over 4
=item B<strtod>(STRING)
String to double translation. Returns the parsed number and the number
of characters in the unparsed portion of the string. When called in a
scalar context C<strtod> returns the parsed number.
=item B<strtol>(STRING, BASE)
String to integer translation. Returns the parsed number and
the number of characters in the unparsed portion of the string.
When called in a scalar context C<strtol> returns the parsed number.
The base should be zero or between 2 and 36, inclusive. When the base
is zero or omitted C<strtol> will use the string itself to determine the
base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
octal; any other leading characters mean decimal. Thus, "1234" is
parsed as a decimal number, "01234" as an octal number, and "0x1234"
as a hexadecimal number.
=item B<strtoul>(STRING, BASE)
String to unsigned integer translation, which behaves like C<strtol>.
=back
=head1 CONSTANTS
The following constants are exported, shown here with the values
discovered during installation of this module:
=for comment
#TABLE_MATH_START
CHAR_BIT 8
CHAR_MAX 127
CHAR_MIN -128
DBL_DIG 15
DBL_EPSILON 2.22044604925031e-16
DBL_MANT_DIG 53
DBL_MAX 1.79769313486232e+308
DBL_MAX_10_EXP 308
DBL_MAX_EXP 1024
DBL_MIN 2.2250738585072e-308
DBL_MIN_10_EXP -307
DBL_MIN_EXP -1021
FLT_DIG 6
FLT_EPSILON 1.19209289550781e-07
FLT_MANT_DIG 24
FLT_MAX 3.40282346638529e+38
FLT_MAX_10_EXP 38
FLT_MAX_EXP 128
FLT_MIN 1.17549435082229e-38
FLT_MIN_10_EXP -37
FLT_MIN_EXP -125
FLT_RADIX 2
FLT_ROUNDS 1
HUGE_VAL inf
INT_MAX 2147483647
INT_MIN -2147483648
LDBL_DIG 18
LDBL_EPSILON undef
LDBL_MANT_DIG 64
LDBL_MAX undef
LDBL_MAX_10_EXP 4932
LDBL_MAX_EXP 16384
LDBL_MIN undef
LDBL_MIN_10_EXP -4931
LDBL_MIN_EXP -16381
LONG_MAX 9223372036854775807
LONG_MIN -9223372036854775808
RAND_MAX 2147483647
SCHAR_MAX 127
SCHAR_MIN -128
SHRT_MAX 32767
SHRT_MIN -32768
UCHAR_MAX 255
UINT_MAX 4294967295
ULONG_MAX 18446744073709551615
USHRT_MAX 65535
=for comment
#TABLE_MATH_END
=head1 SEE ALSO
This module is part of POSIX-1003 distribution version 0.94_2,
built on May 17, 2013. Website: F<http://perl.overmeer.net>. The code is based on L<POSIX>, which
is released with Perl itself. See also L<POSIX::Util> for
additional functionality.
=head1 COPYRIGHTS
Copyrights 2011-2013 on the perl code and the related documentation
by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>