角色 Dateish

可视为日期的对象

role Dateish { ... }

Date 和 DateTime 都支持访问对象中表示的年、月和月中的天数，以及计算星期几等相关功能。

方法§

方法 年§

method year(Date:D: --> Int:D)

返回日期的年份。

say Date.new('2015-12-31').year;                                  # OUTPUT: «2015␤» 
say DateTime.new(date => Date.new('2015-12-24'), hour => 1).year; # OUTPUT: «2015␤»

方法 月§

method month(Date:D: --> Int:D)

返回日期的月份 (1..12)。

say Date.new('2015-12-31').month;                                  # OUTPUT: «12␤» 
say DateTime.new(date => Date.new('2015-12-24'), hour => 1).month; # OUTPUT: «12␤»

方法 日§

method day(Date:D: --> Int:D)

返回日期的月中天数 (1..31)。

say Date.new('2015-12-31').day;                                  # OUTPUT: «31␤» 
say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day; # OUTPUT: «24␤»

方法 格式化程序§

method formatter(Dateish:D:)

返回用于转换为 Str 的格式化函数。如果在对象构造时未提供任何函数，则使用默认格式化程序。在这种情况下，该方法将返回一个 Callable 类型对象。

格式化函数由 DateTime 方法 Str 调用，调用方作为其唯一参数。

my $dt = Date.new('2015-12-31');  # (no formatter specified) 
say $dt.formatter.^name;          # OUTPUT: «Callable␤» 
my $us-format = sub ($self) { sprintf "%02d/%02d/%04d", .month, .day, .year given $self; };
$dt = Date.new('2015-12-31', formatter => $us-format);
say $dt.formatter.^name;           # OUTPUT: «Sub␤» 
say $dt;                          # OUTPUT: «12/31/2015␤»

方法 是否闰年§

method is-leap-year(Dateish:D: --> Bool:D)

如果 Dateish 对象的年份是闰年，则返回 True。

say DateTime.new(:year<2016>).is-leap-year; # OUTPUT: «True␤» 
say Date.new("1900-01-01").is-leap-year;    # OUTPUT: «False␤»

方法 月中的天数§

method day-of-month(Date:D: --> Int:D)

返回日期的月中天数 (1..31)。与 day 方法同义。

say Date.new('2015-12-31').day-of-month;                                  # OUTPUT: «31␤» 
say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day-of-month; # OUTPUT: «24␤»

方法 星期几§

method day-of-week(Date:D: --> Int:D)

返回星期几，其中 1 是星期一，2 是星期二，星期日是 7。

say Date.new('2015-12-31').day-of-week;                                  # OUTPUT: «4␤» 
say DateTime.new(date => Date.new('2015-12-24'), hour => 1).day-of-week; # OUTPUT: «4␤»

方法 年中的天数§

method day-of-year(Date:D: --> Int:D)

返回一年中的天数 (1..366)。

say Date.new('2015-12-31').day-of-year;                                  # OUTPUT: «365␤» 
say DateTime.new(date => Date.new('2015-03-24'), hour => 1).day-of-year; # OUTPUT: «83␤»

方法 年中的天数§

method days-in-year(Dateish:D: --> Int:D)

返回 Dateish 对象表示的年份中的天数

say Date.new("2016-01-02").days-in-year;               # OUTPUT: «366␤» 
say DateTime.new(:year<2100>, :month<2>).days-in-year; # OUTPUT: «365␤»

在 Rakudo 编译器的 2022.12 版本中可用。

方法 月中的天数§

method days-in-month(Dateish:D: --> Int:D)

返回 Dateish 对象表示的月份中的天数

say Date.new("2016-01-02").days-in-month;                # OUTPUT: «31␤» 
say DateTime.new(:year<10000>, :month<2>).days-in-month; # OUTPUT: «29␤»

方法 week§

method week()

返回两个整数的列表：年份和周数。这是因为在一年开始或结束时，该周实际上可能属于另一年。

my ($year, $week) = Date.new("2014-12-31").week;
say $year;                       # OUTPUT: «2015␤» 
say $week;                       # OUTPUT: «1␤» 
say Date.new('2015-01-31').week; # OUTPUT: «(2015 5)␤»

方法 week-number§

method week-number(Date:D: --> Int:D)

返回调用者指定的日期的周数 (1..53)。第一周由 ISO 定义为包含 1 月 4 日的那一周。因此，1 月初的日期通常会出现在前一年的最后一周中，同样，12 月的最后几天可能会被放在下一年的第一周中。

say Date.new("2014-12-31").week-number;   # OUTPUT: «1␤»  (first week of 2015) 
say Date.new("2016-01-02").week-number;   # OUTPUT: «53␤» (last week of 2015)

方法 week-year§

method week-year(Date:D: --> Int:D)

返回调用者指定的日期的周年份。通常情况下，week-year 等于 Date.year。但是请注意，1 月初的日期通常会出现在前一年的最后一周中，同样，12 月的最后几天可能会被放在下一年的第一周中。

say Date.new("2015-11-15").week-year;   # OUTPUT: «2015␤» 
say Date.new("2014-12-31").week-year;   # OUTPUT: «2015␤» (date belongs to the first week of 2015) 
say Date.new("2016-01-02").week-year;   # OUTPUT: «2015␤» (date belongs to the last week of 2015)

