DateTime

Calendar date with time

   |  4   |  831   |  焉知非鱼

DateTime

class DateTime does Dateish {}

对于在国内处理点数，DateTime 对象存储年，月，日，小时，分钟（全部为 Int），秒（可能为小数）和时区。

它提供了用日期和时间计算的方法。

DateTime 方法是不可变的;如果你试图修改它，请改为创建修改后的副本。

时区的处理时间为以 UTC 为单位的整数，而不是时区名称。

use v6.c;
my $dt = DateTime.new(
    year    => 2015,
    month   => 11,
    day     => 21,
    hour    => 16,
    minute  => 1,
);

say $dt;                            # OUTPUT: «2015-11-21T16:01:00Z␤»
say $dt.later(days => 20);          # OUTPUT: «2015-12-11T16:01:00Z␤»
say $dt.truncated-to('hour');       # OUTPUT: «2015-11-21T16:00:00Z␤»
say $dt.in-timezone(-8 * 3600);     # OUTPUT: «2015-11-21T08:01:00-0800␤»

my $now = DateTime.now(formatter => { sprintf "%02d:%02d", .hour, .minute });
say $now;

方法

new 方法

定义为:

multi method new(Int :$year!, Int :$month = 1, Int :$day = 1,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Date :$date!,
                 Int :$hour = 0, Int :$minute = 0, :$second = 0,
                 Int :$timezone = 0, :&formatter)
multi method new(Int() $year, Int() $month, Int() $day,
                 Int() $hour, Int $minute, $second,
                 Int() :$timezone = 0, :&formatter)
multi method new(Instant:D $i,  :$timezone=0, :&formatter)
multi method new(Int:D $posix,  :$timezone=0, :&formatter)
multi method new(Str:D $format, :$timezone=0, :&formatter)

创建一个新的 DateTime 对象。另外一个​​选项是分别从组件（年，月，日，小时…）创建新的 DateTime 对象。另一种方法是为 date 组件传递一个 Date 对象，并以 component-wise 方式指定时间。另一种方法是从 Instant 获取时间，并仅提供时区和 formatter。或者，您可以提供 Int 作为 UNIX 时间戳，而不是 Instant。

您还可以提供格式为 ISO 8601 时间戳记符号或完整 RFC 3339 日期和时间的 Str。字符串格式应为 yyyy-mm-ddThh:mm:ssZ 或 yyyy-mm-ddThh:mm:ss+0100。由于我们允许使用 Unicode 数字和混合浓缩和扩展时间格式，因此我们的限制性比 ISO 8601 标准少一些。

无效的输入字符串将引发 X::Temporal::InvalidFormat 类型的异常。如果您提供的字符串包含时区并提供 timezone 具名参数，则会引发 X::DateTime::TimezoneClash 类型的异常。

my $datetime = DateTime.new(year => 2015,
                            month => 1,
                            day => 1,
                            hour => 1,
                            minute => 1,
                            second => 1,
                            timezone => 1);
$datetime = DateTime.new(date => Date.new('2015-12-24'),
                         hour => 1,
                         minute => 1,
                         second => 1,
                         timezone => 1);
$datetime = DateTime.new(2015, 1, 1, # First January of 2015
                         1, 1, 1);   # Hour, minute, second with default timezone
$datetime = DateTime.new(now);                       # Instant.
# from a Unix timestamp
say $datetime = DateTime.new(1470853583);            # OUTPUT: «2016-08-10T18:26:23Z␤»
$datetime = DateTime.new("2015-01-01T03:17:30+0500") # Formatted string

now 方法

定义为：

method now(:$timezone = $*TZ, :&formatter --> DateTime:D)

从当前系统时间创建一个新的 DateTime 对象。可以提供自定义 formatter 和 timezone。 :$timezone 是 GMT 的偏移量（以秒为单位），默认为 $*TZ 变量的值。

say DateTime.now; # OUTPUT: «2018-01-08T13:05:32.703292-06:00␤»

请注意，可以使用链接到 .now 的以下方法轻松表示当前值，例如，

say DateTime.now.year; # OUTPUT: «2018␤»

clone 方法

定义为：

method clone(:$year, :$month, :$day, :$hour, :$minute, :$second, :$timezone, :&formatter)

根据 invocant 创建一个新的 DateTime 对象，但给定的参数会覆盖 invocant 中的值。

say DateTime.new('2015-12-24T12:23:00Z').clone(hour => 0);
# OUTPUT: «2015-12-24T00:23:00Z␤»

请注意，在某些情况下，这可能会导致日期无效：

