Added descriptions of parsedate(), parsedate_tz(), getdate_tz()

(all contributed by Andrew Kuchling).

2 files changed, 56 insertions, 0 deletions

diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index e2d182e..9b2094f 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -21,6 +21,25 @@ All header matching is done independent of upper or lower case;
 e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
 the same result.
 
+\begin{funcdesc}{parsedate}{date}
+Attempts to parse a date according to the rules in RFC822.  however,
+some mailers don't follow that format as specified, so
+\code{parsedate()} tries to guess correctly in such cases. 
+\var{date} is a string containing an RFC822 date, such as 
+\code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
+the date, \code{parsedate()} returns a 9-tuple that can be passed
+directly to \code{time.mktime()}; otherwise \code{None} will be
+returned.  
+\end{funcdesc}
+
+\begin{funcdesc}{parsedate_tz}{date}
+Performs the same function as \code{parsedate}, but returns either
+\code{None} or a 10-tuple; the first 9 elements make up a tuple that
+can be passed directly to \code{time.mktime()}, and the tenth is the
+offset of the date's time zone from UTC (which is the official term
+for Greenwich Mean Time).
+\end{funcdesc}
+
 \subsection{Message Objects}
 
 A \code{Message} instance has the following methods:
@@ -93,6 +112,15 @@ collection of email from many sources, it is still possible that this
 function may occasionally yield an incorrect result.
 \end{funcdesc}
 
+\begin{funcdesc}{getdate_tz}{name}
+Retrieve a header using \code{getheader} and parse it into a 10-tuple;
+the first 9 elements will make a tuple compatible with
+\code{time.mktime()}, and the 10th is a number giving the offset of
+the date's time zone from UTC.  Similarly to \code{getdate()}, if
+there is no header matching \var{name}, or it is unparsable, return
+\code{None}. 
+\end{funcdesc}
+
 \code{Message} instances also support a read-only mapping interface.
 In particular: \code{m[name]} is the same as \code{m.getheader(name)};
 and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex
index e2d182e..9b2094f 100644
--- a/Doc/librfc822.tex
+++ b/Doc/librfc822.tex
@@ -21,6 +21,25 @@ All header matching is done independent of upper or lower case;
 e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
 the same result.
 
+\begin{funcdesc}{parsedate}{date}
+Attempts to parse a date according to the rules in RFC822.  however,
+some mailers don't follow that format as specified, so
+\code{parsedate()} tries to guess correctly in such cases. 
+\var{date} is a string containing an RFC822 date, such as 
+\code{"Mon, 20 Nov 1995 19:12:08 -0500"}.  If it succeeds in parsing
+the date, \code{parsedate()} returns a 9-tuple that can be passed
+directly to \code{time.mktime()}; otherwise \code{None} will be
+returned.  
+\end{funcdesc}
+
+\begin{funcdesc}{parsedate_tz}{date}
+Performs the same function as \code{parsedate}, but returns either
+\code{None} or a 10-tuple; the first 9 elements make up a tuple that
+can be passed directly to \code{time.mktime()}, and the tenth is the
+offset of the date's time zone from UTC (which is the official term
+for Greenwich Mean Time).
+\end{funcdesc}
+
 \subsection{Message Objects}
 
 A \code{Message} instance has the following methods:
@@ -93,6 +112,15 @@ collection of email from many sources, it is still possible that this
 function may occasionally yield an incorrect result.
 \end{funcdesc}
 
+\begin{funcdesc}{getdate_tz}{name}
+Retrieve a header using \code{getheader} and parse it into a 10-tuple;
+the first 9 elements will make a tuple compatible with
+\code{time.mktime()}, and the 10th is a number giving the offset of
+the date's time zone from UTC.  Similarly to \code{getdate()}, if
+there is no header matching \var{name}, or it is unparsable, return
+\code{None}. 
+\end{funcdesc}
+
 \code{Message} instances also support a read-only mapping interface.
 In particular: \code{m[name]} is the same as \code{m.getheader(name)};
 and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},