List（串列）物件
****************

PyListObject

   This subtype of "PyObject" represents a Python list object.

PyTypeObject PyList_Type

   This instance of "PyTypeObject" represents the Python list type.
   This is the same object as "list" in the Python layer.

int PyList_Check(PyObject *p)

   Return true if *p* is a list object or an instance of a subtype of
   the list type.

int PyList_CheckExact(PyObject *p)

   Return true if *p* is a list object, but not an instance of a
   subtype of the list type.

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

   成功时返回一个长度为 *len* 的新列表，失败时返回 "NULL"。

   備註: If *len* is greater than zero, the returned list object's
     items are set to "NULL".  Thus you cannot use abstract API
     functions such as "PySequence_SetItem()"  or expose the object to
     Python code before setting all items to a real object with
     "PyList_SetItem()".

Py_ssize_t PyList_Size(PyObject *list)

   Return the length of the list object in *list*; this is equivalent
   to "len(list)" on a list object.

Py_ssize_t PyList_GET_SIZE(PyObject *list)

   Macro form of "PyList_Size()" without error checking.

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

   返回 *list* 所指向列表中 *index* 位置上的对象。 位置值必须为非负数
   ；不支持从列表末尾进行索引。 如果 *index* 超出边界 (<0 or
   >=len(list))，则返回 "NULL" 并设置 "IndexError" 异常。

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

   Macro form of "PyList_GetItem()" without error checking.

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

   将列表中索引为 *index* 的项设为 *item*。 成功时返回 "0"。 如果
   *index* 超出范围则返回 "-1" 并设定 "IndexError" 异常。

   備註: This function "steals" a reference to *item* and discards a
     reference to an item already in the list at the affected
     position.

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

   Macro form of "PyList_SetItem()" without error checking. This is
   normally only used to fill in new lists where there is no previous
   content.

   備註: This macro "steals" a reference to *item*, and, unlike
     "PyList_SetItem()", does *not* discard a reference to any item
     that is being replaced; any reference in *list* at position *i*
     will be leaked.

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

   Insert the item *item* into list *list* in front of index *index*.
   Return "0" if successful; return "-1" and set an exception if
   unsuccessful. Analogous to "list.insert(index, item)".

int PyList_Append(PyObject *list, PyObject *item)

   Append the object *item* at the end of list *list*. Return "0" if
   successful; return "-1" and set an exception if unsuccessful.
   Analogous to "list.append(item)".

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

   返回一个对象列表，包含 *list* 当中位于 *low* 和 *high* *之间* 的对
   象。 如果不成功则返回 "NULL" 并设置异常。 相当于 "list[low:high]"。
   不支持从列表末尾进行索引。

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

   将 *list* 当中 *low* 与 *high* 之间的切片设为 *itemlist* 的内容。
   相当于 "list[low:high] = itemlist"。 *itemlist* 可以为 "NULL"，表示
   赋值为一个空列表（删除切片）。 成功时返回 "0"，失败时返回 "-1"。 这
   里不支持从列表末尾进行索引。

int PyList_Sort(PyObject *list)

   Sort the items of *list* in place.  Return "0" on success, "-1" on
   failure.  This is equivalent to "list.sort()".

int PyList_Reverse(PyObject *list)

   Reverse the items of *list* in place.  Return "0" on success, "-1"
   on failure.  This is the equivalent of "list.reverse()".

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

   Return a new tuple object containing the contents of *list*;
   equivalent to "tuple(list)".

int PyList_ClearFreeList()

   Clear the free list. Return the total number of freed items.

   3.3 版新加入.
