The manakai project

Web::DateTime

Date and time for Web

SYNOPSIS

  use Web::DateTime::Parser;
  $parser = Web::DateTime::Parser->new;
  $dt = $parser->parse_global_date_and_time_string ($value);
  warn $dt->to_unix_integer;

DESCRIPTION

The Web::DateTime class represents a date and/or time with accessor and serializer methods for Web. To create an instance of the Web::DateTime class from various date and/or time formatted strings, use Web::DateTime::Parser module.

METHODS

Following methods are available:

$dt = Web::DateTime->new_from_unix_time ($time)

Create a new instance of Web::DateTime from the specified number, representing a Unix time (i.e. number of seconds from January 1, 1970, 00:00:00 UTC). The number can contain fractional part and can be negative.

$dt = Web::DateTime->new_from_jd ($number)

Create a new instance of Web::DateTime from the specified number, representing a Julian Day (i.e. Julian Date, JD, <https://en.wikipedia.org/wiki/Julian_day>). The number can contain fractional part and can be negative.

$dt = Web::DateTime->new_from_mjd ($number)

Create a new instance of Web::DateTime from the specified number, representing a Modified Julian Day (MJD, <https://en.wikipedia.org/wiki/Julian_day>). The number can contain fractional part and can be negative.

$dt = Web::DateTime->new_from_components ($year, $month, $day, $hour, $minute, $second)

Create a new instance of Web::DateTime from the specified set of date/time components.

The arguments are interpreted as the year, month, day, hour, minute, and second components of the date/time in the proleptic Gregorian calendar. Every argument can be omitted; their defaults are 1970, 1, 1, 0, 0, and 0. The month component is an integer, where 1 represents January. They can be out of range (e.g. month can be 33, day can be -1, and so on), but the returned object might or might not be useful.

No time zone offset is set to the object.

$dt = Web::DateTime->new_from_time_components ($ref_dt, $hour, $minute, $second)

Create a new instance of Web::DateTime from a reference time and the specified set of time components.

The first argument is the reference time. It must be a Web::DateTime object representing the time. If it has a time-zone specified, that time-zone is used as part of the reference.

The remaining arguments are interpreted as the hour, minute, and second components of the time in the 24-hour clock system. The second component is optional and can be a fractional number. The components can be out of range (e.g. hour can be 33, minute can be -1, and so on), but the returned object might or might not be useful.

The newly created object represents one of the times whose time-of-day is equal to the specified hour, minute, and second, within the time zone (if specified), that is nearest to the reference time.

The time-zone offset is set to the same object (if any) as the reference time.

$dt = Web::DateTime->new_from_object ($obj)

Create a new instance of Web::DateTime from the specified date/time object. The argument must be an instance of DateTime or Time::Piece. (More classes might be supported in future.)

As the Web::DateTime (and most Web date/time formats) can't handle leap seconds, if the DateTime object represents a leap second, the result Web::DateTime object represents the second just after the leap second.

true = $dt->is_date_time
false = $dt->is_time_zone
false = $dt->is_duration
false = $dt->is_interval

Return whether the object is of the specified type or not.

$boolean = $dt->has_component ($name)

Return whether the specified component is given when the object is created. Available component names are: year, month (month of year), week (week of year), day (day of month, week, or year), time (hour, minute, and optional second of day), and offset (time zone offset).

For example, if the object is created from a valid week string, year and week will return true, and any other value will return false.

$number = $dt->year
$number = $dt->month
$number = $dt->day
$number = $dt->hour
$number = $dt->minute
$number = $dt->second

Return the number in the year, month, day, hour, minute, or second component of the object, in the Gregorian calendar, respectively. If a time zone is associated with the object, the return value is in that time zone.

$number = $dt->julian_year
$number = $dt->julian_month
$number = $dt->julian_day

Return the number in the year, month, or day component of the object, in the Julian calendar, respectively. If a time zone is associated with the object, the return value is in that time zone.

$number = $dt->utc_year
$number = $dt->utc_month
$number = $dt->utc_day
$number = $dt->utc_hour
$number = $dt->utc_minute
$number = $dt->utc_second

Return the number in the year, month, day, hour, minute, or second component of the object, respectively. If a time zone is associated with the object, the return value is converted into UTC. Otherwise, no convertion is performed.

$number = $dt->utc_week

Return the week number of the UTC date and time represented by the object.

$number = $dt->utc_week_year

Return the week-year number of the UTC date and time represented by the object.

$number = $dt->day_of_week

Return the day of week represented by the object, as a number. Sunday, Monday, ..., and Saturday are represented as 0, 1, ..., and 6, respectively.

$number = $dt->utc_day_of_week

Return the day of week of the UTC date represented by the object, as a number. Sunday, Monday, ..., and Saturday are represented as 0, 1, ..., and 6, respectively.

$string = $dt->second_fraction_string

Return the fraction part of the second component of the time represented by the object, including leading . character (decimal separator). If the fraction part is zero (the second component is an integer), the empty string is returned.

$number = $dt->fractional_second

Return the second component, including fractional part if any, as a number.

$number = $dt->utc_fractional_second

Return the second component of the UTC time represented by the object, including fractional part if any, as a number.

$tz = $dt->time_zone

Return the associated Web::DateTime::TimeZone object, if any, or undef.

$dt->set_time_zone ($tz)

Associate a Web::DateTime::TimeZone object to the object. Any existing time zone object is disassociated. If the argument is undef, no new time zone is associated with the object.

$number = $dt->to_unix_integer

Return a Unix time value (time_t integer) [POSIX.1] of the time represented by the object. The value can be positive or negative, and might not be a 32-bit integer. Any fraction part of seconds is discarded. Note that the Unix time_t value represents the time without associated time zone information. If the object has no associated time zone, it is considered as a UTC timestamp for the purpose of conversion.

$number = $dt->to_unix_number

Return a Unix time value of the time represented by the object, with fractional part of the second, if any. The value can be positive or negative, and might not be an integer. Note that the Unix time value represents the time without associated time zone information. If the object has no associated time zone, it is considered as a UTC timestamp for the purpose of conversion.

$number = $dt->to_html_number

Return the number of the date and time represented by the object, as used for, e.g., <input type=datetime> (i.e. number of milliseconds from the beginning of January 1, 1970 UTC) [HTML]. Note that the number might not be an integer.

$number = $dt->to_jd

Return the number representing the Julian Day of the date and time (i.e. Julian Date, JD, <https://en.wikipedia.org/wiki/Julian_day>) represented by the object. Note that the number might not be an integer.

$number = $dt->to_mjd

Return the Modified Julian Day (MJD, <https://en.wikipedia.org/wiki/Julian_day>) of the date and time represented by the object. Note that the number might not be an integer.

$number = $dt->to_rd

Return the Rata Die (RD, <https://en.wikipedia.org/wiki/Rata_Die>) of the date and time represented by the object. Note that the number might not be an integer.

$number = $dt->to_html_month_number

Return the number (an integer) of the month represented by the object, as used for <input type=month> (i.e. number of months from January 1970) [HTML].

$string = $dt->to_global_date_and_time_string

Serialize the date and time value represented by the object as an HTML valid global date and time string [HTML].

The serialized value always uses the UTC time zone. The time zone of the object is ignored (it does affect the value but the time zone itself does not appear in the serialization). If the object is not associated with any time zone, it is interpreted as UTC timestamp (which could be wrong, however).

Use to_time_zoned_global_date_and_time_string method to preserve time zone.

The value might not be a normalized date and time string.

The value is, in most cases, also a valid XML Schema xs:dateTime or xs:dateTimeStamp value, a valid RFC 3339 date-time value, a valid Atom 1.0 Date construct's content, a valid RSS 1.0 dc:date element content, and a valid http://schema.org/DateTime value.

This method is suitable for values for HTML <input type=datetime>, time elements, and <ins datetime=""> and <del datetime=""> attributes.

$string = $dt->to_normalized_forced_utc_global_date_and_time_string

Serialize the date and time value represented by the object as an HTML valid normalized forced-UTC global date and time string [HTML].

$string = $dt->to_time_zoned_global_date_and_time_string

Serialize the date and time value represented by the object as an HTML valid global date and time string [HTML].

If a time zone is associated with the object, it is used to serialize the time value. If the object is not associated with any time zone, it is interpreted as UTC timestamp (which could be wrong, however).

Use to_date_and_time_string method to always obtain a UTC timestamp.

This method is suitable for values for HTML <input type=datetime>, time elements, and <ins datetime=""> and <del datetime=""> attributes.

$string = $dt->to_generalized_time_string

Serialize the date and time value represented by the object as a PKIX GeneralizedTime string [PKIX]. Any fraction part of seconds is discarded.

This method is suitable for various timestamp fields in Certificates, CRLs, and OCSP objects, used with TLS.

$string = $dt->to_http_date_string

Serialize the date and time value represented by the object as an HTTP valid HTTP-date (rfc1123-date) string [HTTP]. Any fraction part of seconds is discarded.

This method is suitable for values for HTTP Last-Modified, Expires, and Date headers, as well as Expires attribute in HTTP Cookies.

$string = $dt->to_rss2_date_time_string

Serialize the date and time value represented by the object as a valid RSS 2.0 date and time string [RSS2] [RSS2BP]. Any fraction part of seconds is discarded.

$string = $dt->to_local_date_and_time_string

Serialize the date and time value represented by the object as an HTML valid local date and time string [HTML]. Note that time zone is ignored.

The value might not be a normalized local date and time string. It is, in most cases, also a valid XML Schema xs:dateTime value.

This method is suitable for values for HTML <input type=datetime-local> and time elements.

$string = $dt->to_normalized_local_date_and_time_string

Serialize the date and time value represented by the object as an HTML valid normalized local date and time string [HTML]. Note that time zone is ignored.

$string = $dt->to_document_last_modified_string

Serialize the date and time value represented by the object in the format of document.lastModified IDL attribute [HTML]. Any fraction part of seconds is discarded. The time zone of the object, if any, or UTC, is used to serialize the value, but the time zone offset is not included in this format.

$string = $dt->to_date_string

Serialize the date value represented by the object as an HTML valid date string [HTML]. Note that time and time zone are ignored.

This method is suitable for values for HTML <input type=date>, time elements, <ins datetime=""> and <del datetime=""> attributes, and microdata http://schema.org/Date item values.

$string = $dt->to_ymd_string

Serialize the date value represented by the object as a YMD string of the Gregorian calendar [DATETIME]. Note that time and time zone are ignored.

$string = $dt->to_julian_ymd_string

Serialize the date value represented by the object as a YMD string of the Julian calendar [DATETIME]. Note that time and time zone are ignored.

$string = $dt->to_date_string_with_optional_time

Serialize the date value represented by the object as HTML valid date string with optional time [HTML]. If the object represents a date, time, and time zone, it is serialized as a global date and time string. Otherwise, it is serialized as a date string.

This method is suitable for values for HTML <ins datetime=""> and <del datetime=""> attributes.

$string = $dt->to_year_string

Serialize the year value represented by the object for HTML. Note that month, day, time, and time zone are ignored.

This method is suitable for values for HTML time elements.

$string = $dt->to_manakai_year_string

Serialize the year value represented by the object as specified by the manakai Date and Time specification [DATETIME]. Note that month, day, time, and time zone are ignored.

$string = $dt->to_month_string

Serialize the month value represented by the object as an HTML valid month string [HTML]. Note that day, time, and time zone are ignored.

This method is suitable for values for HTML <input type=month> and time elements.

$string = $dt->to_yearless_date_string

Serialize the date value represented by the object as an HTML valid yearless date string [HTML]. Note that year, time, and time zone are ignored.

This method is suitable for values for HTML time elements.

$string = $dt->to_week_string

Serialize the week value represented by the object as an HTML valid week string [HTML]. Note that month, day, time, and time zone are ignored.

This method is suitable for values for HTML <input type=week> and time elements.

$string = $dt->to_time_string

Serialize the time value represented by the object as an HTML valid time string [HTML]. Note that date and time zone are ignored.

This method is suitable for values for HTML <input type=time>, time elements, and microdata http://schema.org/Time item values.

$string = $dt->to_shortest_time_string

Serialize the time value represented by the object as an HTML valid time string [HTML], using shortest possible form. Note that date and time zone are ignored.

$datetime = $dt->to_date_time

Return a new DateTime object which represents the time represented by the object. If the object has associated time zone, the returned object is in the equivalent time zone. Otherwise, the returned object is in the floating time zone. Note that Web date and time formats do not support leap seconds while DateTime does support them such that operations on Web date and time values and DateTime objects might obtain different results.

This method requires the DateTime module.

$timepiece = $dt->to_time_piece_gm

Return a new Time::Piece object which represents the time represented by the object, in UTC. If the object is not associated with any time zone, it is handled as if it were associated with UTC.

This method requires the Time::Piece module.

$timepiece = $dt->to_time_piece_local

Return a new Time::Piece object which represents the time represented by the object, in local time zone (i.e. Perl's localtime's time zone). If the object is not associated with any time zone, it is handled as if it were associated with UTC and then converted as appropriate.

This method requires the Time::Piece module.

DEPENDENCY

The module requires Perl 5.8 or later.

Methods to_date_time, to_time_piece_gm, and to_time_piece_local require more modules.

SPECIFICATIONS

HTML

HTML Standard <https://www.whatwg.org/specs/web-apps/current-work/>.

POSIX.1

POSIX.1-2008 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_15>.

HTTP

RFC 1945, Hypertext Transfer Protocol -- HTTP/1.0 <http://tools.ietf.org/html/rfc1945>.

RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content <https://tools.ietf.org/html/rfc7231>.

RSS2

RSS 2.0 Specification <http://www.rssboard.org/rss-specification>.

RSS2BP

Really Simple Syndication Best Practices Profile <http://www.rssboard.org/rss-profile>.

PKIX

RFC 5280, Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile <https://tools.ietf.org/html/rfc5280>.

DATETIME

Dates and times <https://manakai.github.io/spec-datetime/>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

ACKNOWLEDGEMENTS

This module contains a code derived from Time::Local, whose authors are:

  This module is based on a Perl 4 library, timelocal.pl, that was
  included with Perl 4.036, and was most likely written by Tom
  Christiansen.

  The current version was written by Graham Barr.

  It is now being maintained separately from the Perl core by Dave
  Rolsky, <autarch@urth.org>.

LICENSE

Copyright 2008-2023 Wakaba <wakaba@suikawiki.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program partially derived from Time::Local: "Copyright (c) 1997-2003 Graham Barr, 2003-2007 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself."