Debian Codegraph @

upstream/debian-unstable/man3/integer.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "integer 3perl"
58 .TH integer 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 integer \- Perl pragma to use integer arithmetic instead of floating point
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 3
68 \& use integer;
69 \& $x = 10/3;
70 \& # $x is now 3, not 3.33333333333333333
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 This tells the compiler to use integer operations from here to the end
75 of the enclosing BLOCK. On many machines, this doesn't matter a great
76 deal for most computations, but on those without floating point
77 hardware, it can make a big difference in performance.
78 .PP
79 Note that this only affects how most of the arithmetic and relational
80 \&\fBoperators\fR handle their operands and results, and \fBnot\fR how all
81 numbers everywhere are treated. Specifically, \f(CW\*(C`use integer;\*(C'\fR has the
82 effect that before computing the results of the arithmetic operators
83 (+, \-, *, /, %, +=, \-=, *=, /=, %=, and unary minus), the comparison
84 operators (<, <=, >, >=, ==, !=, <=>), and the bitwise operators (|, &,
85 ^, <<, >>, |=, &=, ^=, <<=, >>=), the operands have their fractional
86 portions truncated (or floored), and the result will have its
87 fractional portion truncated as well. In addition, the range of
88 operands and results is restricted to that of familiar two's complement
89 integers, i.e., \-(2**31) .. (2**31\-1) on 32\-bit architectures, and
90 \&\-(2**63) .. (2**63\-1) on 64\-bit architectures. For example, this code
91 .PP
92 .Vb 7
93 \& use integer;
94 \& $x = 5.8;
95 \& $y = 2.5;
96 \& $z = 2.7;
97 \& $a = 2**31 \- 1; # Largest positive integer on 32\-bit machines
98 \& $, = ", ";
99 \& print $x, \-$x, $x+$y, $x\-$y, $x/$y, $x*$y, $y==$z, $a, $a+1;
100 .Ve
101 .PP
102 will print: 5.8, \-5, 7, 3, 2, 10, 1, 2147483647, \-2147483648
103 .PP
104 Note that \f(CW$x\fR is still printed as having its true non-integer value of
105 5.8 since it wasn't operated on. And note too the wrap-around from the
106 largest positive integer to the largest negative one. Also, arguments
107 passed to functions and the values returned by them are \fBnot\fR affected
108 by \f(CW\*(C`use integer;\*(C'\fR. E.g.,
109 .PP
110 .Vb 3
111 \& srand(1.5);
112 \& $, = ", ";
113 \& print sin(.5), cos(.5), atan2(1,2), sqrt(2), rand(10);
114 .Ve
115 .PP
116 will give the same result with or without \f(CW\*(C`use integer;\*(C'\fR The power
117 operator \f(CW\*(C`**\*(C'\fR is also not affected, so that 2 ** .5 is always the
118 square root of 2. Now, it so happens that the pre\- and post\- increment
119 and decrement operators, ++ and \-\-, are not affected by \f(CW\*(C`use integer;\*(C'\fR
120 either. Some may rightly consider this to be a bug \-\- but at least it's
121 a long-standing one.
122 .PP
123 Finally, \f(CW\*(C`use integer;\*(C'\fR also has an additional affect on the bitwise
124 operators. Normally, the operands and results are treated as
125 \&\fBunsigned\fR integers, but with \f(CW\*(C`use integer;\*(C'\fR the operands and results
126 are \fBsigned\fR. This means, among other things, that ~0 is \-1, and \-2 &
127 \&\-5 is \-6.
128 .PP
129 Internally, native integer arithmetic (as provided by your C compiler)
130 is used. This means that Perl's own semantics for arithmetic
131 operations may not be preserved. One common source of trouble is the
132 modulus of negative numbers, which Perl does one way, but your hardware
133 may do another.
134 .PP
135 .Vb 4
136 \& % perl \-le \*(Aqprint (4 % \-3)\*(Aq
137 \& \-2
138 \& % perl \-Minteger \-le \*(Aqprint (4 % \-3)\*(Aq
139 \& 1
140 .Ve
141 .PP
142 See "Pragmatic Modules" in perlmodlib, "Integer Arithmetic" in perlop