Table of Contents

PHP RFC: Add pack()/unpack() endianness modifiers for floating-point numbers

Introduction

This RFC proposes extending the endianness modifier syntax (< and >) to floating-point format codes in PHP's pack() and unpack() functions.

Currently, PHP's pack/unpack functions support floating-point numbers with dedicated format letters:

The new modifier syntax using < and > is not supported yet. Adding the modifier support to float formats would provide consistency with the endianness modifier syntax, recently accepted for integers in the upcoming 8.6.

This RFC presents an evolution mentioned in the “Future scope” section of the accepted RFC.

Perl Specification Reference

According to the Perl documentation (https://perldoc.perl.org/functions/pack), Perl supports endianness modifiers on floating-point format codes: 

f<   single-precision float, little-endian byte order
f>   single-precision float, big-endian byte order
d<   double-precision float, little-endian byte order
d>   double-precision float, big-endian byte order

Proposed Solution

This RFC proposes adding endianness modifiers to floating-point format codes:

Example usage: 

<?php
// little endian
$data = pack('f<d<', 3.14159, 2.71828);
 
// big endian
$data = pack('f>d>', 3.14159, 2.71828);
 
// Unpacking
[$float, $double] = array_values(unpack('f<a/d<b', $data));
?>

Equivalence with Existing Formats: 

<?php
pack('f<', 3.14) === pack('g', 3.14);
pack('f>', 3.14) === pack('G', 3.14);
pack('d<', 3.14) === pack('e', 3.14);
pack('d>', 3.14) === pack('E', 3.14);
?>

Error Handling

Modifiers on formats with inherent endianness (g/G and e/E) will emit a ValueError, for example: 

<?php
 
pack('g<', 3.14); // ValueError: Endianness modifier '<' cannot be applied to format code 'g' which already has inherent endianness
pack('G>', 3.14); // ValueError: Endianness modifier '>' cannot be applied to format code 'G' which already has inherent endianness
pack('e<', 3.14); // ValueError: Endianness modifier '<' cannot be applied to format code 'e' which already has inherent endianness
pack('E>', 3.14); // ValueError: Endianness modifier '>' cannot be applied to format code 'E' which already has inherent endianness
 
?>

Platform Consideration

PHP’s floating-point pack/unpack formats operate on the platform’s native floating-point representation and size. In practice this is typically IEEE 754 with 32 bits float and 64 bits double. This RFC does not introduce a new floating-point representation, only a new syntax for already existing format code.

Future Scope

A possible next step to this RFC would be to deprecate e, E, g and G format letters. These letters are not supported by Perl's pack() and unpack() functions and become useless with the introduction of the endianness modifier syntax.

Backward Incompatible Changes

None. The modifier syntax is opt-in and does not affect existing format strings.

Proposed PHP Version(s)

PHP 8.x (next minor)

Voting Choices

Yes / No vote requiring 2/3 Yes votes to pass.

Add endianness modifiers to pack()/unpack() for floating-point numbers?
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

References