Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Float(3)	      User Contributed Perl Documentation	Data::Float(3)

NAME
       Data::Float - details of	the floating point data	type

SYNOPSIS
	   use Data::Float qw(have_signed_zero);

	   if(have_signed_zero)	{ ...

	   # and many other constants; see text

	   use Data::Float qw(
	       float_class float_is_normal float_is_subnormal
	       float_is_nzfinite float_is_zero float_is_finite
	       float_is_infinite float_is_nan);

	   $class = float_class($value);

	   if(float_is_normal($value)) { ...
	   if(float_is_subnormal($value)) { ...
	   if(float_is_nzfinite($value)) { ...
	   if(float_is_zero($value)) { ...
	   if(float_is_finite($value)) { ...
	   if(float_is_infinite($value)) { ...
	   if(float_is_nan($value)) { ...

	   use Data::Float qw(float_sign signbit float_parts);

	   $sign = float_sign($value);
	   $sign_bit = signbit($value);
	   ($sign, $exponent, $significand) = float_parts($value);

	   use Data::Float qw(float_hex	hex_float);

	   print float_hex($value);
	   $value = hex_float($string);

	   use Data::Float qw(float_id_cmp totalorder);

	   @sorted_floats = sort { float_id_cmp($a, $b)	} @floats;
	   if(totalorder($a, $b)) { ...

	   use Data::Float qw(
	       pow2 mult_pow2 copysign nextup nextdown nextafter);

	   $x =	pow2($exp);
	   $x =	mult_pow2($value, $exp);
	   $x =	copysign($magnitude, $sign_from);
	   $x =	nextup($x);
	   $x =	nextdown($x);
	   $x =	nextafter($x, $direction);

DESCRIPTION
       This module is about the	native floating	point numerical	data type.  A
       floating	point number is	one of the types of datum that can appear in
       the numeric part	of a Perl scalar.  This	module supplies	constants
       describing the native floating point type, classification functions,
       and functions to	manipulate floating point values at a low level.

FLOATING POINT
   Classification
       Floating	point values are divided into five subtypes:

       normalised
	   The value is	made up	of a sign bit (making the value	positive or
	   negative), a	significand, and exponent.  The	significand is a
	   number in the range [1, 2), expressed as a binary fraction of a
	   certain fixed length.  (Significands	requiring a longer binary
	   fraction, or	lacking	a terminating binary representation, cannot be
	   obtained.)  The exponent is an integer in a certain fixed range.
	   The magnitude of the	value represented is the product of the
	   significand and two to the power of the exponent.

       subnormal
	   The value is	made up	of a sign bit, significand, and	exponent, as
	   for normalised values.  However, the	exponent is fixed at the
	   minimum possible for	a normalised value, and	the significand	is in
	   the range (0, 1).  The length of the	significand is the same	as for
	   normalised values.  This is essentially a fixed-point format, used
	   to provide gradual underflow.  Not all floating point formats
	   support this	subtype.  Where	it is not supported, underflow is
	   sudden, and the difference between two minimum-exponent normalised
	   values cannot be exactly represented.

       zero
	   Depending on	the floating point type, there may be either one or
	   two zero values: zeroes may carry a sign bit.  Where	zeroes are
	   signed, it is primarily in order to indicate	the direction from
	   which a value underflowed (was rounded) to zero.  Positive and
	   negative zero compare as numerically	equal, and they	give identical
	   results in most arithmetic operations.  They	are on opposite	sides
	   of some branch cuts in complex arithmetic.

       infinite
	   Some	floating point formats include special infinite	values.	 These
	   are generated by overflow, and by some arithmetic cases that
	   mathematically generate infinities.	There are two infinite values:
	   positive infinity and negative infinity.

	   Perl	does not always	generate infinite values when normal floating
	   point behaviour calls for it.  For example, the division "1.0/0.0"
	   causes an exception rather than returning an	infinity.

       not-a-number (NaN)
	   This	type of	value exists in	some floating point formats to
	   indicate error conditions.  Mathematically undefined	operations may
	   generate NaNs, and NaNs propagate through all arithmetic
	   operations.	A NaN has the distinctive property of comparing
	   numerically unequal to all floating point values, including itself.

	   Perl	does not always	generate NaNs when normal floating point
	   behaviour calls for it.  For	example, the division "0.0/0.0"	causes
	   an exception	rather than returning a	NaN.

	   Perl	has only (at most) one NaN value, even if the underlying
	   system supports different NaNs.  (IEEE 754 arithmetic has NaNs
	   which carry a quiet/signal bit, a sign bit (yes, a sign on a	not-
	   number), and	many bits of implementation-defined data.)

   Mixing floating point and integer values
       Perl does not draw a strong type	distinction between native integer
       (see Data::Integer) and native floating point values.  Both types of
       value can be stored in the numeric part of a plain (string) scalar.  No
       distinction is made between the integer representation and the floating
       point representation where they encode identical	values.	 Thus, for
       floating	point arithmetic, native integer values	that can be
       represented exactly in floating point may be freely used	as floating
       point values.

       Native integer arithmetic has exactly one zero value, which has no
       sign.  If the floating point type does not have signed zeroes then the
       floating	point and integer zeroes are exactly equivalent.  If the
       floating	point type does	have signed zeroes then	the integer zero can
       still be	used in	floating point arithmetic, and it behaves as an
       unsigned	floating point zero.  On such systems there are	therefore
       three types of zero available.  There is	a bug in Perl which sometimes
       causes floating point zeroes to change into integer zeroes; see "BUGS"
       for details.

       Where a native integer value is used that is too	large to exactly
       represent in floating point, it will be rounded as necessary to a
       floating	point value.  This rounding will occur whenever	an operation
       has to be performed in floating point because the result	could not be
       exactly represented as an integer.  This	may be confusing to functions
       that expect a floating point argument.

       Similarly, some operations on floating point numbers will actually be
       performed in integer arithmetic,	and may	result in values that cannot
       be exactly represented in floating point.  This happens whenever	the
       arguments have integer values that fit into the native integer type and
       the mathematical	result can be exactly represented as a native integer.
       This may	be confusing in	cases where floating point semantics are
       expected.

       See perlnumber(1) for discussion	of Perl's numeric semantics.

CONSTANTS
   Features
       have_signed_zero
	   Truth value indicating whether floating point zeroes	carry a	sign.
	   If yes, then	there are two floating point zero values: +0.0 and
	   -0.0.  (Perl	scalars	can nevertheless also hold an integer zero,
	   which is unsigned.)	If no, then there is only one zero value,
	   which is unsigned.

       have_subnormal
	   Truth value indicating whether there	are subnormal floating point
	   values.

       have_infinite
	   Truth value indicating whether there	are infinite floating point
	   values.

       have_nan
	   Truth value indicating whether there	are NaN	floating point values.

	   It is difficult to reliably generate	a NaN in Perl, so in some
	   unlikely circumstances it is	possible that there might be NaNs that
	   this	module failed to detect.  In that case this constant would be
	   false but a NaN might still turn up somewhere.  What	this constant
	   reliably indicates is the availability of the "nan" constant	below.

   Extrema
       significand_bits
	   The number of fractional bits in the	significand of finite floating
	   point values.  The significand also has an implicit integer bit,
	   not counted in this constant; the integer bit is always 1 for
	   normalised values and always	0 for subnormal	values.

       significand_step
	   The difference between adjacent representable values	in the range
	   [1, 2] (where the exponent is zero).	 This is equal to
	   2^-significand_bits.

       max_finite_exp
	   The maximum exponent	permitted for finite floating point values.

       max_finite_pow2
	   The maximum representable power of two.  This is 2^max_finite_exp.

       max_finite
	   The maximum representable finite value.  This is
	   2^(max_finite_exp+1)	- 2^(max_finite_exp-significand_bits).

       max_number
	   The maximum representable number.  This is positive infinity	if
	   there are infinite values, or max_finite if there are not.

       max_integer
	   The maximum integral	value for which	all integers from zero to that
	   value inclusive are representable.  Equivalently: the minimum
	   positive integral value N for which the value N+1 is	not
	   representable.  This	is 2^(significand_bits+1).  The	name is
	   somewhat misleading.

       min_normal_exp
	   The minimum exponent	permitted for normalised floating point
	   values.

       min_normal
	   The minimum positive	value representable as a normalised floating
	   point value.	 This is 2^min_normal_exp.

       min_finite_exp
	   The base two	logarithm of the minimum representable positive	finite
	   value.  If there are	subnormals then	this is	min_normal_exp -
	   significand_bits.  If there are no subnormals then this is
	   min_normal_exp.

       min_finite
	   The minimum representable positive finite value.  This is
	   2^min_finite_exp.

   Special Values
       pos_zero
	   The positive	zero value.  (Exists only if zeroes are	signed,	as
	   indicated by	the "have_signed_zero" constant.)

	   If Perl is at risk of transforming floating point zeroes into
	   integer zeroes (see "BUGS"),	then this is actually a	non-constant
	   function that always	returns	a fresh	floating point zero.  Thus the
	   return value	is always a true floating point	zero, regardless of
	   what	happened to zeroes previously returned.

       neg_zero
	   The negative	zero value.  (Exists only if zeroes are	signed,	as
	   indicated by	the "have_signed_zero" constant.)

	   If Perl is at risk of transforming floating point zeroes into
	   integer zeroes (see "BUGS"),	then this is actually a	non-constant
	   function that always	returns	a fresh	floating point zero.  Thus the
	   return value	is always a true floating point	zero, regardless of
	   what	happened to zeroes previously returned.

       pos_infinity
	   The positive	infinite value.	 (Exists only if there are infinite
	   values, as indicated	by the "have_infinite" constant.)

       neg_infinity
	   The negative	infinite value.	 (Exists only if there are infinite
	   values, as indicated	by the "have_infinite" constant.)

       nan Not-a-number.  (Exists only if NaN values were detected, as
	   indicated by	the "have_nan" constant.)

FUNCTIONS
       Each "float_" function takes a floating point argument to operate on.
       The argument must be a native floating point value, or a	native integer
       with a value that can be	represented in floating	point.	Giving a non-
       numeric argument	will cause mayhem.  See	"is_number" in
       Params::Classify	for a way to check for numericness.  Only the numeric
       value of	the scalar is used; the	string value is	completely ignored, so
       dualvars	are not	a problem.

   Classification
       Each "float_is_"	function returns a simple truth	value result.

       float_class(VALUE)
	   Determines which of the five	classes	described above	VALUE falls
	   into. Returns "NORMAL", "SUBNORMAL",	"ZERO",	"INFINITE", or "NAN"
	   accordingly.

       float_is_normal(VALUE)
	   Returns true	iff VALUE is a normalised floating point value.

       float_is_subnormal(VALUE)
	   Returns true	iff VALUE is a subnormal floating point	value.

       float_is_nzfinite(VALUE)
	   Returns true	iff VALUE is a non-zero	finite value (either normal or
	   subnormal; not zero,	infinite, or NaN).

       float_is_zero(VALUE)
	   Returns true	iff VALUE is a zero.  If zeroes	are signed then	the
	   sign	is irrelevant.

       float_is_finite(VALUE)
	   Returns true	iff VALUE is a finite value (either normal, subnormal,
	   or zero; not	infinite or NaN).

       float_is_infinite(VALUE)
	   Returns true	iff VALUE is an	infinity (either positive infinity or
	   negative infinity).

       float_is_nan(VALUE)
	   Returns true	iff VALUE is a NaN.

   Examination
       float_sign(VALUE)
	   Returns "+" or "-" to indicate the sign of VALUE.  An unsigned zero
	   returns the sign "+".  "die"s if VALUE is a NaN.

       signbit(VALUE)
	   VALUE must be a floating point value.  Returns the sign bit of
	   VALUE: 0 if VALUE is	positive or a positive or unsigned zero, or 1
	   if VALUE is negative	or a negative zero.  Returns an	unpredictable
	   value if VALUE is a NaN.

	   This	is an IEEE 754 standard	function.  According to	the standard
	   NaNs	have a well-behaved sign bit, but Perl can't see that bit.

       float_parts(VALUE)
	   Divides up a	non-zero finite	floating point value into sign,
	   exponent, and significand, returning	these as a three-element list
	   in that order.  The significand is returned as a floating point
	   value, in the range [1, 2) for normalised values, and in the	range
	   (0, 1) for subnormals.  "die"s if VALUE is not finite and non-zero.

   String conversion
       float_hex(VALUE[, OPTIONS])
	   Encodes the exact value of VALUE as a hexadecimal fraction,
	   returning the fraction as a string.	Specifically, for finite
	   values the output is	of the form "s0xm.mmmmmpeee", where "s"	is the
	   sign, "m.mmmm" is the significand in	hexadecimal, and "eee" is the
	   exponent in decimal with a sign.

	   The details of the output format are	very configurable.  If OPTIONS
	   is supplied,	it must	be a reference to a hash, in which these keys
	   may be present:

	   exp_digits
	       The number of digits of exponent	to show, unless	this is
	       modified	by exp_digits_range_mod	or more	are required to	show
	       the exponent exactly.  (The exponent is always shown in full.)
	       Default 0, so the minimum possible number of digits is used.

	   exp_digits_range_mod
	       Modifies	the number of exponent digits to show, based on	the
	       number of digits	required to show the full range	of exponents
	       for normalised and subnormal values.  If	"IGNORE" then nothing
	       is done.	 If "ATLEAST" then at least this many digits are
	       shown.  Default "IGNORE".

	   exp_neg_sign
	       The string that is prepended to a negative exponent.  Default
	       "-".

	   exp_pos_sign
	       The string that is prepended to a non-negative exponent.
	       Default "+".  Make it the empty string to suppress the positive
	       sign.

	   frac_digits
	       The number of fractional	digits to show,	unless this is
	       modified	by frac_digits_bits_mod	or frac_digits_value_mod.
	       Default 0, but by default this gets modified.

	   frac_digits_bits_mod
	       Modifies	the number of fractional digits	to show, based on the
	       length of the significand.  There is a certain number of	digits
	       that is the minimum required to explicitly state	every bit that
	       is stored, and the number of digits to show might get set to
	       that number depending on	this option.  If "IGNORE" then nothing
	       is done.	 If "ATLEAST" then at least this many digits are
	       shown.  If "ATMOST" then	at most	this many digits are shown.
	       If "EXACTLY" then exactly this many digits are shown.  Default
	       "ATLEAST".

	   frac_digits_value_mod
	       Modifies	the number of fractional digits	to show, based on the
	       number of digits	required to show the actual value exactly.
	       Works the same way as frac_digits_bits_mod.  Default "ATLEAST".

	   hex_prefix_string
	       The string that is prefixed to hexadecimal digits.  Default
	       "0x".  Make it the empty	string to suppress the prefix.

	   infinite_string
	       The string that is returned for an infinite magnitude.  Default
	       "inf".

	   nan_string
	       The string that is returned for a NaN value.  Default "nan".

	   neg_sign
	       The string that is prepended to a negative value	(including
	       negative	zero).	Default	"-".

	   pos_sign
	       The string that is prepended to a positive value	(including
	       positive	or unsigned zero).  Default "+".  Make it the empty
	       string to suppress the positive sign.

	   subnormal_strategy
	       The manner in which subnormal values are	displayed.  If
	       "SUBNORMAL", they are shown with	the minimum exponent for
	       normalised values and a significand in the range	(0, 1).	 This
	       matches how they	are stored internally.	If "NORMAL", they are
	       shown with a significand	in the range [1, 2) and	a lower
	       exponent, as if they were normalised.  This gives a consistent
	       appearance for magnitudes regardless of normalisation.  Default
	       "SUBNORMAL".

	   zero_strategy
	       The manner in which zero	values are displayed.  If
	       "STRING=str", the string	str is used, preceded by a sign.  If
	       "SUBNORMAL", it is shown	with significand zero and the minimum
	       normalised exponent.  If	"EXPONENT=exp",	it is shown with
	       significand zero	and exponent exp.  Default "STRING=0.0".  An
	       unsigned	zero is	treated	as having a positive sign.

       hex_float(STRING)
	   Generates and returns a floating point value	from a string encoding
	   it in hexadecimal.  The standard input form is
	   "[s][0x]m[.mmmmm][peee]", where "s" is the sign, "m[.mmmm]" is a
	   (fractional)	hexadecimal number, and	"eee" an optionally-signed
	   exponent in decimal.	 If present, the exponent identifies a power
	   of two (not sixteen)	by which the given fraction will be
	   multiplied.

	   If the value	given in the string cannot be exactly represented in
	   the floating	point type because it has too many fraction bits, the
	   nearest representable value is returned, with ties broken in	favour
	   of the value	with a zero low-order bit.  If the value given is too
	   large to exactly represent then an infinity is returned, or the
	   largest finite value	if there are no	infinities.

	   Additional input formats are	accepted for special values.
	   "[s]inf[inity]" returns an infinity,	or "die"s if there are no
	   infinities.	"[s][s]nan" returns a NaN, or "die"s if	there are no
	   NaNs	available.

	   All input formats are understood case insensitively.	 The function
	   correctly interprets	all possible outputs from "float_hex" with
	   default settings.

   Comparison
       float_id_cmp(A, B)
	   This	is a comparison	function supplying a total ordering of
	   floating point values.  A and B must	both be	floating point values.
	   Returns -1, 0, or +1, indicating whether A is to be sorted before,
	   the same as,	or after B.

	   The ordering	is of the identities of	floating point values, not
	   their numerical values.  If zeroes are signed, then the two types
	   are considered to be	distinct.  NaNs	compare	equal to each other,
	   but different from all numeric values.  The exact ordering provided
	   is mostly numerical order: NaNs come	first, followed	by negative
	   infinity, then negative finite values, then negative	zero, then
	   positive (or	unsigned) zero,	then positive finite values, then
	   positive infinity.

	   In addition to sorting, this	function can be	useful to check	for a
	   zero	of a particular	sign.

       totalorder(A, B)
	   This	is a comparison	function supplying a total ordering of
	   floating point values.  A and B must	both be	floating point values.
	   Returns a truth value indicating whether A is to be sorted before-
	   or-the-same-as B.  That is, it is a <= predicate on the total
	   ordering.  The ordering is the same as that provided	by
	   "float_id_cmp": NaNs	come first, followed by	negative infinity,
	   then	negative finite	values,	then negative zero, then positive (or
	   unsigned) zero, then	positive finite	values,	then positive
	   infinity.

	   This	is an IEEE 754r	standard function.  According to the standard
	   it is meant to distinguish different	kinds of NaNs, based on	their
	   sign	bit, quietness,	and payload, but this function (like the rest
	   of Perl) perceives only one NaN.

   Manipulation
       pow2(EXP)
	   EXP must be an integer.  Returns the	value two the the power	EXP.
	   "die"s if that value	cannot be represented exactly as a floating
	   point value.	 The return value may be either	normalised or
	   subnormal.

       mult_pow2(VALUE,	EXP)
	   EXP must be an integer, and VALUE a floating	point value.
	   Multiplies VALUE by two to the power	EXP.  This gives exact
	   results, except in cases of underflow and overflow.	The range of
	   EXP is not constrained.  All	normal floating	point multiplication
	   behaviour applies.

       copysign(VALUE, SIGN_FROM)
	   VALUE and SIGN_FROM must both be floating point values.  Returns a
	   floating point value	with the magnitude of VALUE and	the sign of
	   SIGN_FROM.  If SIGN_FROM is an unsigned zero	then it	is treated as
	   positive.  If VALUE is an unsigned zero then	it is returned
	   unchanged.  If VALUE	is a NaN then it is returned unchanged.	 If
	   SIGN_FROM is	a NaN then the sign copied to VALUE is unpredictable.

	   This	is an IEEE 754 standard	function.  According to	the standard
	   NaNs	have a well-behaved sign bit, which can	be read	and modified
	   by this function, but Perl only perceives one NaN and can't see its
	   sign	bit, so	behaviour on NaNs is not standard-conforming.

       nextup(VALUE)
	   VALUE must be a floating point value.  Returns the next
	   representable floating point	value adjacent to VALUE	with a
	   numerical value that	is strictly greater than VALUE,	or returns
	   VALUE unchanged if there is no such value.  Infinite	values are
	   regarded as being adjacent to the largest representable finite
	   values.  Zero counts	as one value, even if it is signed, and	it is
	   adjacent to the smallest representable positive and negative	finite
	   values.  If a zero is returned, because VALUE is the	smallest
	   representable negative value, and zeroes are	signed,	it is a
	   negative zero that is returned.  Returns NaN	if VALUE is a NaN.

	   This	is an IEEE 754r	standard function.

       nextdown(VALUE)
	   VALUE must be a floating point value.  Returns the next
	   representable floating point	value adjacent to VALUE	with a
	   numerical value that	is strictly less than VALUE, or	returns	VALUE
	   unchanged if	there is no such value.	 Infinite values are regarded
	   as being adjacent to	the largest representable finite values.  Zero
	   counts as one value,	even if	it is signed, and it is	adjacent to
	   the smallest	representable positive and negative finite values.  If
	   a zero is returned, because VALUE is	the smallest representable
	   positive value, and zeroes are signed, it is	a positive zero	that
	   is returned.	 Returns NaN if	VALUE is a NaN.

	   This	is an IEEE 754r	standard function.

       nextafter(VALUE,	DIRECTION)
	   VALUE and DIRECTION must both be floating point values.  Returns
	   the next representable floating point value adjacent	to VALUE in
	   the direction of DIRECTION, or returns DIRECTION if it is
	   numerically equal to	VALUE.	Infinite values	are regarded as	being
	   adjacent to the largest representable finite	values.	 Zero counts
	   as one value, even if it is signed, and it is adjacent to the
	   positive and	negative smallest representable	finite values.	If a
	   zero	is returned and	zeroes are signed then it has the same sign as
	   VALUE.  Returns NaN if either argument is a NaN.

	   This	is an IEEE 754 standard	function.

BUGS
       As of Perl 5.8.7	floating point zeroes will be partially	transformed
       into integer zeroes if used in almost any arithmetic, including
       numerical comparisons.  Such a transformed zero appears as a floating
       point zero (with	its original sign) for some purposes, but behaves as
       an integer zero for other purposes.  Where this happens to a positive
       zero the	result is indistinguishable from a true	integer	zero.  Where
       it happens to a negative	zero the result	is a fourth type of zero, the
       existence of which is a bug in Perl.  This fourth type of zero will
       give confusing results, and in particular will elicit inconsistent
       behaviour from the functions in this module.

       Because of this transforming behaviour, it is best to avoid relying on
       the sign	of zeroes.  If you require signed-zero semantics then take
       special care to maintain	signedness.  Avoid using a zero	directly in
       arithmetic and handle it	as a special case.  Any	flavour	of zero	can be
       accurately copied from one scalar to another without affecting the
       original.  The functions	in this	module all avoid modifying their
       arguments, and where they are meant to return signed zeroes they	always
       return a	pristine one.

       As of Perl 5.8.7	stringification	of a floating point zero does not
       preserve	its signedness.	 The number-to-string-to-number	round trip
       turns a positive	floating point zero into an integer zero, but
       accurately maintains negative and integer zeroes.  If a negative	zero
       gets partially transformed into an integer zero,	as described above,
       the stringification that	it gets	is based on its	state at the first
       occasion	on which the scalar was	stringified.

       NaN handling is generally not well defined in Perl.  Arithmetic with a
       mathematically undefined	result may either "die"	or generate a NaN.
       Avoid relying on	any particular behaviour for such operations, even if
       your hardware's behaviour is known.

       As of Perl 5.8.7	the % operator truncates its arguments to integers, if
       the divisor is within the range of the native integer type.  It
       therefore operates correctly on non-integer values only when the
       divisor is very large.

SEE ALSO
       Data::Integer, Scalar::Number, perlnumber(1)

AUTHOR
       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT
       Copyright (C) 2006, 2007, 2008, 2010, 2012, 2017	Andrew Main (Zefram)
       <zefram@fysh.org>

LICENSE
       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2020-08-08			Data::Float(3)

NAME | SYNOPSIS | DESCRIPTION | FLOATING POINT | CONSTANTS | FUNCTIONS | BUGS | SEE ALSO | AUTHOR | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Float&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help