---
title: "Dates"
---

# Dates

> Python has some [built-in libraries](../libraries.md#python-libraries) to create and manipulate dates and times. However, most users find both Ignition's built-in [system functions](appendix/scripting-functions/scripting-functions.md) and even Java's Calendar class easier to use. Regardless, this section will demonstrate some examples from each approach.

## Overview
Dates can normally be tricky since they generally require very specific formats. Furthermore, some functions/objects require a date object instead of a string. Fortunately, there are several ways to create and alter date objects with scripting in Ignition.

## Ignition's System Functions
Ignition's [system.date](appendix/scripting-functions/system-date/system-date.md) library has a large number of functions that provide easy access to datetime creation and manipulation. This page has just a few simple examples. Additional examples and functions can be found in the [scripting appendix](appendix\scripting-functions\system-date\system-date.md).

### Creating Dates

New datetimes can be created by using either the [system.date.now](appendix/scripting-functions/system-date/system-date-now.md) or [system.date.getDate](appendix/scripting-functions/system-date/system-date-getDate.md). The system.date.getDate function returns a datetime, but the time is set to midnight. However, we can use [system.date.setTime](appendix/scripting-functions/system-date/system-date-setTime.md) to change the time. 

```python title="Python - System Functions - Creating Dates"
# Get the current datetime.
print system.date.now()
 
# Create a date. The time will be set to midnight.
newDate = system.date.getDate(2018, 10, 28)
print newDate
 
# Change the time on the new date to 11:30 am.
print system.date.setTime(newDate, 11, 30, 0)
```

### Formatting Dates
When printed, datetimes default to a format like the following: **Sun Jan 1 00:00:00 TZ 2018**. However, this can be manipulated by using special characters in the [system.date.format](appendix/scripting-functions/system-date/system-date-format.md) function:

```python title="Python - System Functions - Date Formatting"
rightNow = system.date.now()
 
# Demonstrating the standard format.
print rightNow
 
# Demonstrating the modified format.
print system.date.format(rightNow, "yyyy-MM-dd HH:mm:ss")
```

### Date Arithmetic
The [system.date.add*](appendix/scripting-functions/system-date/system-date-add.md) functions can be used to add to or subtract some amount of time from a date. See the [system.date.add*](appendix/scripting-functions/system-date/system-date-add.md) functions for more information.

```python title="Python - System Functions - Date Arithmetic"
# Get the current datetime.
newDate = system.date.now()
 
# Change the time on the new date to 30 minutes ago.
print system.date.addMinutes(newDate, -30)
```

### Date Formatting Characters
The following is a reference of date formatting characters that can be used by [system.date.format](appendix/scripting-functions/system-date/system-date-format.md) or Java's DateFormat class. Additionally, there are many other non-scripting uses in Ignition (such as the [Vision - Calendar](appendix/components/vision-components/calendars/calendar/calendar.md) component's Format String property) that can utilize this reference. 

