rt4-doc-html 4.2.12-5 / usr / share / doc / rt4-doc-html / RT / Date.html

<ul id="index">
  <li><a href="#NAME">NAME</a></li>
  <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="#METHODS">METHODS</a>
    <ul>
      <li><a href="#new">new</a></li>
      <li><a href="#Set">Set</a></li>
      <li><a href="#SetToNow">SetToNow</a></li>
      <li><a href="#SetToMidnight-Timezone-utc">SetToMidnight [Timezone =&gt; &#39;utc&#39;]</a></li>
      <li><a href="#Diff">Diff</a></li>
      <li><a href="#DiffAsString">DiffAsString</a></li>
      <li><a href="#DurationAsString">DurationAsString</a></li>
      <li><a href="#AgeAsString">AgeAsString</a></li>
      <li><a href="#AsString">AsString</a></li>
      <li><a href="#GetWeekday-DAY">GetWeekday DAY</a></li>
      <li><a href="#GetMonth-MONTH">GetMonth MONTH</a></li>
      <li><a href="#AddSeconds-SECONDS">AddSeconds SECONDS</a></li>
      <li><a href="#AddDays-DAYS">AddDays [DAYS]</a></li>
      <li><a href="#AddDay">AddDay</a></li>
      <li><a href="#Unix-unixtime">Unix [unixtime]</a></li>
      <li><a href="#DateTime">DateTime</a></li>
      <li><a href="#Date">Date</a></li>
      <li><a href="#Time">Time</a></li>
      <li><a href="#Get">Get</a></li>
      <li><a href="#Output-formatters">Output formatters</a>
        <ul>
          <li><a href="#Formatters">Formatters</a></li>
          <li><a href="#ValidFormatter-FORMAT">ValidFormatter FORMAT</a></li>
          <li><a href="#DefaultFormat">DefaultFormat</a></li>
        </ul>
      </li>
      <li><a href="#LocaleObj">LocaleObj</a>
        <ul>
          <li><a href="#LocalizedDateTime">LocalizedDateTime</a></li>
          <li><a href="#ISO">ISO</a></li>
          <li><a href="#W3CDTF">W3CDTF</a></li>
          <li><a href="#RFC2822-MIME">RFC2822 (MIME)</a></li>
          <li><a href="#RFC2616-HTTP">RFC2616 (HTTP)</a>
            <ul>
              <li><a href="#iCal">iCal</a></li>
            </ul>
          </li>
        </ul>
      </li>
      <li><a href="#Timezones-handling">Timezones handling</a>
        <ul>
          <li><a href="#Localtime-context-time">Localtime $context [$time]</a></li>
          <li><a href="#Timelocal-context-time">Timelocal $context @time</a></li>
          <li><a href="#Timezone-context">Timezone $context</a></li>
          <li><a href="#IsSet">IsSet</a></li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

<h1 id="NAME"><a href="#___top">NAME</a></h1>

<pre><code>  RT::Date - a simple Object Oriented date.</code></pre>

<h1 id="SYNOPSIS"><a href="#___top">SYNOPSIS</a></h1>

<pre><code>  use RT::Date</code></pre>

<h1 id="DESCRIPTION"><a href="#___top">DESCRIPTION</a></h1>

<p>RT Date is a simple Date Object designed to be speedy and easy for RT to use.</p>

<p>The fact that it assumes that a time of 0 means &quot;never&quot; is probably a bug.</p>

<h1 id="METHODS"><a href="#___top">METHODS</a></h1>

<h2 id="new"><a href="#___top">new</a></h2>

<p>Object constructor takes one argument <code>RT::CurrentUser</code> object.</p>

<h2 id="Set"><a href="#___top">Set</a></h2>

<p>Takes a param hash with the fields <code>Format</code>, <code>Value</code> and <code>Timezone</code>.</p>

<p>If $args-&gt;{&#39;Format&#39;} is &#39;unix&#39;, takes the number of seconds since the epoch.</p>

<p>If $args-&gt;{&#39;Format&#39;} is ISO, tries to parse an ISO date.</p>

<p>If $args-&gt;{&#39;Format&#39;} is &#39;unknown&#39;, require Time::ParseDate and make it figure things out. This is a heavyweight operation that should never be called from within RT&#39;s core. But it&#39;s really useful for something like the textbox date entry where we let the user do whatever they want.</p>

<p>If $args-&gt;{&#39;Value&#39;} is 0, assumes you mean never.</p>

<h2 id="SetToNow"><a href="#___top">SetToNow</a></h2>

<p>Set the object&#39;s time to the current time. Takes no arguments and returns unix time.</p>

<h2 id="SetToMidnight-Timezone-utc"><a href="#___top">SetToMidnight [Timezone =&gt; &#39;utc&#39;]</a></h2>

<p>Sets the date to midnight (at the beginning of the day). Returns the unixtime at midnight.</p>

<p>Arguments:</p>

<dl>

<dt id="Timezone">Timezone</dt>
<dd>

<p>Timezone context <code>user</code>, <code>server</code> or <code>UTC</code>. See also <a href="#Timezone">&quot;Timezone&quot;</a>.</p>

</dd>
</dl>

<h2 id="Diff"><a href="#___top">Diff</a></h2>

<p>Takes either an <code>RT::Date</code> object or the date in unixtime format as a string, if nothing is specified uses the current time.</p>

<p>Returns the differnce between the time in the current object and that time as a number of seconds. Returns <code>undef</code> if any of two compared values is incorrect or not set.</p>

<h2 id="DiffAsString"><a href="#___top">DiffAsString</a></h2>

<p>Takes either an <code>RT::Date</code> object or the date in unixtime format as a string, if nothing is specified uses the current time.</p>

<p>Returns the differnce between <code>$self</code> and that time as a number of seconds as a localized string fit for human consumption. Returns empty string if any of two compared values is incorrect or not set.</p>

<h2 id="DurationAsString"><a href="#___top">DurationAsString</a></h2>

<p>Takes a number of seconds. Returns a localized string describing that duration.</p>

<p>Takes optional named arguments:</p>

<ul>

<li><p>Show</p>

<p>How many elements to show, how precise it should be. Default is 1, most vague variant.</p>

</li>
<li><p>Short</p>

<p>Turn on short notation with one character units, for example &quot;3M 2d 1m 10s&quot;.</p>

</li>
</ul>

<h2 id="AgeAsString"><a href="#___top">AgeAsString</a></h2>

<p>Takes nothing. Returns a string that&#39;s the difference between the time in the object and now.</p>

<h2 id="AsString"><a href="#___top">AsString</a></h2>

<p>Returns the object&#39;s time as a localized string with curent user&#39;s preferred format and timezone.</p>

<p>If the current user didn&#39;t choose preferred format then system wide setting is used or <a href="#DefaultFormat">&quot;DefaultFormat&quot;</a> if the latter is not specified. See config option <code>DateTimeFormat</code>.</p>

<h2 id="GetWeekday-DAY"><a href="#___top">GetWeekday DAY</a></h2>

<p>Takes an integer day of week and returns a localized string for that day of week. Valid values are from range 0-6, Note that <b>0 is sunday</b>.</p>

<h2 id="GetMonth-MONTH"><a href="#___top">GetMonth MONTH</a></h2>

<p>Takes an integer month and returns a localized string for that month. Valid values are from from range 0-11.</p>

<h2 id="AddSeconds-SECONDS"><a href="#___top">AddSeconds SECONDS</a></h2>

<p>Takes a number of seconds and returns the new unix time.</p>

<p>Negative value can be used to substract seconds.</p>

<h2 id="AddDays-DAYS"><a href="#___top">AddDays [DAYS]</a></h2>

<p>Adds <code>24 hours * DAYS</code> to the current time. Adds one day when no argument is specified. Negative value can be used to substract days.</p>

<p>Returns new unix time.</p>

<h2 id="AddDay"><a href="#___top">AddDay</a></h2>

<p>Adds 24 hours to the current time. Returns new unix time.</p>

<h2 id="Unix-unixtime"><a href="#___top">Unix [unixtime]</a></h2>

<p>Optionally takes a date in unix seconds since the epoch format. Returns the number of seconds since the epoch</p>

<h2 id="DateTime"><a href="#___top">DateTime</a></h2>

<p>Alias for <a href="#Get">&quot;Get&quot;</a> method. Arguments <code>Date</code> and <code>Time</code> are fixed to true values, other arguments could be used as described in <a href="#Get">&quot;Get&quot;</a>.</p>

<h2 id="Date"><a href="#___top">Date</a></h2>

<p>Takes Format argument which allows you choose date formatter. Pass throught other arguments to the formatter method.</p>

<p>Returns the object&#39;s formatted date. Default formatter is ISO.</p>

<h2 id="Time"><a href="#___top">Time</a></h2>

<h2 id="Get"><a href="#___top">Get</a></h2>

<p>Returns a formatted and localized string that represents the time of the current object.</p>

<h2 id="Output-formatters"><a href="#___top">Output formatters</a></h2>

<p>Fomatter is a method that returns date and time in different configurable format.</p>

<p>Each method takes several arguments:</p>

<dl>

<dt id="Date1">Date</dt>
<dd>

</dd>
<dt id="Time1">Time</dt>
<dd>

</dd>
<dt id="Timezone---Timezone-context-server-user-or-UTC">Timezone - Timezone context <code>server</code>, <code>user</code> or <code>UTC</code></dt>
<dd>

</dd>
</dl>

<p>Formatters may also add own arguments to the list, for example in RFC2822 format day of time in output is optional so it understands boolean argument <code>DayOfTime</code>.</p>

<h3 id="Formatters"><a href="#___top">Formatters</a></h3>

<p>Returns an array of available formatters.</p>

<h3 id="ValidFormatter-FORMAT"><a href="#___top">ValidFormatter FORMAT</a></h3>

<p>Returns a true value if <code>FORMAT</code> is a known formatter. Otherwise returns false.</p>

<h3 id="DefaultFormat"><a href="#___top">DefaultFormat</a></h3>

<h2 id="LocaleObj"><a href="#___top">LocaleObj</a></h2>

<p>Returns the <a href="http://metacpan.org/module/DateTime::Locale">DateTime::Locale</a> object representing the current user&#39;s locale.</p>

<h3 id="LocalizedDateTime"><a href="#___top">LocalizedDateTime</a></h3>

<p>Returns date and time as string, with user localization.</p>

<p>Supports arguments: <code>DateFormat</code> and <code>TimeFormat</code> which may contains date and time format as specified in <a href="http://metacpan.org/module/DateTime::Locale">DateTime::Locale</a> (default to <code>date_format_full</code> and <code>time_format_medium</code>), <code>AbbrDay</code> and <code>AbbrMonth</code> which may be set to 0 if you want full Day/Month names instead of abbreviated ones.</p>

<h3 id="ISO"><a href="#___top">ISO</a></h3>

<p>Returns the object&#39;s date in ISO format <code>YYYY-MM-DD mm:hh:ss</code>. ISO format is locale-independent, but adding timezone offset info is not implemented yet.</p>

<p>Supports arguments: <code>Timezone</code>, <code>Date</code>, <code>Time</code> and <code>Seconds</code>. See <a href="#Output-formatters">&quot;Output formatters&quot;</a> for description of arguments.</p>

<h3 id="W3CDTF"><a href="#___top">W3CDTF</a></h3>

<p>Returns the object&#39;s date and time in W3C date time format (<a href="http://www.w3.org/TR/NOTE-datetime">http://www.w3.org/TR/NOTE-datetime</a>).</p>

<p>Format is locale-independent and is close enough to ISO, but note that date part is <b>not optional</b> and output string has timezone offset mark in <code>[+-]hh:mm</code> format.</p>

<p>Supports arguments: <code>Timezone</code>, <code>Time</code> and <code>Seconds</code>. See <a href="#Output-formatters">&quot;Output formatters&quot;</a> for description of arguments.</p>

<h3 id="RFC2822-MIME"><a href="#___top">RFC2822 (MIME)</a></h3>

<p>Returns the object&#39;s date and time in RFC2822 format, for example <code>Sun, 06 Nov 1994 08:49:37 +0000</code>. Format is locale-independent as required by RFC. Time part always has timezone offset in digits with sign prefix.</p>

<p>Supports arguments: <code>Timezone</code>, <code>Date</code>, <code>Time</code>, <code>DayOfWeek</code> and <code>Seconds</code>. See <a href="#Output-formatters">&quot;Output formatters&quot;</a> for description of arguments.</p>

<h3 id="RFC2616-HTTP"><a href="#___top">RFC2616 (HTTP)</a></h3>

<p>Returns the object&#39;s date and time in RFC2616 (HTTP/1.1) format, for example <code>Sun, 06 Nov 1994 08:49:37 GMT</code>. While the RFC describes version 1.1 of HTTP, but the same form date can be used in version 1.0.</p>

<p>Format is fixed-length, locale-independent and always represented in GMT which makes it quite useless for users, but any date in HTTP transfers must be presented using this format.</p>

<pre><code>    HTTP-date = rfc1123 | ...
    rfc1123   = wkday &quot;,&quot; SP date SP time SP &quot;GMT&quot;
    date      = 2DIGIT SP month SP 4DIGIT
                ; day month year (e.g., 02 Jun 1982)
    time      = 2DIGIT &quot;:&quot; 2DIGIT &quot;:&quot; 2DIGIT
                ; 00:00:00 - 23:59:59
    wkday     = &quot;Mon&quot; | &quot;Tue&quot; | &quot;Wed&quot; | &quot;Thu&quot; | &quot;Fri&quot; | &quot;Sat&quot; | &quot;Sun&quot;
    month     = &quot;Jan&quot; | &quot;Feb&quot; | &quot;Mar&quot; | &quot;Apr&quot; | &quot;May&quot; | &quot;Jun&quot;
              | &quot;Jul&quot; | &quot;Aug&quot; | &quot;Sep&quot; | &quot;Oct&quot; | &quot;Nov&quot; | &quot;Dec&quot;</code></pre>

<p>Supports arguments: <code>Date</code> and <code>Time</code>, but you should use them only for some personal reasons, RFC2616 doesn&#39;t define any optional parts. See <a href="#Output-formatters">&quot;Output formatters&quot;</a> for description of arguments.</p>

<h4 id="iCal"><a href="#___top">iCal</a></h4>

<p>Returns the object&#39;s date and time in iCalendar format. If only date requested then user&#39;s timezone is used, otherwise it&#39;s UTC.</p>

<p>Supports arguments: <code>Date</code> and <code>Time</code>. See <a href="#Output-formatters">&quot;Output formatters&quot;</a> for description of arguments.</p>

<h2 id="Timezones-handling"><a href="#___top">Timezones handling</a></h2>

<h3 id="Localtime-context-time"><a href="#___top">Localtime $context [$time]</a></h3>

<p>Takes one mandatory argument <code>$context</code>, which determines whether we want &quot;user local&quot;, &quot;system&quot; or &quot;UTC&quot; time. Also, takes optional argument unix <code>$time</code>, default value is the current unix time.</p>

<p>Returns object&#39;s date and time in the format provided by perl&#39;s builtin functions <code>localtime</code> and <code>gmtime</code> with two exceptions:</p>

<dl>

<dt id="pod1">1)</dt>
<dd>

<p>&quot;Year&quot; is a four-digit year, rather than &quot;years since 1900&quot;</p>

</dd>
<dt id="pod2">2)</dt>
<dd>

<p>The last element of the array returned is <code>offset</code>, which represents timezone offset against <code>UTC</code> in seconds.</p>

</dd>
</dl>

<h3 id="Timelocal-context-time"><a href="#___top">Timelocal $context @time</a></h3>

<p>Takes argument <code>$context</code>, which determines whether we should treat <code>@time</code> as &quot;user local&quot;, &quot;system&quot; or &quot;UTC&quot; time.</p>

<p><code>@time</code> is array returned by <a href="#Localtime">&quot;Localtime&quot;</a> functions. Only first six elements are mandatory - $sec, $min, $hour, $mday, $mon and $year. You may pass $wday, $yday and $isdst, these are ignored.</p>

<p>If you pass <code>$offset</code> as ninth argument, it&#39;s used instead of <code>$context</code>. It&#39;s done such way as code <code>$self-&gt;Timelocal(&#39;utc&#39;, $self-&gt;Localtime(&#39;server&#39;))</code> doesn&#39;t make much sense and most probably would produce unexpected results, so the method ignores &#39;utc&#39; context and uses the offset returned by the <a href="#Localtime">&quot;Localtime&quot;</a> method.</p>

<h3 id="Timezone-context"><a href="#___top">Timezone $context</a></h3>

<p>Returns the timezone name for the specified context. <code>$context</code> should be one of these values:</p>

<dl>

<dt id="user"><code>user</code></dt>
<dd>

<p>The current user&#39;s Timezone value will be returned.</p>

</dd>
<dt id="server"><code>server</code></dt>
<dd>

<p>The value of the <code>Timezone</code> RT config option will be returned.</p>

</dd>
</dl>

<p>For any other value of <code>$context</code>, or if the specified context has no defined timezone, <code>UTC</code> is returned.</p>

<h3 id="IsSet"><a href="#___top">IsSet</a></h3>

<p>Returns true if this Date is set in the database, otherwise returns a false value.</p>

<p>This avoids needing to compare to 1970-01-01 in any of your code.</p>

<a href="./../">&larr; Back to index</a>