Skip to content

bpo-46906: Mention PY_BIG_ENDIAN in PyFloat_Pack8() doc #31832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

bpo-46906: Mention PY_BIG_ENDIAN in PyFloat_Pack8() doc #31832

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions Doc/c-api/float.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,8 @@ Pack functions
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:type:`int` argument, non-zero if you want the bytes string in little-endian
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
want big-endian format (exponent first, at *p*).
want big-endian format (exponent first, at *p*). Pass :c:data:`PY_BIG_ENDIAN`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if your platform is little-endian, then passing PY_BIG_ENDIAN uses a little-endian format? That seems confusing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PY_BIG_ENDIAN is 1 on big endian platform, and 0 on little endian platform.

int.to_bytes() uses the native endian by default (if the byte_order parameter is not set). Maybe we could accept -1 to mean "use native endian"?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

int.to_bytes() uses the native endian by default

It uses big-endian by default.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops. You're right. I now recall a long discussion about the default :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems confusing.

Agreed, but it's primarily a problem with the naming of PY_BIG_ENDIAN, which would perhaps be better spelled as something like PY_PLATFORM_ENDIAN_IS_BIG_ENDIAN.

But usage of PY_BIG_ENDIAN is at least a little bit problematic, since there's nothing anywhere in C that guarantees that integer types and float types will use the same endianness (or even that float types have to follow one of big-endian or little-endian at all).

Maybe we could accept -1 to mean "use native endian"?

I'd suggest leaving it as-is - it's easy enough to pass PY_BIG_ENDIAN.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I proposed a different wording for the documentation: PR #31866. Is it better?

to *le* to use the native endian.

Return value: ``0`` if all is OK, ``-1`` if error (and an exception is set,
most likely :exc:`OverflowError`).
Expand Down Expand Up @@ -138,7 +139,8 @@ Unpack functions
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:type:`int` argument, non-zero if the bytes string is in little-endian format
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
(exponent first, at *p*).
(exponent first, at *p*). Pass :c:data:`PY_BIG_ENDIAN` to *le* to use the
native endian.

Return value: The unpacked double. On error, this is ``-1.0`` and
:c:func:`PyErr_Occurred` is true (and an exception is set, most likely
Expand Down