Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 23:21:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source
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
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*:: Copy the Python integer value to a native *buffer* of size *n_bytes*::
int value; 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) { if (bytes < 0) {
// Error occurred // Error occurred
return NULL; return NULL;
} }
else if (bytes > sizeof(value)) { else if (bytes <= (Py_ssize_t)sizeof(value)) {
// Overflow occurred, but 'value' contains as much as could fit // Success!
}
else {
// Overflow occurred, but 'value' contains truncated value
} }
*endianness* may be passed ``-1`` for the native endian that CPython was *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 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 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 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 Values are always copied as two's-complement, and sufficient buffer will be
requested for a sign bit. For example, this may cause an value that fits into requested to include a sign bit. For example, this may cause an value that
8 bytes when treated as unsigned to request 9 bytes, even though all eight fits into 8 bytes when treated as unsigned to request 9 bytes, even though
bytes were copied into the buffer. What has been omitted is the zero sign all eight bytes were copied into the buffer. What has been omitted is the
bit, which is redundant when the intention is to treat the value as unsigned. 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:: .. note::