DateTag is a class for representing a Date metadata tag. When a date metadata is represented in W3CDTF format there are three attributes that can be extracted from the field:
- The DateTime being represented.
- The TimeZone information.
- The Precision of the DateTime.
This C# class represents all three components and includes for parsing, formatting, and using DateTime values. Even when DateTime data are not represented in W3CDTF format, the class is valuable for combining and representing all three related attributes.
The DateTime contains both the date and the time of the event associated with the metadata. The value is usually, but not always, in local time. In some cases, the DateTime may be in UTC (see TimeZone). Here are examples of the DateTime in W3CDTF format:
- 2019-01-23
- 2019-01-23T12:45
- 2019-01-23T12:50:22.213
The TimeZone information is included using a TimeZoneTag instance. Under ideal conditions, the TimeZone value contains the timezone in which the event occurred. This allows a local DateTime to be converted to UTC for indexing and sorting purposes. However, some file formats don't include timezone information and some devices, such as cameras, may not have time zone information. So, there are two special values of TimeZoneTag.
ForceUTC indicates that the value should be interpreted as UTC regardless of the file format specification. In W3CDTF format this is indicated by a "Z" timezone suffix. As a standalone timezone value it is represented by "Z".
ForceLocal indicates that the value should be interpreted as Local time regardless of the file format definition. In W3CDTF format, ForceLocal is indicated by the absence of any timezone suffix. As a standalone value it is represented by "0".
ForceLocal is used on video files produced by certain digital cameras. The MP4 video file format specification indicates that DateTime should be in UTC. However, many digital cameras don't have a timezone setting. In these cases, the digital camera puts local time into the field even though it's defined as UTC.
Here are examples of W3CDTF format times with various timezone suffix values.
| Sample | Timezone Interpretation |
|---|---|
| 2019-01-23T13:30-05:00 | Local time UTC minus five hours (U.S. Eastern Time). |
| 2019-01-23T13:30+01:00 | Local time UTC plus one hour (Central European Time). |
| 2019-01-23T13:30Z | UTC time (ForceUTC). Offset from UTC unspecified. |
| 2019-01-23T13:30 | Local time (ForceLocal) Offset from UTC unspecified. |
Date values in W3CDTF format may be truncated according to the precision of available information. Too often, this precision information is lost when the field is parsed. The DateTag class preserves precision as the number of significant digits.
Here are examples of Date values in W3CDTF format including their precision.
| Sample | Precision | Description |
|---|---|---|
| 2019 | 4 | Year |
| 2019-01 | 6 | Month |
| 2019-01-23 | 8 | Day |
| 2019-01-23T13 | 10 | Hour |
| 2019-01-23T13:30 | 12 | Minute |
| 2019-01-23T13:30:21 | 14 | Second |
| 2019-01-23T13:30:21.482 | 17 | Millisecond |
| 2019-01-23T13:30:21:482496 | 20 | Microsecond |
The software is distributed in C# as a CodeBit located here. It is released under a BSD 3-Clause open source license.
DateTag is part of the FileMeta initiative because it manages a particular type of metadata field.
This project includes the master copy of the DateTag.cs CodeBit plus a set of unit tests which may also serve as sample code.
DateTag depends on the TimeZoneTag CodeBit.
A CodeBit is a way to share common code that's lighter weight than NuGet. Each CodeBit consists of a single source code file. A structured comment at the beginning of the file indicates where to find the master copy so that automated tools can retrieve and update CodeBits to the latest version.