/Doc/c-api/list.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 190 lines · 112 code · 78 blank · 0 comment · 0 complexity · ab1cb4beb7e62d5b4bfae4b6a85910f7 MD5 · raw file

  1. .. highlightlang:: c
  2. .. _listobjects:
  3. List Objects
  4. ------------
  5. .. index:: object: list
  6. .. ctype:: PyListObject
  7. This subtype of :ctype:`PyObject` represents a Python list object.
  8. .. cvar:: PyTypeObject PyList_Type
  9. .. index:: single: ListType (in module types)
  10. This instance of :ctype:`PyTypeObject` represents the Python list type.
  11. This is the same object as ``list`` and ``types.ListType`` in the Python
  12. layer.
  13. .. cfunction:: int PyList_Check(PyObject *p)
  14. Return true if *p* is a list object or an instance of a subtype of the list
  15. type.
  16. .. versionchanged:: 2.2
  17. Allowed subtypes to be accepted.
  18. .. cfunction:: int PyList_CheckExact(PyObject *p)
  19. Return true if *p* is a list object, but not an instance of a subtype of
  20. the list type.
  21. .. versionadded:: 2.2
  22. .. cfunction:: PyObject* PyList_New(Py_ssize_t len)
  23. Return a new list of length *len* on success, or *NULL* on failure.
  24. .. note::
  25. If *length* is greater than zero, the returned list object's items are
  26. set to ``NULL``. Thus you cannot use abstract API functions such as
  27. :cfunc:`PySequence_SetItem` or expose the object to Python code before
  28. setting all items to a real object with :cfunc:`PyList_SetItem`.
  29. .. versionchanged:: 2.5
  30. This function used an :ctype:`int` for *size*. This might require
  31. changes in your code for properly supporting 64-bit systems.
  32. .. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
  33. .. index:: builtin: len
  34. Return the length of the list object in *list*; this is equivalent to
  35. ``len(list)`` on a list object.
  36. .. versionchanged:: 2.5
  37. This function returned an :ctype:`int`. This might require changes in
  38. your code for properly supporting 64-bit systems.
  39. .. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
  40. Macro form of :cfunc:`PyList_Size` without error checking.
  41. .. versionchanged:: 2.5
  42. This macro returned an :ctype:`int`. This might require changes in your
  43. code for properly supporting 64-bit systems.
  44. .. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
  45. Return the object at position *pos* in the list pointed to by *p*. The
  46. position must be positive, indexing from the end of the list is not
  47. supported. If *pos* is out of bounds, return *NULL* and set an
  48. :exc:`IndexError` exception.
  49. .. versionchanged:: 2.5
  50. This function used an :ctype:`int` for *index*. This might require
  51. changes in your code for properly supporting 64-bit systems.
  52. .. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
  53. Macro form of :cfunc:`PyList_GetItem` without error checking.
  54. .. versionchanged:: 2.5
  55. This macro used an :ctype:`int` for *i*. This might require changes in
  56. your code for properly supporting 64-bit systems.
  57. .. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
  58. Set the item at index *index* in list to *item*. Return ``0`` on success
  59. or ``-1`` on failure.
  60. .. note::
  61. This function "steals" a reference to *item* and discards a reference to
  62. an item already in the list at the affected position.
  63. .. versionchanged:: 2.5
  64. This function used an :ctype:`int` for *index*. This might require
  65. changes in your code for properly supporting 64-bit systems.
  66. .. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
  67. Macro form of :cfunc:`PyList_SetItem` without error checking. This is
  68. normally only used to fill in new lists where there is no previous content.
  69. .. note::
  70. This macro "steals" a reference to *item*, and, unlike
  71. :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
  72. it being replaced; any reference in *list* at position *i* will be
  73. leaked.
  74. .. versionchanged:: 2.5
  75. This macro used an :ctype:`int` for *i*. This might require
  76. changes in your code for properly supporting 64-bit systems.
  77. .. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
  78. Insert the item *item* into list *list* in front of index *index*. Return
  79. ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
  80. Analogous to ``list.insert(index, item)``.
  81. .. versionchanged:: 2.5
  82. This function used an :ctype:`int` for *index*. This might require
  83. changes in your code for properly supporting 64-bit systems.
  84. .. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
  85. Append the object *item* at the end of list *list*. Return ``0`` if
  86. successful; return ``-1`` and set an exception if unsuccessful. Analogous
  87. to ``list.append(item)``.
  88. .. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
  89. Return a list of the objects in *list* containing the objects *between*
  90. *low* and *high*. Return *NULL* and set an exception if unsuccessful.
  91. Analogous to ``list[low:high]``.
  92. .. versionchanged:: 2.5
  93. This function used an :ctype:`int` for *low* and *high*. This might
  94. require changes in your code for properly supporting 64-bit systems.
  95. .. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
  96. Set the slice of *list* between *low* and *high* to the contents of
  97. *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
  98. be *NULL*, indicating the assignment of an empty list (slice deletion).
  99. Return ``0`` on success, ``-1`` on failure.
  100. .. versionchanged:: 2.5
  101. This function used an :ctype:`int` for *low* and *high*. This might
  102. require changes in your code for properly supporting 64-bit systems.
  103. .. cfunction:: int PyList_Sort(PyObject *list)
  104. Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
  105. failure. This is equivalent to ``list.sort()``.
  106. .. cfunction:: int PyList_Reverse(PyObject *list)
  107. Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
  108. failure. This is the equivalent of ``list.reverse()``.
  109. .. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
  110. .. index:: builtin: tuple
  111. Return a new tuple object containing the contents of *list*; equivalent to
  112. ``tuple(list)``.