say DateTime.new("2012-02-29T12:34:56Z").clone(year => 2015);
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::OutOfRange: Day out of range. Is: 29, should be in 1..28␤»

hh-mm-ss 方法

定义为：

method hh-mm-ss(DateTime:D: --> Str:D)

以 24 小时 HH:MM:SS 格式返回对象以字符串形式表示的时间：

say DateTime.new("2052-02-29T22:34:56Z").hh-mm-ss;
# OUTPUT: «22:34:56␤»

hour 方法

定义为：

method hour(DateTime:D: --> Int:D)

返回小时组件。

say DateTime.new('2012-02-29T12:34:56Z').hour;      # OUTPUT: «12␤»

minute 方法

定义为：

method minute(DateTime:D: --> Int:D)

返回分钟组件。

say DateTime.new('2012-02-29T12:34:56Z').minute;     # OUTPUT: «34␤»

second 方法

定义为：

method second(DateTime:D:)

返回秒组件，可能包括小数秒。

say DateTime.new('2012-02-29T12:34:56Z').second;     # OUTPUT: «56␤»
say DateTime.new('2012-02-29T12:34:56.789Z').second; # OUTPUT: «56.789␤»
say DateTime.new('2012-02-29T12:34:56,789Z').second; # comma also ok

whole-second

定义为：

method whole-second(DateTime:D:)

返回秒组件，向下舍入为 Int。

say DateTime.new('2012-02-29T12:34:56.789Z').whole-second;      # OUTPUT: «56␤»

timezone 方法

定义为：

method timezone(DateTime:D: --> Int:D)

以秒为单位 返回时区，作为与 UTC 的偏移量。

say DateTime.new('2015-12-24T12:23:00+0200').timezone;          # OUTPUT: «7200␤»

offset 方法

定义为：

method offset(DateTime:D: --> Int:D)

以秒为单位 返回时区，作为与UTC的偏移量。这是方法时区的别名。

say DateTime.new('2015-12-24T12:23:00+0200').offset;            # OUTPUT: «7200␤»

offset-in-minutes 方法

定义为：

method offset-in-minutes(DateTime:D: --> Real:D)

以 UTC 为单位返回以小时为单位的时区。

say DateTime.new('2015-12-24T12:23:00+0200').offset-in-hours;   # OUTPUT: «2␤»

Str 方法

定义为：

method Str(DateTime:D: --> Str:D)

返回调用者的字符串表示形式，由格式化程序完成。如果未指定格式化程序，则会返回ISO 8601时间戳。

say DateTime.new('2015-12-24T12:23:00+0200').Str; # OUTPUT: «2015-12-24T12:23:00+02:00␤»

Instant 方法

定义为：

method Instant(DateTime:D: --> Instant:D)

基于调用者返回一个Instant对象。

say DateTime.new('2015-12-24T12:23:00+0200').Instant; # OUTPUT: «2015-12-24T12:23:00+02:00␤»

posix 方法

定义为：

method posix(DateTime:D: $ignore-timezone = False --> Int:D)

将日期和时间作为POSIX / UNIX时间戳（自Epoch，1970年1月1日UTC以来的秒数）返回。

say DateTime.new('2015-12-24T12:23:00Z').posix;       # OUTPUT: «1450959780␤»

later 方法

定义为：

method later(DateTime:D: *%unit)

返回基于当前日期对象的DateTime对象，但应用了时间增量。时间增量可以作为参数名称为单位的命名参数传递。

除非给定的单位是秒或秒，否则给定的值将被转换为Int。

允许的单位是秒，秒，分，分，小时，小时，日，星期，星期，月，月，年，年。请注意，复数形式只能用于较晚和较早的方法。

第二种形式的结构可以用作指定三角洲的紧凑和自我记录方式：

say DateTime.new('2015-12-24T12:23:00Z').later(:2years); # OUTPUT: «2017-12-24T12:23:00Z␤»

由于添加几个不同的时间单位不可交换，所以只能传递一个单位。

my $d = DateTime.new(date => Date.new('2015-02-27'));
say $d.later(month => 1).later(:2days);  # OUTPUT: «2015-03-29T00:00:00Z␤»
say $d.later(days => 2).later(:1month);  # OUTPUT: «2015-04-01T00:00:00Z␤»
say $d.later(days => 2).later(:month);   # same, as +True === 1

如果结果时间的值为60秒，但实际上当前没有闰秒，则秒数将设置为59：

say DateTime.new('2008-12-31T23:59:60Z').later: :1day;
# OUTPUT: «2009-01-01T23:59:59Z␤»

负偏移是允许的，虽然早些时候更习惯于此。

earlier 方法

定义为：

