Date and Time Functions

DateList[]give the current local date and time in the form
DateList[TimeZone->z]give the current date and time in time zone z
$TimeZonegive the time zone assumed by your computer system

Finding the date and time.

This gives the current date and time.
In[1]:=
Click for copyable input
Out[1]=

The Mathematica DateList function returns whatever your computer system gives as the current date and time. It assumes that any corrections for daylight saving time and so on have already been done by your computer system. In addition, it assumes that your computer system has been set for the appropriate time zone.

The variable $TimeZone returns the current time zone assumed by your computer system. The time zone is given as the number of hours which must be added to Greenwich Mean Time (GMT) to obtain the correct local time. Thus, for example, U.S. Eastern Standard Time (EST) corresponds to time zone . Note that daylight saving time corrections must be included in the time zone, so U.S. Eastern Daylight Time (EDT) corresponds to time zone .

This gives the current time zone assumed by your computer system.
In[2]:=
Click for copyable input
Out[2]=
This gives the current date and time in time zone , the time zone for Japan.
In[3]:=
Click for copyable input
Out[3]=
AbsoluteTime[]total number of seconds since the beginning of January 1, 1900
SessionTime[]total number of seconds elapsed since the beginning of your current Mathematica session
TimeUsed[]total number of seconds of CPU time used in your current Mathematica session
$TimeUnitthe minimum time interval recorded on your computer system

Time functions.

You should realize that on any computer system, there is a certain "granularity" in the times that can be measured. This granularity is given as the value of the global variable $TimeUnit. Typically it is either about or of a second.

Pause[n]pause for at least n seconds

Pausing during a calculation.

This gives various time functions.
In[4]:=
Click for copyable input
Out[4]=
This pauses for 10 seconds, then reevaluates the time functions. Note that TimeUsed[] is not affected by the pause.
In[5]:=
Click for copyable input
Out[5]=
AbsoluteTime[date]convert from date to absolute time
DateList[time]convert from absolute time to date

Converting between dates and absolute times.

This sets to be the current date.
In[6]:=
Click for copyable input
Out[6]=
This adds one month to the current date.
In[7]:=
Click for copyable input
Out[7]=
This gives the number of seconds in the additional month.
In[8]:=
Click for copyable input
Out[8]=
DateList["string"]convert a date string to a date list
DateList[{"string",{"e1","e2",...}}]give the date list obtained by extracting elements from

Converting from different date formats.

You can use DateList["string"] to convert a date string into a date list, as long as the date format is sufficiently unambiguous.

This attempts to interpret the string as a date.
In[9]:=
Click for copyable input
Out[9]=

For more control of the conversion, you can specify the order and type of date elements appearing in the string. The elements can be strings like , , , , , , , , , or .

This extracts a date using the specified elements.
In[10]:=
Click for copyable input
Out[10]=

If the date element delimiters contain letters or digits, these must also be specified as part of the date elements.

This extracts a date containing a letter as a separator.
In[11]:=
Click for copyable input
Out[11]=
DateString[]give a string representing current local date and time
DateString[datespec,elems]give elements elems of date and time given by datespec

Converting to different date formats.

DateString is used to give a nice string representation of a date and time. The exact output format can be specified from a long list of date elements, such as , , , etc.

This gives the current date and time in the default format.
In[12]:=
Click for copyable input
Out[12]=
This specifies a format for the given date.
In[13]:=
Click for copyable input
Out[13]=
DatePattern[elems]string pattern matching a date with the given elements

Extracting dates from a string.

You can use DatePattern[elems] as a string pattern in string matching functions. The date elements are the same as used in DateList, although the default date element delimiters are restricted to the , , , or characters. Other delimiters can be given explicitly in the list of date elements.

