1Math::Int64(3)        User Contributed Perl Documentation       Math::Int64(3)
2
3
4

NAME

6       Math::Int64 - Manipulate 64 bits integers in Perl
7

SYNOPSIS

9         use Math::Int64 qw(int64 uint64);
10
11         my $i = int64(1);
12         my $j = $i << 40;
13         print($i + $j * 1000000);
14
15         my $k = uint64("12345678901234567890");
16

DESCRIPTION

18       This module adds support for 64 bit integers, signed and unsigned, to
19       Perl.
20
21   Exportable functions
22       int64()
23       int64($value)
24           Creates a new int64 value and initializes it to $value, where
25           $value can be a Perl number or a string containing a number.
26
27           For instance:
28
29             $i = int64(34);
30             $j = int64("-123454321234543212345");
31
32             $k = int64(1234567698478483938988988); # wrong!!!
33                                                    #  the unquoted number would
34                                                    #  be converted first to a
35                                                    #  real number causing it to
36                                                    #  loose some precision.
37
38           Once the int64 number is created it can be manipulated as any other
39           Perl value supporting all the standard operations (addition,
40           negation, multiplication, postincrement, etc.).
41
42       net_to_int64($str)
43           Converts an 8 bytes string containing an int64 in network order to
44           the internal representation used by this module.
45
46       int64_to_net($int64)
47           Returns an 8 bytes string with the representation of the int64
48           value in network order.
49
50       native_to_int64($str)
51       int64_to_native($int64)
52           similar to net_to_int64 and int64_to_net, but using the native CPU
53           order.
54
55       int64_to_number($int64)
56           returns the optimum representation of the int64 value using Perl
57           internal types (IV, UV or NV). Precision may be lost.
58
59           For instance:
60
61             for my $l (10, 20, 30, 40, 50, 60) {
62               my $i = int64(1) << $l;
63               my $n = int64_to_number($i);
64               print "int64:$i => perl:$n\n";
65             }
66
67       string_to_int64($str, $base)
68           Converts the string to a int64 value. The conversion is done
69           according to the given base, which must be a number between 2 and
70           36 inclusive or the special value 0. $base defaults to 0.
71
72           The string may begin with an arbitrary amount of white space
73           followed by a single optional "+" or "-" sign. If base is zero or
74           16, the string may then include a "0x" prefix, and the number will
75           be read in base 16; otherwise, a zero base is taken as 10 (decimal)
76           unless the next character is '0', in which case it is taken as 8
77           (octal).
78
79           Underscore characters ("_") between the digits are ignored.
80
81           No overflow checks are performed by this function unless the
82           "die_on_overflow" pragma is used (see "Die on overflow" below).
83
84           See also strtoll(3).
85
86       hex_to_int64($i64)
87           Shortcut for string_to_int64($str, 16)
88
89       int64_to_string($i64, $base)
90           Converts the int64 value to its string representation in the given
91           base (defaults to 10).
92
93       int64_to_hex($i64)
94           Shortcut for "int64_to_string($i64, 16)".
95
96       int64_to_BER($i64)
97           Converts the int64 value to its BER representation (see "pack" in
98           perlfunc for a description of the BER format).
99
100           In the case of signed numbers, they are transformed into unsigned
101           numbers before encoding them in the BER format with the following
102           rule:
103
104             $neg = ($i64 < 0 ? 1 : 0);
105             $u64 = (($neg ? ~$i64 : $i64) << 1) | $neg;
106
107           That way, positive and negative integers are interleaved as 0, -1,
108           1, 2, -2, .... The format is similar to that used by Google
109           protocol buffers to encode signed variants but with the most
110           significant groups first (protocol buffers uses the least
111           significant groups first variant).
112
113           If you don't want that preprocessing for signed numbers, just use
114           the "uint64_to_BER" function instead.
115
116       BER_to_int64($str)
117           Decodes the int64 number in BER format from the given string.
118
119           There must not be any extra bytes on the string after the encoded
120           number.
121
122       BER_length($str)
123           Given a string with a BER encoded number at the beginning, this
124           function returns the number of bytes it uses.
125
126           The right way to shift a BER encoded number from the beginning of
127           some string is as follows:
128
129              $i64 = BER_to_int64(substr($str, 0, BER_length($str), ''));
130
131       int64_rand
132           Generates a 64 bit random number using ISAAC-64 algorithm.
133
134       int64_srand($seed)
135       int64_srand()
136           Sets the seed for the random number generator.
137
138           $seed, if given, should be a 2KB long string.
139
140       uint64
141       uint64_to_number
142       net_to_uint64
143       uint64_to_net
144       native_to_uint64
145       uint64_to_native
146       string_to_uint64
147       hex_to_uint64
148       uint64_to_string
149       uint64_to_hex
150           These functions are similar to their int64 counterparts, but
151           manipulate 64 bit unsigned integers.
152
153       uint64_to_BER($u64)
154           Encodes the given unsigned integer in BER format (see "pack" in
155           perlfunc).
156
157       BER_to_uint64($str)
158           Decodes from the given string an unsigned number in BER format.
159
160       uint64_rand
161           Generates a 64 bit random unsigned number using ISAAC-64 algorithm.
162
163   Die on overflow
164       The lexical pragma "Math::Int64::die_on_overflow" configures the module
165       to throw an error when some operation results in integer overflow.
166
167       For instance:
168
169         use Math::Int64 qw(uint64);
170         use Math::Int64::die_on_overflow;
171
172         my $zero = uint64(0);
173         say ($zero - 1);                 # dies as -1 falls outside
174                                          # the uint64_t range
175
176         no Math::Int64::die_on_overflow; # deactivates lexical pragma
177         say ($zero - 1);                 # no error is detected here!
178
179       The pragma can also be activated as follows:
180
181         use Math::Int64 ':die_on_overflow';
182
183       Once this pragma is used, several Math::Int64 operations may become
184       slower. Deactivating the pragma will not make them fast again.
185
186       On Perl 5.8.x, as lexical pragmas support is not available, the pragma
187       "die_on_overflow" pragma is global and can not be deactivated.
188
189   Fallback to native 64bit support if available
190       If the lexical pragma "Math::Int64::native_if_available" is used in
191       your program and the version of perl in use has native support for
192       64bit integers, the functions imported from the module that create
193       64bit integers (i.e. "uint64", "int64", "string_to_int64",
194       "native_to_int64", etc.) will return regular perl scalars.
195
196       For instance:
197
198         use Math::Int64 qw(int64);
199
200         $a = int64(34); # always returns an object of the class Math::Int64
201
202         use Math::Int64::native_if_available;
203         $a = int64(34); # returns a regular scalar on perls compiled with
204                         # 64bit support
205
206       This feature is not enabled by default because the semantics for perl
207       scalars and for 64 bit integers as implemented in this module are not
208       identical.
209
210       Perl is prone to coerce integers into floats while this module keeps
211       then always as 64bit integers. Specifically, the division operation and
212       overflows are the most problematic cases. Also, when using native
213       integers, the signed/unsigned division blurs.
214
215       Besides that, in most situations it is safe to use the native fallback.
216
217       As happens with the "die_on_overflow" pragma, on Perl 5.8.x it is
218       global.
219
220       The pragma can also be activated as follows:
221
222         use Math::Int64 ':native_if_available';
223
224   Transparent conversion of objects to int64/uint64
225       When in some operation involving int64/uint64 numbers, a blessed object
226       is passed as an operand, the module would try to coerce the object into
227       an int64/uint64 number calling the methods "as_int64"/"as_uint64"
228       respectively.
229
230       If the corresponding method is not implemented, the object will be
231       stringified and then parsed as a base 10 number.
232
233   Storable integration
234       Objects of classes Math::Int64 and Math::UInt64 implement the
235       STORABLE_freeze and STORABLE_thaw methods for a transparent integration
236       with Storable.
237
238   C API
239       This module provides a native C API that can be used to create and read
240       Math::Int64 int64 and uint64 SVs from your own XS modules.
241
242       In order to use it you need to follow these steps:
243
244       •   Import the files "perl_math_int64.c", "perl_math_int64.h" and
245           optionally "typemaps" from Math::Int64 "c_api_client" directory
246           into your project directory.
247
248       •   Include the file "perl_math_int64.h" in the C or XS source files
249           where you want to convert 64bit integers to/from Perl SVs.
250
251           Note that this header file requires the types int64_t and uint64_t
252           to be defined beforehand.
253
254       •   Add the file "perl_math_int64.c" to your compilation targets (see
255           the sample Makefile.PL below).
256
257       •   Add a call to the macro "PERL_MATH_INT64_LOAD_OR_CROAK" into the
258           "BOOT" section of your XS file.
259
260       For instance:
261
262        --- Foo64.xs ---------
263
264         #include "EXTERN.h"
265         #include "perl.h"
266         #include "XSUB.h"
267         #include "ppport.h"
268
269         /* #define MATH_INT64_NATIVE_IF_AVAILABLE */
270         #include "math_int64.h"
271
272         MODULE = Foo64                PACKAGE = Foo64
273         BOOT:
274             PERL_MATH_INT64_LOAD_OR_CROAK;
275
276         int64_t
277         some_int64()
278         CODE:
279             RETVAL = -42;
280         OUTPUT:
281             RETVAL
282
283
284         --- Makefile.PL -----
285
286         use ExtUtils::MakeMaker;
287         WriteMakefile( NAME         => 'Foo64',
288                        VERSION_FROM => 'lib/Foo64.pm',
289                        OBJECT       => '$(O_FILES)' );
290
291       If the macro "MATH_INT64_NATIVE_IF_AVAILABLE" is defined before
292       including "perl_math_int64.h" and the perl interpreter is compiled with
293       native 64bit integer support, IVs will be used to represent 64bit
294       integers instead of the object representation provided by Math::Int64.
295
296       These are the C macros available from Math::Int64 C API:
297
298       SV *newSVi64(int64_t i64)
299           Returns an SV representing the given int64_t value.
300
301       SV *newSVu64(uint64_t 64)
302           Returns an SV representing the given uint64_t value.
303
304       int64_t SvI64(SV *sv)
305           Extracts the int64_t value from the given SV.
306
307       uint64_t SvU64(SV *sv)
308           Extracts the uint64_t value from the given SV.
309
310       int SvI64OK(SV *sv)
311           Returns true is the given SV contains a valid int64_t value.
312
313       int SvU64OK(SV *sv)
314           Returns true is the given SV contains a valid uint64_t value.
315
316       uint64_t randU64(void)
317           Returns a random 64 bits unsigned integer.
318
319       SV sv_seti64(SV *sv, uint64_t i64)
320           Sets the value of the perl scalar to the given int64_t value.
321
322       SV sv_setu64(SV *sv, uint64_t i64)
323           Sets the value of the perl scalar to the given uint64_t value.
324
325       If you require any other function available through the C API don't
326       hesitate to ask for it!
327

BUGS AND SUPPORT

329       The Storable integration feature is experimental.
330
331       The C API feature is experimental.
332
333       This module requires int64 support from the C compiler.
334
335       In order to report bugs you can send me and email to the address that
336       appears below or use the CPAN RT bug tracking system available at
337       <http://rt.cpan.org>.
338
339       The source for the development version of the module is hosted at
340       GitHub: <https://github.com/salva/p5-Math-Int64>.
341
342   My wishlist
343       If you like this module and you're feeling generous, take a look at my
344       Amazon Wish List: <http://amzn.com/w/1WU1P6IR5QZ42>
345

SEE ALSO

347       The C API usage sample module Math::Int64::C_API::Sample.
348
349       Other modules providing support for larger integers or numbers are
350       Math::BigInt, Math::BigRat and Math::Big, Math::BigInt::BitVect,
351       Math::BigInt::Pari and Math::BigInt::GMP.
352
354       Copyright © 2007, 2009, 2011-2015 by Salvador Fandiño
355       (sfandino@yahoo.com)
356
357       Copyright © 2014-2015 by Dave Rolsky (autarch@urth.org)
358
359       This library is free software; you can redistribute it and/or modify it
360       under the same terms as Perl itself, either Perl version 5.8.8 or, at
361       your option, any later version of Perl 5 you may have available.
362
363
364
365perl v5.38.0                      2023-07-20                    Math::Int64(3)
Impressum