title: Phi::DateTime
author: KUMAGAI Hidetake
author: YOSHIDA Kazuhiro
mailto: moriq@moriq.com

1. Phi::DateTime

Apollo(Delphi) で使用する標準的な日付＋時間のクラス。

Delphi の TDateTime 型は単純に Double 型のデータであり、メソッドを持たず、「日付時刻ルーチン」を介してシステムが管理するようになっています。それに対して Apollo の DateTime はクラスになっています。Delphiの「日付時刻ルーチン」は Apollo ではメソッドとして実装されます。

1.1. super class

Object#

1.1. included modules

Comparable#

1.1. class methods

: new
: now
  : 引数がない場合
    現在時刻となります。

  : 引数がひとつの場合
    文字列の場合には "yyyy/mm/dd hh:mm:ss" の形式を指定できます。ミリ秒は指定できません。"hh" 以降は省略可能で、省略した場合には０とみなされます。
    Time# Date# オブジェクトを指定した場合には相当の時刻に変換して作成します。 Date# の時刻は 00:00:00 になります。

  : 引数が2個以上の場合
    yyyy,mm,dd, hh,MM,ss,zz の順になります。hh 以降は省略可能です。ミリ秒も指定できます。

: today

  今日の日付を返します。DateTime.now.date と同じです。

1.1. methods

: year : Fixnum
: year=
  年の部分。出し入れ可能。

: month : Fixnum
: month=
  月の部分。出し入れ可能。

: day : Fixnum
: day=
  日の部分。出し入れ可能。

: hour : Fixnum
: hour=
  時の部分。出し入れ可能。

: minute : Fixnum
: minute=
  分の部分。出し入れ可能。

: second : Fixnum
: second=
  秒の部分。出し入れ可能。

: msec : Fixnum
: msec=
  ミリ秒の部分。出し入れ可能。

: +
  日付を１日増加させた DateTime を返す。
  小数点部分がある場合には、1.0/(24*60*60*1000) で１ミリ秒を表す。

: -
  日付を１日減少させた DateTime を返す。
  小数点部分がある場合には、1.0/(24*60*60*1000) で１ミリ秒を表す。

: <
: <=
: <=>
: >
: >=
: ==
  時刻を比較する。
  右側が String, Time, Date の場合には DateTime に変換して比較する。
  : 注意
    DateTime に変換するのは DateTime が左側にある場合だけです。右側にある場合には変換しません。
    左側が String で右側が DateTime の場合には文字列として比較されてしまい、結果として誤った結果になります。

: ===
: =~

  検討中。使わないでください。（「所属する」という意味なので DateTime.new("2001/2/3") === 2001）とかDateTime.new("2001/2/3") === [2001,2]）とかを判断すべきか？）。

: between?

  時刻が指定された範囲にあるかを調べる。
  文字列等も使用可能。

: date

  日付部分で構成される DateTime インスタンスを返す。

: day_of_week

  曜日を数字で返す。1:日曜日〜7:土曜日。

: end_of_month

  その日付が含む月末の 23:59:59.999 の DateTime を返す。

: end_of_year

  その日付が含む年末の 23:59:59.999 の DateTime を返す。

: format

  書式にしたがって文字列にします。

: inc_month

  月の部分を増減した DateTime を返します。
  日付が月末を越えた場合には月末の日付になります。DateTime.new("2001/1/31").inc_month(1) => "2001/2/28"。

: jd

  ユリウス日を返します。ユリウス日というのは天文学で使われる日付で、ｘｘの正午を0.0 とした通算日数です。小数点部分に時刻を含います。Date クラスからの変換で使用しています。

: time

  時刻部分の DateTime を返します。
  日付部分が０の DateTime は xx の日付の意味にもなるので、注意してください。

: time_t

  Unix の time_t 相当の値を返します。Time クラスからの変換で使用しています。

: to_a

  [y,m,d,h,M,s,z] という配列を返します。

