@@ -1502,3 +1502,87 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
1502
1502
:c:func: `PyUnicode_InternInPlace `, returning either a new Unicode string
1503
1503
object that has been interned, or a new ("owned") reference to an earlier
1504
1504
interned string object with the same value.
1505
+
1506
+ PyUnicodeWriter
1507
+ ^^^^^^^^^^^^^^^
1508
+
1509
+ The :c:type:`PyUnicodeWriter` API can be used to create a Python :class:`str`
1510
+ object.
1511
+
1512
+ .. versionadded:: 3.14
1513
+
1514
+ .. c:type:: PyUnicodeWriter
1515
+
1516
+ A Unicode writer instance.
1517
+
1518
+ The instance must be destroyed by :c:func:`PyUnicodeWriter_Finish` on
1519
+ success, or :c:func:`PyUnicodeWriter_Discard` on error.
1520
+
1521
+ .. c:function:: PyUnicodeWriter* PyUnicodeWriter_Create(Py_ssize_t length)
1522
+
1523
+ Create a Unicode writer instance.
1524
+
1525
+ Set an exception and return ``NULL`` on error.
1526
+
1527
+ .. c:function:: PyObject* PyUnicodeWriter_Finish(PyUnicodeWriter *writer)
1528
+
1529
+ Return the final Python :class: `str ` object and destroy the writer instance.
1530
+
1531
+ Set an exception and return ``NULL `` on error.
1532
+
1533
+ .. c :function :: void PyUnicodeWriter_Discard (PyUnicodeWriter *writer)
1534
+
1535
+ Discard the internal Unicode buffer and destroy the writer instance.
1536
+
1537
+ .. c :function :: int PyUnicodeWriter_WriteChar (PyUnicodeWriter *writer, Py_UCS4 ch)
1538
+
1539
+ Write the single Unicode character *ch * into *writer *.
1540
+
1541
+ On success, return ``0 ``.
1542
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
1543
+
1544
+ .. c :function :: int PyUnicodeWriter_WriteUTF8 (PyUnicodeWriter *writer, const char *str, Py_ssize_t size)
1545
+
1546
+ Decode the string *str * from UTF-8 in strict mode and write the output into *writer *.
1547
+
1548
+ *size * is the string length in bytes. If *size * is equal to ``-1 ``, call
1549
+ ``strlen(str) `` to get the string length.
1550
+
1551
+ On success, return ``0 ``.
1552
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
1553
+
1554
+ To use a different error handler than ``strict ``,
1555
+ :c:func: `PyUnicode_DecodeUTF8 ` can be used with
1556
+ :c:func: `PyUnicodeWriter_WriteStr `.
1557
+
1558
+ .. c :function :: int PyUnicodeWriter_WriteStr (PyUnicodeWriter *writer, PyObject *obj)
1559
+
1560
+ Call :c:func: `PyObject_Str ` on *obj * and write the output into *writer *.
1561
+
1562
+ On success, return ``0 ``.
1563
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
1564
+
1565
+ .. c :function :: int PyUnicodeWriter_WriteRepr (PyUnicodeWriter *writer, PyObject *obj)
1566
+
1567
+ Call :c:func: `PyObject_Repr ` on *obj * and write the output into *writer *.
1568
+
1569
+ On success, return ``0 ``.
1570
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
1571
+
1572
+ .. c :function :: int PyUnicodeWriter_WriteSubstring (PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)
1573
+
1574
+ Write the substring ``str[start:end] `` into *writer *.
1575
+
1576
+ *str * must be Python :class: `str ` object. *start * must be greater than or
1577
+ equal to 0, and less than or equal to *end *. *end * must be less than or
1578
+ equal to *str * length.
1579
+
1580
+ On success, return ``0 ``.
1581
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
1582
+
1583
+ .. c :function :: int PyUnicodeWriter_Format (PyUnicodeWriter *writer, const char *format, ...)
1584
+
1585
+ Similar to :c:func: `PyUnicode_FromFormat `, but write the output directly into *writer *.
1586
+
1587
+ On success, return ``0 ``.
1588
+ On error, set an exception, leave the writer unchanged, and return ``-1 ``.
0 commit comments