1 .. highlightlang:: c

     2 

     3 .. _cell-objects:

     4 

     5 Cell Objects

     6 ------------

     7 

     8 "Cell" objects are used to implement variables referenced by multiple scopes.

     9 For each such variable, a cell object is created to store the value; the local

    10 variables of each stack frame that references the value contains a reference to

    11 the cells from outer scopes which also use that variable.  When the value is

    12 accessed, the value contained in the cell is used instead of the cell object

    13 itself.  This de-referencing of the cell object requires support from the

    14 generated byte-code; these are not automatically de-referenced when accessed.

    15 Cell objects are not likely to be useful elsewhere.

    16 

    17 

    18 .. ctype:: PyCellObject

    19 

    20    The C structure used for cell objects.

    21 

    22 

    23 .. cvar:: PyTypeObject PyCell_Type

    24 

    25    The type object corresponding to cell objects.

    26 

    27 

    28 .. cfunction:: int PyCell_Check(ob)

    29 

    30    Return true if *ob* is a cell object; *ob* must not be *NULL*.

    31 

    32 

    33 .. cfunction:: PyObject* PyCell_New(PyObject *ob)

    34 

    35    Create and return a new cell object containing the value *ob*. The parameter may

    36    be *NULL*.

    37 

    38 

    39 .. cfunction:: PyObject* PyCell_Get(PyObject *cell)

    40 

    41    Return the contents of the cell *cell*.

    42 

    43 

    44 .. cfunction:: PyObject* PyCell_GET(PyObject *cell)

    45 

    46    Return the contents of the cell *cell*, but without checking that *cell* is

    47    non-*NULL* and a cell object.

    48 

    49 

    50 .. cfunction:: int PyCell_Set(PyObject *cell, PyObject *value)

    51 

    52    Set the contents of the cell object *cell* to *value*.  This releases the

    53    reference to any current content of the cell. *value* may be *NULL*.  *cell*

    54    must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On

    55    success, ``0`` will be returned.

    56 

    57 

    58 .. cfunction:: void PyCell_SET(PyObject *cell, PyObject *value)

    59 

    60    Sets the value of the cell object *cell* to *value*.  No reference counts are

    61    adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must

    62    be a cell object.