: to_s

  Phi.date_format グローバル変数で指定された形式の日付の後に，Phi.time_format グローバル変数で指定された形式の時刻が続く。DateTime 値の小数部分がゼロの場合，時刻は表示されない。
  デフォルトでは "yyyy/mm/dd hh:mm:ss" の書式で変換します。
  注意：DateTime.now にはミリ秒部分を含んでいるので、デフォルトで文字列にした後に DateTime に戻して比較するとイコールになりません。format("yyyy/mm/dd hh:mm:ss.zzz")で文字列に変換すれば正確です。

1.1. functions

: Phi.date_separator
: Phi.date_separator=

: Phi.time_separator
: Phi.time_separator=

  文字列を DateTime に変換するときの日付区切り（"/"）、時刻区切り（":"）です。

: Phi.date_format
: Phi.date_format=

: Phi.time_format
: Phi.time_format=

  DateTime を文字列に変換するとき（to_s）のデフォルトの書式です。
  デフォルトの内容は次の通り。
--ruby
date_format = "yyyy/mm/dd"
time_format = "hh:mm:dd"
--
: Phi.short_date_format
: Phi.short_date_format=

: Phi.short_time_format
: Phi.short_time_format=

: Phi.long_date_format
: Phi.long_date_format=

: Phi.long_time_format
: Phi.long_time_format=

1.1. constants

: Phi::LOCAL_TIME_DIFF

  ローカルタイムと世界標準時との差を %c:Float% で返します。 DateTime#now はローカルタイム（日本標準時）を返しますので，世界標準時を求めるにはローカルタイムから %c:LOCAL_TIME_DIFF% を差し引けば ok 。
--ruby
require "phi" ; include Phi
local  = DateTime.now
global = local - LOCAL_TIME_DIFF
p Phi::LOCAL_TIME_DIFF  ##  0.375
p local                 ##  #<Phi::DateTime: 2001/04/22 01:05:36>
p global                ##  #<Phi::DateTime: 2001/04/21 16:05:36>
--

1.1. format

  : 指定子
    表示内容

  : aaa
    曜日を日本語の省略形（日〜土）で表示する
  : aaaa
    曜日を日本語（日曜日〜土曜日）で表示する

  : c
    Phi.date_format グローバル変数で指定された形式の日付の後に，Phi.time_format グローバル変数で指定された形式の時刻が続く。DateTime 値の小数部分がゼロの場合，時刻は表示されない
    * Phi.date_format == Phi.short_date_format , Phi.time_format == Phi.long_time_format
    となっています。
  : d
    日付を先頭のゼロなしで表示する（1 から 31 まで）
  : dd
    日付を先頭のゼロも含めて表示する（01 から 31 まで）

  : ddd
    ShortDayNames グローバル変数で指定された文字列を使って，曜日を省略形（日〜土）で表示する
  : dddd
    LongDayNames グローバル変数で与えられた文字列を使って，曜日を完全形（日曜日〜土曜日）で表示する
  : ddddd
    Phi.short_date_format グローバル変数で与えられた形式で日付を表示する
  : dddddd
    Phi.long_date_format グローバル変数で与えられた形式で日付を表示する

  : e
    元号に基づく和暦の年を 0 を付けずに表示する（1995 年ならば 7）
  : ee
    元号に基づく和暦の年を 2 桁で表示する（1995 年ならば 07）
  : g
    元号の先頭 1 文字を表示する（明，大，昭，平）。2.0 では，英字で表現された先頭 1 文字でしたが，このバージョンで変更されています。
  : gg
    元号を表示する（明治，大正，昭和，平成）。2.0 では，元号の先頭 1 文字を表しましたが，このバージョンで変更されています。
  : ggg
    元号を表示する（明治，大正，昭和，平成）

  : m
    先頭にゼロのない数字（1〜12）として月を表示する。h 指定子または hh 指定子の直後に m 指定子を指定すると，月ではなく分が表示される
  : mm
    先頭にゼロのある数字（01〜12）として月を表示する。h 指定子または hh 指定子の直後に mm 指定子を指定すると，月ではなく分が表示される

  : mmm
    ShortMonthNames グローバル変数で与えられた文字列を使って，月を省略形（1〜12）で表示する
  : mmmm
    LongMonthNames グローバル変数で与えられた文字列を使って，月を完全形（1月〜12月）で表示する

  : yy
    年を 2 桁の数字（00〜99）で表示する
  : yyyy
    年を 4 桁の数字（0000〜9999）で表示する

  : h
    先頭にゼロのない数字（0〜23）として時を表示する
  : hh
    先頭にゼロのある数字（00〜23）として時を表示する

  : n
    先頭にゼロのない数字（0〜59）として分を表示する
  : nn
    先頭にゼロのある数字（00〜59）として分を表示する

  : s
    先頭にゼロのない数字（0〜59）として秒を表示する
  : ss
    先頭にゼロのある数字（00〜59）として秒を表示する

  : zzz
    先頭にゼロのある数字（000-999）としてミリ秒を表示する

  : t
    Phi.short_time_format グローバル変数で与えられた形式で時刻を表示する
  : tt
    Phi.long_time_format グローバル変数で与えられた形式で時刻を表示する

  : am/pm
    先行する h 指定子または hh 指定子に 12 時間形式の時刻値を使い，正午以前の時間には am を，正午以降の時間には pm を表示する。am/pm 指定子には，大文字，小文字，大文字と小文字の両方が使え，指定のとおりに結果が表示される
  : a/p
    先行する h 指定子または hh 指定子に 12 時間形式の時刻値を使い，正午以前の時間には a を，正午以降の時間には p を表示する。a/p 指定子には，大文字，小文字，大文字と小文字の両方が使え，指定のとおりに結果が表示される
  : ampm
    先行する h 指定子または hh 指定子に 12 時間形式の時刻値を使い，正午以前の時間には TimeAMString グローバル変数の値を，正午以降の時間には TimePMString グローバル変数の値を表示する

  : /
    Phi.date_separator グローバル変数で与えられた日付区切り文字を表示する
  : :
    Phi.time_separator グローバル変数で与えられた時刻区切り文字を表示する

  : 'xx' / "xx"
    単引用符または二重引用符で囲まれた文字はそのまま表示され，形式には影響を与えない

  形式指定子には大文字でも小文字でも使えます。どちらを使っても同じ結果になります。

  以下のものは使わない方が無難です。
  Delphi のヘルプの「zz」記述に誤りがある模様。２桁になるので、"ss.zz"とすると誤った値になる。

  : z
    先頭にゼロのない数字（0-999）としてミリ秒を表示する
  : zz
    先頭にゼロのある数字（000-999）としてミリ秒を表示する

