Dates
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.
Python has some built-in libraries to create and manipulate dates and times. However, most users find both Ignition's built-in system functions and even Java's Calendar class easier to use. Regardless, this section will demonstrate some examples from each approach.
Ignition's System Functions
Ignition's system.date library has a large number of functions that provide easy access to datetime creation and manipulation. This page has just a few simple examples.
Creating Dates
New datetimes can be created by using either the system.date.now or system.date.getDate. The system.date.getDate function returns a datetime, but the time is set to midnight. However, we can use system.date.setTime to change the time.
# 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 function:
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* functions can be used to add to or subtract some amount of time from a date. See the system.date.add* functions for more information.
# 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 or Java's DateFormat class. Additionally, there are many other non-scripting uses in Ignition (such as the Calendar component's Format String property) that can utilize this reference.
| Symbol | Description | Presentation | Example | Other Notes |
|---|---|---|---|---|
| G | Era designator | Text | G=AD | |
| y | Year | Year | yyyy=1996; yy=96 | Lowercase y is the most commonly used year symbol |
| Y | Week year | 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 | MMMM=July; MMM=Jul; MM=07 | |
| w | Week in year | Number | 27 | If Dec31 is mid-week, it will be in week 1 of the next year |
| W | Week in month | Number | 2 | |
| D | Day in year | Number | 189 | |
| d | Day in month | Number | 10 | |
| F | Day of week in month | Number | 2 | 2nd Sunday of the month |
| E | Day name in week | Text | EEEE=Tuesday; E=Tue | |
| u | Day number of week | Number | 1 | (1 = Monday, ..., 7 = Sunday) |
| a | Am/Pm marker | Text | PM | |
| H | Hour in day (0-23) | Number | 0 | |
| h | Hour in am/pm (1-12) | Number | 12 | |
| k | Hour in day (1-24) | Number | 24 | |
| K | Hour in am/pm (0-11) | Number | 0 | |
| m | Minute in hour | Number | 30 | |
| s | Second in minute | Number | 55 | |
| S | Millisecond | Number | 978 | |
| z | Time zone | General time zone | zzzz=Pacific Standard Time; z=PST | |
| Z | Time zone | RFC 822 time zone | Z=-0800 | |
| X | Time zone | ISO 8601 time zone | X=-08; XX=-0800; XXX=-08:00 |
Java's Calendar Class
Ignition's System Functions vs Java's Calendar Class
While Java's Calendar class if useful, in many cases Ignition's built-in system.date 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.
It is highly advisable to use Ignition's 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:
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 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.
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.
As a result, it is highly recommended to use Ignition's built-in system.date 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 for more information.
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.
Note the double use of datetime in the example below. This is because the datetime library has a class named 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:
# 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:
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
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.
# 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