mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 17:08:35 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

gh-69011: : clarify & deduplicate ctypes.create_*_buffer docs (GH-132858)

Browse source 
This adds a warning about the possibly-missing NUL terminator, but in a way
that doesn't make it sound like a bug/wart.
This commit is contained in:
Stan Ulbrych 2025-05-29 14:16:20 +01:00 • committed by GitHub
parent e64395e8eb
commit b783e1791b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 36 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

52
Doc/library/ctypes.rst
View file

@ -2031,35 +2031,55 @@ Utility functions
pointer.
.. function:: create_string_buffer(init_or_size, size=None)
.. function:: create_string_buffer(init, size=None)
create_string_buffer(size)
This function creates a mutable character buffer. The returned object is a
ctypes array of :class:`c_char`.
*init_or_size* must be an integer which specifies the size of the array, or a
bytes object which will be used to initialize the array items.
If *size* is given (and not ``None``), it must be an :class:`int`.
It specifies the size of the returned array.
If a bytes object is specified as first argument, the buffer is made one item
larger than its length so that the last element in the array is a NUL
termination character. An integer can be passed as second argument which allows
specifying the size of the array if the length of the bytes should not be used.
If the *init* argument is given, it must be :class:`bytes`. It is used
to initialize the array items. Bytes not initialized this way are
set to zero (NUL).
If *size* is not given (or if it is ``None``), the buffer is made one element
larger than *init*, effectively adding a NUL terminator.
If both arguments are given, *size* must not be less than ``len(init)``.
.. warning::
If *size* is equal to ``len(init)``, a NUL terminator is
not added. Do not treat such a buffer as a C string.
For example::
>>> bytes(create_string_buffer(2))
b'\x00\x00'
>>> bytes(create_string_buffer(b'ab'))
b'ab\x00'
>>> bytes(create_string_buffer(b'ab', 2))
b'ab'
>>> bytes(create_string_buffer(b'ab', 4))
b'ab\x00\x00'
>>> bytes(create_string_buffer(b'abcdef', 2))
Traceback (most recent call last):
...
ValueError: byte string too long
.. audit-event:: ctypes.create_string_buffer init,size ctypes.create_string_buffer
.. function:: create_unicode_buffer(init_or_size, size=None)
.. function:: create_unicode_buffer(init, size=None)
create_unicode_buffer(size)
This function creates a mutable unicode character buffer. The returned object is
a ctypes array of :class:`c_wchar`.
*init_or_size* must be an integer which specifies the size of the array, or a
string which will be used to initialize the array items.
If a string is specified as first argument, the buffer is made one item
larger than the length of the string so that the last element in the array is a
NUL termination character. An integer can be passed as second argument which
allows specifying the size of the array if the length of the string should not
be used.
The function takes the same arguments as :func:`~create_string_buffer` except
*init* must be a string and *size* counts :class:`c_wchar`.
.. audit-event:: ctypes.create_unicode_buffer init,size ctypes.create_unicode_buffer