1Math::Int64(3) User Contributed Perl Documentation Math::Int64(3)
2
6 Math::Int64 - Manipulate 64 bits integers in Perl
7
9 use Math::Int64 qw(int64 uint64);
10 my $i = int64(1);
12 my $j = $i << 40;
13 print($i + $j * 1000000);
14 my $k = uint64("12345678901234567890");
16
18 This module adds support for 64 bit integers, signed and unsigned, to
19 Perl.
20 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 For instance:
28 $i = int64(34);
30 $j = int64("-123454321234543212345");
31 $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 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 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 int64_to_net($int64)
47 Returns an 8 bytes string with the representation of the int64
48 value in network order.
49 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 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 For instance:
60 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 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 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 Underscore characters ("_") between the digits are ignored.
80 No overflow checks are performed by this function unless the
82 "die_on_overflow" pragma is used (see "Die on overflow" below).
83 See also strtoll(3).
85 hex_to_int64($i64)
87 Shortcut for string_to_int64($str, 16)
88 int64_to_string($i64, $base)
90 Converts the int64 value to its string representation in the given
91 base (defaults to 10).
92 int64_to_hex($i64)
94 Shortcut for "int64_to_string($i64, 16)".
95 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 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 $neg = ($i64 < 0 ? 1 : 0);
105 $u64 = (($neg ? ~$i64 : $i64) << 1) | $neg;
106 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 If you don't want that preprocessing for signed numbers, just use
114 the "uint64_to_BER" function instead.
115 BER_to_int64($str)
117 Decodes the int64 number in BER format from the given string.
118 There must not be any extra bytes on the string after the encoded
120 number.
121 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 The right way to shift a BER encoded number from the beginning of
127 some string is as follows:
128 $i64 = BER_to_int64(substr($str, 0, BER_length($str), ''));
130 int64_rand
132 Generates a 64 bit random number using ISAAC-64 algorithm.
133 int64_srand($seed)
135 int64_srand()
136 Sets the seed for the random number generator.
137 $seed, if given, should be a 2KB long string.
139 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 uint64_to_BER($u64)
154 Encodes the given unsigned integer in BER format (see "pack" in
155 perlfunc).
156 BER_to_uint64($str)
158 Decodes from the given string an unsigned number in BER format.
159 uint64_rand
161 Generates a 64 bit random unsigned number using ISAAC-64 algorithm.
162 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 For instance:
168 use Math::Int64 qw(uint64);
170 use Math::Int64::die_on_overflow;
171 my $zero = uint64(0);
173 say ($zero - 1); # dies as -1 falls outside
174 # the uint64_t range
175 no Math::Int64::die_on_overflow; # deactivates lexical pragma
177 say ($zero - 1); # no error is detected here!
178 The pragma can also be activated as follows:
180 use Math::Int64 ':die_on_overflow';
182 Once this pragma is used, several Math::Int64 operations may become
184 slower. Deactivating the pragma will not make them fast again.
185 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 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 For instance:
197 use Math::Int64 qw(int64);
199 $a = int64(34); # always returns an object of the class Math::Int64
201 use Math::Int64::native_if_available;
203 $a = int64(34); # returns a regular scalar on perls compiled with
204 # 64bit support
205 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 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 Besides that, in most situations it is safe to use the native fallback.
216 As happens with the "die_on_overflow" pragma, on Perl 5.8.x it is
218 global.
219 The pragma can also be activated as follows:
221 use Math::Int64 ':native_if_available';
223 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 If the corresponding method is not implemented, the object will be
231 stringified and then parsed as a base 10 number.
232 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 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 In order to use it you need to follow these steps:
243 • 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 • 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 Note that this header file requires the types int64_t and uint64_t
252 to be defined beforehand.
253 • Add the file "perl_math_int64.c" to your compilation targets (see
255 the sample Makefile.PL below).
256 • Add a call to the macro "PERL_MATH_INT64_LOAD_OR_CROAK" into the
258 "BOOT" section of your XS file.
259 For instance:
261 --- Foo64.xs ---------
263 #include "EXTERN.h"
265 #include "perl.h"
266 #include "XSUB.h"
267 #include "ppport.h"
268 /* #define MATH_INT64_NATIVE_IF_AVAILABLE */
270 #include "math_int64.h"
271 MODULE = Foo64 PACKAGE = Foo64
273 BOOT:
274 PERL_MATH_INT64_LOAD_OR_CROAK;
275 int64_t
277 some_int64()
278 CODE:
279 RETVAL = -42;
280 OUTPUT:
281 RETVAL
282 --- Makefile.PL -----
285 use ExtUtils::MakeMaker;
287 WriteMakefile( NAME => 'Foo64',
288 VERSION_FROM => 'lib/Foo64.pm',
289 OBJECT => '$(O_FILES)' );
290 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 These are the C macros available from Math::Int64 C API:
297 SV *newSVi64(int64_t i64)
299 Returns an SV representing the given int64_t value.
300 SV *newSVu64(uint64_t 64)
302 Returns an SV representing the given uint64_t value.
303 int64_t SvI64(SV *sv)
305 Extracts the int64_t value from the given SV.
306 uint64_t SvU64(SV *sv)
308 Extracts the uint64_t value from the given SV.
309 int SvI64OK(SV *sv)
311 Returns true is the given SV contains a valid int64_t value.
312 int SvU64OK(SV *sv)
314 Returns true is the given SV contains a valid uint64_t value.
315 uint64_t randU64(void)
317 Returns a random 64 bits unsigned integer.
318 SV sv_seti64(SV *sv, uint64_t i64)
320 Sets the value of the perl scalar to the given int64_t value.
321 SV sv_setu64(SV *sv, uint64_t i64)
323 Sets the value of the perl scalar to the given uint64_t value.
324 If you require any other function available through the C API don't
326 hesitate to ask for it!
327
329 The Storable integration feature is experimental.
330 The C API feature is experimental.
332 This module requires int64 support from the C compiler.
334 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 The source for the development version of the module is hosted at
340 GitHub: <https://github.com/salva/p5-Math-Int64>.
341 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
347 The C API usage sample module Math::Int64::C_API::Sample.
348 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 Copyright © 2014-2015 by Dave Rolsky (autarch@urth.org)
358 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.
362perl v5.38.0 2023-07-20 Math::Int64(3)