# Introducing Julia/Working with dates and times
## Working with dates and times

Functions for working with dates and times are provided in the standard package Dates. To use any of the time and date functions, you must do one of the following:
* using Dates
* import Dates
If you use import Dates functions, you’ll need to prefix every function with an explicit Dates., e.g. Dates.dayofweek(dt), as shown in this chapter. However, if you add the line using Dates to your code, this brings all exported Dates functions into Main, and they can be used without the Dates. prefix.

#### Types

This diagram shows the relationship between the various types used to store Times, Dates, and DateTimes.

### Date, Time, and DateTimes

There are three main datatypes available:
* A Dates.Time object represents a precise moment of time in a day. It doesn't say anything about the day of the week, or the year, though. It's accurate to a nanosecond.
* A Dates.Date object represents just a date: no time zones, no daylight saving issues, etc... It's accurate to, well, a day.
* A Dates.DateTime object is a combination of a date and a time of day, and so it specifies an exact moment in time. It's accurate to a millisecond or so.
Use one of these constructors to make the type of object you want:
The Dates.today function returns a Date object for the current date:
The Dates.now function returns a DateTime object for the current instant in time:
(We used Dates.now earlier to define rightnow, then converted it to a Dates.Time using Dates.Time.)
Sometimes you want UTC (the reference time for the world, without local adjustments for daylight savings):
To create an object from a formatted string, use the DateTime function in Dates, and supply a suitable format string that matches the formatting:
See Date Formatting below for more examples.

### Date and time queries

Once you have a date/time or date object, you can extract information from it with the following functions. For both date and datetime objects, you can obtain the year, month, day, and so on:
and, for date/time objects:
There's also a bunch of other useful ones:
Two of those functions are very similarly named: the Dates.daysofweekinmonth (days of week in month) function tells you how many days there are in the month with the same day name as the specified day — there are five Tuesdays in the current month (at the time of writing). The last function, dayofweekofmonth(birthday) (day of week of month), tells us that the 15th of March, 1997, was the third Saturday of the month.
You can also find days relative to a date, such as the first day of the week containing that day, using the adjusting functions, described below.

### Date arithmetic

You can do arithmetic on dates and date/time objects. Subtracting two dates or datetimes to find the difference is the most obvious one:
which you can convert to Dates.Days or Dates.Milliseconds or some other unit:
To add and subtract periods of time to date and date/time objects, use the Dates. constructor functions to specify the period. For example, Dates.Year(20) defines a period of 20 years, and Dates.Month(6) defines a period of 6 months. So, to add 20 years and 6 months to the birthday date:
Here's 6 months ago from now:
and similarly for months, weeks:
and similarly for weeks and hours. Here's the date and time for two weeks and 12 hours from now:
and there are
or 148 (shopping) days till Christmas (at the time this was written).
To retrieve the value as a number, use the function Dates.value:
This works with different types of date/time objects too:

### Range of dates

You can make iterable range objects that define a range of dates:
This iterator yields the first day of every third month. To find out which of these fall on weekdays, you can provide an anonymous function to filter that tests the day name against the given day names:
104-element Array{Date,1}:
Similarly, here's a range of times 3 hours apart from now, for a year hence:
If you have to pay a bill every 30 days, starting on the 1st of January 2018, the following code shows how the due date creeps forward every month:

### Date formatting

To specify date formats, you use date formatting codes in a formatting string. Each character refers to a date/time element:
You can use these formatting strings with functions such as DateTime and Dates.format. For example, you create a DateTime object from a string by identifying the different elements in the incoming string:
Other characters are used literally. In the second example, the formatting characters matched up as follows:
You can supply a format string to Dates.format to format a date object. In the formatting string, you repeat the characters to control how years and days, for example, are output:
When you're creating a formatted date, you can double some of the components of the format string to produce a leading zero for single digit date elements:
To convert a date string from one format to another, you can use DateTime and a format string to convert the string to a DateTime object, then DateFormat to output the object in a different format:
If you're doing a lot of date formatting (you can apply date functions to an array of strings), it's a good idea to pre-define a DateFormat object and then use that for bulk conversions (this is quicker):
There are some built-in formats that you can use. For example, there's Dates.ISODateTimeFormat to give you the ISO8601 format:
and here's good old RFC1123:

### Date adjustments

Sometimes you want to find a date nearest to another - for example, the first day of that week, or the last day of the month that contains that date. You can do this with the functions like Dates.firstdayofweek and Dates.lastdayofmonth. So, if we're currently in the middle of the week:
the first day of the week is returned by this:
which you could also write using the function chain operator:
A more general solution is provided by the tofirst, tolast, tonext, and toprev methods.
With tonext and toprev, you can provide a (possibly anonymous) function that returns true when a date has been correctly adjusted. For example, the function:
returns true if the day d is a Tuesday. Use this with the tonext method:
Or you can find the next Sunday following the birthday date:
With tofirst and tolast, you can find the first Sunday, or Thursday, or whatever, of a month. Monday is 1, Tuesday 2, etc.
Supply the keyword argument of=Year to get the first matching weekday of the year.

#### Rounding dates and times

You can use round, floor, and ceil, usually used to round numbers up or down to the nearest preferred values, to adjust dates forward or backwards in time so that they have 'rounder' values.
The ceil adjusts dates or times forward in time:

### Recurring dates

It's useful to be able to find all dates in a range of dates that satisfy some particular criteria. For example, you can work out the second Sunday in a month by using the Dates.dayofweekofmonth and Dates.dayname functions.
For example, let's create a range of dates from the first of September 2014 until Christmas Day, 2014:
Now an anonymous function similar to the ones we used in tonext earlier finds a selection of those dates in that range that satisfy that function:
These are the dates of every Sunday between September 1st 2014 until Christmas Day, 2014.
By combining criteria in the anonymous function, you can build up more complicated recurring events. Here's a list of all the Tuesdays in that period which are on days that are odd numbered and greater than 20:
and here's every second Tuesday in 2016 between April and November:

### Unix time

You sometimes have to deal with another type of timekeeping: Unix time. Unix time is a count of the number of seconds that have elapsed since the beginning of the year 1970 (the birth of Unix). In Julia the count is stored in a 64 bit integer, and we'll never see the end of Unix time. (The universe will have ended long before 64 bit Unix time reaches the maximum possible value, which will be in approximately 292 billion years from now, at 15:30:08 on Sunday, 4 December 292,277,026,596.)
In Julia, the time function, used without arguments, returns the Unix time value of the current second:
The strftime ("string format time") function, which lives in the Libc module, converts a number of seconds in Unix time to a more readable form:
You can choose a different format by supplying a format string, with the different components of the date and time defined by '%' letter codes:
The strptime function takes a format string and a date string, and returns a TmStruct expression. This can then be converted to a Unix time value by passing it to time:
The Dates module also offers a unix2datetime function, which converts a Unix time value to a date/time object:

### Moments in time

DateTimes are stored as milliseconds, in the field instant. Use Dates.value to obtain the value.
If you use the more precise Dates.Time type, you can access nanoseconds.

## Timing and monitoring

The @elapsed macro returns the number of seconds an expression took to evaluate:
The @time macro tells you how long an expression took to evaluate, and how memory was allocated.