### ----------------------------------------------------
### -- Numeric::Pack
### -- Licenses: Artistic-2.0
### -- Authors: Sam Gillespie
### -- File: README.md
### ----------------------------------------------------
### -- Chunk 1 of 3
��[![Build Status](https://travis-ci.org/samgwise/p6-Numeric-Pack.svg?branch=master)](https://travis-ci.org/samgwise/p6-Numeric-Pack)



NAME

====



Numeric::Pack - Convert Raku Numerics to Bufs and back again!



SYNOPSIS

========



    use Numeric::Pack :ALL;



    # pack and unpack floats

    my Buf $float-buf = pack-float 2.5;

    say "{ $float-buf.perl } -> { unpack-float $float-buf }";



    # pack and unpack doubles

    my Buf $double-buf = pack-double 2.5;

    say "{ $double-buf.perl } -> { unpack-double $double-buf }";



    # pack and unpack Int (see also int64 variants)

    my Buf $int-buf = pack-int32 11;

    say "{ $int-buf.perl } -> { unpack-int32 $int-buf }";



    # pack and unpack specific byte orders (native-endian is the default)

    my Buf $little-endian-buf = pack-int32 11, :byte-order(little-endian);

    say "{ $little-endian-buf.perl } -> {

      unpack-int32 $little-endian-buf, :byte-order(little-endian)

    }";



DESCRIPTION

===========



Numeric::Pack is a Raku module for packing values of the Numeric role into Buf objects (With the exception of Complex numbers). This module provides a Rakudo compatible, non-experimental, numeric packing and unpacking facility, built with utilities of NativeCall. Integer ranges from 8 to 64 bits are supported and floating point as well as double precision floating point numbers. Byte order defaults to the native byte order of the system and can be specified with the ByteOrder enum.



Numeric::Pack exports the enum ByteOrder by default (ByteOrder is exported as :MANDATORY).



<table class="pod-table">

<thead><tr>

<th>ByteOrder</th> <th>Description</th>

</tr></thead>

<tbody>

<tr> <td>native-endian</td> <td>The native byte ordering of the current system</td> </tr> <tr> <td>little-endian</td> <td>Common byte ordering of contemporary CPUs</td> </tr> <tr> <td>big-endian</td> <td>Also known as network byte order</td> </tr>

</tbody>

</table>



By default Numeric::Pack's pack and unpack functions return and accept big-endian Bufs. To override this provide the :byte-order named parameter with the enum value for your desired behaviour. To disable byte order management pass :byte-order(native-endian).



Use Numeric::Pack :ALL to export all exportable functionality.



Use :floats or :ints flags to export subsets of the module's functionality.



<table class="pod-table">

<thead><tr>

<th>Export tag</th> <th>Functions</th>

</tr></thead>

<tbody>

<tr> <td>:floats</td> <td>pack-float, unpack-float, pack-double, unpack-double</td> </tr> <tr> <td>:ints</td> <td>pack-uint32, pack-int32, unpack-int32, unpack-uint32, pack-int64, unpack-int64, pack-uint64, unpack-uint64, pack-int16, unpack-int16, pack-uint16, unpack-uint16, pack-int8, unpack-int8, pack-uint8, unpack-uint8</td> </tr> <tr> <td>:ber</td> <td>pack-ber, unpack-ber, collect-ber</td> </tr>

</tbody>

</table>



CHANGES

=======



<table class="pod-table">

<tbody>

<tr> <td>Added ber encoding and decoding ala perl pack &#39;w&#39;</td> <td>Expanded potential use cases</td> <td>2020-04-28</td> </tr> <tr> <td>Added 8 and 16 bit integer types</td> <td>Expanded potential use cases</td> <td>2020-04-27</td> </tr> <tr> <td>Removed bundled native library, now pure perl6</td> <td>Improved portability and reliability</td> <td>2018-06-20</td> </tr> <tr> <td>Added pack-uint32, pack-uint32 and unpack-uint32</td> <td>Added support for unsigned types</td> <td>2017-04-20</td> </tr> <tr> <td>Changed named argument :endianness to :byte-order</td> <td>Signatures now read more naturally</td> <td>2016-08-30</td> </tr>

</tbody>

</table>



SEE ALSO

========



Rakudo core from 6.d 2018 and later supports reading values from a blob8 with a very similar interface to this module, see the docs here: [https://docs.perl6.org/type/Blob#Methods_on_blob8_only_(6.d,_2018.12_and_later)](https://docs.perl6.org/type/Blob#Methods_on_blob8_only_(6.d,_2018.12_and_later)).



The [Native::Packing](https://github.com/pdf-raku/Native-Packing-raku) module provides a role based packing mechanism for clas