diff options
Diffstat (limited to 'Doc/api/concrete.tex')
| -rw-r--r-- | Doc/api/concrete.tex | 193 |
1 files changed, 157 insertions, 36 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index 63f9667..176d786 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -137,7 +137,7 @@ There is no \cfunction{PyNone_Check()} function for the same reason. int base} Return a new \ctype{PyIntObject} or \ctype{PyLongObject} based on the string value in \var{str}, which is interpreted according to the radix in - \var{base}. If \var{pend} is non-\NULL, \code{*\var{pend}} will point to + \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to the first character in \var{str} which follows the representation of the number. If \var{base} is \code{0}, the radix will be determined based on the leading characters of \var{str}: if \var{str} starts with \code{'0x'} @@ -248,7 +248,7 @@ There is no \cfunction{PyNone_Check()} function for the same reason. int base} Return a new \ctype{PyLongObject} based on the string value in \var{str}, which is interpreted according to the radix in - \var{base}. If \var{pend} is non-\NULL, \code{*\var{pend}} will + \var{base}. If \var{pend} is non-\NULL{}, \code{*\var{pend}} will point to the first character in \var{str} which follows the representation of the number. If \var{base} is \code{0}, the radix will be determined based on the leading characters of \var{str}: if @@ -538,7 +538,7 @@ parameter and are called with a non-string parameter. \begin{cfuncdesc}{PyObject*}{PyString_FromString}{const char *v} Returns a new string object with the value \var{v} on success, and - \NULL{} on failure. The parameter \var{v} must not be \NULL; it + \NULL{} on failure. The parameter \var{v} must not be \NULL{}; it will not be checked. \end{cfuncdesc} @@ -546,7 +546,7 @@ parameter and are called with a non-string parameter. int len} Returns a new string object with the value \var{v} and length \var{len} on success, and \NULL{} on failure. If \var{v} is - \NULL, the contents of the string are uninitialized. + \NULL{}, the contents of the string are uninitialized. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...} @@ -615,7 +615,7 @@ parameter and are called with a non-string parameter. The function accepts both string and Unicode objects as input. For Unicode objects it returns the default encoded version of the - object. If \var{length} is \NULL, the resulting buffer may not + object. If \var{length} is \NULL{}, the resulting buffer may not contain NUL characters; if it does, the function returns \code{-1} and a \exception{TypeError} is raised. @@ -636,7 +636,7 @@ parameter and are called with a non-string parameter. new reference. The reference to the old value of \var{string} will be stolen. If the new string cannot be created, the old reference to \var{string} will still be discarded and the value of - \var{*string} will be set to \NULL; the appropriate exception will + \var{*string} will be set to \NULL{}; the appropriate exception will be set. \end{cfuncdesc} @@ -898,9 +898,9 @@ use these APIs: given size. \var{u} may be \NULL{} which causes the contents to be undefined. It is the user's responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is - not \NULL, the return value might be a shared object. Therefore, + not \NULL{}, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when - \var{u} is \NULL. + \var{u} is \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} @@ -1070,9 +1070,9 @@ These are the UTF-16 codec APIs: int *byteorder} Decodes \var{length} bytes from a UTF-16 encoded buffer string and returns the corresponding Unicode object. \var{errors} (if - non-\NULL) defines the error handling. It defaults to ``strict''. + non-\NULL{}) defines the error handling. It defaults to ``strict''. - If \var{byteorder} is non-\NULL, the decoder starts decoding using + If \var{byteorder} is non-\NULL{}, the decoder starts decoding using the given byte order: \begin{verbatim} @@ -1086,7 +1086,7 @@ These are the UTF-16 codec APIs: string. After completion, \var{*byteorder} is set to the current byte order at the end of input data. - If \var{byteorder} is \NULL, the codec starts in native order mode. + If \var{byteorder} is \NULL{}, the codec starts in native order mode. Returns \NULL{} if an exception was raised by the codec. \end{cfuncdesc} @@ -1351,7 +1351,7 @@ They all return \NULL{} or \code{-1} if an exception occurs. \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, PyObject *sep, int maxsplit} - Split a string giving a list of Unicode strings. If sep is \NULL, + Split a string giving a list of Unicode strings. If sep is \NULL{}, splitting will be done at all whitespace substrings. Otherwise, splits occur at the given separator. At most \var{maxsplit} splits will be done. If negative, no limit is set. Separators are not @@ -1605,7 +1605,7 @@ format. The tuple values are initialized to the subsequent \var{n} C arguments pointing to Python objects. \samp{PyTuple_Pack(2, \var{a}, \var{b})} is equivalent to \samp{Py_BuildValue("(OO)", \var{a}, \var{b})}. - \versionadded{2.4} + \versionadded{2.4} \end{cfuncdesc} \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} @@ -1661,7 +1661,7 @@ format. \code{*\var{p}} will be the same as before calling this function. If the object referenced by \code{*\var{p}} is replaced, the original \code{*\var{p}} is destroyed. On failure, returns - \code{-1} and sets \code{*\var{p}} to \NULL, and raises + \code{-1} and sets \code{*\var{p}} to \NULL{}, and raises \exception{MemoryError} or \exception{SystemError}. \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} @@ -1841,7 +1841,7 @@ format. in \var{p} is matches \var{key}, return \code{1}, otherwise return \code{0}. On error, return \code{-1}. This is equivalent to the Python expression \samp{\var{key} in \var{p}}. - \versionadded{2.4} + \versionadded{2.4} \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} @@ -1923,7 +1923,7 @@ format. dictionary, and false once all pairs have been reported. The parameters \var{pkey} and \var{pvalue} should either point to \ctype{PyObject*} variables that will be filled in with each key and - value, respectively, or may be \NULL. Any references returned through + value, respectively, or may be \NULL{}. Any references returned through them are borrowed. \var{ppos} should not be altered during iteration. Its value represents offsets within the internal dictionary structure, and since the structure is sparse, the offsets are not consecutive. @@ -2040,7 +2040,7 @@ implementation detail and may change in future releases of Python. On success, returns a new file object that is opened on the file given by \var{filename}, with a file mode given by \var{mode}, where \var{mode} has the same semantics as the standard C routine - \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL. + \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, @@ -2143,7 +2143,7 @@ There are very few functions specific to instance objects. Create a new instance of a specific class without calling it's constructor. \var{class} is the class of new object. The \var{dict} parameter will be used as the object's \member{__dict__}; - if \NULL, a new dictionary will be created for the instance. + if \NULL{}, a new dictionary will be created for the instance. \end{cfuncdesc} @@ -2161,7 +2161,7 @@ method objects. \begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o} Return true if \var{o} is a method object (has type - \cdata{PyMethod_Type}). The parameter must not be \NULL. + \cdata{PyMethod_Type}). The parameter must not be \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func. @@ -2196,7 +2196,7 @@ method objects. \begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth} Return the instance associated with the method \var{meth} if it is - bound, otherwise return \NULL. + bound, otherwise return \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth} @@ -2260,7 +2260,7 @@ There are only a few functions special to module objects. Return the name of the file from which \var{module} was loaded using \var{module}'s \member{__file__} attribute. If this is not defined, or if it is not a string, raise \exception{SystemError} and return - \NULL. + \NULL{}. \withsubitem{(module attribute)}{\ttindex{__file__}} \withsubitem{(built-in exception)}{\ttindex{SystemError}} \end{cfuncdesc} @@ -2401,7 +2401,7 @@ They are found in the dictionary of type objects. \begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob} Returns true if \var{ob} is a slice object; \var{ob} must not be - \NULL. + \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop, @@ -2409,7 +2409,7 @@ They are found in the dictionary of type objects. Return a new slice object with the given values. The \var{start}, \var{stop}, and \var{step} parameters are used as the values of the slice object attributes of the same names. Any of the values may be - \NULL, in which case the \code{None} will be used for the + \NULL{}, in which case the \code{None} will be used for the corresponding attribute. Returns \NULL{} if the new object could not be allocated. \end{cfuncdesc} @@ -2431,7 +2431,7 @@ suitably renamed, in the source of your extension. \end{cfuncdesc} \begin{cfuncdesc}{int}{PySlice_GetIndicesEx}{PySliceObject *slice, int length, - int *start, int *stop, int *step, + int *start, int *stop, int *step, int *slicelength} Usable replacement for \cfunction{PySlice_GetIndices}. Retrieve the start, stop, and step indices from the slice object \var{slice} @@ -2475,9 +2475,9 @@ acts as a proxy for the original object as much as it can. parameter, \var{callback}, can be a callable object that receives notification when \var{ob} is garbage collected; it should accept a single parameter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL. If \var{ob} + \var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not a weakly-referencable object, or if \var{callback} is not - callable, \code{None}, or \NULL, this will return \NULL{} and + callable, \code{None}, or \NULL{}, this will return \NULL{} and raise \exception{TypeError}. \versionadded{2.2} \end{cfuncdesc} @@ -2490,9 +2490,9 @@ acts as a proxy for the original object as much as it can. parameter, \var{callback}, can be a callable object that receives notification when \var{ob} is garbage collected; it should accept a single parameter, which will be the weak reference object itself. - \var{callback} may also be \code{None} or \NULL. If \var{ob} is not + \var{callback} may also be \code{None} or \NULL{}. If \var{ob} is not a weakly-referencable object, or if \var{callback} is not callable, - \code{None}, or \NULL, this will return \NULL{} and raise + \code{None}, or \NULL{}, this will return \NULL{} and raise \exception{TypeError}. \versionadded{2.2} \end{cfuncdesc} @@ -2535,7 +2535,7 @@ information on using these objects. void (*destr)(void *)} Create a \ctype{PyCObject} from the \code{void *}\var{cobj}. The \var{destr} function will be called when the object is reclaimed, - unless it is \NULL. + unless it is \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, @@ -2557,7 +2557,7 @@ information on using these objects. \end{cfuncdesc} \begin{cfuncdesc}{int}{PyCObject_SetVoidPtr}{PyObject* self, void* cobj} - Set the void pointer inside \var{self} to \var{cobj}. + Set the void pointer inside \var{self} to \var{cobj}. The \ctype{PyCObject} must not have an associated destructor. Return true on success, false on failure. \end{cfuncdesc} @@ -2585,12 +2585,12 @@ when accessed. Cell objects are not likely to be useful elsewhere. \begin{cfuncdesc}{int}{PyCell_Check}{ob} Return true if \var{ob} is a cell object; \var{ob} must not be - \NULL. + \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyCell_New}{PyObject *ob} Create and return a new cell object containing the value \var{ob}. - The parameter may be \NULL. + The parameter may be \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyCell_Get}{PyObject *cell} @@ -2605,7 +2605,7 @@ when accessed. Cell objects are not likely to be useful elsewhere. \begin{cfuncdesc}{int}{PyCell_Set}{PyObject *cell, PyObject *value} Set the contents of the cell object \var{cell} to \var{value}. This releases the reference to any current content of the cell. - \var{value} may be \NULL. \var{cell} must be non-\NULL; if it is + \var{value} may be \NULL{}. \var{cell} must be non-\NULL{}; if it is not a cell object, \code{-1} will be returned. On success, \code{0} will be returned. \end{cfuncdesc} @@ -2633,16 +2633,137 @@ rather than explicitly calling \cfunction{PyGen_New}. \begin{cfuncdesc}{int}{PyGen_Check}{ob} Return true if \var{ob} is a generator object; \var{ob} must not be - \NULL. + \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{int}{PyGen_CheckExact}{ob} Return true if \var{ob}'s type is \var{PyGen_Type} is a generator object; \var{ob} must not be - \NULL. + \NULL{}. \end{cfuncdesc} \begin{cfuncdesc}{PyObject*}{PyGen_New}{PyFrameObject *frame} Create and return a new generator object based on the \var{frame} object. - The parameter must not be \NULL. + The parameter must not be \NULL{}. +\end{cfuncdesc} + + +\subsection{DateTime Objects \label{datetime-objects}} + +Various date and time objects are supplied by the \module{datetime} +module. Before using any of these functions, the header file +\file{datetime.h} must be included in your source (note that this is +not include by \file{Python.h}), and macro \cfunction{PyDateTime_IMPORT()} +must be invoked. The macro arranges to put a pointer to a C structure +in a static variable \code{PyDateTimeAPI}, which is used by the following +macros: + +\begin{cfuncdesc}{int}{PyDate_Check}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DateType} or + a subtype of \cdata{PyDateTime_DateType}. \var{ob} must not be + \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDate_CheckExact}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DateType}. + \var{ob} must not be \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDateTime_Check}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType} or + a subtype of \cdata{PyDateTime_DateTimeType}. \var{ob} must not be + \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDateTime_CheckExact}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DateTimeType}. + \var{ob} must not be \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTime_Check}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_TimeType} or + a subtype of \cdata{PyDateTime_TimeType}. \var{ob} must not be + \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTime_CheckExact}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_TimeType}. + \var{ob} must not be \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDelta_Check}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType} or + a subtype of \cdata{PyDateTime_DeltaType}. \var{ob} must not be + \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyDelta_CheckExact}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_DeltaType}. + \var{ob} must not be \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTZInfo_Check}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType} or + a subtype of \cdata{PyDateTime_TZInfoType}. \var{ob} must not be + \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{int}{PyTZInfo_CheckExact}{ob} + Return true if \var{ob} is of type \cdata{PyDateTime_TZInfoType}. + \var{ob} must not be \NULL{}. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDate_FromDate}{int year, int month, int day} + Return a \code{datetime.date} object with the specified year, month + and day. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDate_FromDateAndTime}{int year, int month, + int day, int hour, int minute, int second, int usecond} + Return a \code{datetime.datetime} object with the specified year, month, + day, hour, minute, second and microsecond. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyTime_FromTime}{int hour, int minute, + int second, int usecond} + Return a \code{datetime.time} object with the specified hour, minute, + second and microsecond. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDelta_FromDSU}{int days, int seconds, + int useconds} + Return a \code{datetime.timedelta} object representing the given number + of days, seconds and microseconds. Normalization is performed so that + the resulting number of microseconds and seconds lie in the ranges + documented for \code{datetime.timedelta} objects. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDateTime_FromTimestamp}{PyObject *args} + Create and return a new \code{datetime.datetime} object given an argument + tuple suitable for passing to \code{datetime.datetime.fromtimestamp()}. + This macro is included for the convenience of modules implementing the + DB API. + \versionadded{2.4} +\end{cfuncdesc} + +\begin{cfuncdesc}{PyObject*}{PyDate_FromTimestamp}{PyObject *args} + Create and return a new \code{datetime.date} object given an argument + tuple suitable for passing to \code{datetime.date.fromtimestamp()}. + This macro is included for the convenience of modules implementing the + DB API. + \versionadded{2.4} \end{cfuncdesc} |