https://github.com/python/cpython/commit/10756b10ff8e47ece33f7fbf62c9a06f8a866fed
commit: 10756b10ff8e47ece33f7fbf62c9a06f8a866fed
branch: main
author: Steve Dower <[email protected]>
committer: zooba <[email protected]>
date: 2024-02-12T22:28:36Z
summary:
gh-111140: Minor doc fixes for PyLong_AsNativeBytes (GH-115375)
files:
M Doc/c-api/long.rst
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index c39823e5e6787f..f24282e76a33d1 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -359,13 +359,16 @@ distinguished from a number. Use
:c:func:`PyErr_Occurred` to disambiguate.
Copy the Python integer value to a native *buffer* of size *n_bytes*::
int value;
- Py_ssize_t bytes = PyLong_CopyBits(v, &value, sizeof(value), -1);
+ Py_ssize_t bytes = PyLong_AsNativeBytes(v, &value, sizeof(value), -1);
if (bytes < 0) {
// Error occurred
return NULL;
}
- else if (bytes > sizeof(value)) {
- // Overflow occurred, but 'value' contains as much as could fit
+ else if (bytes <= (Py_ssize_t)sizeof(value)) {
+ // Success!
+ }
+ else {
+ // Overflow occurred, but 'value' contains truncated value
}
*endianness* may be passed ``-1`` for the native endian that CPython was
@@ -379,15 +382,16 @@ distinguished from a number. Use
:c:func:`PyErr_Occurred` to disambiguate.
Unless an exception is raised, all *n_bytes* of the buffer will be written
with as much of the value as can fit. This allows the caller to ignore all
non-negative results if the intent is to match the typical behavior of a
- C-style downcast.
+ C-style downcast. No exception is set for this case.
- Values are always copied as twos-complement, and sufficient size will be
- requested for a sign bit. For example, this may cause an value that fits
into
- 8 bytes when treated as unsigned to request 9 bytes, even though all eight
- bytes were copied into the buffer. What has been omitted is the zero sign
- bit, which is redundant when the intention is to treat the value as
unsigned.
+ Values are always copied as two's-complement, and sufficient buffer will be
+ requested to include a sign bit. For example, this may cause an value that
+ fits into 8 bytes when treated as unsigned to request 9 bytes, even though
+ all eight bytes were copied into the buffer. What has been omitted is the
+ zero sign bit, which is redundant when the intention is to treat the value
as
+ unsigned.
- Passing *n_bytes* of zero will always return the requested buffer size.
+ Passing zero to *n_bytes* will return the requested buffer size.
.. note::
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
