The Name Class
==============

.. class:: Name

   Information relating to a named reference, formula, macro, etc.

   - *New in version 0.6.0*
   - *Name information is **not** extracted from files older than
     Excel 5.0 (Book.biff_version < 50)*

.. method:: Name.area2d(clipped=True)

   This is a convenience method for the use case where the name
   refers to one rectangular area in one worksheet.

   :param bool clipped: If *True* (the default), the returned rectangle is clipped
      to fit in (0, sheet.nrows, 0, sheet.ncols) -- it is guaranteed that
      0 <= rowxlo <= rowxhi <= sheet.nrows and that the number of usable rows
      in the area (which may be zero) is rowxhi - rowxlo; likewise for columns.
   :returns: a tuple (sheet_object, rowxlo, rowxhi, colxlo, colxhi).

Raises **XLRDError**:
   The name is not a constant absolute reference
   to a single area in a single sheet.

.. attribute:: Name.binary

   0 = Formula definition; 1 = Binary data

   *No examples have been sighted.*

.. attribute:: Name.builtin

   0 = User-defined name; 1 = Built-in name

   (common examples: Print_Area, Print_Titles; see OOo docs for full list)

.. method:: Name.cell()

   This is a convenience method for the frequent use case where the name
   refers to a single cell.

.. :returns: An instance of the Cell class.

Raises **XLRDError**:
   The name is not a constant absolute reference
   to a single cell.

.. attribute:: Name.complex

   0 = Simple formula; 1 = Complex formula (array formula or user defined)

   *No examples have been sighted.*

.. attribute:: Name.func

   0 = Command macro; 1 = Function macro. Relevant only if macro == 1

.. attribute:: Name.funcgroup

   Function group. Relevant only if macro == 1; see OOo docs for values.

.. attribute:: Name.hidden

   0 = Visible; 1 = Hidden

.. attribute:: Name.macro

   0 = Standard name; 1 = Macro name

.. attribute:: Name.name

   A string. If builtin, decoded as per OOo docs.

.. attribute:: Name.name_index

   The index of this object in book.name_obj_list

.. attribute:: Name.raw_formula

   An 8-bit string.

.. attribute:: Name.result

   The result of evaluating the formula, if any.
   If no formula, or evaluation of the formula encountered problems,
   the result is None. Otherwise the result is a single instance of the
   Operand class.

.. attribute:: Name.scope

============ ============================================================
Value        Description
============ ============================================================
-1           The name is global (visible in all calculation sheets).
-2           The name belongs to a macro sheet or VBA sheet.
-3           The name is invalid.
0 .. nsheets The name is local to the sheet whose index is scope.
============ ============================================================

.. attribute:: Name.vbasic

   0 = Sheet macro; 1 = VisualBasic macro. Relevant only if macro == 1