方法 weekday-of-month§

method weekday-of-month(Date:D: --> Int:D)

返回一个数字 (1..5)，表示在该月中到目前为止特定星期几出现的次数，包括该天本身。

say Date.new("2003-06-09").weekday-of-month;  # OUTPUT: «2␤»  (second Monday of the month)

方法 yyyy-mm-dd§

method yyyy-mm-dd(str $sep = "-" --> Str:D)

以 YYYY-MM-DD 格式返回日期 (ISO 8601)。可选的位置参数 $sep（默认为 -）是一个单字符分隔符，放置在日期的不同部分之间。

say Date.new("2015-11-15").yyyy-mm-dd;   # OUTPUT: «2015-11-15␤» 
say DateTime.new(1470853583).yyyy-mm-dd; # OUTPUT: «2016-08-10␤» 
say Date.today.yyyy-mm-dd("/");          # OUTPUT: «2020/03/14␤» 

方法 mm-dd-yyyy§

method mm-dd-yyyy(str $sep = "-" --> Str:D)

以 MM-DD-YYYY 格式返回日期 (ISO 8601)。可选的位置参数 $sep（默认为 -）是一个单字符分隔符，放置在日期的不同部分之间。

say Date.new("2015-11-15").mm-dd-yyyy;   # OUTPUT: «11-15-2015␤» 
say DateTime.new(1470853583).mm-dd-yyyy; # OUTPUT: «08-10-2016␤» 
say Date.today.mm-dd-yyyy("/");          # OUTPUT: «03/14/2020␤» 

方法 dd-mm-yyyy§

method dd-mm-yyyy(str $sep = "-" --> Str:D)

以 DD-MM-YYYY 格式返回日期 (ISO 8601)。可选的位置参数 $sep（默认为 -）是一个单字符分隔符，放置在日期的不同部分之间。

say Date.new("2015-11-15").dd-mm-yyyy;    # OUTPUT: «15-11-2015␤» 
say DateTime.new(1470853583).dd-mm-yyyy;  # OUTPUT: «10-08-2016␤» 
say Date.today.dd-mm-yyyy("/");           # OUTPUT: «14/03/2020␤» 

方法 daycount§

method daycount(Dateish:D: --> Int:D)

返回从 1858 年 11 月 17 日到调用者日期的天数。此方法返回的 daycount 是 修正儒略日 (MJD) 的整数部分，天文学家、大地测量学家、科学家和其他人员经常使用它。MJD 公约旨在简化年代计算。MJD 的小数部分由使用 DateTime 对象的小时、分钟和秒转换为 24 小时的等效分数组成。添加的这两个值定义了该时刻的 MJD。

say Date.new('1995-09-27').daycount;    # OUTPUT: «49987␤»

方法 IO§

method IO(Dateish:D: --> IO::Path:D)

返回一个IO::Path对象，表示Dateish对象的字符串化值

Date.today.IO.say;   # OUTPUT: «"2016-10-03".IO␤» 
DateTime.now.IO.say; # OUTPUT: «"2016-10-03T11:14:47.977994-04:00".IO␤»

可移植性注意：一些操作系统（例如 Windows）不允许文件名中出现冒号（:），而从DateTime对象创建的IO::Path中会出现冒号。

方法 earlier§

multi method earlier(Dateish:D: *%unit)
multi method earlier(Dateish:D: @pairs)

返回一个基于当前对象的对象，但应用了指向过去的日期增量。除非给定的单位是second或seconds，否则给定的值将被转换为Int。有关用法，请参见.later。它通常将通过实现此角色的类（Date或DateTime）使用

my $d = Date.new('2015-02-27');
say $d.earlier(month => 5).earlier(:2days);  # OUTPUT: «2014-09-25␤» 
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␤»

允许负偏移，尽管later更符合惯例。

如果您需要使用多个单位，则需要将它们构建到List的Pair中，以使用该方法的第二种形式

say Date.new('2021-03-31').earlier(  ( year => 3, month => 2, day => 8 ) ); # OUTPUT: «2018-01-23␤» 

此功能在 Rakudo 编译器的 2021.02 版本中引入。

方法 later§

multi method later(DateTime:D: *%unit)

返回一个基于当前对象（属于混合此角色的任何类）的对象，但应用了时间增量。时间增量可以作为命名参数传递，其中参数名称是单位。

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

允许的单位有second、seconds、minute、minutes、hour、hours、day、days、week、weeks、month、months、year、years。请注意，复数形式只能与later和earlier方法一起使用。

冒号对的:2nd形式可以用作指定增量的一种紧凑且自文档化的方式

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

您还可以（自 Rakudo 编译器的 2021.02 版本以来）同时传递多个单位，但您必须将它们加入到List中以激活第二种形式

say DateTime.new(date => Date.new('2015-02-27')).later( (:1month, :2days) )
# OUTPUT: «2015-03-29T00:00:00Z␤» 

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

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

允许负偏移，尽管earlier更符合惯例。

Date类型的对象将以相同的方式表现

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

类型图§

Dateish的类型关系
raku-type-graph Dateish Dateish Mu Mu Any Any Any->Mu Date Date Date->Dateish Date->Any DateTime DateTime DateTime->Dateish DateTime->Any

展开上面的图表