1.1. Delphi(ver.6.0) の「日付時刻ルーチン」との対応関係
--text
  【実装済み】           ☆＝今回足したもの [ap-dev:0488]

CompareDateTime 関数        DateTime#<==>
Date 関数                   DateTime::today
DateOf 関数                 DateTime#date
DateTimeToStr 関数          DateTime#to_s
DateTimeToString 手続き     DateTime#format
DayOf 関数                  DateTime#day
DayOfTheMonth 関数          DateTime#day
DayOfTheYear 関数        ☆ DateTime#day_of_year。
DayOfTheYear 関数        ☆ DateTime#yday
DayOfTheWeek 関数        ☆ DateTime#cwday。ISO 8601「月曜日が 1 で，日曜日が 7」
DayOfWeek 関数           ☆ DateTime#wday。         「日曜日が 0 で，土曜日が 6」
DayOfWeek 関数              DateTime#day_of_week。  「日曜日が 1 で，土曜日が 7」
DecodeDate 手続き           DateTime#to_a
DecodeDateTime 手続き       DateTime#to_a
EncodeDate 関数;            DateTime::new(y,m,d,h,n,s,z)
TryEncodeDate 関数
EncodeDateTime 関数
EncodeTime 関数;
TryEncodeTime 関数
EndOfTheDay 関数         ☆ DateTime#end_of_day
EndOfTheMonth 関数          DateTime#end_of_month
EndOfTheYear 関数           DateTime#end_of_year
FormatDateTime 関数         DateTime#format
HourOf 関数                 DateTime#hour
HourOfTheDay 関数
IncMilliSecond 関数      ☆ DateTime#inc_msec
IncSecond 関数           ☆ DateTime#inc_sec
IncMinute 関数           ☆ DateTime#inc_minute
IncHour 関数             ☆ DateTime#inc_hour。
IncDay 関数              ☆ DateTime#inc_day。  →DateTime#+。
IncWeek 関数             ☆ DateTime#inc_week
IncMonth 関数               DateTime#inc_month
IncYear 関数             ☆ DateTime#inc_year
IsInLeapYear 関数        ☆ DateTime#leap?
IsPM 関数                ☆ DateTime#pm?
MilliSecondOf 関数          DateTime#msec
MilliSecondOfTheSecond 関数
MinuteOf 関数               DateTime#minute
MinuteOfTheHour 関数
MonthOf 関数                DateTime#month
MonthOfTheYear 関数
Now 関数                    DateTime::now
RecodeDay 関数              DateTime#day=
RecodeHour 関数             DateTime#hour=
RecodeMilliSecond 関数      DateTime#msec=
RecodeMinute 関数           DateTime#minute=
RecodeMonth 関数            DateTime#month=
RecodeSecond 関数           DateTime#sec=
RecodeYear 関数             DateTime#year=
SecondOf 関数               DateTime#sec
SecondOfTheMinute 関数  
StartOfTheDay 関数       ☆ DateTime#start_of_day
StartOfTheMonth 関数     ☆ DateTime#start_of_month
StartOfTheYear 関数      ☆ DateTime#start_of_year
StartOfTheWeek 関数         未実装（iso）
StrToDate 関数              DateTime.new( str )。StrToDate 関数は，文字列を TDateTime 値に変換します。
StrToDateTime 関数
StrToTime 関数          
Time 関数                   DateTime::now。Time 関数は現在の時刻を返します。
TimeOf 関数                 DateTime#time。TimeOf 関数は，TDateTime 値から日付部分を削除します。
YearOf 関数                 DateTime#year。YearOf 関数は，TDateTime 値で表された年を返します。

  【簡単に実現できるもの】
