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

NAME

6       Data::Integer - details of the native integer data type
7

SYNOPSIS

9           use Data::Integer qw(natint_bits);
10
11           $n = natint_bits;
12
13           # and other constants; see text
14
15           use Data::Integer qw(nint sint uint nint_is_sint nint_is_uint);
16
17           $ni = nint($ni);
18           $si = sint($si);
19           $ui = uint($ui);
20           if(nint_is_sint($ni)) { ...
21           if(nint_is_uint($ni)) { ...
22
23           use Data::Integer qw(
24               nint_sgn sint_sgn uint_sgn
25               nint_abs sint_abs uint_abs
26               nint_cmp sint_cmp uint_cmp
27               nint_min sint_min uint_min
28               nint_max sint_max uint_max
29               nint_neg sint_neg uint_neg
30               nint_add sint_add uint_add
31               nint_sub sint_sub uint_sub);
32
33           $sn = nint_sgn($ni);
34           $sn = sint_sgn($si);
35           $sn = uint_sgn($ui);
36           $ni = nint_abs($ni);
37           $si = sint_abs($si);
38           $ui = uint_abs($ui);
39           @sorted_nints = sort { nint_cmp($a, $b) } @nints;
40           @sorted_sints = sort { sint_cmp($a, $b) } @sints;
41           @sorted_uints = sort { uint_cmp($a, $b) } @uints;
42           $ni = nint_min($na, $nb);
43           $si = sint_min($sa, $sb);
44           $ui = uint_min($ua, $ub);
45           $ni = nint_max($na, $nb);
46           $si = sint_max($sa, $sb);
47           $ui = uint_max($ua, $ub);
48           $ni = nint_neg($ni);
49           $si = sint_neg($si);
50           $ui = uint_neg($ui);
51           $ni = nint_add($na, $nb);
52           $si = sint_add($sa, $sb);
53           $ui = uint_add($ua, $ub);
54           $ni = nint_sub($na, $nb);
55           $si = sint_sub($sa, $sb);
56           $ui = uint_sub($ua, $ub);
57
58           use Data::Integer qw(
59               sint_shl uint_shl
60               sint_shr uint_shr
61               sint_rol uint_rol
62               sint_ror uint_ror);
63
64           $si = sint_shl($si, $dist);
65           $ui = uint_shl($ui, $dist);
66           $si = sint_shr($si, $dist);
67           $ui = uint_shr($ui, $dist);
68           $si = sint_rol($si, $dist);
69           $ui = uint_rol($ui, $dist);
70           $si = sint_ror($si, $dist);
71           $ui = uint_ror($ui, $dist);
72
73           use Data::Integer qw(
74               nint_bits_as_sint nint_bits_as_uint
75               sint_bits_as_uint uint_bits_as_sint);
76
77           $si = nint_bits_as_sint($ni);
78           $ui = nint_bits_as_uint($ni);
79           $ui = sint_bits_as_uint($si);
80           $si = uint_bits_as_sint($ui);
81
82           use Data::Integer qw(
83               sint_not uint_not
84               sint_and uint_and
85               sint_nand uint_nand
86               sint_andn uint_andn
87               sint_or uint_or
88               sint_nor uint_nor
89               sint_orn uint_orn
90               sint_xor uint_xor
91               sint_nxor uint_nxor
92               sint_mux uint_mux);
93
94           $si = sint_not($si);
95           $ui = uint_not($ui);
96           $si = sint_and($sa, $sb);
97           $ui = uint_and($ua, $ub);
98           $si = sint_nand($sa, $sb);
99           $ui = uint_nand($ua, $ub);
100           $si = sint_andn($sa, $sb);
101           $ui = uint_andn($ua, $ub);
102           $si = sint_or($sa, $sb);
103           $ui = uint_or($ua, $ub);
104           $si = sint_nor($sa, $sb);
105           $ui = uint_nor($ua, $ub);
106           $si = sint_orn($sa, $sb);
107           $ui = uint_orn($ua, $ub);
108           $si = sint_xor($sa, $sb);
109           $ui = uint_xor($ua, $ub);
110           $si = sint_nxor($sa, $sb);
111           $ui = uint_nxor($ua, $ub);
112           $si = sint_mux($sa, $sb, $sc);
113           $ui = uint_mux($ua, $ub, $uc);
114
115           use Data::Integer qw(
116               sint_madd uint_madd
117               sint_msub uint_msub
118               sint_cadd uint_cadd
119               sint_csub uint_csub
120               sint_sadd uint_sadd
121               sint_ssub uint_ssub);
122
123           $si = sint_madd($sa, $sb);
124           $ui = uint_madd($ua, $ub);
125           $si = sint_msub($sa, $sb);
126           $ui = uint_msub($ua, $ub);
127           ($carry, $si) = sint_cadd($sa, $sb, $carry);
128           ($carry, $ui) = uint_cadd($ua, $ub, $carry);
129           ($carry, $si) = sint_csub($sa, $sb, $carry);
130           ($carry, $ui) = uint_csub($ua, $ub, $carry);
131           $si = sint_sadd($sa, $sb);
132           $ui = uint_sadd($ua, $ub);
133           $si = sint_ssub($sa, $sb);
134           $ui = uint_ssub($ua, $ub);
135
136           use Data::Integer qw(natint_hex hex_natint);
137
138           print natint_hex($value);
139           $value = hex_natint($string);
140

DESCRIPTION

142       This module is about the native integer numerical data type.  A native
143       integer is one of the types of datum that can appear in the numeric
144       part of a Perl scalar.  This module supplies constants describing the
145       native integer type.
146
147       There are actually two native integer representations: signed and
148       unsigned.  Both are handled by this module.
149

NATIVE INTEGERS

151       Each native integer format represents a value using binary place value,
152       with some fixed number of bits.  The number of bits is the same for
153       both signed and unsigned representations.  In each case the least-
154       significant bit has the value 1, the next 2, the next 4, and so on.  In
155       the unsigned representation, this pattern continues up to and including
156       the most-significant bit, which for a 32-bit machine therefore has the
157       value 2^31 (2147483648).  The unsigned format cannot represent any
158       negative numbers.
159
160       In the signed format, the most-significant bit is exceptional, having
161       the negation of the value that it does in the unsigned format.  Thus on
162       a 32-bit machine this has the value -2^31 (-2147483648).  Values with
163       this bit set are negative, and those with it clear are non-negative;
164       this bit is also known as the "sign bit".
165
166       It is usual in machine arithmetic to use one of these formats at a
167       time, for example to add two signed numbers yielding a signed result.
168       However, Perl has a trick: a scalar with a native integer value
169       contains an additional flag bit which indicates whether the signed or
170       unsigned format is being used.  It is therefore possible to mix signed
171       and unsigned numbers in arithmetic, at some extra expense.
172

CONSTANTS

174       Each of the extreme-value constants has two names, a short one and a
175       long one.  The short names are more convenient to use, but the long
176       names are clearer in a context where other similar constants exist.
177
178       Due to the risks of Perl changing the behaviour of a native integer
179       value that has been involved in floating point arithmetic (see "BUGS"),
180       the extreme-value constants are actually non-constant functions that
181       always return a fresh copy of the appropriate value.  The returned
182       value is always a pure native integer value, unsullied by floating
183       point or string operations.
184
185       natint_bits
186           The width, in bits, of the native integer data types.
187
188       min_nint
189       min_natint
190           The minimum representable value in either representation.  This is
191           -2^(natint_bits - 1).
192
193       max_nint
194       max_natint
195           The maximum representable value in either representation.  This is
196           2^natint_bits - 1.
197
198       min_sint
199       min_signed_natint
200           The minimum representable value in the signed representation.  This
201           is -2^(natint_bits - 1).
202
203       max_sint
204       max_signed_natint
205           The maximum representable value in the signed representation.  This
206           is 2^(natint_bits - 1) - 1.
207
208       min_uint
209       min_unsigned_natint
210           The minimum representable value in the unsigned representation.
211           This is zero.
212
213       max_uint
214       max_unsigned_natint
215           The maximum representable value in the unsigned representation.
216           This is 2^natint_bits - 1.
217

FUNCTIONS

219       Each "nint_", "sint_", or "uint_" function operates on one of the three
220       integer formats.  "nint_" functions operate on Perl's union of signed
221       and unsigned; "sint_" functions operate on signed integers; and "uint_"
222       functions operate on unsigned integers.  Except where indicated
223       otherwise, the function returns a value of its primary type.
224
225       Parameters A, B, and C, where present, must be numbers of the
226       appropriate type: specifically, with a numerical value that can be
227       represented in that type.  If there are multiple flavours of zero, due
228       to floating point funkiness, all zeroes are treated the same.
229       Parameters with other names have other requirements, explained with
230       each function.
231
232       The functions attempt to detect unsuitable arguments, and "die" if an
233       invalid argument is detected, but they can't notice some kinds of
234       incorrect argument.  Generally, it is the caller's responsibility to
235       provide a sane numerical argument, and supplying an invalid argument
236       will cause mayhem.  Only the numeric value of plain scalar arguments is
237       used; the string value is completely ignored, so dualvars are not a
238       problem.
239
240   Canonicalisation and classification
241       These are basic glue functions.
242
243       nint(A)
244       sint(A)
245       uint(A)
246           These functions each take an argument in a specific integer format
247           and return its numerical value.  This is the argument
248           canonicalisation that is performed by all of the functions in this
249           module, presented in isolation.
250
251       nint_is_sint(A)
252           Takes a native integer of either type.  Returns a truth value
253           indicating whether this value can be exactly represented as a
254           signed native integer.
255
256       nint_is_uint(A)
257           Takes a native integer of either type.  Returns a truth value
258           indicating whether this value can be exactly represented as an
259           unsigned native integer.
260
261   Arithmetic
262       These functions operate on numerical values rather than just bit
263       patterns.  They will all "die" if the true numerical result doesn't fit
264       into the result format, rather than give a wrong answer.
265
266       nint_sgn(A)
267       sint_sgn(A)
268       uint_sgn(A)
269           Returns +1 if the argument is positive, 0 if the argument is zero,
270           or -1 if the argument is negative.
271
272       nint_abs(A)
273       sint_abs(A)
274       uint_abs(A)
275           Absolute value (magnitude, discarding sign).
276
277       nint_cmp(A, B)
278       sint_cmp(A, B)
279       uint_cmp(A, B)
280           Arithmetic comparison.  Returns -1, 0, or +1, indicating whether A
281           is less than, equal to, or greater than B.
282
283       nint_min(A, B)
284       sint_min(A, B)
285       uint_min(A, B)
286           Arithmetic minimum.  Returns the arithmetically lesser of the two
287           arguments.
288
289       nint_max(A, B)
290       sint_max(A, B)
291       uint_max(A, B)
292           Arithmetic maximum.  Returns the arithmetically greater of the two
293           arguments.
294
295       nint_neg(A)
296       sint_neg(A)
297       uint_neg(A)
298           Negation: returns -A.
299
300       nint_add(A, B)
301       sint_add(A, B)
302       uint_add(A, B)
303           Addition: returns A + B.
304
305       nint_sub(A, B)
306       sint_sub(A, B)
307       uint_sub(A, B)
308           Subtraction: returns A - B.
309
310   Bit shifting
311       These functions all operate on the bit patterns representing integers,
312       mostly ignoring the numerical values represented.  In most cases the
313       results for particular numerical arguments are influenced by the word
314       size, because that determines where a bit being left-shifted will drop
315       off the end of the word and where a bit will be shifted in during a
316       rightward shift.
317
318       With the exception of rightward shifts (see below), each pair of
319       functions performs exactly the same operations on the bit sequences.
320       There inevitably can't be any functions here that operate on Perl's
321       union of signed and unsigned; you must choose, by which function you
322       call, which type the result is to be tagged as.
323
324       sint_shl(A, DIST)
325       uint_shl(A, DIST)
326           Bitwise left shift (towards more-significant bits).  DIST is the
327           distance to shift, in bits, and must be an integer in the range [0,
328           natint_bits).  Zeroes are shifted in from the right.
329
330       sint_shr(A, DIST)
331       uint_shr(A, DIST)
332           Bitwise right shift (towards less-significant bits).  DIST is the
333           distance to shift, in bits, and must be an integer in the range [0,
334           natint_bits).
335
336           When performing an unsigned right shift, zeroes are shifted in from
337           the left.  A signed right shift is different: the sign bit gets
338           duplicated, so right-shifting a negative number always gives a
339           negative result.
340
341       sint_rol(A, DIST)
342       uint_rol(A, DIST)
343           Bitwise left rotation (towards more-significant bits, with the
344           most-significant bit wrapping round to the least-significant bit).
345           DIST is the distance to rotate, in bits, and must be an integer in
346           the range [0, natint_bits).
347
348       sint_ror(A, DIST)
349       uint_ror(A, DIST)
350           Bitwise right rotation (towards less-significant bits, with the
351           least-significant bit wrapping round to the most-significant bit).
352           DIST is the distance to rotate, in bits, and must be an integer in
353           the range [0, natint_bits).
354
355   Format conversion
356       These functions convert between the various native integer formats by
357       reinterpreting the bit patterns used to represent the integers.  The
358       bit pattern remains unchanged; its meaning changes, and so the
359       numerical value changes.  Perl scalars preserve the numerical value,
360       rather than just the bit pattern, so from the Perl point of view these
361       are functions that change numbers into other numbers.
362
363       nint_bits_as_sint(A)
364           Converts a native integer of either type to a signed integer, by
365           reinterpreting the bits.  The most-significant bit (whether a sign
366           bit or not) becomes a sign bit.
367
368       nint_bits_as_uint(A)
369           Converts a native integer of either type to an unsigned integer, by
370           reinterpreting the bits.  The most-significant bit (whether a sign
371           bit or not) becomes an ordinary most-significant bit.
372
373       sint_bits_as_uint(A)
374           Converts a signed integer to an unsigned integer, by reinterpreting
375           the bits.  The sign bit becomes an ordinary most-significant bit.
376
377       uint_bits_as_sint(A)
378           Converts an unsigned integer to a signed integer, by reinterpreting
379           the bits.  The most-significant bit becomes a sign bit.
380
381   Bitwise operations
382       These functions all operate on the bit patterns representing integers,
383       completely ignoring the numerical values represented.  They are mostly
384       not influenced by the word size, in the sense that they will produce
385       the same numerical result for the same numerical arguments regardless
386       of word size.  However, a few are affected by the word size: those on
387       unsigned operands that return a non-zero result if given zero
388       arguments.
389
390       Each pair of functions performs exactly the same operations on the bit
391       sequences.  There inevitably can't be any functions here that operate
392       on Perl's union of signed and unsigned; you must choose, by which
393       function you call, which type the result is to be tagged as.
394
395       sint_not(A)
396       uint_not(A)
397           Bitwise complement (NOT).
398
399       sint_and(A, B)
400       uint_and(A, B)
401           Bitwise conjunction (AND).
402
403       sint_nand(A, B)
404       uint_nand(A, B)
405           Bitwise inverted conjunction (NAND).
406
407       sint_andn(A, B)
408       uint_andn(A, B)
409           Bitwise conjunction with inverted argument (A AND (NOT B)).
410
411       sint_or(A, B)
412       uint_or(A, B)
413           Bitwise disjunction (OR).
414
415       sint_nor(A, B)
416       uint_nor(A, B)
417           Bitwise inverted disjunction (NOR).
418
419       sint_orn(A, B)
420       uint_orn(A, B)
421           Bitwise disjunction with inverted argument (A OR (NOT B)).
422
423       sint_xor(A, B)
424       uint_xor(A, B)
425           Bitwise symmetric difference (XOR).
426
427       sint_nxor(A, B)
428       uint_nxor(A, B)
429           Bitwise symmetric similarity (NXOR).
430
431       sint_mux(A, B, C)
432       uint_mux(A, B, C)
433           Bitwise multiplex.  The output has a bit from B wherever A has a 1
434           bit, and a bit from C wherever A has a 0 bit.  That is, the result
435           is (A AND B) OR ((NOT A) AND C).
436
437   Machine arithmetic
438       These functions perform arithmetic operations that are inherently
439       influenced by the word size.  They always produce a well-defined output
440       if given valid inputs.  There inevitably can't be any functions here
441       that operate on Perl's union of signed and unsigned; you must choose,
442       by which function you call, which type the result is to be tagged as.
443
444       sint_madd(A, B)
445       uint_madd(A, B)
446           Modular addition.  The result for unsigned addition is (A + B) mod
447           2^natint_bits.  The signed version behaves similarly, but with a
448           different result range.
449
450       sint_msub(A, B)
451       uint_msub(A, B)
452           Modular subtraction.  The result for unsigned subtraction is (A -
453           B) mod 2^natint_bits.  The signed version behaves similarly, but
454           with a different result range.
455
456       sint_cadd(A, B, CARRY_IN)
457       uint_cadd(A, B, CARRY_IN)
458           Addition with carry.  Two word arguments (A and B) and an input
459           carry bit (CARRY_IN, which must have the value 0 or 1) are all
460           added together.  Returns a list of two items: an output carry and
461           an output word (of the same signedness as the inputs).  Precisely,
462           the output list (CARRY_OUT, R) is such that CARRY_OUT*2^natint_bits
463           + R = A + B + CARRY_IN.
464
465       sint_csub(A, B, CARRY_IN)
466       uint_csub(A, B, CARRY_IN)
467           Subtraction with carry (borrow).  The second word argument (B) and
468           an input carry bit (CARRY_IN, which must have the value 0 or 1) are
469           subtracted from the first word argument (A).  Returns a list of two
470           items: an output carry and an output word (of the same signedness
471           as the inputs).  Precisely, the output list (CARRY_OUT, R) is such
472           that R - CARRY_OUT*2^natint_bits = A - B - CARRY_IN.
473
474       sint_sadd(A, B)
475       uint_sadd(A, B)
476           Saturating addition.  The result is A + B if that will fit into the
477           result format, otherwise the minimum or maximum value of the result
478           format is returned depending on the direction in which the addition
479           overflowed.
480
481       sint_ssub(A, B)
482       uint_ssub(A, B)
483           Saturating subtraction.  The result is A - B if that will fit into
484           the result format, otherwise the minimum or maximum value of the
485           result format is returned depending on the direction in which the
486           subtraction overflowed.
487
488   String conversion
489       natint_hex(VALUE)
490           VALUE must be a native integer value.  The function encodes VALUE
491           in hexadecimal, returning that representation as a string.
492           Specifically, the output is of the form "s0xdddd", where "s" is the
493           sign and "dddd" is a sequence of hexadecimal digits.
494
495       hex_natint(STRING)
496           Generates and returns a native integer value from a string encoding
497           it in hexadecimal.  Specifically, the input format is
498           "[s][0x]dddd", where "s" is the sign and "dddd" is a sequence of
499           one or more hexadecimal digits.  The input is interpreted case
500           insensitively.  If the value given in the string cannot be exactly
501           represented in the native integer type, the function "die"s.
502
503           The core Perl function "hex" (see "hex" in perlfunc) does a similar
504           job to this function, but differs in several ways.  Principally,
505           "hex" doesn't handle negative values, and it gives the wrong answer
506           for values that don't fit into the native integer type.  In Perl
507           5.6 it also gives the wrong answer for values that don't fit into
508           the native floating point type.  It also doesn't enforce strict
509           syntax on the input string.
510

BUGS

512       In Perl 5.6, when a native integer scalar is used in any arithmetic
513       other than specifically integer arithmetic, it gets partially
514       transformed into a floating point scalar.  Even if its numerical value
515       can be represented exactly in floating point, so that floating point
516       arithmetic uses the correct numerical value, some operations are
517       affected by the floatness.  In particular, the stringification of the
518       scalar doesn't necessarily represent its exact value if it is tagged as
519       floating point.
520
521       Because of this transforming behaviour, if you need to stringify a
522       native integer it is best to ensure that it doesn't get used in any
523       non-integer arithmetic first.  If an integer scalar must be used in
524       standard Perl arithmetic, it may be copied first and the copy operated
525       upon to avoid causing side effects on the original.  If an integer
526       scalar might have already been transformed, it can be cleaned by
527       passing it through the canonicalisation function "nint".  The functions
528       in this module all avoid modifying their arguments, and always return
529       pristine integers.
530
531       Perl 5.8+ still internally modifies integer scalars in the same
532       circumstances, but seems to have corrected all the misbehaviour that
533       resulted from it.
534
535       Also in Perl 5.6, default Perl arithmetic doesn't necessarily work
536       correctly on native integers.  (This is part of the motivation for the
537       myriad arithmetic functions in this module.)  Default arithmetic here
538       is strictly floating point, so if there are native integers that cannot
539       be exactly represented in floating point then the arithmetic will
540       approximate the values before operating on them.  Perl 5.8+ attempts to
541       use native integer operations where possible in its default arithmetic,
542       but as of Perl 5.8.8 it doesn't always succeed.  For reliable integer
543       arithmetic, integer operations must still be requested explicitly.
544

SEE ALSO

546       Data::Float, Scalar::Number, perlnumber(1)
547

AUTHOR

549       Andrew Main (Zefram) <zefram@fysh.org>
550
552       Copyright (C) 2007, 2010, 2015, 2017 Andrew Main (Zefram)
553       <zefram@fysh.org>
554

LICENSE

556       This module is free software; you can redistribute it and/or modify it
557       under the same terms as Perl itself.
558
559
560
561perl v5.36.0                      2023-01-20                  Data::Integer(3)
Impressum