/ 
Math-Int64-0.11
River stage two • 28 direct dependents • 86 total dependents
/ Math::Int64

NAME

Math::Int64 - Manipulate 64 bits integers in Perl

SYNOPSIS

use Math::Int64 qw(int64);

my $i = int64(1);
my $j = $i << 40;
my $k = int64("12345678901234567890");
print($i + $j * 1000000);

DESCRIPTION

This module adds support for 64 bit integers, signed and unsigned, to Perl.

Exportable functions

int64()
int64($value)

Creates a new int64 value and initializes it to $value, where $value can be a Perl number or a string containing a number.

For instance:

$i = int64(34);
$j = int64("-123454321234543212345");

$k = int64(1234567698478483938988988); # wrong!!!
                                       #  the unquoted number would
                                       #  be converted first to a
                                       #  real number causing it to
                                       #  loose some precision.

Once the int64 number is created it can be manipulated as any other Perl value supporting all the standard operations (addition, negation, multiplication, postincrement, etc.).

net_to_int64($str)

Converts an 8 bytes string containing an int64 in network order to the internal representation used by this module.

int64_to_net($int64)

Returns an 8 bytes string with the representation of the int64 value in network order.

native_to_int64($str)
int64_to_native($int64)

similar to net_to_int64 and int64_to_net, but using the native CPU order.

int64_to_number($int64)

returns the optimum representation of the int64 value using Perl internal types (IV, UV or NV). Precision may be lost.

For instance:

for my $l (10, 20, 30, 40, 50, 60) {
  my $i = int64(1) << $l;
  my $n = int64_to_number($i);
  print "int64:$i => perl:$n\n";
}
uint64
uint64_to_number
net_to_uint64
uint64_to_net
native_to_uint64
uint64_to_native

These functions are similar to their int64 counterparts, but manipulate 64 bit unsigned integers.

Fallback to native 64bit support if available

If the tag :native_if_available is added to the import list and the version of perl used has native support for 64bit integers, the functions exported by the module to create 64bit integers will return regular perl scalars.

Usage example:

use Math::Int64 qw( :native_if_available int64 );

This feature is not enabled by default because the semantics for perl scalars and for 64 bit integers as implemented in this module are not identical. Perl is prone to coerze integers into floats while this module keeps then always as 64bit integers. Specifically, the division operation and overflows are the most problematic cases.

Besides that, in most situations it is safe to use the native fallback.

C API

This module provides a native C API that can be used to create and read Math::Int64 int64 and uint64 SVs from your own XS modules.

In order to use it you need to follow these steps:

  • Import the files perl_math_int64.c, perl_math_int64.h and optionally typemaps from Math::Int64 c_api directory into your project directory.

  • Include the file perl_math_int64.h in the C or XS source files where you want to convert 64bit integers to/from Perl SVs.

    Note that this header file requires the types int64_t and uint64_t to be defined beforehand.

  • Add the file perl_math_int64.c to your compilation targets (see the sample Makefile.PL below).

  • Add a call to the macro MATH_INT64_BOOT to the BOOT section of your XS file.

For instance:

--- Foo64.xs ---------

 #include "EXTERN.h"
 #include "perl.h"
 #include "XSUB.h"
 #include "ppport.h"
 
 /* #define MATH_INT64_NATIVE_IF_AVAILABLE */
 #include "math_int64.h"
 
 MODULE = Foo64		PACKAGE = Foo64
 BOOT:
     MATH_INT64_BOOT;
 
 int64_t
 some_int64()
 CODE:
     RETVAL = -42;
 OUTPUT:
     RETVAL
 
 
 --- Makefile.PL -----

 use ExtUtils::MakeMaker;
 WriteMakefile( NAME         => 'Foo64',
                VERSION_FROM => 'lib/Foo64.pm',
                OBJECT       => '$(O_FILES)' );

If the macro MATH_INT64_NATIVE_IF_AVAILABLE is defined before including perl_math_int64.h and the perl interpreter is compiled with mative 64bit integer support, IVs will be used to represent 64bit integers instead of the object representation provided by Math::Int64.

These are the C macros available from Math::Int64 C API:

SV *newSVi64(int64_t i64)

Returns an SV representing the given int64_t value.

SV *newSVu64(uint64_t 64)

Returns an SV representing the given uint64_t value.

int64_t SvI64(SV *sv)

Extracts the int64_t value from the given SV.

uint64_t SvU64(SV *sv)

Extracts the uint64_t value from the given SV.

int SvI64OK(SV *sv)

Returns true is the given SV contains a valid int64_t value.

int SvU64OK(SV *sv)

Returns true is the given SV contains a valid uint64_t value.

BUGS AND SUPPORT

The C API feature is experimental.

The fallback to native 64bit integers feature is experimental.

This module requires int64 support from the C compiler.

For bug reports, feature requests or just help using this module, use the RT system at http://rt.cpan.org or send my and email or both!

The source code of this module is hosted at GitHub: http://github.com/salva/p5-Math-Int64.

SEE ALSO

The C API usage sample module Math::Int64::C_API::Sample.

Other modules that allow Perl to support larger integers or numbers are Math::BigInt, Math::BigRat and Math::Big, Math::BigInt::BitVect, Math::BigInt::Pari and Math::BigInt::GMP.

COPYRIGHT AND LICENSE

Copyright © 2007, 2009, 2011 by Salvador Fandiño (sfandino@yahoo.com)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.