update docs after renaming of PyString -> PyBytes

3 files changed, 195 insertions, 246 deletions

diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
new file mode 100644
index 0000000..916e20e
--- /dev/null
+++ b/Doc/c-api/bytes.rst
@@ -0,0 +1,194 @@
+.. highlightlang:: c
+
+.. _bytesobjects:
+
+Bytes Objects
+-------------
+
+These functions raise :exc:`TypeError` when expecting a bytes parameter and are
+called with a non-bytes parameter.
+
+.. index:: object: bytes
+
+
+.. ctype:: PyBytesObject
+
+   This subtype of :ctype:`PyObject` represents a Python bytes object.
+
+
+.. cvar:: PyTypeObject PyBytes_Type
+
+   .. index:: single: BytesType (in module types)
+
+   This instance of :ctype:`PyTypeObject` represents the Python bytes type; it
+   is the same object as ``bytes`` in the Python layer. .
+
+
+.. cfunction:: int PyBytes_Check(PyObject *o)
+
+   Return true if the object *o* is a bytes object or an instance of a subtype
+   of the bytes type.
+
+
+.. cfunction:: int PyBytes_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytes object, but not an instance of a
+   subtype of the bytes type.
+
+
+.. cfunction:: PyObject* PyBytes_FromString(const char *v)
+
+   Return a new bytes object with a copy of the string *v* as value on success,
+   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
+   checked.
+
+
+.. cfunction:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
+
+   Return a new bytes object with a copy of the string *v* as value and length
+   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of
+   the bytes object are uninitialized.
+
+
+.. cfunction:: PyObject* PyBytes_FromFormat(const char *format, ...)
+
+   Take a C :cfunc:`printf`\ -style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python bytes object and return
+   a bytes object with the values formatted into it.  The variable arguments
+   must be C types and must correspond exactly to the format characters in the
+   *format* string.  The following format characters are allowed:
+
+   .. % XXX: This should be exactly the same as the table in PyErr_Format.
+   .. % One should just refer to the other.
+   .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
+   .. % because not all compilers support the %z width modifier -- we fake it
+   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+   +-------------------+---------------+--------------------------------+
+   | Format Characters | Type          | Comment                        |
+   +===================+===============+================================+
+   | :attr:`%%`        | *n/a*         | The literal % character.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%c`        | int           | A single character,            |
+   |                   |               | represented as an C int.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%d`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%d")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
+   |                   |               | ``printf("%u")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%ld`       | long          | Exactly equivalent to          |
+   |                   |               | ``printf("%ld")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
+   |                   |               | ``printf("%lu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
+   |                   |               | ``printf("%zd")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
+   |                   |               | ``printf("%zu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%i`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%i")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%x`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%x")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   |                   |               | array.                         |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   |                   |               | pointer. Mostly equivalent to  |
+   |                   |               | ``printf("%p")`` except that   |
+   |                   |               | it is guaranteed to start with |
+   |                   |               | the literal ``0x`` regardless  |
+   |                   |               | of what the platform's         |
+   |                   |               | ``printf`` yields.             |
+   +-------------------+---------------+--------------------------------+
+
+   An unrecognized format character causes all the rest of the format string to be
+   copied as-is to the result string, and any extra arguments discarded.
+
+
+.. cfunction:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :func:`PyBytes_FromFormat` except that it takes exactly two
+   arguments.
+
+
+.. cfunction:: Py_ssize_t PyBytes_Size(PyObject *o)
+
+   Return the length of the bytes in bytes object *o*.
+
+
+.. cfunction:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
+
+   Macro form of :cfunc:`PyBytes_Size` but without error checking.
+
+
+.. cfunction:: char* PyBytes_AsString(PyObject *o)
+
+   Return a NUL-terminated representation of the contents of *o*.  The pointer
+   refers to the internal buffer of *o*, not a copy.  The data must not be
+   modified in any way, unless the string was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
+   *o* is not a string object at all, :cfunc:`PyBytes_AsString` returns *NULL*
+   and raises :exc:`TypeError`.
+
+
+.. cfunction:: char* PyBytes_AS_STRING(PyObject *string)
+
+   Macro form of :cfunc:`PyBytes_AsString` but without error checking.
+
+
+.. cfunction:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+
+   Return a NUL-terminated representation of the contents of the object *obj*
+   through the output variables *buffer* and *length*.
+
+   If *length* is *NULL*, the resulting buffer may not contain NUL characters;
+   if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
+
+   The buffer refers to an internal string buffer of *obj*, not a copy. The data
+   must not be modified in any way, unless the string was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
+   *string* is not a string object at all, :cfunc:`PyBytes_AsStringAndSize`
+   returns ``-1`` and raises :exc:`TypeError`.
+
+
+.. cfunction:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
+
+   Create a new bytes object in *\*bytes* containing the contents of *newpart*
+   appended to *bytes*; the caller will own the new reference.  The reference to
+   the old value of *bytes* will be stolen.  If the new string cannot be
+   created, the old reference to *bytes* will still be discarded and the value
+   of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
+
+
+.. cfunction:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
+
+   Create a new string object in *\*bytes* containing the contents of *newpart*
+   appended to *bytes*.  This version decrements the reference count of
+   *newpart*.
+
+
+.. cfunction:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
+
+   A way to resize a bytes object even though it is "immutable". Only use this
+   to build up a brand new bytes object; don't use this if the bytes may already
+   be known in other parts of the code.  It is an error to call this function if
+   the refcount on the input bytes object is not one. Pass the address of an
+   existing bytes object as an lvalue (it may be written into), and the new size
+   desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
+   returned; the address in *\*bytes* may differ from its input value.  If the
+   reallocation fails, the original bytes object at *\*bytes* is deallocated,
+   *\*bytes* is set to *NULL*, a memory exception is set, and ``-1`` is
+   returned.
+
+
+.. cfunction:: PyObject* PyBytes_Format(PyObject *format, PyObject *args)
+
+   Return a new bytes object from *format* and *args*. Analogous to ``format %
+   args``.  The *args* argument must be a tuple.
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
index a0dfe21..733a0bc 100644
--- a/Doc/c-api/concrete.rst
+++ b/Doc/c-api/concrete.rst
@@ -65,7 +65,7 @@ intrinsic to the Python language.
 
 .. toctree::
 
