Representing time data in ArcGIS

---

Time data in ArcGIS is held in two types of objects: TimeInstant and TimeExtent.

TimeInstant is similar to a point on a line in that it has no measurable width. TimeInstant is useful when you want to model a single point on the time. For example, if you're modeling the temperature in a stream at regular intervals, you can record the temperature and assign a TimeInstant object to it.

TimeExtent has a start time and an end time. TimeExtent is useful when you're specifying a time period for which data is valid. For example, if the average rainfall over a region is valid for one year, you can assign a time range to that region using a TimeExtent object. In this case, the time interval would start on January 1 and end on December 31 of the same year.

The time objects include properties for assigning and retrieving values for year, month, day, hour, minute, second, and nanosecond. There is no field for millisecond, so the valid values for nanosecond range from 0 to 999,999,999 (or 10³ - 1). For TimeExtent objects, both the start and end times can be assigned and retrieved. 

The data in TimeInstant and TimeExtent can also be accessed as a complete object (instead of individually accessing the year, month, day, and so on.) The complete time values can be accessed as an Extensible Markup Language (XML) text string, a text string with an arbitrary format, an Object Linking and Embedding (OLE) time object, a WKSDateTime object, or an integer representing "ticks". A tick is a 100 nanosecond time increment.

You can also access the year, month, and day as a single value called a Julian day number. The Julian day number is the number of days since January 1, 4713 BC.

When setting or incrementing values individually (such as adding a month to a time value), be sure you create the time you really want. For example, if a month is added to January 31st, this creates February 31st, which does not exist. In general, when setting individual fields, you must create a date that exists or an error will be returned. When adding values to a field, the time object assumes you want to move forward or backward that amount of time, and resolves invalid dates and times for you.

For example, if you set the month to March, and the day to 31, an error is returned. However, if you set the month to March, and the day to 30, then add a day, the result is April 1st. If you add a day to December 31st, 2000, the result is January 1st 2001. This functionality also works with time in a single day. Adding 10 minutes to 3:55 results in 4:05.

Some ambiguity exists when adding a month or a year to a time value. In the example of adding a month to January 31st, it is not clear if the desired behavior is to go to the end of February, or to the beginning of March. The ArcGIS time application programming interface (API) provides several options for dealing with this situation. For example, to add a month to a time object representing January 31st, you can direct the function to automatically push this into March (for example, March 3rd during a non leap year), or pull the value back into a valid range for February (for example, February 28th). The desired option must be specified when calling this function.

There are a number of options for storing time values. It is often tempting to store the value as a number or a text string. These choices, however, can lead to confusion and ambiguity later on. For example, if you store the value 3:00, it is not clear if this is a.m. or p.m. Similarly, the value 1/2/2000 can mean January 2nd or February 1st of the year 2000. For these reasons, it is preferable to store time values in a binary format that was created specifically for storing time values. If you store time values in such a format (such as a date field), ArcGIS time classes have functions to read and write these values. The QueryOleTime function gives you the date object representing the stored time value. SetFromOleTime allows you to set the value of a time object using the value from a date field.

If you're unable to store your date using the date field, ArcGIS provides methods to read and write in a variety of other formats. ArcGIS uses a limited set of time formats stored as text. If you have time values stored in one of these formats, you can use the SetFromTimeString and QueryTimeString functions to read and write values in one of these accepted formats. If you have time stored in a text field that is not one of the ESRI supported text formats, then the Time class provides functions to read and write arbitrary time formats. To do this, use the SetFromTimeStringCustom and QueryTimeStringCustom functions. These functions require that you pass in the format of the text as well as the text value. For details on other supported formats, refer to the class and interface APIs.