CurrentYear 関数            → DateTime.now.year
DateToStr 関数              → dt.date.to_s
DaysInAMonth 関数           → DateTime.new(year,month).end_of_month.day。
DaysInAYear 関数            → DateTime.new(year).end_of_year.yday。
DaysInMonth 関数            → dt.end_of_month.day。
DaysInYear 関数             → dt.end_of_year.yday。
DecodeTime 手続き           → dt.to_a[3,3]
EndOfADay 関数              → DateTime.new.end_of_day
EndOfAMonth 関数            → DateTime.new(year,month).end_of_month
EndOfAYear 関数             → DateTime.new(year).end_of_year
HourOfTheMonth 関数         → dt.sec_of_month/3600
HourOfTheWeek 関数          → dt.sec_of_week/3600
HourOfTheYear 関数          → dt.sec_of_year/3600
IncAMonth 手続き            → DateTime.new(year,month,day).inc_month。
IsLeapYear 関数             → DateTime.new(year).leap?
RecodeDate 関数             → dt.date = DateTime.new(year,month,day)
RecodeTime 関数             → dt.time = DateTime.time(hour,minuts,second) ??
ReplaceDate 手続き          → dt.date = dt2
ReplaceTime 手続き          → dt.time = dt2
StartOfADay 関数            → DateTime.new(y,m,d).start_of_xx
StartOfAMonth 関数      
StartOfAYear 関数       
TimeToStr 関数              → dt.time.to_s。TimeToStr 関数は，TDateTime 値を表す文字列を返します。

  【TDateTime以外の時刻型に関連するもの】・・基本的に実装しない