-   string.rst
+   bytes.rst
    unicode.rst
    buffer.rst
    tuple.rst
diff --git a/Doc/c-api/string.rst b/Doc/c-api/string.rst
deleted file mode 100644
index 56fcd80..0000000
--- a/Doc/c-api/string.rst
+++ /dev/null
@@ -1,245 +0,0 @@
-.. highlightlang:: c
-
-.. _stringobjects:
-
-String Objects
---------------
-
-These functions raise :exc:`TypeError` when expecting a string parameter and are
-called with a non-string parameter.
-
-.. index:: object: string
-
-
-.. ctype:: PyStringObject
-
-   This subtype of :ctype:`PyObject` represents a Python string object.
-
-
-.. cvar:: PyTypeObject PyString_Type
-
-   .. index:: single: StringType (in module types)
-
-   This instance of :ctype:`PyTypeObject` represents the Python string type; it is
-   the same object as ``str`` and ``types.StringType`` in the Python layer. .
-
-
-.. cfunction:: int PyString_Check(PyObject *o)
-
-   Return true if the object *o* is a string object or an instance of a subtype of
-   the string type.
-
-
-.. cfunction:: int PyString_CheckExact(PyObject *o)
-
-   Return true if the object *o* is a string object, but not an instance of a
-   subtype of the string type.
-
-
-.. cfunction:: PyObject* PyString_FromString(const char *v)
-
-   Return a new string object with a copy of the string *v* as value on success,
-   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
-   checked.
-
-
-.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
-
-   Return a new string object with a copy of the string *v* as value and length
-   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of the
-   string are uninitialized.
-
-
-.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
-
-   Take a C :cfunc:`printf`\ -style *format* string and a variable number of
-   arguments, calculate the size of the resulting Python string and return a string
-   with the values formatted into it.  The variable arguments must be C types and
-   must correspond exactly to the format characters in the *format* string.  The
-   following format characters are allowed:
-
-   .. % XXX: This should be exactly the same as the table in PyErr_Format.
-   .. % One should just refer to the other.
-   .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
-   .. % because not all compilers support the %z width modifier -- we fake it
-   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
-
-   +-------------------+---------------+--------------------------------+
-   | Format Characters | Type          | Comment                        |
-   +===================+===============+================================+
-   | :attr:`%%`        | *n/a*         | The literal % character.       |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%c`        | int           | A single character,            |
-   |                   |               | represented as an C int.       |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%d`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%d")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
-   |                   |               | ``printf("%u")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%ld`       | long          | Exactly equivalent to          |
-   |                   |               | ``printf("%ld")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
-   |                   |               | ``printf("%lu")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
-   |                   |               | ``printf("%zd")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
-   |                   |               | ``printf("%zu")``.             |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%i`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%i")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%x`        | int           | Exactly equivalent to          |
-   |                   |               | ``printf("%x")``.              |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%s`        | char\*        | A null-terminated C character  |
-   |                   |               | array.                         |
-   +-------------------+---------------+--------------------------------+
-   | :attr:`%p`        | void\*        | The hex representation of a C  |
-   |                   |               | pointer. Mostly equivalent to  |
-   |                   |               | ``printf("%p")`` except that   |
-   |                   |               | it is guaranteed to start with |
-   |                   |               | the literal ``0x`` regardless  |
-   |                   |               | of what the platform's         |
-   |                   |               | ``printf`` yields.             |
-   +-------------------+---------------+--------------------------------+
-
-   An unrecognized format character causes all the rest of the format string to be
-   copied as-is to the result string, and any extra arguments discarded.
-
-
-.. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
-
-   Identical to :func:`PyString_FromFormat` except that it takes exactly two
-   arguments.
-
-
-.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
-
-   Return the length of the string in string object *string*.
-
-
-.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
-
-   Macro form of :cfunc:`PyString_Size` but without error checking.
-
-
-.. cfunction:: char* PyString_AsString(PyObject *string)
-
-   Return a NUL-terminated representation of the contents of *string*.  The pointer
-   refers to the internal buffer of *string*, not a copy.  The data must not be
-   modified in any way, unless the string was just created using
-   ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
-   *string* is a Unicode object, this function computes the default encoding of
-   *string* and operates on that.  If *string* is not a string object at all,
-   :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
-
-
-.. cfunction:: char* PyString_AS_STRING(PyObject *string)
-
-   Macro form of :cfunc:`PyString_AsString` but without error checking.  Only
-   string objects are supported; no Unicode objects should be passed.
-
-
-.. cfunction:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
-
-   Return a NUL-terminated representation of the contents of the object *obj*
-   through the output variables *buffer* and *length*.
-
-   The function accepts both string and Unicode objects as input. For Unicode
-   objects it returns the default encoded version of the object.  If *length* is
-   *NULL*, the resulting buffer may not contain NUL characters; if it does, the
-   function returns ``-1`` and a :exc:`TypeError` is raised.
-
-   The buffer refers to an internal string buffer of *obj*, not a copy. The data
-   must not be modified in any way, unless the string was just created using
-   ``PyString_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
-   *string* is a Unicode object, this function computes the default encoding of
-   *string* and operates on that.  If *string* is not a string object at all,
-   :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
-
-
-.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
-
-   Create a new string object in *\*string* containing the contents of *newpart*
-   appended to *string*; the caller will own the new reference.  The reference to
-   the old value of *string* will be stolen.  If the new string cannot be created,
-   the old reference to *string* will still be discarded and the value of
-   *\*string* will be set to *NULL*; the appropriate exception will be set.
-
-
-.. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
-
-   Create a new string object in *\*string* containing the contents of *newpart*
-   appended to *string*.  This version decrements the reference count of *newpart*.
-
-
-.. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
-
-   A way to resize a string object even though it is "immutable". Only use this to
-   build up a brand new string object; don't use this if the string may already be
-   known in other parts of the code.  It is an error to call this function if the
-   refcount on the input string object is not one. Pass the address of an existing
-   string object as an lvalue (it may be written into), and the new size desired.
-   On success, *\*string* holds the resized string object and ``0`` is returned;
-   the address in *\*string* may differ from its input value.  If the reallocation
-   fails, the original string object at *\*string* is deallocated, *\*string* is
-   set to *NULL*, a memory exception is set, and ``-1`` is returned.
-
-
-.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
-
-   Return a new string object from *format* and *args*. Analogous to ``format %
-   args``.  The *args* argument must be a tuple.
-
-
-.. cfunction:: void PyString_InternInPlace(PyObject **string)
-
-   Intern the argument *\*string* in place.  The argument must be the address of a
-   pointer variable pointing to a Python string object.  If there is an existing
-   interned string that is the same as *\*string*, it sets *\*string* to it
-   (decrementing the reference count of the old string object and incrementing the
-   reference count of the interned string object), otherwise it leaves *\*string*
-   alone and interns it (incrementing its reference count).  (Clarification: even
-   though there is a lot of talk about reference counts, think of this function as
-   reference-count-neutral; you own the object after the call if and only if you
-   owned it before the call.)
-
-
-.. cfunction:: PyObject* PyString_InternFromString(const char *v)
-
-   A combination of :cfunc:`PyString_FromString` and
-   :cfunc:`PyString_InternInPlace`, returning either a new string object that has
-   been interned, or a new ("owned") reference to an earlier interned string object
-   with the same value.
-
-
-.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
-
-   Create an object by decoding *size* bytes of the encoded buffer *s* using the
-   codec registered for *encoding*.  *encoding* and *errors* have the same meaning
-   as the parameters of the same name in the :func:`unicode` built-in function.
-   The codec to be used is looked up using the Python codec registry.  Return
-   *NULL* if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
-
-   Decode a string object by passing it to the codec registered for *encoding* and
-   return the result as Python object. *encoding* and *errors* have the same
-   meaning as the parameters of the same name in the string :meth:`encode` method.
-   The codec to be used is looked up using the Python codec registry. Return *NULL*
-   if an exception was raised by the codec.
-
-
-.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
-
-   Encode a string object using the codec registered for *encoding* and return the
-   result as Python object. *encoding* and *errors* have the same meaning as the
-   parameters of the same name in the string :meth:`encode` method. The codec to be
-   used is looked up using the Python codec registry. Return *NULL* if an exception
-   was raised by the codec.