cpython-lru_cache-weakref: Doc/c-api/string.rst annotate

annotate Doc/c-api/string.rst @ 58765:2ba7677bfa95 legacy-trunk

testCopysign was defined twice in test_math; combine the definitions

author	Mark Dickinson <dickinsm@gmail.com>
date	Sat, 06 Feb 2010 23:11:25 +0000
parents	51028709abc3
children	62d7f049703b

rev	line source
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	3 .. _stringobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	4
47305 708a561279ca note that PyString and has been aliased to PyBytes Benjamin Peterson <benjamin@python.org> parents: 44796 diff changeset	5 String/Bytes Objects
708a561279ca note that PyString and has been aliased to PyBytes Benjamin Peterson <benjamin@python.org> parents: 44796 diff changeset	6 --------------------
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	7
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	8 These functions raise :exc:`TypeError` when expecting a string parameter and are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	9 called with a non-string parameter.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	10
47305 708a561279ca note that PyString and has been aliased to PyBytes Benjamin Peterson <benjamin@python.org> parents: 44796 diff changeset	11 .. note::
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	12
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	13 These functions have been renamed to PyBytes_* in Python 3.x. Unless
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	14 otherwise noted, the PyBytes functions available in 3.x are aliased to their
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	15 PyString_* equivalents to help porting.
47305 708a561279ca note that PyString and has been aliased to PyBytes Benjamin Peterson <benjamin@python.org> parents: 44796 diff changeset	16
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	17 .. index:: object: string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	18
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	19
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	20 .. ctype:: PyStringObject
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	21
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	22 This subtype of :ctype:`PyObject` represents a Python string object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	23
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	24
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	25 .. cvar:: PyTypeObject PyString_Type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	26
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	27 .. index:: single: StringType (in module types)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	28
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	29 This instance of :ctype:`PyTypeObject` represents the Python string type; it is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	30 the same object as ``str`` and ``types.StringType`` in the Python layer. .
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	31
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	32
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	33 .. cfunction:: int PyString_Check(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	34
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	35 Return true if the object o is a string object or an instance of a subtype of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	36 the string type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	37
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	38 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	39 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	40
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	41
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	42 .. cfunction:: int PyString_CheckExact(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	43
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	44 Return true if the object o is a string object, but not an instance of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	45 subtype of the string type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	46
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	47 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	48
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	49
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	50 .. cfunction:: PyObject* PyString_FromString(const char *v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	51
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	52 Return a new string object with a copy of the string v as value on success,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	53 and NULL on failure. The parameter v must not be NULL; it will not be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	54 checked.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	55
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	56
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	57 .. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	58
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	59 Return a new string object with a copy of the string v as value and length
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	60 len on success, and NULL on failure. If v is NULL, the contents of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	61 string are uninitialized.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	62
53414 85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	63 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	64 This function used an :ctype:`int` type for len. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	65 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	66
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	67
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	68 .. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	69
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	70 Take a C :cfunc:`printf`\ -style format string and a variable number of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	71 arguments, calculate the size of the resulting Python string and return a string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	72 with the values formatted into it. The variable arguments must be C types and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	73 must correspond exactly to the format characters in the format string. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	74 following format characters are allowed:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	75
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	76 .. % This should be exactly the same as the table in PyErr_Format.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	77 .. % One should just refer to the other.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	78 .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	79 .. % because not all compilers support the %z width modifier -- we fake it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	80 .. % when necessary via interpolating PY_FORMAT_SIZE_T.
57277 51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	81 .. % Similar comments apply to the %ll width modifier and
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	82 .. % PY_FORMAT_LONG_LONG.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	83 .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	84
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	85 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	86 \| Format Characters \| Type \| Comment \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	87 +===================+===============+================================+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	88 \| :attr:`%%` \| n/a \| The literal % character. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	89 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	90 \| :attr:`%c` \| int \| A single character, \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	91 \| \| \| represented as an C int. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	92 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	93 \| :attr:`%d` \| int \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	94 \| \| \| ``printf("%d")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	95 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	96 \| :attr:`%u` \| unsigned int \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	97 \| \| \| ``printf("%u")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	98 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	99 \| :attr:`%ld` \| long \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	100 \| \| \| ``printf("%ld")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	101 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	102 \| :attr:`%lu` \| unsigned long \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	103 \| \| \| ``printf("%lu")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	104 +-------------------+---------------+--------------------------------+
57277 51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	105 \| :attr:`%lld` \| long long \| Exactly equivalent to \|
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	106 \| \| \| ``printf("%lld")``. \|
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	107 +-------------------+---------------+--------------------------------+
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	108 \| :attr:`%llu` \| unsigned \| Exactly equivalent to \|
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	109 \| \| long long \| ``printf("%llu")``. \|
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	110 +-------------------+---------------+--------------------------------+
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	111 \| :attr:`%zd` \| Py_ssize_t \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	112 \| \| \| ``printf("%zd")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	113 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	114 \| :attr:`%zu` \| size_t \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	115 \| \| \| ``printf("%zu")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	116 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	117 \| :attr:`%i` \| int \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	118 \| \| \| ``printf("%i")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	119 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	120 \| :attr:`%x` \| int \| Exactly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	121 \| \| \| ``printf("%x")``. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	122 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	123 \| :attr:`%s` \| char\* \| A null-terminated C character \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	124 \| \| \| array. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	125 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	126 \| :attr:`%p` \| void\* \| The hex representation of a C \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	127 \| \| \| pointer. Mostly equivalent to \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	128 \| \| \| ``printf("%p")`` except that \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	129 \| \| \| it is guaranteed to start with \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	130 \| \| \| the literal ``0x`` regardless \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	131 \| \| \| of what the platform's \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	132 \| \| \| ``printf`` yields. \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	133 +-------------------+---------------+--------------------------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	134
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	135 An unrecognized format character causes all the rest of the format string to be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	136 copied as-is to the result string, and any extra arguments discarded.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	137
57277 51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	138 .. note::
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	139
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	140 The `"%lld"` and `"%llu"` format specifiers are only available
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	141 when `HAVE_LONG_LONG` is defined.
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	142
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	143 .. versionchanged:: 2.7
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	144 Support for `"%lld"` and `"%llu"` added.
51028709abc3 Issue #7228: Add '%lld' and '%llu' support to PyFormat_FromString, Mark Dickinson <dickinsm@gmail.com> parents: 53436 diff changeset	145
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	146
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	147 .. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	148
47307 34e41f4e962f fix a minor typo Benjamin Peterson <benjamin@python.org> parents: 47305 diff changeset	149 Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	150 arguments.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	151
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	152
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	153 .. cfunction:: Py_ssize_t PyString_Size(PyObject *string)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	154
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	155 Return the length of the string in string object string.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	156
53414 85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	157 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	158 This function returned an :ctype:`int` type. This might require changes
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	159 in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	160
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	161
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	162 .. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	163
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	164 Macro form of :cfunc:`PyString_Size` but without error checking.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	165
53436 ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	166 .. versionchanged:: 2.5
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	167 This macro returned an :ctype:`int` type. This might require changes in
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	168 your code for properly supporting 64-bit systems.
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	169
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	170
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	171 .. cfunction:: char* PyString_AsString(PyObject *string)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	172
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	173 Return a NUL-terminated representation of the contents of string. The pointer
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	174 refers to the internal buffer of string, not a copy. The data must not be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	175 modified in any way, unless the string was just created using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	176 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	177 string is a Unicode object, this function computes the default encoding of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	178 string and operates on that. If string is not a string object at all,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	179 :cfunc:`PyString_AsString` returns NULL and raises :exc:`TypeError`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	180
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	181
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	182 .. cfunction:: char* PyString_AS_STRING(PyObject *string)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	183
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	184 Macro form of :cfunc:`PyString_AsString` but without error checking. Only
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	185 string objects are supported; no Unicode objects should be passed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	186
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	187
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	188 .. cfunction:: int PyString_AsStringAndSize(PyObject obj, char buffer, Py_ssize_t length)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	189
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	190 Return a NUL-terminated representation of the contents of the object obj
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	191 through the output variables buffer and length.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	192
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	193 The function accepts both string and Unicode objects as input. For Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	194 objects it returns the default encoded version of the object. If length is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	195 NULL, the resulting buffer may not contain NUL characters; if it does, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	196 function returns ``-1`` and a :exc:`TypeError` is raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	197
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	198 The buffer refers to an internal string buffer of obj, not a copy. The data
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	199 must not be modified in any way, unless the string was just created using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	200 ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	201 string is a Unicode object, this function computes the default encoding of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	202 string and operates on that. If string is not a string object at all,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	203 :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	204
53436 ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	205 .. versionchanged:: 2.5
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	206 This function used an :ctype:`int ` type for length*. This might
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	207 require changes in your code for properly supporting 64-bit systems.
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	208
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	209
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	210 .. cfunction:: void PyString_Concat(PyObject *string, PyObject newpart)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	211
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	212 Create a new string object in \string* containing the contents of newpart
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	213 appended to string; the caller will own the new reference. The reference to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	214 the old value of string will be stolen. If the new string cannot be created,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	215 the old reference to string will still be discarded and the value of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	216 \string* will be set to NULL; the appropriate exception will be set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	217
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	218
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	219 .. cfunction:: void PyString_ConcatAndDel(PyObject *string, PyObject newpart)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	220
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	221 Create a new string object in \string* containing the contents of newpart
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	222 appended to string. This version decrements the reference count of newpart.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	223
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	224
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	225 .. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	226
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	227 A way to resize a string object even though it is "immutable". Only use this to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	228 build up a brand new string object; don't use this if the string may already be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	229 known in other parts of the code. It is an error to call this function if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	230 refcount on the input string object is not one. Pass the address of an existing
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	231 string object as an lvalue (it may be written into), and the new size desired.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	232 On success, \string* holds the resized string object and ``0`` is returned;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	233 the address in \string* may differ from its input value. If the reallocation
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	234 fails, the original string object at \string* is deallocated, \string* is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	235 set to NULL, a memory exception is set, and ``-1`` is returned.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	236
53414 85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	237 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	238 This function used an :ctype:`int` type for newsize. This might
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 51654 diff changeset	239 require changes in your code for properly supporting 64-bit systems.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	240
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	241 .. cfunction:: PyObject* PyString_Format(PyObject format, PyObject args)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	242
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	243 Return a new string object from format and args. Analogous to ``format %
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	244 args``. The args argument must be a tuple.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	245
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	246
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	247 .. cfunction:: void PyString_InternInPlace(PyObject **string)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	248
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	249 Intern the argument \string* in place. The argument must be the address of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	250 pointer variable pointing to a Python string object. If there is an existing
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	251 interned string that is the same as \string, it sets \string to it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	252 (decrementing the reference count of the old string object and incrementing the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	253 reference count of the interned string object), otherwise it leaves \string*
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	254 alone and interns it (incrementing its reference count). (Clarification: even
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	255 though there is a lot of talk about reference counts, think of this function as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	256 reference-count-neutral; you own the object after the call if and only if you
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	257 owned it before the call.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	258
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	259 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	260
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	261 This function is not available in 3.x and does not have a PyBytes alias.
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	262
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	263
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	264 .. cfunction:: PyObject* PyString_InternFromString(const char *v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	265
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	266 A combination of :cfunc:`PyString_FromString` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	267 :cfunc:`PyString_InternInPlace`, returning either a new string object that has
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	268 been interned, or a new ("owned") reference to an earlier interned string object
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	269 with the same value.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	270
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	271 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	272
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	273 This function is not available in 3.x and does not have a PyBytes alias.
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	274
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	275
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	276 .. cfunction:: PyObject* PyString_Decode(const char s, Py_ssize_t size, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	277
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	278 Create an object by decoding size bytes of the encoded buffer s using the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	279 codec registered for encoding. encoding and errors have the same meaning
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	280 as the parameters of the same name in the :func:`unicode` built-in function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	281 The codec to be used is looked up using the Python codec registry. Return
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	282 NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	283
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	284 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	285
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	286 This function is not available in 3.x and does not have a PyBytes alias.
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	287
53436 ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	288 .. versionchanged:: 2.5
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	289 This function used an :ctype:`int` type for size. This might require
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	290 changes in your code for properly supporting 64-bit systems.
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	291
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	292
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	293 .. cfunction:: PyObject* PyString_AsDecodedObject(PyObject str, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	294
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	295 Decode a string object by passing it to the codec registered for encoding and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	296 return the result as Python object. encoding and errors have the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	297 meaning as the parameters of the same name in the string :meth:`encode` method.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	298 The codec to be used is looked up using the Python codec registry. Return NULL
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	299 if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	300
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	301 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	302
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	303 This function is not available in 3.x and does not have a PyBytes alias.
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	304
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	305
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	306 .. cfunction:: PyObject* PyString_Encode(const char s, Py_ssize_t size, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	307
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	308 Encode the :ctype:`char` buffer of the given size by passing it to the codec
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	309 registered for encoding and return a Python object. encoding and errors
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	310 have the same meaning as the parameters of the same name in the string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	311 :meth:`encode` method. The codec to be used is looked up using the Python codec
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	312 registry. Return NULL if an exception was raised by the codec.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	313
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	314 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	315
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	316 This function is not available in 3.x and does not have a PyBytes alias.
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	317
53436 ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	318 .. versionchanged:: 2.5
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	319 This function used an :ctype:`int` type for size. This might require
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	320 changes in your code for properly supporting 64-bit systems.
ecaca7177f66 Issue #4129: more int -> Py_ssize_t documentation. Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 53414 diff changeset	321
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	322
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	323 .. cfunction:: PyObject* PyString_AsEncodedObject(PyObject str, const char encoding, const char *errors)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	324
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	325 Encode a string object using the codec registered for encoding and return the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	326 result as Python object. encoding and errors have the same meaning as the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	327 parameters of the same name in the string :meth:`encode` method. The codec to be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	328 used is looked up using the Python codec registry. Return NULL if an exception
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	329 was raised by the codec.
51654 6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	330
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	331 .. note::
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	332
6a118cc4f3b7 note functions that are not aliased to PyBytes_ #5280 Benjamin Peterson <benjamin@python.org> parents: 47307 diff changeset	333 This function is not available in 3.x and does not have a PyBytes alias.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/string.rst @ 58765:2ba7677bfa95 legacy-trunk