Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/float.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 74ff71b2f53d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _floatobjects:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Floating Point Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ----------------------
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: object: floating point
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
11 .. c:type:: PyFloatObject
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
13 This subtype of :c:type:`PyObject` represents a Python floating point object.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
16 .. c:var:: PyTypeObject PyFloat_Type
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 .. index:: single: FloatType (in modules types)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
20 This instance of :c:type:`PyTypeObject` represents the Python floating point
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 type. This is the same object as ``float`` and ``types.FloatType``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
24 .. c:function:: int PyFloat_Check(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
26 Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
27 :c:type:`PyFloatObject`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
33 .. c:function:: int PyFloat_CheckExact(PyObject *p)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
35 Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
36 :c:type:`PyFloatObject`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
41 .. c:function:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
43 Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 *NULL* on failure. The *pend* argument is ignored. It remains only for
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 backward compatibility.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
48 .. c:function:: PyObject* PyFloat_FromDouble(double v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
50 Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
53 .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
55 Return a C :c:type:`double` representation of the contents of *pyfloat*. If
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 *pyfloat* is not a Python floating point object but has a :meth:`__float__`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 method, this method will first be called to convert *pyfloat* into a float.
74025
059e4d752fbe Issue #13522: document error return values of some float and complex C API functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 56607
diff changeset
58 This method returns ``-1.0`` upon failure, so one should call
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
59 :c:func:`PyErr_Occurred` to check for errors.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
62 .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
64 Return a C :c:type:`double` representation of the contents of *pyfloat*, but
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 without error checking.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
68 .. c:function:: PyObject* PyFloat_GetInfo(void)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 Return a structseq instance which contains information about the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 precision, minimum and maximum values of a float. It's a thin wrapper
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 around the header file :file:`float.h`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
77 .. c:function:: double PyFloat_GetMax()
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
79 Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 .. versionadded:: 2.6
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
84 .. c:function:: double PyFloat_GetMin()
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
86 Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 .. versionadded:: 2.6
45143
8fdd6d62ea55 Patch #1953
Christian Heimes <christian@cheimes.de>
parents: 44796
diff changeset
89
8fdd6d62ea55 Patch #1953
Christian Heimes <christian@cheimes.de>
parents: 44796
diff changeset
90
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
91 .. c:function:: int PyFloat_ClearFreeList()
45143
8fdd6d62ea55 Patch #1953
Christian Heimes <christian@cheimes.de>
parents: 44796
diff changeset
92
47897
0738119c1ef8 - Issue #2862: Make int and float freelist management consistent with other
Gregory P. Smith <greg@mad-scientist.com>
parents: 45143
diff changeset
93 Clear the float free list. Return the number of items that could not
0738119c1ef8 - Issue #2862: Make int and float freelist management consistent with other
Gregory P. Smith <greg@mad-scientist.com>
parents: 45143
diff changeset
94 be freed.
45143
8fdd6d62ea55 Patch #1953
Christian Heimes <christian@cheimes.de>
parents: 44796
diff changeset
95
8fdd6d62ea55 Patch #1953
Christian Heimes <christian@cheimes.de>
parents: 44796
diff changeset
96 .. versionadded:: 2.6
56607
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
97
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
98
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
99 .. c:function:: void PyFloat_AsString(char *buf, PyFloatObject *v)
56607
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
100
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
101 Convert the argument *v* to a string, using the same rules as
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
102 :func:`str`. The length of *buf* should be at least 100.
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
103
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
104 This function is unsafe to call because it writes to a buffer whose
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
105 length it does not know.
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
106
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
107 .. deprecated:: 2.7
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
108 Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead.
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
109
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
110
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 74025
diff changeset
111 .. c:function:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)
56607
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
112
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
113 Same as PyFloat_AsString, except uses the same rules as
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
114 :func:`repr`. The length of *buf* should be at least 100.
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
115
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
116 This function is unsafe to call because it writes to a buffer whose
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
117 length it does not know.
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
118
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
119 .. deprecated:: 2.7
79cb07fa36ec Issue #7169: Document PyFloat_AsString and PyFloat_AsReprString, and note that they are unsafe and deprecated.
Eric Smith <eric@trueblade.com>
parents: 56816
diff changeset
120 Use :func:`PyObject_Repr` or :func:`PyOS_double_to_string` instead.