From 57236552eae1a1b580c6bd427b092cf4ef3b276c Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 23 Apr 2025 22:45:50 +0100 Subject: [PATCH 1/5] commit --- Doc/library/ctypes.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 0bf88b0e3b66c6..6fd88b9d6e56ea 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2041,8 +2041,9 @@ Utility functions 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. + termination character. An integer *size* can be passed which allows + specifying the size of the array if the length of the bytes should not be used; + Note that if *size* is too small the NUL termination character will be omitted. .. audit-event:: ctypes.create_string_buffer init,size ctypes.create_string_buffer @@ -2057,9 +2058,9 @@ Utility functions 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. + NUL termination character. An integer *size* can be passed which allows + specifying the size of the array if the length of the bytes should not be used; + Note that if *size* is too small the NUL termination character will be omitted. .. audit-event:: ctypes.create_unicode_buffer init,size ctypes.create_unicode_buffer From 03843e1bf00b6ca9b44b0777bec8e04a8dc995f2 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 23 Apr 2025 22:48:12 +0100 Subject: [PATCH 2/5] fixup! commit --- Doc/library/ctypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 6fd88b9d6e56ea..0939609cb6f5b1 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2058,7 +2058,7 @@ Utility functions 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 *size* can be passed which allows + NUL termination character. An integer *size* can be passed which allows specifying the size of the array if the length of the bytes should not be used; Note that if *size* is too small the NUL termination character will be omitted. From 4fe532476ccbe913b2ff04cafa7ab348791e61e6 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 24 Apr 2025 14:36:20 +0100 Subject: [PATCH 3/5] Peter's suggestions --- Doc/library/ctypes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 0939609cb6f5b1..15da19f46f0c39 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2043,7 +2043,7 @@ Utility functions larger than its length so that the last element in the array is a NUL termination character. An integer *size* can be passed which allows specifying the size of the array if the length of the bytes should not be used; - Note that if *size* is too small the NUL termination character will be omitted. + note that if *size* is too small, the buffer will not be null terminated. .. audit-event:: ctypes.create_string_buffer init,size ctypes.create_string_buffer @@ -2060,7 +2060,7 @@ Utility functions larger than the length of the string so that the last element in the array is a NUL termination character. An integer *size* can be passed which allows specifying the size of the array if the length of the bytes should not be used; - Note that if *size* is too small the NUL termination character will be omitted. + note that if *size* is too small, the buffer will not be null terminated. .. audit-event:: ctypes.create_unicode_buffer init,size ctypes.create_unicode_buffer From 23a91c106911b6b929509ccaa6f752d0aec22b28 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 28 Apr 2025 16:49:01 +0100 Subject: [PATCH 4/5] Petr's suggestion # Conflicts: # Doc/library/ctypes.rst --- Doc/library/ctypes.rst | 80 +++++++++++++++++++++++++++++++++--------- 1 file changed, 64 insertions(+), 16 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 15da19f46f0c39..441fc842c2fea4 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2031,36 +2031,84 @@ 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 *size* can be passed which allows - specifying the size of the array if the length of the bytes should not be used; - note that if *size* is too small, the buffer will not be null terminated. + 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 byte + larger than *init*, effectively adding a NUL termination byte. + + 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 *size* is given (and not ``None``), it must be an :class:`int`. + It specifies the size of the returned array. + + If the *init* argument is given, it must be a string. 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 byte + larger than *init*, effectively adding a NUL termination byte. + + 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:: - 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 *size* can be passed which allows - specifying the size of the array if the length of the bytes should not be used; - note that if *size* is too small, the buffer will not be null terminated. + >>> bytes(create_unicode_buffer(2)) + b'\x00\x00\x00\x00\x00\x00\x00\x00' + >>> bytes(create_unicode_buffer('ab')) + b'a\x00\x00\x00b\x00\x00\x00\x00\x00\x00\x00' + >>> bytes(create_unicode_buffer('ab', 2)) + b'a\x00\x00\x00b\x00\x00\x00' + >>> bytes(create_unicode_buffer('ab', 4)) + b'a\x00\x00\x00b\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' + >>> bytes(create_unicode_buffer('abcdef', 2)) + Traceback (most recent call last): + ... + ValueError: string too long .. audit-event:: ctypes.create_unicode_buffer init,size ctypes.create_unicode_buffer From b39c8acaaaa6f2a531e862255410046b2fe72c9b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 18 May 2025 08:45:29 +0100 Subject: [PATCH 5/5] De-duplicate --- Doc/library/ctypes.rst | 37 ++++--------------------------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 441fc842c2fea4..0d578c8cb03d4b 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2044,8 +2044,8 @@ Utility functions 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 byte - larger than *init*, effectively adding a NUL termination byte. + 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)``. @@ -2078,37 +2078,8 @@ Utility functions This function creates a mutable unicode character buffer. The returned object is a ctypes array of :class:`c_wchar`. - If *size* is given (and not ``None``), it must be an :class:`int`. - It specifies the size of the returned array. - - If the *init* argument is given, it must be a string. 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 byte - larger than *init*, effectively adding a NUL termination byte. - - 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_unicode_buffer(2)) - b'\x00\x00\x00\x00\x00\x00\x00\x00' - >>> bytes(create_unicode_buffer('ab')) - b'a\x00\x00\x00b\x00\x00\x00\x00\x00\x00\x00' - >>> bytes(create_unicode_buffer('ab', 2)) - b'a\x00\x00\x00b\x00\x00\x00' - >>> bytes(create_unicode_buffer('ab', 4)) - b'a\x00\x00\x00b\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00' - >>> bytes(create_unicode_buffer('abcdef', 2)) - Traceback (most recent call last): - ... - ValueError: string too long + 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