bpo-42431: Fix outdated bytes comments (GH-23458)
Also move definitions of internal macros F_LJUST etc to private header.
diff --git a/Include/bytesobject.h b/Include/bytesobject.h
index 5062d8d..39c241a 100644
--- a/Include/bytesobject.h
+++ b/Include/bytesobject.h
@@ -1,5 +1,5 @@
-/* Bytes (String) object interface */
+/* Bytes object interface */
#ifndef Py_BYTESOBJECT_H
#define Py_BYTESOBJECT_H
@@ -10,23 +10,20 @@ extern "C" {
#include <stdarg.h>
/*
-Type PyBytesObject represents a character string. An extra zero byte is
+Type PyBytesObject represents a byte string. An extra zero byte is
reserved at the end to ensure it is zero-terminated, but a size is
present so strings with null bytes in them can be represented. This
is an immutable object type.
-There are functions to create new string objects, to test
-an object for string-ness, and to get the
-string value. The latter function returns a null pointer
+There are functions to create new bytes objects, to test
+an object for bytes-ness, and to get the
+byte string value. The latter function returns a null pointer
if the object is not of the proper type.
There is a variant that takes an explicit size as well as a
variant that assumes a zero-terminated string. Note that none of the
-functions should be applied to nil objects.
+functions should be applied to NULL pointer.
*/
-/* Caching the hash (ob_shash) saves recalculation of a string's hash value.
- This significantly speeds up dict lookups. */
-
PyAPI_DATA(PyTypeObject) PyBytes_Type;
PyAPI_DATA(PyTypeObject) PyBytesIter_Type;
@@ -50,26 +47,16 @@ PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t,
const char *, Py_ssize_t,
const char *);
-/* Provides access to the internal data buffer and size of a string
- object or the default encoded version of a Unicode object. Passing
- NULL as *len parameter will force the string buffer to be
- 0-terminated (passing a string with embedded NULL characters will
+/* Provides access to the internal data buffer and size of a bytes object.
+ Passing NULL as len parameter will force the string buffer to be
+ 0-terminated (passing a string with embedded NUL characters will
cause an exception). */
PyAPI_FUNC(int) PyBytes_AsStringAndSize(
- PyObject *obj, /* string or Unicode object */
+ PyObject *obj, /* bytes object */
char **s, /* pointer to buffer variable */
- Py_ssize_t *len /* pointer to length variable or NULL
- (only possible for 0-terminated
- strings) */
+ Py_ssize_t *len /* pointer to length variable or NULL */
);
-/* Flags used by string formatting */
-#define F_LJUST (1<<0)
-#define F_SIGN (1<<1)
-#define F_BLANK (1<<2)
-#define F_ALT (1<<3)
-#define F_ZERO (1<<4)
-
#ifndef Py_LIMITED_API
# define Py_CPYTHON_BYTESOBJECT_H
# include "cpython/bytesobject.h"
diff --git a/Include/cpython/bytesobject.h b/Include/cpython/bytesobject.h
index f284c58..6b3f552 100644
--- a/Include/cpython/bytesobject.h
+++ b/Include/cpython/bytesobject.h
@@ -10,7 +10,7 @@ typedef struct {
/* Invariants:
* ob_sval contains space for 'ob_size+1' elements.
* ob_sval[ob_size] == 0.
- * ob_shash is the hash of the string or -1 if not computed yet.
+ * ob_shash is the hash of the byte string or -1 if not computed yet.
*/
} PyBytesObject;
diff --git a/Include/internal/pycore_format.h b/Include/internal/pycore_format.h
new file mode 100644
index 0000000..1b8d575
--- /dev/null
+++ b/Include/internal/pycore_format.h
@@ -0,0 +1,27 @@
+#ifndef Py_INTERNAL_FORMAT_H
+#define Py_INTERNAL_FORMAT_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_BUILD_CORE
+# error "this header requires Py_BUILD_CORE define"
+#endif
+
+/* Format codes
+ * F_LJUST '-'
+ * F_SIGN '+'
+ * F_BLANK ' '
+ * F_ALT '#'
+ * F_ZERO '0'
+ */
+#define F_LJUST (1<<0)
+#define F_SIGN (1<<1)
+#define F_BLANK (1<<2)
+#define F_ALT (1<<3)
+#define F_ZERO (1<<4)
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_INTERNAL_FORMAT_H */