1Data::Float(3)        User Contributed Perl Documentation       Data::Float(3)
2
3
4

NAME

6       Data::Float - details of the floating point data type
7

SYNOPSIS

9           use Data::Float qw(have_signed_zero);
10
11           if(have_signed_zero) { ...
12
13           # and many other constants; see text
14
15           use Data::Float qw(
16               float_class float_is_normal float_is_subnormal
17               float_is_nzfinite float_is_zero float_is_finite
18               float_is_infinite float_is_nan);
19
20           $class = float_class($value);
21
22           if(float_is_normal($value)) { ...
23           if(float_is_subnormal($value)) { ...
24           if(float_is_nzfinite($value)) { ...
25           if(float_is_zero($value)) { ...
26           if(float_is_finite($value)) { ...
27           if(float_is_infinite($value)) { ...
28           if(float_is_nan($value)) { ...
29
30           use Data::Float qw(float_sign signbit float_parts);
31
32           $sign = float_sign($value);
33           $sign_bit = signbit($value);
34           ($sign, $exponent, $significand) = float_parts($value);
35
36           use Data::Float qw(float_hex hex_float);
37
38           print float_hex($value);
39           $value = hex_float($string);
40
41           use Data::Float qw(float_id_cmp totalorder);
42
43           @sorted_floats = sort { float_id_cmp($a, $b) } @floats;
44           if(totalorder($a, $b)) { ...
45
46           use Data::Float qw(
47               pow2 mult_pow2 copysign nextup nextdown nextafter);
48
49           $x = pow2($exp);
50           $x = mult_pow2($value, $exp);
51           $x = copysign($magnitude, $sign_from);
52           $x = nextup($x);
53           $x = nextdown($x);
54           $x = nextafter($x, $direction);
55

DESCRIPTION

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

FLOATING POINT

64   Classification
65       Floating point values are divided into five subtypes:
66
67       normalised
68           The value is made up of a sign bit (making the value positive or
69           negative), a significand, and exponent.  The significand is a
70           number in the range [1, 2), expressed as a binary fraction of a
71           certain fixed length.  (Significands requiring a longer binary
72           fraction, or lacking a terminating binary representation, cannot be
73           obtained.)  The exponent is an integer in a certain fixed range.
74           The magnitude of the value represented is the product of the
75           significand and two to the power of the exponent.
76
77       subnormal
78           The value is made up of a sign bit, significand, and exponent, as
79           for normalised values.  However, the exponent is fixed at the
80           minimum possible for a normalised value, and the significand is in
81           the range (0, 1).  The length of the significand is the same as for
82           normalised values.  This is essentially a fixed-point format, used
83           to provide gradual underflow.  Not all floating point formats
84           support this subtype.  Where it is not supported, underflow is
85           sudden, and the difference between two minimum-exponent normalised
86           values cannot be exactly represented.
87
88       zero
89           Depending on the floating point type, there may be either one or
90           two zero values: zeroes may carry a sign bit.  Where zeroes are
91           signed, it is primarily in order to indicate the direction from
92           which a value underflowed (was rounded) to zero.  Positive and
93           negative zero compare as numerically equal, and they give identical
94           results in most arithmetic operations.  They are on opposite sides
95           of some branch cuts in complex arithmetic.
96
97       infinite
98           Some floating point formats include special infinite values.  These
99           are generated by overflow, and by some arithmetic cases that
100           mathematically generate infinities.  There are two infinite values:
101           positive infinity and negative infinity.
102
103           Perl does not always generate infinite values when normal floating
104           point behaviour calls for it.  For example, the division "1.0/0.0"
105           causes an exception rather than returning an infinity.
106
107       not-a-number (NaN)
108           This type of value exists in some floating point formats to
109           indicate error conditions.  Mathematically undefined operations may
110           generate NaNs, and NaNs propagate through all arithmetic
111           operations.  A NaN has the distinctive property of comparing
112           numerically unequal to all floating point values, including itself.
113
114           Perl does not always generate NaNs when normal floating point
115           behaviour calls for it.  For example, the division "0.0/0.0" causes
116           an exception rather than returning a NaN.
117
118           Perl has only (at most) one NaN value, even if the underlying
119           system supports different NaNs.  (IEEE 754 arithmetic has NaNs
120           which carry a quiet/signal bit, a sign bit (yes, a sign on a not-
121           number), and many bits of implementation-defined data.)
122
123   Mixing floating point and integer values
124       Perl does not draw a strong type distinction between native integer
125       (see Data::Integer) and native floating point values.  Both types of
126       value can be stored in the numeric part of a plain (string) scalar.  No
127       distinction is made between the integer representation and the floating
128       point representation where they encode identical values.  Thus, for
129       floating point arithmetic, native integer values that can be
130       represented exactly in floating point may be freely used as floating
131       point values.
132
133       Native integer arithmetic has exactly one zero value, which has no
134       sign.  If the floating point type does not have signed zeroes then the
135       floating point and integer zeroes are exactly equivalent.  If the
136       floating point type does have signed zeroes then the integer zero can
137       still be used in floating point arithmetic, and it behaves as an
138       unsigned floating point zero.  On such systems there are therefore
139       three types of zero available.  There is a bug in Perl which sometimes
140       causes floating point zeroes to change into integer zeroes; see "BUGS"
141       for details.
142
143       Where a native integer value is used that is too large to exactly
144       represent in floating point, it will be rounded as necessary to a
145       floating point value.  This rounding will occur whenever an operation
146       has to be performed in floating point because the result could not be
147       exactly represented as an integer.  This may be confusing to functions
148       that expect a floating point argument.
149
150       Similarly, some operations on floating point numbers will actually be
151       performed in integer arithmetic, and may result in values that cannot
152       be exactly represented in floating point.  This happens whenever the
153       arguments have integer values that fit into the native integer type and
154       the mathematical result can be exactly represented as a native integer.
155       This may be confusing in cases where floating point semantics are
156       expected.
157
158       See perlnumber(1) for discussion of Perl's numeric semantics.
159

CONSTANTS

161   Features
162       have_signed_zero
163           Truth value indicating whether floating point zeroes carry a sign.
164           If yes, then there are two floating point zero values: +0.0 and
165           -0.0.  (Perl scalars can nevertheless also hold an integer zero,
166           which is unsigned.)  If no, then there is only one zero value,
167           which is unsigned.
168
169       have_subnormal
170           Truth value indicating whether there are subnormal floating point
171           values.
172
173       have_infinite
174           Truth value indicating whether there are infinite floating point
175           values.
176
177       have_nan
178           Truth value indicating whether there are NaN floating point values.
179
180           It is difficult to reliably generate a NaN in Perl, so in some
181           unlikely circumstances it is possible that there might be NaNs that
182           this module failed to detect.  In that case this constant would be
183           false but a NaN might still turn up somewhere.  What this constant
184           reliably indicates is the availability of the "nan" constant below.
185
186   Extrema
187       significand_bits
188           The number of fractional bits in the significand of finite floating
189           point values.  The significand also has an implicit integer bit,
190           not counted in this constant; the integer bit is always 1 for
191           normalised values and always 0 for subnormal values.
192
193       significand_step
194           The difference between adjacent representable values in the range
195           [1, 2] (where the exponent is zero).  This is equal to
196           2^-significand_bits.
197
198       max_finite_exp
199           The maximum exponent permitted for finite floating point values.
200
201       max_finite_pow2
202           The maximum representable power of two.  This is 2^max_finite_exp.
203
204       max_finite
205           The maximum representable finite value.  This is
206           2^(max_finite_exp+1) - 2^(max_finite_exp-significand_bits).
207
208       max_number
209           The maximum representable number.  This is positive infinity if
210           there are infinite values, or max_finite if there are not.
211
212       max_integer
213           The maximum integral value for which all integers from zero to that
214           value inclusive are representable.  Equivalently: the minimum
215           positive integral value N for which the value N+1 is not
216           representable.  This is 2^(significand_bits+1).  The name is
217           somewhat misleading.
218
219       min_normal_exp
220           The minimum exponent permitted for normalised floating point
221           values.
222
223       min_normal
224           The minimum positive value representable as a normalised floating
225           point value.  This is 2^min_normal_exp.
226
227       min_finite_exp
228           The base two logarithm of the minimum representable positive finite
229           value.  If there are subnormals then this is min_normal_exp -
230           significand_bits.  If there are no subnormals then this is
231           min_normal_exp.
232
233       min_finite
234           The minimum representable positive finite value.  This is
235           2^min_finite_exp.
236
237   Special Values
238       pos_zero
239           The positive zero value.  (Exists only if zeroes are signed, as
240           indicated by the "have_signed_zero" constant.)
241
242           If Perl is at risk of transforming floating point zeroes into
243           integer zeroes (see "BUGS"), then this is actually a non-constant
244           function that always returns a fresh floating point zero.  Thus the
245           return value is always a true floating point zero, regardless of
246           what happened to zeroes previously returned.
247
248       neg_zero
249           The negative zero value.  (Exists only if zeroes are signed, as
250           indicated by the "have_signed_zero" constant.)
251
252           If Perl is at risk of transforming floating point zeroes into
253           integer zeroes (see "BUGS"), then this is actually a non-constant
254           function that always returns a fresh floating point zero.  Thus the
255           return value is always a true floating point zero, regardless of
256           what happened to zeroes previously returned.
257
258       pos_infinity
259           The positive infinite value.  (Exists only if there are infinite
260           values, as indicated by the "have_infinite" constant.)
261
262       neg_infinity
263           The negative infinite value.  (Exists only if there are infinite
264           values, as indicated by the "have_infinite" constant.)
265
266       nan Not-a-number.  (Exists only if NaN values were detected, as
267           indicated by the "have_nan" constant.)
268

FUNCTIONS

270       Each "float_" function takes a floating point argument to operate on.
271       The argument must be a native floating point value, or a native integer
272       with a value that can be represented in floating point.  Giving a non-
273       numeric argument will cause mayhem.  See "is_number" in
274       Params::Classify for a way to check for numericness.  Only the numeric
275       value of the scalar is used; the string value is completely ignored, so
276       dualvars are not a problem.
277
278   Classification
279       Each "float_is_" function returns a simple truth value result.
280
281       float_class(VALUE)
282           Determines which of the five classes described above VALUE falls
283           into. Returns "NORMAL", "SUBNORMAL", "ZERO", "INFINITE", or "NAN"
284           accordingly.
285
286       float_is_normal(VALUE)
287           Returns true iff VALUE is a normalised floating point value.
288
289       float_is_subnormal(VALUE)
290           Returns true iff VALUE is a subnormal floating point value.
291
292       float_is_nzfinite(VALUE)
293           Returns true iff VALUE is a non-zero finite value (either normal or
294           subnormal; not zero, infinite, or NaN).
295
296       float_is_zero(VALUE)
297           Returns true iff VALUE is a zero.  If zeroes are signed then the
298           sign is irrelevant.
299
300       float_is_finite(VALUE)
301           Returns true iff VALUE is a finite value (either normal, subnormal,
302           or zero; not infinite or NaN).
303
304       float_is_infinite(VALUE)
305           Returns true iff VALUE is an infinity (either positive infinity or
306           negative infinity).
307
308       float_is_nan(VALUE)
309           Returns true iff VALUE is a NaN.
310
311   Examination
312       float_sign(VALUE)
313           Returns "+" or "-" to indicate the sign of VALUE.  An unsigned zero
314           returns the sign "+".  "die"s if VALUE is a NaN.
315
316       signbit(VALUE)
317           VALUE must be a floating point value.  Returns the sign bit of
318           VALUE: 0 if VALUE is positive or a positive or unsigned zero, or 1
319           if VALUE is negative or a negative zero.  Returns an unpredictable
320           value if VALUE is a NaN.
321
322           This is an IEEE 754 standard function.  According to the standard
323           NaNs have a well-behaved sign bit, but Perl can't see that bit.
324
325       float_parts(VALUE)
326           Divides up a non-zero finite floating point value into sign,
327           exponent, and significand, returning these as a three-element list
328           in that order.  The significand is returned as a floating point
329           value, in the range [1, 2) for normalised values, and in the range
330           (0, 1) for subnormals.  "die"s if VALUE is not finite and non-zero.
331
332   String conversion
333       float_hex(VALUE[, OPTIONS])
334           Encodes the exact value of VALUE as a hexadecimal fraction,
335           returning the fraction as a string.  Specifically, for finite
336           values the output is of the form "s0xm.mmmmmpeee", where "s" is the
337           sign, "m.mmmm" is the significand in hexadecimal, and "eee" is the
338           exponent in decimal with a sign.
339
340           The details of the output format are very configurable.  If OPTIONS
341           is supplied, it must be a reference to a hash, in which these keys
342           may be present:
343
344           exp_digits
345               The number of digits of exponent to show, unless this is
346               modified by exp_digits_range_mod or more are required to show
347               the exponent exactly.  (The exponent is always shown in full.)
348               Default 0, so the minimum possible number of digits is used.
349
350           exp_digits_range_mod
351               Modifies the number of exponent digits to show, based on the
352               number of digits required to show the full range of exponents
353               for normalised and subnormal values.  If "IGNORE" then nothing
354               is done.  If "ATLEAST" then at least this many digits are
355               shown.  Default "IGNORE".
356
357           exp_neg_sign
358               The string that is prepended to a negative exponent.  Default
359               "-".
360
361           exp_pos_sign
362               The string that is prepended to a non-negative exponent.
363               Default "+".  Make it the empty string to suppress the positive
364               sign.
365
366           frac_digits
367               The number of fractional digits to show, unless this is
368               modified by frac_digits_bits_mod or frac_digits_value_mod.
369               Default 0, but by default this gets modified.
370
371           frac_digits_bits_mod
372               Modifies the number of fractional digits to show, based on the
373               length of the significand.  There is a certain number of digits
374               that is the minimum required to explicitly state every bit that
375               is stored, and the number of digits to show might get set to
376               that number depending on this option.  If "IGNORE" then nothing
377               is done.  If "ATLEAST" then at least this many digits are
378               shown.  If "ATMOST" then at most this many digits are shown.
379               If "EXACTLY" then exactly this many digits are shown.  Default
380               "ATLEAST".
381
382           frac_digits_value_mod
383               Modifies the number of fractional digits to show, based on the
384               number of digits required to show the actual value exactly.
385               Works the same way as frac_digits_bits_mod.  Default "ATLEAST".
386
387           hex_prefix_string
388               The string that is prefixed to hexadecimal digits.  Default
389               "0x".  Make it the empty string to suppress the prefix.
390
391           infinite_string
392               The string that is returned for an infinite magnitude.  Default
393               "inf".
394
395           nan_string
396               The string that is returned for a NaN value.  Default "nan".
397
398           neg_sign
399               The string that is prepended to a negative value (including
400               negative zero).  Default "-".
401
402           pos_sign
403               The string that is prepended to a positive value (including
404               positive or unsigned zero).  Default "+".  Make it the empty
405               string to suppress the positive sign.
406
407           subnormal_strategy
408               The manner in which subnormal values are displayed.  If
409               "SUBNORMAL", they are shown with the minimum exponent for
410               normalised values and a significand in the range (0, 1).  This
411               matches how they are stored internally.  If "NORMAL", they are
412               shown with a significand in the range [1, 2) and a lower
413               exponent, as if they were normalised.  This gives a consistent
414               appearance for magnitudes regardless of normalisation.  Default
415               "SUBNORMAL".
416
417           zero_strategy
418               The manner in which zero values are displayed.  If
419               "STRING=str", the string str is used, preceded by a sign.  If
420               "SUBNORMAL", it is shown with significand zero and the minimum
421               normalised exponent.  If "EXPONENT=exp", it is shown with
422               significand zero and exponent exp.  Default "STRING=0.0".  An
423               unsigned zero is treated as having a positive sign.
424
425       hex_float(STRING)
426           Generates and returns a floating point value from a string encoding
427           it in hexadecimal.  The standard input form is
428           "[s][0x]m[.mmmmm][peee]", where "s" is the sign, "m[.mmmm]" is a
429           (fractional) hexadecimal number, and "eee" an optionally-signed
430           exponent in decimal.  If present, the exponent identifies a power
431           of two (not sixteen) by which the given fraction will be
432           multiplied.
433
434           If the value given in the string cannot be exactly represented in
435           the floating point type because it has too many fraction bits, the
436           nearest representable value is returned, with ties broken in favour
437           of the value with a zero low-order bit.  If the value given is too
438           large to exactly represent then an infinity is returned, or the
439           largest finite value if there are no infinities.
440
441           Additional input formats are accepted for special values.
442           "[s]inf[inity]" returns an infinity, or "die"s if there are no
443           infinities.  "[s][s]nan" returns a NaN, or "die"s if there are no
444           NaNs available.
445
446           All input formats are understood case insensitively.  The function
447           correctly interprets all possible outputs from "float_hex" with
448           default settings.
449
450   Comparison
451       float_id_cmp(A, B)
452           This is a comparison function supplying a total ordering of
453           floating point values.  A and B must both be floating point values.
454           Returns -1, 0, or +1, indicating whether A is to be sorted before,
455           the same as, or after B.
456
457           The ordering is of the identities of floating point values, not
458           their numerical values.  If zeroes are signed, then the two types
459           are considered to be distinct.  NaNs compare equal to each other,
460           but different from all numeric values.  The exact ordering provided
461           is mostly numerical order: NaNs come first, followed by negative
462           infinity, then negative finite values, then negative zero, then
463           positive (or unsigned) zero, then positive finite values, then
464           positive infinity.
465
466           In addition to sorting, this function can be useful to check for a
467           zero of a particular sign.
468
469       totalorder(A, B)
470           This is a comparison function supplying a total ordering of
471           floating point values.  A and B must both be floating point values.
472           Returns a truth value indicating whether A is to be sorted before-
473           or-the-same-as B.  That is, it is a <= predicate on the total
474           ordering.  The ordering is the same as that provided by
475           "float_id_cmp": NaNs come first, followed by negative infinity,
476           then negative finite values, then negative zero, then positive (or
477           unsigned) zero, then positive finite values, then positive
478           infinity.
479
480           This is an IEEE 754r standard function.  According to the standard
481           it is meant to distinguish different kinds of NaNs, based on their
482           sign bit, quietness, and payload, but this function (like the rest
483           of Perl) perceives only one NaN.
484
485   Manipulation
486       pow2(EXP)
487           EXP must be an integer.  Returns the value two the the power EXP.
488           "die"s if that value cannot be represented exactly as a floating
489           point value.  The return value may be either normalised or
490           subnormal.
491
492       mult_pow2(VALUE, EXP)
493           EXP must be an integer, and VALUE a floating point value.
494           Multiplies VALUE by two to the power EXP.  This gives exact
495           results, except in cases of underflow and overflow.  The range of
496           EXP is not constrained.  All normal floating point multiplication
497           behaviour applies.
498
499       copysign(VALUE, SIGN_FROM)
500           VALUE and SIGN_FROM must both be floating point values.  Returns a
501           floating point value with the magnitude of VALUE and the sign of
502           SIGN_FROM.  If SIGN_FROM is an unsigned zero then it is treated as
503           positive.  If VALUE is an unsigned zero then it is returned
504           unchanged.  If VALUE is a NaN then it is returned unchanged.  If
505           SIGN_FROM is a NaN then the sign copied to VALUE is unpredictable.
506
507           This is an IEEE 754 standard function.  According to the standard
508           NaNs have a well-behaved sign bit, which can be read and modified
509           by this function, but Perl only perceives one NaN and can't see its
510           sign bit, so behaviour on NaNs is not standard-conforming.
511
512       nextup(VALUE)
513           VALUE must be a floating point value.  Returns the next
514           representable floating point value adjacent to VALUE with a
515           numerical value that is strictly greater than VALUE, or returns
516           VALUE unchanged if there is no such value.  Infinite values are
517           regarded as being adjacent to the largest representable finite
518           values.  Zero counts as one value, even if it is signed, and it is
519           adjacent to the smallest representable positive and negative finite
520           values.  If a zero is returned, because VALUE is the smallest
521           representable negative value, and zeroes are signed, it is a
522           negative zero that is returned.  Returns NaN if VALUE is a NaN.
523
524           This is an IEEE 754r standard function.
525
526       nextdown(VALUE)
527           VALUE must be a floating point value.  Returns the next
528           representable floating point value adjacent to VALUE with a
529           numerical value that is strictly less than VALUE, or returns VALUE
530           unchanged if there is no such value.  Infinite values are regarded
531           as being adjacent to the largest representable finite values.  Zero
532           counts as one value, even if it is signed, and it is adjacent to
533           the smallest representable positive and negative finite values.  If
534           a zero is returned, because VALUE is the smallest representable
535           positive value, and zeroes are signed, it is a positive zero that
536           is returned.  Returns NaN if VALUE is a NaN.
537
538           This is an IEEE 754r standard function.
539
540       nextafter(VALUE, DIRECTION)
541           VALUE and DIRECTION must both be floating point values.  Returns
542           the next representable floating point value adjacent to VALUE in
543           the direction of DIRECTION, or returns DIRECTION if it is
544           numerically equal to VALUE.  Infinite values are regarded as being
545           adjacent to the largest representable finite values.  Zero counts
546           as one value, even if it is signed, and it is adjacent to the
547           positive and negative smallest representable finite values.  If a
548           zero is returned and zeroes are signed then it has the same sign as
549           VALUE.  Returns NaN if either argument is a NaN.
550
551           This is an IEEE 754 standard function.
552

BUGS

554       As of Perl 5.8.7 floating point zeroes will be partially transformed
555       into integer zeroes if used in almost any arithmetic, including
556       numerical comparisons.  Such a transformed zero appears as a floating
557       point zero (with its original sign) for some purposes, but behaves as
558       an integer zero for other purposes.  Where this happens to a positive
559       zero the result is indistinguishable from a true integer zero.  Where
560       it happens to a negative zero the result is a fourth type of zero, the
561       existence of which is a bug in Perl.  This fourth type of zero will
562       give confusing results, and in particular will elicit inconsistent
563       behaviour from the functions in this module.
564
565       Because of this transforming behaviour, it is best to avoid relying on
566       the sign of zeroes.  If you require signed-zero semantics then take
567       special care to maintain signedness.  Avoid using a zero directly in
568       arithmetic and handle it as a special case.  Any flavour of zero can be
569       accurately copied from one scalar to another without affecting the
570       original.  The functions in this module all avoid modifying their
571       arguments, and where they are meant to return signed zeroes they always
572       return a pristine one.
573
574       As of Perl 5.8.7 stringification of a floating point zero does not
575       preserve its signedness.  The number-to-string-to-number round trip
576       turns a positive floating point zero into an integer zero, but
577       accurately maintains negative and integer zeroes.  If a negative zero
578       gets partially transformed into an integer zero, as described above,
579       the stringification that it gets is based on its state at the first
580       occasion on which the scalar was stringified.
581
582       NaN handling is generally not well defined in Perl.  Arithmetic with a
583       mathematically undefined result may either "die" or generate a NaN.
584       Avoid relying on any particular behaviour for such operations, even if
585       your hardware's behaviour is known.
586
587       As of Perl 5.8.7 the % operator truncates its arguments to integers, if
588       the divisor is within the range of the native integer type.  It
589       therefore operates correctly on non-integer values only when the
590       divisor is very large.
591

SEE ALSO

593       Data::Integer, Scalar::Number, perlnumber(1)
594

AUTHOR

596       Andrew Main (Zefram) <zefram@fysh.org>
597
599       Copyright (C) 2006, 2007, 2008, 2010, 2012, 2017 Andrew Main (Zefram)
600       <zefram@fysh.org>
601

LICENSE

603       This module is free software; you can redistribute it and/or modify it
604       under the same terms as Perl itself.
605
606
607
608perl v5.32.1                      2021-01-27                    Data::Float(3)
Impressum