method earlier(DateTime:D: *%unit)

返回基于当前日期对象的日期时间对象，但是应用了过去的时间差值。除非给定的单位是秒或秒，否则给定的值将被转换为Int。请参阅后面的使用方法。

my $d = DateTime.new(date => Date.new('2015-02-27'));
say $d.earlier(month => 1).earlier(:2days);  # OUTPUT: «2015-01-25T00:00:00Z␤»

如果结果时间的值为60秒，但实际上当前没有闰秒，则秒数将设置为59：

say DateTime.new('2008-12-31T23:59:60Z').earlier: :1day;
# OUTPUT: «2008-12-30T23:59:59Z␤»

负偏移是允许的，尽管后来更加习惯于此。

truncated-to 方法

定义为：

method truncated-to(DateTime:D: Cool $unit)

返回调用者的副本，将小于指定单位的所有内容截断为尽可能最小的值。

my $d = DateTime.new("2012-02-29T12:34:56.946314Z");
say $d.truncated-to('second');      # OUTPUT: «2012-02-29T12:34:56Z␤»
say $d.truncated-to('minute');      # OUTPUT: «2012-02-29T12:34:00Z␤»
say $d.truncated-to('hour');        # OUTPUT: «2012-02-29T12:00:00Z␤»
say $d.truncated-to('day');         # OUTPUT: «2012-02-29T00:00:00Z␤»
say $d.truncated-to('month');       # OUTPUT: «2012-02-01T00:00:00Z␤»
say $d.truncated-to('year');        # OUTPUT: «2012-01-01T00:00:00Z␤»

使用.truncated-to（‘second’）可以将小数秒的日期时间截断为整秒。

Date 方法

定义为：

multi method Date(DateTime:U --> Date:U)
multi method Date(DateTime:D --> Date:D)

将调用者转换为 Date

say DateTime.new("2012-02-29T12:34:56.946314Z").Date; # OUTPUT: «2012-02-29␤»
say DateTime.Date;                                    # OUTPUT: «(Date)␤»

DateTime 方法

定义为：

method DateTime(--> DateTime)

返回调用者。

say DateTime.new("2012-02-29T12:34:56.946314Z").DateTime; # 2012-02-29T12:34:56.946314Z
say DateTime.DateTime;                                    # OUTPUT: «(DateTime)␤»

utc 方法

定义为：

method utc(DateTime:D: --> DateTime:D)

同时返回一个 DateTime 对象，但是在 UTC 时区。

say DateTime.new('2015-12-24T12:23:00+0200').utc;  # OUTPUT: «2015-12-24T10:23:00Z␤»

in-timezone 方法

定义为：

method in-timezone(DateTime:D: $timezone = 0 --> DateTime:D)

同一时间返回一个DateTime对象，但在指定的$ timezone中，这是距离GMT的偏移量（以秒为单位）。

say DateTime.new('2015-12-24T12:23:00Z').in-timezone(3600 + 1800); # OUTPUT: «2015-12-24T13:53:00+0130␤»

local 方法

定义为：

method local(DateTime:D: --> DateTime:D)

同时返回DateTime对象，但在本地时区（$ * TZ）中。

my $*TZ = -3600;
say DateTime.new('2015-12-24T12:23:00+0200').local; # OUTPUT: «2015-12-24T09:23:00-0100␤»

infix:<->

定义为：

multi sub infix:<-> (DateTime:D, Duration:D --> DateTime:D)
multi sub infix:<-> (DateTime:D, DateTime:D --> Duration:D)

将DateTime从持续时间或另一个DateTime对象中减去。分别返回一个新的DateTime对象或两个日期之间的持续时间。当减去持续时间时，原始DateTime的时区保留在返回的DateTime对象中。

say perl DateTime.new(:2016year) - DateTime.new(:2015year):;           # OUTPUT: «Duration.new(31536001.0)␤»
say DateTime.new(:2016year, :3600timezone) - Duration.new(31536001.0); # OUTPUT: «2015-01-01T00:00:00+01:00␤»

infix:<+> 方法

定义为：

multi sub infix:<+> (DateTime:D, Duration:D --> DateTime:D)
multi sub infix:<+> (Duration:D, DateTime:D --> DateTime:D)

采用日期时间并按给定持续时间增加它，以保留时区。

say DateTime.new(:2015year) + Duration.new(31536001.0);        # OUTPUT: «2016-01-01T00:00:00Z␤»
say Duration.new(42) + DateTime.new(:2015year, :3600timezone); # OUTPUT: «2015-01-01T00:00:42+01:00␤»
DateTime 
comments powered by Disqus