<doc>

<legacy_id>2064</legacy_id>

<name>convert</name>

<type>command</type>

<syntax>

<example>convert <i>dateAndTime</i> [from <i>format</i> [and <i>format</i>]] to <i>format</i> [and <i>format</i>]</example>

</syntax>

<synonyms>

</synonyms>

<summary>Changes a date, a time, or a date and time to a specified format.</summary>

<examples>

<example>convert "11/22/90" to long english date</example>

<example>convert the internet date from internet date to system date</example>

<example><p>convert lastChangedTime to abbreviated time and long date</p></example>

<example>convert the date &amp;&amp; the time to seconds</example>

</examples>

<history>

<introduced version="1.0">Added.</introduced>

<deprecated version=""></deprecated>

<removed version=""></removed>

<changed version="1.1">1.1</changed>

<experimental version=""></experimental>

<nonexperimental version=""></nonexperimental>

</history>

<objects>

</objects>

<platforms>

<mac/>

<windows/>

<linux/>

<ios/>

<android/>

</platforms>

<classes>

<desktop/>

<server/>

<web/>

<mobile/>

</classes>

<security>

</security>

<classification>

<category>Math, Logic, &amp; Dates</category>

</classification>

<references>

<function tag="dateFormat">dateFormat Function</function>

<function tag="time">time Function</function>

<function tag="milliseconds">milliseconds Function</function>

<function tag="date">date Function</function>

<command tag="sort container">sort container Command</command>

<property tag="twelveHourTime">twelveHourTime Property</property>

<property tag="centuryCutoff">centuryCutoff Property</property>

<operator tag="is a">is a Operator</operator>

<keyword tag="english">english Keyword</keyword>

<keyword tag="internet">internet Keyword</keyword>

<keyword tag="long">long Keyword</keyword>

<keyword tag="seconds">seconds Keyword</keyword>

<keyword tag="system">system Keyword</keyword>

<keyword tag="dateItems">dateItems Keyword</keyword>

<keyword tag="short">short Keyword</keyword>

<keyword tag="abbreviated">abbreviated Keyword</keyword>

</references>

<description>Use the <b>convert</b> <glossary tag="command">command</glossary> to change a date or time to a <function tag="format">format</function> that's more convenient for calculation or display.<p></p><p><b>Parameters:</b></p><p>The <i>dateAndTime</i> is a <keyword tag="string">string</keyword> or <glossary tag="container">container</glossary> with a date, a time, or a date and time separated by a space, tab, or return <keyword tag="character">character</keyword>.</p><p></p><p>The <i>format</i> is one of the following (examples are February 17, 2000 at 10:13:21 PM, in the Eastern time zone, using US date and time formats):</p><p></p><p>&#9;* short date: 2/17/00</p><p>&#9;* abbreviated date: Thu, Feb 17, 2000</p><p>&#9;* long date: Thursday, February 17, 2000</p><p>&#9;* short time: 10:13 PM</p><p>&#9;* abbreviated time: 10:13 PM</p><p>&#9;* long time: 10:13:21 PM</p><p>&#9;* internet date: Thu, 17 Feb 2000 22:13:21 -0500</p><p>&#9;* seconds: the number of seconds since the start of the eon</p><p>&#9;* dateItems: 2000,2,17,22,13,21,5</p><p></p><p>If you specify both a date and time format, they can be in either order and must be separated by a space. The resulting date and time are in the order you provided, separated by a space. If you specify seconds or dateItems, you can request only one format.</p><p></p><p><b>Comments:</b></p><p>If the <i>dateAndTime</i> is a <glossary tag="container">container</glossary>, the converted date and time is placed in the <glossary tag="container">container</glossary>, replacing the previous contents. If the <i>dateAndTime</i> is a <keyword tag="string">string</keyword>, the converted date and time is placed in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary>.</p><p></p><p>The dateItems format is a comma-separated list of numbers:</p><p>&#9;* the year</p><p>&#9;* the month number</p><p>&#9;* the day of the month</p><p>&#9;* the hour in 24-hour time</p><p>&#9;* the minute</p><p>&#9;* the second</p><p>&#9;* the numeric day of the week where Sunday is day 1, Monday is day 2, and so forth</p><p></p><p>The <b>convert</b> <glossary tag="command">command</glossary> can handle dates in dateItems format where one or more of the items is out of the normal range. This means you can add arbitrary numbers to an item in the dateItems and let the <b>convert</b> <glossary tag="command">command</glossary> handle the calculations that span minute, hour, day, month, and year boundaries.</p><p></p><p>For example, suppose you start with 9:30 AM , convert that time to <b>dateItems</b> format, then add 45 minutes to item 5 (the minute) of the resulting value. This gives you 75 as the minute. When you convert the value to any other time format, the <b>convert</b> <glossary tag="command">command</glossary> automatically converts "75 minutes" to "1 hour and 15 minutes":</p><p></p><p> convert "9:30 AM" to dateItems</p><p> add 45 to item 5 of it</p><p> convert it to time -- yields "10:15 AM"</p><p></p><p>You can optionally use the <b>english</b> or <keyword tag="system">system</keyword> <glossary tag="keyword">keyword</glossary> before the <keyword tag="short">short</keyword>, <keyword tag="abbreviated">abbreviated</keyword>, or <keyword tag="long">long</keyword> date or time. If the <property tag="useSystemDate">useSystemDate</property> is true, or if you use the <keyword tag="system">system</keyword> keyword, the user's current system preferences are used to format the date or time. Otherwise, the standard US date and time formats are used.</p><p></p><p>The internet date, seconds, and dateItems formats are invariant and do not change according to the user's preferences.</p><p></p><p></p><note>The <b>convert</b> command assumes all dates / times are in local time except for 'the seconds', which is taken to be universal time.</note><p></p><p></p><note>If you convert a date without a time to a form that includes the time, the time will be given as midnight local time.</note><p></p><p></p><note>The range of dates that the <command tag="convert">convert</command><glossary tag="command">command</glossary> can handle is limited by the operating system's date routines. In particular, Windows systems are limited to dates after 1/1/1970.</note><p></p><p></p><change><p>The ability to use the date and time format preferred by the user was introduced in version 1.1. In previous versions, the <b>convert</b> <glossary tag="command">command</glossary>, along with the <function tag="time">time</function> and <function tag="date">date</function> <glossary tag="function">functions</glossary>, consistently used the standard U.S. <function tag="format">format</function>, even if the operating system's settings specified another language or date and time <function tag="format">format</function>.</change><p></p><p>The ability to specify a <i>format</i> to convert from was introduced in version 1.1. In previous versions, LiveCode automatically guessed the <function tag="format">format</function> to convert from.</p></description>

</doc>