Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-111140: Minor doc fixes for PyLong_AsNativeBytes (GH-115375)

This commit is contained in:
Steve Dower 2024-02-12 22:28:36 +00:00 committed by GitHub
parent 341d7874f0
commit 10756b10ff
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 14 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
Doc/c-api/long.rst
View File

@ -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::