# List（串列）物件

`PyListObject`

  这个C类型 `PyObject` 的子类型代表一个Python列表对象。

PyTypeObject `PyList_Type`

  这是个属于 `PyTypeObject` 的代表Python列表类型的实例。在Python层面和类型 `list` 是同一个对象。

int `PyList_Check`(PyObject *p)

  如果 p 是一个列表对象或者是一个列表类型的子类型实例时，返回真。

int `PyList_CheckExact`(PyObject *p)

  当 p 是一个列表对象，但是不是列表类型的子类型实例时，返回真。

PyObject* `PyList_New`(Py_ssize_t len)
  Return value: New reference.

  Return a new list of length len on success, or NULL on failure.

  備註

  当 len 大于零时，被返回的列表对象项目被设成 `NULL`。因此你不能用类似C函数 `PySequence_SetItem()` 的抽象API或者用C函数 `PyList_SetItem()` 将所有项目设置成真实对象前对Python代码公开这个对象。

Py_ssize_t `PyList_Size`(PyObject *list)

  返回 list 中列表对象的长度；这等于在列表对象调用 `len(list)` 。

Py_ssize_t `PyList_GET_SIZE`(PyObject *list)

  宏版本的C函数 `PyList_Size()` ，没有错误检测。

PyObject* `PyList_GetItem`(PyObject *list, Py_ssize_t index)
  Return value: Borrowed reference.

  Return the object at position index in the list pointed to by list. The position must be positive, indexing from the end of the list is not supported. If index is out of bounds, return NULL and set an `IndexError` exception.

PyObject* `PyList_GET_ITEM`(PyObject *list, Py_ssize_t i)
  Return value: Borrowed reference.

  宏版本的C函数 `PyList_GetItem()` ，没有错误检测。

int `PyList_SetItem`(PyObject *list, Py_ssize_t index, PyObject *item)

  Set the item at index index in list to item. Return `0` on success or `-1` on failure.

  備註

  此函数会“偷走”一个对 item 的引用并丢弃一个对列表中受影响位置上的已有条目的引用。

void `PyList_SET_ITEM`(PyObject *list, Py_ssize_t i, PyObject *o)

  不带错误检测的宏版本 `PyList_SetItem()`。 这通常只被用于新列表中之前没有内容的位置进行填充。

  備註

  该宏会“偷走”一个对 item 的引用，但与 `PyList_SetItem()` 不同的是它 不会 丢弃对任何被替换条目的引用；在 list 的 i 位置上的任何引用都将被泄露。

int `PyList_Insert`(PyObject *list, Py_ssize_t index, PyObject *item)

  将条目 item 插入到列表 list 索引号 index 之前的位置。 如果成功将返回 `0`；如果不成功则返回 `-1` 并设置一个异常。 相当于 `list.insert(index, item)`。

int `PyList_Append`(PyObject *list, PyObject *item)

  将对象 item 添加到列表 list 的末尾。 如果成功将返回 `0`；如果不成功则返回 `-1` 并设置一个异常。 相当于 `list.append(item)`。

PyObject* `PyList_GetSlice`(PyObject *list, Py_ssize_t low, Py_ssize_t high)
  Return value: New reference.

  Return a list of the objects in list containing the objects between low and high. Return NULL and set an exception if unsuccessful. Analogous to `list[low:high]`. Negative indices, as when slicing from Python, are not supported.

int `PyList_SetSlice`(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)

  Set the slice of list between low and high to the contents of itemlist. Analogous to `list[low:high] = itemlist`. The itemlist may be NULL, indicating the assignment of an empty list (slice deletion). Return `0` on success, `-1` on failure. Negative indices, as when slicing from Python, are not supported.

int `PyList_Sort`(PyObject *list)

  对 list 中的条目进行原地排序。 成功时返回 `0`，失败时返回 `-1`。 这等价于 `list.sort()`。

int `PyList_Reverse`(PyObject *list)

  对 list 中的条目进行原地反转。 成功时返回 `0`，失败时返回 `-1`。 这等价于 `list.reverse()`。

PyObject* `PyList_AsTuple`(PyObject *list)
  Return value: New reference.

  返回一个新的元组对象，其中包含 list 的内容；等价于 `tuple(list)`。

int `PyList_ClearFreeList`()

  清空释放列表。 返回所释放的条目数。

  3.3 版新加入.