~~Title: Date ~~
<pageheader/>

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.


<commandtable columns="3" id="cmdtable_1">
$$ 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.
</commandtable>


<commandtable columns="4" id="cmdtable_2">
$$ Method Name
$$ **Arguments**
$$ Return Type
$$ Description
$$ Add
$$ <int:value>\\
<string:type>
$$ //none//
$$ Adds the specified value to the date. The interpretation of the specified value is controlled by the //type// string:
|**l**|milliseconds|
|**s**|seconds|
|**m**|minutes|
|**h**|hours|
|**d**|days|
|**w**|weeks|
|**M**|months|
|**y**|years|
$$ Clone
$$ //none//
$$ //object://**Date**
$$ Returns a new **Date** object set to the same date as this one.
$$ Compare
$$ <date:other>\\
[<string:type>]\\
[<int:tolerance>]
$$ //int//
$$ Compares this date against the //other// date. The return value will be **0** (equal), **1** (greater) or **-1** (less).

The optional //type// string controls how the comparison is performed:

|**s**|ignore seconds. If specified, the optional //tolerance// argument specifies the comparison tolerance in seconds.|
|**sD**|ignore seconds, and compensate automatically for daylight savings.|
|**t**|compare times only|
|**d**|compare dates only|
$$ Format
$$ [<string:format>]\\
[<string:flags>]
$$ //string//
$$ Returns a formatted date or time string. The //format// and //flags// arguments are both optional.

If you do not give a //format//, the result will include both date and time, formatted the same as date-time columns in the file display.

If you give a //format// of just **"d"** or **"t"** then the result will be just the date or time part, formatted the same as date or time columns in the file display.

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.

When using the file display's format (that is, the //format// argument is empty, **"d"** or **"t"**), you can optionally pass one or more case-sensitive flags in the second //flags// argument to override a few settings:
|**N**|Force day names on in dates within the last week. "Today", "Monday", etc. |
|**n**|Force day names off. |
|**S**|Force seconds on in times. |
|**s**|Force seconds off. |
|**M**|Force milliseconds on in times. (Milliseconds will be zero if the stored time does not have millisecond accuracy.) |
|**m**|Force milliseconds off. |
|**P**|Force time hours to be padded to two digits. |
|**p**|Do not force time hours to be padded.|

For example, to get just the date, using the user's locale, but with day names forced off:
<code>
myDate.Format("d","n")
</code>

To get the date and time, using the user's locale, but with day names forced on and seconds forced off:
<code>
myDate.Format("","Ns")
</code>

The //format// can also use the syntax shown in [[..:..:command_reference:external_control_codes:codes_for_date_and_time|Codes for date and time]], allowing for arbitrary formats. For example,

<code>myDate.Format("D#yyyy-MM-dd T#HH:mm:ss")</code>

This would return a string like **2023-07-28 15:45:26**.

When explicitly specifying a format, the //flags// argument should not be used and will be ignored.
$$ FromUTC
$$ //none//
$$ //object://**Date**
$$ Returns a new **Date** object with the date converted from UTC (based on the local time zone).
$$ Reset
$$ //none//
$$ //none//
$$ Resets the date to the current local date/time.
$$ Set
$$ <date:newdate>
$$ //none//
$$ Sets the value of this **Date** object to the supplied date. //newdate// can be:
  * Another **Date** object
  * A string in the form "yyyymmdd"
  * A string in the form "yyyy-mm-dd hh:mm:ss.mmm" (or part thereof)
  * A JScript **Date** object
  * A unix epoch time value (seconds since 1/1/1970).
  * The string "now" (sets to the current time)
$$ Sub
$$ <int:value>\\
<string:type>
$$ //none//
$$ Subtracts the specified value from the date. The parameters are the same as for the **Add** method.
$$ ToUTC
$$ //none//
$$ //object://**Date**
$$ Returns a new **Date** object with the date converted to UTC (based on the local time zone).
</commandtable>