# Date

The **Date** object is provided to make it easier to deal with variables representing dates. It converts automatically to an ActiveX _VT\_DATE_ value and so can function as a drop-in replacement for a scripting language's native date variables. The main advantage is that it retains milliseconds, unlike _VT\_DATE_ which has a one second resolution. It also provides some utility methods to manipulate dates. The [**Item**](item) object\*\* \*\*has a number of properties that returns **Date** objects.

You can create a new **Date** object using the [**DOpusFactory**](dopusfactory)**.Date** method.

| Property Name      | Return Type | Description                                                                                       |
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------- |
| _\<default value>_ | _date_      | Returns a _VT\_DATE_ representing the value of this **Date** object (excluding the milliseconds). |
| day                | _int_       | Get or set the _day_ value of the date.                                                           |
| hour               | _int_       | Get or set the _hour_ value of the date.                                                          |
| min                | _int_       | Get or set the _minute_ value of the date.                                                        |
| month              | _int_       | Get or set the _month_ value of the date.                                                         |
| ms                 | _int_       | Get or set the _milliseconds_ value of the date.                                                  |
| sec                | _int_       | Get or set the _seconds_ value of the date.                                                       |
| wday               | _int_       | Get the _day-of-the-week_ value of the date. 0 = Sunday, 1 = Monday, 2 = Tuesday, etc.            |
| year               | _int_       | Get or set the _year_ value of the date.                                                          |

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td>Method Name</td><td><strong>Arguments</strong></td><td>Return Type</td><td>Description</td><td></td><td></td></tr><tr><td>Add</td><td>&#x3C;int:value><br>&#x3C;string:type></td><td><em>none</em></td><td><p>Adds the specified value to the date. The interpretation of the specified value is controlled by the <em>type</em> string:</p><table><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>l</strong></td><td>milliseconds</td><td></td></tr><tr><td><strong>s</strong></td><td>seconds</td><td></td></tr><tr><td><strong>m</strong></td><td>minutes</td><td></td></tr><tr><td><strong>h</strong></td><td>hours</td><td></td></tr><tr><td><strong>d</strong></td><td>days</td><td></td></tr><tr><td><strong>w</strong></td><td>weeks</td><td></td></tr><tr><td><strong>M</strong></td><td>months</td><td></td></tr><tr><td><strong>y</strong></td><td>years</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Clone</td><td></td><td></td></tr></tbody></table><p><em>none</em></p></td><td>*object:*<strong>Date</strong></td><td>Returns a new <strong>Date</strong> object set to the same date as this one.</td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td><strong>l</strong></td><td>milliseconds</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>s</strong></td><td>seconds</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>m</strong></td><td>minutes</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>h</strong></td><td>hours</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>d</strong></td><td>days</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>w</strong></td><td>weeks</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>M</strong></td><td>months</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>y</strong></td><td>years</td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Clone</td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Compare</td><td>&#x3C;date:other><br>[&#x3C;string:type>]<br>[&#x3C;int:tolerance>]</td><td><em>int</em></td><td><p>Compares this date against the <em>other</em> date. The return value will be <strong>0</strong> (equal), <strong>1</strong> (greater) or <strong>-1</strong> (less).</p><p>The optional <em>type</em> string controls how the comparison is performed:</p><table><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>s</strong></td><td>ignore seconds. If specified, the optional <em>tolerance</em> argument specifies the comparison tolerance in seconds.</td><td></td></tr><tr><td><strong>sD</strong></td><td>ignore seconds, and compensate automatically for daylight savings.</td><td></td></tr><tr><td><strong>t</strong></td><td>compare times only</td><td></td></tr><tr><td><strong>d</strong></td><td>compare dates only</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Format</td><td></td><td></td></tr></tbody></table><p>[&#x3C;string:format>]<br>[&#x3C;string:flags>]</p></td><td><em>string</em></td><td><p>Returns a formatted date or time string. The <em>format</em> and <em>flags</em> arguments are both optional.</p><p>If you do not give a <em>format</em>, the result will include both date and time, formatted the same as date-time columns in the file display.</p><p>If you give a <em>format</em> of just <strong>"d"</strong> or <strong>"t"</strong> then the result will be just the date or time part, formatted the same as date or time columns in the file display.</p><p>The file display's formats depend on the user's locale and Windows settings. You should use those options if you wish to present a date/time to the user in the way they expect them to look, but not if you need to store them in a specific format.</p><p>When using the file display's format (that is, the <em>format</em> argument is empty, <strong>"d"</strong> or <strong>"t"</strong>), you can optionally pass one or more case-sensitive flags in the second <em>flags</em> argument to override a few settings:</p><table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>N</strong></td><td>Force day names on in dates within the last week. "Today", "Monday", etc.</td></tr><tr><td><strong>n</strong></td><td>Force day names off.</td></tr><tr><td><strong>S</strong></td><td>Force seconds on in times.</td></tr><tr><td><strong>s</strong></td><td>Force seconds off.</td></tr><tr><td><strong>M</strong></td><td>Force milliseconds on in times. (Milliseconds will be zero if the stored time does not have millisecond accuracy.)</td></tr><tr><td><strong>m</strong></td><td>Force milliseconds off.</td></tr><tr><td><strong>P</strong></td><td>Force time hours to be padded to two digits.</td></tr><tr><td><strong>p</strong></td><td>Do not force time hours to be padded.</td></tr></tbody></table><p>For example, to get just the date, using the user's locale, but with day names forced off:</p><pre><code>myDate.Format("d","n")
</code></pre><p>To get the date and time, using the user's locale, but with day names forced on and seconds forced off:</p><pre><code>myDate.Format("","Ns")
</code></pre><p>The <em>format</em> can also use the syntax shown in <a href="../../command_reference/external_control_codes/codes_for_date_and_time">Codes for date and time</a>, allowing for arbitrary formats. For example,</p><pre><code>myDate.Format("D#yyyy-MM-dd T#HH:mm:ss")
</code></pre><p>This would return a string like <strong>2023-07-28 15:45:26</strong>.</p><p>When explicitly specifying a format, the <em>flags</em> argument should not be used and will be ignored.</p></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td><strong>s</strong></td><td>ignore seconds. If specified, the optional <em>tolerance</em> argument specifies the comparison tolerance in seconds.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>sD</strong></td><td>ignore seconds, and compensate automatically for daylight savings.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>t</strong></td><td>compare times only</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>d</strong></td><td>compare dates only</td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Format</td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td><strong>N</strong></td><td>Force day names on in dates within the last week. "Today", "Monday", etc.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>n</strong></td><td>Force day names off.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>S</strong></td><td>Force seconds on in times.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>s</strong></td><td>Force seconds off.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>M</strong></td><td>Force milliseconds on in times. (Milliseconds will be zero if the stored time does not have millisecond accuracy.)</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>m</strong></td><td>Force milliseconds off.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>P</strong></td><td>Force time hours to be padded to two digits.</td><td></td><td></td><td></td><td></td></tr><tr><td><strong>p</strong></td><td>Do not force time hours to be padded.</td><td></td><td></td><td></td><td></td></tr><tr><td>FromUTC</td><td><em>none</em></td><td>*object:*<strong>Date</strong></td><td>Returns a new <strong>Date</strong> object with the date converted from UTC (based on the local time zone).</td><td></td><td></td></tr><tr><td>Reset</td><td><em>none</em></td><td><em>none</em></td><td>Resets the date to the current local date/time.</td><td></td><td></td></tr><tr><td>Set</td><td>&#x3C;date:newdate></td><td><em>none</em></td><td><p>Sets the value of this <strong>Date</strong> object to the supplied date. <em>newdate</em> can be:</p><ul><li>Another <strong>Date</strong> object</li><li>A string in the form "yyyymmdd"</li><li>A string in the form "yyyy-mm-dd hh:mm:ss.mmm" (or part thereof)</li><li>A JScript <strong>Date</strong> object</li><li>A unix epoch time value (seconds since 1/1/1970).</li><li>The string "now" (sets to the current time)</li></ul></td><td></td><td></td></tr><tr><td>Sub</td><td>&#x3C;int:value><br>&#x3C;string:type></td><td><em>none</em></td><td>Subtracts the specified value from the date. The parameters are the same as for the <strong>Add</strong> method.</td><td></td><td></td></tr><tr><td>ToUTC</td><td><em>none</em></td><td>*object:*<strong>Date</strong></td><td>Returns a new <strong>Date</strong> object with the date converted to UTC (based on the local time zone).</td><td></td><td></td></tr></tbody></table>
