mirror of
https://github.com/python/cpython.git
synced 2025-09-20 07:31:10 +00:00
gh-111140: Minor doc fixes for PyLong_AsNativeBytes (GH-115375)
This commit is contained in:
parent
341d7874f0
commit
10756b10ff
1 changed files with 14 additions and 10 deletions
|
@ -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::
|
||||||
|
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue