1Data::Float(3pm) User Contributed Perl Documentation Data::Float(3pm)
2
6 Data::Float - details of the floating point data type
7
9 use Data::Float qw(have_signed_zero);
10 if(have_signed_zero) { ...
12 # and many other constants; see text
14 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 $class = float_class($value);
21 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 use Data::Float qw(float_sign signbit float_parts);
31 $sign = float_sign($value);
33 $sign_bit = signbit($value);
34 ($sign, $exponent, $significand) = float_parts($value);
35 use Data::Float qw(float_hex hex_float);
37 print float_hex($value);
39 $value = hex_float($string);
40 use Data::Float qw(float_id_cmp totalorder);
42 @sorted_floats = sort { float_id_cmp($a, $b) } @floats;
44 if(totalorder($a, $b)) { ...
45 use Data::Float qw(
47 pow2 mult_pow2 copysign nextup nextdown nextafter);
48 $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
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
64 Classification
65 Floating point values are divided into five subtypes:
66 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 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 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 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 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 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 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 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 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 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 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 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 See perlnumber(1) for discussion of Perl's numeric semantics.
159
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 have_subnormal
170 Truth value indicating whether there are subnormal floating point
171 values.
172 have_infinite
174 Truth value indicating whether there are infinite floating point
175 values.
176 have_nan
178 Truth value indicating whether there are NaN floating point values.
179 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 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 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 max_finite_exp
199 The maximum exponent permitted for finite floating point values.
200 max_finite_pow2
202 The maximum representable power of two. This is 2^max_finite_exp.
203 max_finite
205 The maximum representable finite value. This is
206 2^(max_finite_exp+1) - 2^(max_finite_exp-significand_bits).
207 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 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 min_normal_exp
220 The minimum exponent permitted for normalised floating point
221 values.
222 min_normal
224 The minimum positive value representable as a normalised floating
225 point value. This is 2^min_normal_exp.
226 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 min_finite
234 The minimum representable positive finite value. This is
235 2^min_finite_exp.
236 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 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 neg_zero
249 The negative zero value. (Exists only if zeroes are signed, as
250 indicated by the "have_signed_zero" constant.)
251 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 pos_infinity
259 The positive infinite value. (Exists only if there are infinite
260 values, as indicated by the "have_infinite" constant.)
261 neg_infinity
263 The negative infinite value. (Exists only if there are infinite
264 values, as indicated by the "have_infinite" constant.)
265 nan Not-a-number. (Exists only if NaN values were detected, as
267 indicated by the "have_nan" constant.)
268
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 Classification
279 Each "float_is_" function returns a simple truth value result.
280 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 float_is_normal(VALUE)
287 Returns true iff VALUE is a normalised floating point value.
288 float_is_subnormal(VALUE)
290 Returns true iff VALUE is a subnormal floating point value.
291 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 float_is_zero(VALUE)
297 Returns true iff VALUE is a zero. If zeroes are signed then the
298 sign is irrelevant.
299 float_is_finite(VALUE)
301 Returns true iff VALUE is a finite value (either normal, subnormal,
302 or zero; not infinite or NaN).
303 float_is_infinite(VALUE)
305 Returns true iff VALUE is an infinity (either positive infinity or
306 negative infinity).
307 float_is_nan(VALUE)
309 Returns true iff VALUE is a NaN.
310 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 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 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 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 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 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 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 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 exp_neg_sign
358 The string that is prepended to a negative exponent. Default
359 "-".
360 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 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 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 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 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 infinite_string
392 The string that is returned for an infinite magnitude. Default
393 "inf".
394 nan_string
396 The string that is returned for a NaN value. Default "nan".
397 neg_sign
399 The string that is prepended to a negative value (including
400 negative zero). Default "-".
401 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 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 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 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 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 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 All input formats are understood case insensitively. The function
447 correctly interprets all possible outputs from "float_hex" with
448 default settings.
449 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 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 In addition to sorting, this function can be useful to check for a
467 zero of a particular sign.
468 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 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 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 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 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 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 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 This is an IEEE 754r standard function.
525 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 This is an IEEE 754r standard function.
539 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 This is an IEEE 754 standard function.
552
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 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 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 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 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
593 Data::Integer, Scalar::Number, perlnumber(1)
594
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
603 This module is free software; you can redistribute it and/or modify it
604 under the same terms as Perl itself.
605perl v5.38.0 2023-07-20 Data::Float(3pm)