|Symbol|Description|Presentation|Example|Other Notes|
|--|--|--|--|--|
|G |Era designator |[Text](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#text) |G=AD | |
|y |Year |[Year](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#year) | yyyy=1996; yy=96| Lowercase y is the most commonly used year symbol|
|Y |Week year |[Year](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#year) |YYYY=2009; YY=09 |Capital Y gives the year based on weeks (ie. changes to the new year up to a week early) |
|M |Month in year |[Month](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#month) |MMMM=July; MMM=Jul; MM=07 | |
|w |Week in year |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |27 |If Dec31 is mid-week, it will be in week 1 of the next year |
|W |Week in month |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |2 | |
|D |Day in year |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |189 | |
|d |Day in month |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |10 | |
|F |Day of week in month |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |2 |2nd Sunday of the month |
|E |Day name in week |[Text](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#text) |EEEE=Tuesday; E=Tue | |
|u |Day number of week |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |1 |(1 = Monday, ..., 7 = Sunday) |
|a |Am/Pm marker |[Text](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#text) |PM | |
|H |Hour in day (0-23) |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |0| |
|h|Hour in am/pm (1-12) |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |12 | |
|k |Hour in day (1-24) |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |24 | |
|K |Hour in am/pm (0-11) |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |0 | |
|m |Minute in hour |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |30 | |
|s |Second in minute |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) | 55| |
|S |Millisecond |[Number](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#number) |978 | |
|z |Time zone |[General time zone](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#timezone) |zzzz=Pacific Standard Time; z=PST | |
|Z |Time zone |[RFC 822 time zone](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#rfc822timezone) |Z=-0800 | |
|X |Time zone |[ISO 8601 time zone](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html#iso8601timezone) |X=-08; XX=-0800; XXX=-08:00 | |

## Java's Calendar Class
While Java's Calendar class if useful, in many cases Ignition's built-in [system.date](appendix/scripting-functions/system-date/system-date.md) functions are simpler to use. Furthermore, the system.date functions typically use the Calendar class to retrieve the current time, so you are not losing any functionality by using the system functions.

:::note Ignition's System Functions vs Java's Calendar Class
It is highly advisable to use [Ignition's system functions](#ignitions-system-functions) to generate and manipulate dates. The information on this page pertaining to the Calendar class is maintained in the interest for legacy installations.
:::

### Creating Dates
To create an arbitrary date, you can use the `java.util.Calendar` class. It has various functions to alter the calendar fields, like Calendar.HOUR, Calendar.MONTH, and so on. After you're done manipulating the Calendar, you can use its `getTime()` function to retrieve the Date represented by the calendar. It also has a handy `set()` function that takes the common parameters of a Date. The one major "gotcha" here is that January is month zero, not month one. For example:

```python title="Python - Calendar Class - Creating Dates"
from java.util import Calendar
cal = Calendar.getInstance()
 
# set year, month, day, hour, minute, second in one call
# This sets it to Feb 25th, 1:05:00 PM, 2010
cal.set(2010, 1, 25, 13, 5, 0)
myDate = cal.getTime()
```

### Date Arithmetic
Often you'll have a Date object from a component like the [Popup Calendar](appendix/components/vision-components/calendars/popup-calendar/popup-calendar.md) and want to alter it programmatically. Say, subtracting 8 hours from it, or something like that. The `java.util.Calendar` class is used for this as well. Following the example above, this code would subtract 8 hours from the variable `myDate`.

```python title="Python - Calendar Class - Date Arithmetic"
from java.util import Calendar
cal = Calendar.getInstance()
cal.setTime(myDate)
cal.add(Calendar.HOUR, -8)
myNewDate = cal.getTime()
```

## Python's Time and Datetime Libraries
Many components in Ignition that contain a Date property actually expect a Java calendar object. Creating a datetime object using Python's built-in libraries and passing them to a date property on a component will result in an exception.

:::note Ignition's System Functions vs Python's LIbraries
It is highly recommended to use [Ignition's built-in](#ignitions-system-functions) [system.date](appendix/scripting-functions/system-date/system-date.md) functions.
:::

### Creating Dates - Python's Time Library
The time library can be use to return dates as well as time. Times are created as a tuple of integers. The integers represent the following values: year, month, day of the month, hour, minute, second, weekday, day of the year, daylight savings time)

Check out [Python's time library documentation](https://docs.python.org/release/2.5.3/lib/module-time.html) for more information. 

```python title="Python - Python Library - time"
import time
 
# Finds the current local time. The time is returned as a tuple of integers.
myTime = time.localtime()
 
# Print the time into a 24-character string with the following format: Sun Nov 20 12:00:00 2017
print time.asctime(myTime)

# Alternatively, we can reformat the time in a custom manner, then print it
print time.strftime('%H:%M:%S %b %d %Y', myTime)
```

### Creating Dates - Python's Datetime Library
Python's datetime library offers a bit more flexibility since arithmetic can easily be applied. Additional information on the datetime library can be found in [Python's official documentation](https://docs.python.org/release/2.5.3/lib/datetime-datetime.html). 

Notice the double use of `datetime` in the example below. This is because the `datetime` library has a class named `datetime`.

```python title="Python - Python Library - datetime"
import datetime
 
# Returns the current datetime.
print datetime.datetime.now()
```

However, we can clean up the above by importing in the datetime class from the library:

```python title="Python - Python Library - datetime"
# Imports the class named 'datetime' from the 'datetime' library, so we don't have to state it twice.
from datetime import datetime
 
# Returns the current datetime.
print datetime.now()
```

If you need to create a specific datetime, instead of just using the current, you can pass in the values directly when creating an instance of datetime:

```python title="Python - Python Library - Creating a New Time"
from datetime import datetime
 
# Prints out the following datetime: 2018-01-02 03:04:05.000006
print datetime(2018,1,2,3,4,5,6)
```

Finding the difference between two datetime objects can easily be accomplished by using the '-' character

```python title="Python - Python Library - Date Difference"
from datetime import datetime
 
rightNow = datetime.now()
someTime = datetime(2018,1,1,1,1,1,1)
 
# Find the difference between the two dates.
print someTime - rightNow
```

### Date Arithmetic
With Python's built-in libraries, the timedelta class provides the simplest way to perform arithmetic on a date: It simply creates an object that effectively represents a duration. The duration can then be applied to a datetime. 

```python title="Python - Python Library - Date Arithmetic"
# We're including the timedelta class here
from datetime import datetime, timedelta
 
rightNow = datetime.now()
 
# Creating a timedelta object, and setting the hours to 8
offset = timedelta(hours = 8)
 
# Print the current time, and then print the time minus the offset.
print rightNow
print rightNow - offset
```