CheckSqlTimeStamp 手続き    未実装
DateDelta 定数              未実装。TDateTime 値と TTimeStamp 値の差を示します。
DateTimeToFileDate 関数     未実装。ApolloではFileDate型は隠蔽される。
DateTimeToSQLTimeStamp 手続き  未実装。ApolloではTSQLTimeStamp 型は隠蔽される。Year は 1 〜 9999 までの年で1/1000単位で時間を管理するが、DateTime 型も同等以上の範囲の日付を扱える（加算では紀元後６５０００年まで可能だが、DateTime.new "10000/1/1" ははねられる）。
DateTimeToTimeStamp 関数
MSecsToTimeStamp 関数
NullSQLTimeStamp 定数  「NullSQLTimeStamp 定数は，NULL TSQLTimeStamp 値を表します。
SQLDayOfWeek 関数       SQLDayOfWeek 関数は，指定された TSQLTimeStamp 値の曜日を示します。
SQLTimeStampToDateTime 関数  SQLTimeStampToDateTime 関数は，TSQLTimeStamp 値を TDateTime 値に変換します。
SQLTimeStampToStr 関数  SQLTimeStampToStr 関数は，TSQLTimeStamp 値を文字列に変換します。
StrToSQLTimeStamp 関数  StrToSQLTimeStamp 関数は，文字列を TSQLTimeStamp 値に変換します。
TimeStampToDateTime 関数  TimeStampToDateTime 関数は，TTimeStamp 値を対応する TDateTime 値に変換します。
TimeStampToMSecs 関数   TimeStampToMSecs 関数は，TTimeStamp 値をミリ秒数の合計に変換します。

  【ISO 8601 規格のため実装しないもの】

EndOfTheWeek 関数           未実装（iso）：DateTime#end_of_the_week
EndOfAWeek 関数             未実装（iso）：DateTime#end_of_week .. iso type
StartOfAWeek 関数       

  【研究中】

DaysBetween 関数            未実装。「DaysBetween 関数を呼び出すと，2 つの TDateTime 値の差（日数）を取得できます。
DaysBetween は，経過した完全な日（24 時間）だけを数に入れます。このため，DaysBetween は，1999 年 12 月 31 日の午後 11 時 59 分と 2000 年 1 月 1 日の午後 11 時 58 分の差を 0 として報告します。この差が 1 日としてカウントされるには 1 分足りないからです。」
DaySpan 関数                未実装。「function DaySpan(const ANow, AThen: TDateTime): Double;DaySpan 関数を呼び出すと，2 つの TDateTime 値の差（日数）を取得できます。完全な日（24 時間）だけを数に入れる DaysBetween 関数とは違って，DaySpan は不完全な日を端数として報告します。」

DecodeDateDay 手続き        未実装。「procedure DecodeDateDay(const AValue: TDateTime; out AYear, ADayOfYear: Word);」
DecodeDateFully 関数        未実装。「function DecodeDateFully(const DateTime: TDateTime; var Year, Month, Day,DOW: Word): Boolean;  DecodeDateFully 関数は，Date パラメータとして指定された値を Year，Month，Day，および DOW の各値に分解します。Year がうるう年である場合，この関数は True を返し，それ以外の場合は false を返します。」
DecodeDateWeek 手続き       未実装。「procedure DecodeDateWeek(const AValue: TDateTime; out AYear, AWeekOfYear, ADayOfWeek: Word);」「1 は月曜，7 は日曜を示します。注意：AWeekOfYear と ADayOfWeek の定義は，ISO 8601 規格に基づいています。」

EncodeDateDay 関数          未実装。「function EncodeDateDay(const AYear, ADayOfYear: Word): TDateTime;」
EncodeDateWeek 関数         未実装。「function EncodeDateWeek(const AYear, AWeekOfYear: Word; const ADayOfWeek: Word = 1): 」

HoursBetween 関数          
HourSpan 関数

HoursPerDay 定数;
MinsPerDay 定数;
SecsPerDay 定数;
MSecsPerDay 定数

IsValidDate 関数           ☆：DateTime::valid_date_time?。「function IsValidDate(const AYear, AMonth, ADay: Word): Boolean;」
IsValidDateTime 関数
IsValidTime 関数

IsValidDateDay 関数       「function IsValidDateDay(const AYear, ADayOfYear: Word): Boolean;」
IsValidDateWeek 関数      「function IsValidDateWeek(const AYear, AWeekOfYear, ADayOfWeek: Word): Boolean;」

MilliSecondOfTheDay 関数
MilliSecondOfTheHour 関数
MilliSecondOfTheMinute 関数
MilliSecondOfTheMonth 関数
MilliSecondOfTheWeek 関数
MilliSecondOfTheYear 関数
MilliSecondsBetween 関数
MilliSecondSpan 関数

MinuteOfTheDay 関数
MinuteOfTheMonth 関数
MinuteOfTheWeek 関数
MinuteOfTheYear 関数