This extracts dates of the given format from a string.
In[14]:=
Click for copyable input
Out[14]=
This extracts dates with explicit delimiters.
In[15]:=
Click for copyable input
Out[15]=
DateListPlot[list]generate a plot from a list of data with date coordinates
DateListPlot[list,datespec]generate a plot from a list of data with dates specified by datespec
DateListLogPlot[list]generate a linear-log plot from a list of data with date coordinates
DateListLogPlot[list,datespec]generate a linear-log plot from a list of data with dates specified by datespec

Plotting data with date coordinates.

DateListPlot can be used to plot data with date or time horizontal coordinates. Dates can be lists, strings, or absolute times as with DateList, DateString, and AbsoluteTime. A date specification datespec can be given to associate dates with data given as . DateListLogPlot allows you to plot the data with a logarithmic vertical scale.

This gathers some financial time series data.
In[16]:=
Click for copyable input
This plots the financial data.
In[17]:=
Click for copyable input
Out[17]=
This plots the same data on a logarithmic scale.
In[18]:=
Click for copyable input
Out[18]=
This plots monthly data which does not contain explicit dates.
In[19]:=
Click for copyable input
Out[19]=
Timing[expr]evaluate expr, and return a list of the CPU time needed, together with the result obtained
AbsoluteTiming[expr]evaluate expr, giving the absolute time taken

Timing Mathematica operations.

Timing allows you to measure the CPU time associated with the evaluation of a single Mathematica expression. Timing corresponds to the increase in TimeUsed. Note that only CPU time associated with the actual evaluation of the expression within the Mathematica kernel is included. The time needed to format the expression for output, and any time associated with external programs, is not included.

AbsoluteTiming allows you to measure absolute total elapsed time. You should realize, however, that the time reported for a particular calculation by both AbsoluteTiming and Timing depends on many factors.

First, the time depends in detail on the computer system you are using. It depends not only on instruction times, but also on memory caching, as well as on the details of the optimization done in compiling the parts of the internal code of Mathematica used in the calculation.

The time also depends on the precise state of your Mathematica session when the calculation was done. Many of the internal optimizations used by Mathematica depend on details of preceding calculations. For example, Mathematica often uses previous results it has obtained, and avoids unnecessarily reevaluating expressions. In addition, some Mathematica functions build internal tables when they are first called in a particular way, so that if they are called in that way again, they run much faster. For all of these kinds of reasons, it is often the case that a particular calculation may not take the same amount of time if you run it at different points in the same Mathematica session.

This gives the CPU time needed for the calculation. The semicolon causes the result of the calculation to be given as Null.
In[20]:=
Click for copyable input
Out[20]=
Now Mathematica has built internal tables for factorial functions, and the calculation takes no measurable CPU time.
In[21]:=
Click for copyable input
Out[21]=
However, some absolute time does elapse.
In[22]:=
Click for copyable input
Out[22]=

Note that the results you get from Timing are only accurate to the timing granularity $TimeUnit of your computer system. Thus, for example, a timing reported as could in fact be as much as $TimeUnit.

TimeConstrained[expr,t]try to evaluate expr, aborting the calculation after t seconds
TimeConstrained[expr,t,failexpr]return failexpr if the time constraint is not met

Time-constrained calculation.

When you use Mathematica interactively, it is quite common to try doing a calculation, but to abort the calculation if it seems to be taking too long. You can emulate this behavior inside a program by using TimeConstrained. TimeConstrained tries to evaluate a particular expression for a specified amount of time. If it does not succeed, then it aborts the evaluation, and returns either $Aborted, or an expression you specify.

You can use TimeConstrained, for example, to have Mathematica try a particular approach to a problem for a certain amount of time, and then to switch to another approach if the first one has not yet succeeded. You should realize however that TimeConstrained may overrun the time you specify if Mathematica cannot be interrupted during a particular part of a calculation. In addition, you should realize that because different computer systems run at different speeds, programs that use TimeConstrained will often give different results on different systems.

New to Mathematica? Find your learning path »
Have a question? Ask support »