Doc/c-api/float.rst

   1 .. highlightlang:: c
   2
   3 .. _floatobjects:
   4
   5 Floating Point Objects
   6 ----------------------
   7
   8 .. index:: object: floating point
   9
  10
  11 .. ctype:: PyFloatObject
  12
  13    This subtype of :ctype:`PyObject` represents a Python floating point object.
  14
  15
  16 .. cvar:: PyTypeObject PyFloat_Type
  17
  18    .. index:: single: FloatType (in modules types)
  19
  20    This instance of :ctype:`PyTypeObject` represents the Python floating point
  21    type.  This is the same object as ``float`` and ``types.FloatType``.
  22
  23
  24 .. cfunction:: int PyFloat_Check(PyObject *p)
  25
  26    Return true if its argument is a :ctype:`PyFloatObject` or a subtype of
  27    :ctype:`PyFloatObject`.
  28
  29    .. versionchanged:: 2.2
  30       Allowed subtypes to be accepted.
  31
  32
  33 .. cfunction:: int PyFloat_CheckExact(PyObject *p)
  34
  35    Return true if its argument is a :ctype:`PyFloatObject`, but not a subtype of
  36    :ctype:`PyFloatObject`.
  37
  38    .. versionadded:: 2.2
  39
  40
  41 .. cfunction:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
  42
  43    Create a :ctype:`PyFloatObject` object based on the string value in *str*, or
  44    *NULL* on failure.  The *pend* argument is ignored.  It remains only for
  45    backward compatibility.
  46
  47
  48 .. cfunction:: PyObject* PyFloat_FromDouble(double v)
  49
  50    Create a :ctype:`PyFloatObject` object from *v*, or *NULL* on failure.
  51
  52
  53 .. cfunction:: double PyFloat_AsDouble(PyObject *pyfloat)
  54
  55    Return a C :ctype:`double` representation of the contents of *pyfloat*.  If
  56    *pyfloat* is not a Python floating point object but has a :meth:`__float__`
  57    method, this method will first be called to convert *pyfloat* into a float.
  58
  59
  60 .. cfunction:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
  61
  62    Return a C :ctype:`double` representation of the contents of *pyfloat*, but
  63    without error checking.
  64
  65
  66 .. cfunction:: PyObject* PyFloat_GetInfo(void)
  67
  68    Return a structseq instance which contains information about the
  69    precision, minimum and maximum values of a float. It's a thin wrapper
  70    around the header file :file:`float.h`.
  71
  72    .. versionadded:: 2.6
  73
  74
  75 .. cfunction:: double PyFloat_GetMax()
  76
  77    Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.
  78
  79    .. versionadded:: 2.6
  80
  81
  82 .. cfunction:: double PyFloat_GetMin()
  83
  84    Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.
  85
  86    .. versionadded:: 2.6
  87
  88
  89 .. cfunction:: int PyFloat_ClearFreeList()
  90
  91    Clear the float free list. Return the number of items that could not
  92    be freed.
  93
  94    .. versionadded:: 2.6
  95
  96
  97 .. cfunction:: void PyFloat_AsString(char *buf, PyFloatObject *v)
  98
  99    Convert the argument *v* to a string, using the same rules as
 100    :func:`str`. The length of *buf* should be at least 100.
 101
 102    This function is unsafe to call because it writes to a buffer whose
 103    length it does not know.
 104
 105    .. deprecated:: 2.7
 106       Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead.
 107
 108
 109 .. cfunction:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)
 110
 111    Same as PyFloat_AsString, except uses the same rules as
 112    :func:`repr`.  The length of *buf* should be at least 100.
 113
 114    This function is unsafe to call because it writes to a buffer whose
 115    length it does not know.
 116
 117    .. deprecated:: 2.7
 118       Use :func:`PyObject_Repr` or :func:`PyOS_double_to_string` instead.