MinutesBetween 関数
MinuteSpan 関数

MonthsBetween 関数
MonthSpan 関数

RecodeDateTime 関数    ☆：DateTime#update。「RecodeDateTime 関数は，指定された TDateTime 値の構成要素を選択的に置換します。」
RecodeLeaveFieldAsIs 定数：→ nil。RecodeLeaveFieldAsIs 定数は，使わない RecodeDateTime のパラメータを識別します。

SameDateTime 関数       SameDateTime 関数は，2 つの TDateTime 値が同じ年，月，日，時，分，秒，およびミリ秒を表しているかどうかを示します。

SecondOfTheDay 関数     
SecondOfTheHour 関数    
SecondOfTheMonth 関数   
SecondOfTheWeek 関数    
SecondOfTheYear 関数    

SecondsBetween 関数     SecondsBetween 関数は，2 つの指定された TDateTime 値の間にある秒数を返します。
SecondSpan 関数         SecondSpan 関数は，2 つの指定された TDateTime 値の間にある秒数（端数を含む）を返します。

TryEncodeDateDay 関数   TryEncodeDateDay 関数は，指定された年の指定された日を表す TDateTime 値を計算します。
TryEncodeDateTime 関数  TryEncodeDateTime 関数は，指定された年，月，日，時，分，秒，およびミリ秒を表す TDateTime 値を計算します。
TryEncodeDateWeek 関数  TryEncodeDateWeek 関数は，指定された年の指定された週の指定された曜日を表す TDateTime 値を計算します。
TryRecodeDateTime 関数  TryRecodeDateTime 関数は，指定された TDateTime 値の構成要素を選択的に置換します。
TryStrToSQLTimeStamp 関数  TryStrToSQLTimeStamp 関数は，文字列を TSQLTimeStamp 値に変換します。

UnixDateDelta 定数      UnixDateDelta 定数は，TDateTime 値と TIME_T 値の差を指定します。

WeekOf 関数             WeekOf 関数は，TDateTime 値で表された週を返します。
WeekOfTheMonth 関数     WeekOfTheMonth 関数は，TDateTime 値で表された週を返します。
WeekOfTheYear 関数      WeekOfTheYear 関数は，TDateTime 値で表された週を返します。

WeeksBetween 関数       WeeksBetween 関数は，2 つの指定された TDateTime 値の間にある週数を返します。
WeeksInAYear 関数       WeeksInAYear 関数は，指定された年の週数を返します。
WeeksInYear 関数        WeeksInYear 関数は，指定された TDateTime 値の年の週数を返します。

WeekSpan 関数           WeekSpan 関数は，2 つの指定された TDateTime 値の間にある週数（端数を含む）を返します。

WithinPastDays 関数     WithinPastDays 関数は，2 つの日付が互いに指定された日数内にあるかどうかを示します。
WithinPastHours 関数    WithinPastHours 関数は，2 つの日付時刻値が互いに指定された時間内にあるかどうかを示します。
WithinPastMilliSeconds 関数  WithinPastMilliSeconds 関数は，2 つの日付時刻値が互いに指定されたミリ秒内にあるかどうかを示します。
WithinPastMinutes 関数  WithinPastMinutes 関数は，2 つの日付時刻値が互いに指定された分数内にあるかどうかを示します。
WithinPastMonths 関数   WithinPastMonths 関数は，2 つの日付時刻値が互いに指定された月数内にあるかどうかを示します。
WithinPastSeconds 関数  WithinPastSeconds 関数は，2 つの日付時刻値が互いに指定された秒数内にあるかどうかを示します。
WithinPastWeeks 関数    WithinPastWeeks 関数は，2 つの日付時刻値が互いに指定された週数内にあるかどうかを示します。
WithinPastYears 関数    WithinPastYears 関数は，2 つの日付時刻値が互いに指定された年数内にあるかどうかを示します。

YearsBetween 関数       YearsBetween 関数は，2 つの指定された TDateTime 値の間にあるおよその年数を返します。
YearSpan 関数           YearSpan 関数は，2 つの指定された TDateTime 値の間にあるおよその年数（端数を含む）を返します。

* [ruby-dev:15298] time.rb 
--
