Methodの概要

Methodの概要

メインとなるカレンダーのクラス(Calendarのサブクラス)はすべて共通APIを共有しています(共通のクラスメソッド)。あるクラスでは細かなバリエーションがありますが、一度、なにが利用できるかを知ってしまえば、直感的に理解し、容易に思い出すことができるでしょう。このセクションでは共通のメソッドを要約し、このバリエーションを強調します。詳しい情報はAPIのドキュメントをみてください。

コンストラクター

データクラスのコンストラクターは日付の数値を引数にとります。年のはじまり(左側)から秒(右側)までです。これはあなたの利用するクラスに依存します。たとえば;

<?php
// Natural カレンダークラス
$Year = new Calendar_Year(2003);                         // 2003
$Month = new Calendar_Month(2003, 10);                   // 2003年10月
$Day = new Calendar_Day(2003, 10, 25);                   // 2003年10月25日
$Hour = new Calendar_Hour(2003, 10, 25, 13);             // 2003年10月25日 13:00:00
$Minute = new Calendar_Minute(2003, 10, 25, 13, 31);     // 2003年10月25日 13:31:00
$Second = new Calendar_Second(2003, 10, 25, 13, 31, 45); // 2003年10月25日 13:31:45

// Tabular カレンダークラス
$Month = new Calendar_Month_Weekdays(2003, 10);          // 2003年10月
$Month = new Calendar_Month_Weeks(2003, 10);             // 2003年10月
$Week = new Calendar_Week(2003, 10, 25);                 // 2003年10月25日を含む週
?>

Location メソッド

すべての日付とtabularの日付のクラスは抽象基本クラスのCalendarで定義されたメソッドを共有しています(Among these are methods for an object of any of these classes to identify itself (what's it's date is) and the previous and next dates.)。これらのクラスのオブジェクトのためのメソッドにはオブジェクト自体を識別するメソッドや以前の日付、次の日付を識別するメソッドがあります。例;

<?php
// 日の作成
$Day = new Calendar_Day(2003, 10, 1); // 2003年10月1日

echo $Day->thisDay(); // 1日を表示
echo $Day->prevDay(); // 30日を表示 (9月30日)
echo $Day->nextDay(); // 2日を表示

echo $Day->thisMonth(); // 10月を表示
echo $Day->prevMonth(); // 9月を表示
echo $Day->nextMonth(); // 11月を表示
?>

Calling any of these methods and passing the value TRUE will result in a timestamp being returned (タイムスタンプの形式は使用しているカレンダーエンジンによります - see the FAQ), 例;

<?php
// Create a second
$Second = new Calendar_Second(2003, 10, 25, 13, 32, 44);

echo $Second->thisYear(TRUE);     // Displays 1041375600
echo $Second->thisMonth(TRUE);    // Displays 1064959200
echo $Second->thisDay(TRUE);      // Displays 1067032800
echo $Second->thisHour(TRUE);     // Displays 1067079600
echo $Second->thisMinute(TRUE);   // Displays 1067081520
echo $Second->thisSecond(TRUE);   // Displays 1067081564
?>

thisWeek(), prevWeek() および nextWeek()といったメソッドもあります。これらのメソッドはCalendar_Weekのインスタンスを利用した場合のみ利用すことができます。返される値のフォーマットは'timestamp', 'n_in_month', 'n_in_year' or 'array'の中から選択することができます。'n_in_month'を選択した場合に、月のはじまりか終わりになってしまった場合にはNULL値が返されることに注意してください。

最後になりますが、すべてのカレンダーオブジェクトはgetTimeStamp() と setTimeStamp()メソッドを提供します。前者はあなたが利用しているカレンダーエンジンのフォーマットでのタイムスタンプを返します（例えば、もしデフォルトのUnixタイムエンジンを使用しているなら、Unix形式のYYYY-MM-DD HH:MM:SSというフォーマットのタイムスタンプです）。後者はカレンダーオブジェクトが構築した値を変換するのに用いたタイムスタンプを除外します。

Building and Fetching

すべての日付とtabularの日付のクラスはデータオブジェクトの子供を作るためのbuild()メソッドを持っています。たとえば、Calendar_Monthは月の"子供"の存在であるCalendar_Dayオブジェクトをビルドします。

一度、build()が呼び出されると、子供は単純なfetch()イテレータを使用して日付オブジェクトから取り出すことができます。例えば;

<?php
$Month = new Calendar_Month(2003, 10);

$Month->build();

$i = 1;
while ($Day = $Month->fetch()) {
    echo $Day->thisDay()."<br />\n";
    $i++;
}

echo $i; // Displays 31 (31 days in October)
?>

もしあなたがこのようなイテレータを好まず、独自のものを使用したいと望むなら、単純に子供をfetchAll()メソッド(子供の日付のオブジェクトのインデックス化された配列が返されます)で取り出し、size()で得た数をチェックすることができます。fetchAll()で返されるのはインデックスの配列であることに注意してください。Calendar_Year, Calendar_Month, Calendar_Month_Weekdays, Calendar_Month_Weeks そして Calendar_Weekではインデックスの最初の値は1です。一方で、Calendar_Day, Calendar_Hour, Calendar_Minute そして Calendar_Secondではインデックスの最初の値は0です。なぜでしょうか？次のような表記をかんがえてみてください。 2003-1-1 00:00:00 ...

Note: Calendar_Second::build() doesn't do anything - it has no children.

Selecting Children

カレンダーのレンダリングを簡単にするために、build()メソッドは子供のオブジェクトと比較する日付オブジェクトの配列のインデックスを受け取ることができます(どの日付のオブジェクトやtabular日付のオブジェクトでも利用することができます)。オブジェクトが子とマッチする場合は、isSelected()メソッド(どんな日付やtabularな日付オブジェクトも利用できます)がTRUEを返すことを意味しています。例えば;

<?php
$Month = new Calendar_Month(2003, 10);

$DayX = new Calendar_Day(2003, 10, 15);
$DayY = new Calendar_Day(2003, 10, 23);
$selection = array($DayX, $DayY);

$Month->build($selection);

while ($Day = $Month->fetch()) {
    if ($Day->isSelected()) {
        echo $Day->thisDay()."<br />\n"; // Displays 15 or 23
    }
}
?>

The objects you pass to build()によって作成した子供とマッチするオブジェクトは子供とreplaceすることができます(i.e. ここでマッチするなら、あなたのオブジェクトを受け取ります)。このことでうまくCalendar_Decoratorを拡張したあなたのオブジェクトをループの中に"inject"することができます。

Note:Calendar_Year::build()メソッドは2番目の引数に週のはじまりの曜日をとります(上記のコンストラクタの記述を参照してください)。

Tabular Days

Calendar_Dayクラスは3つの独自のメソッドを持っています。これらのメソッドは他のクラスにはありません。これらは純粋にtabularカレンダーを作成するために用いられます。isEmpty()は日にちが空白かどうかを判断するために用いられます(FAQの空白の日にちの説明を参照してください)。isFirst() と isLast()は週のはじまりとおわりを区別するために使用されます。

あなたがこれらのメソッドを使用する必要があるかどうかは、日付けオブジェクトを構築するするのにどのクラスを使用したかによります。もし、日付オブジェクトがCalendar_Month_Weekdaysによって構築されたのなら、これら3つのメソッドのどれもを利用することができます（もし空の日付があり、Calendar_Month_Weekdaysで完全な月を作成し、それぞれの週のはじまりとおわりが区切られていた場合、isFirst() と isLast()によって判断することができます）。Calendar_Weekによって日付が作られれたなら、isEmpty()メソッドだけが利用できます（月の最初と最後の週だけが空白の日付を含みます）。他の方法で日付オブジェクトが作成された場合、isEmpty(), isFirst() と isLast()は無意味です。

Validation

すべての日付オブジェクトとtabularオブジェクト(週を除く)はそれ自体をvalidateすることができます。デフォルトではどのような引数もコンストラクタに渡すことができますが、isValid()メソッドを用いて日付をvalidateすることができます。例えば;

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    die ('Invalid date');
}
?>

<?php
$Day = new Calendar_Day(2003, 10, 32);

if (!$Day->isValid()) {
    $Validator = & $Day->getValidator();
    while ($Error = $Validator->fetch()) {
        echo $Error->getUnit().' is invalid<br>';
    }
}
?>

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Validator = & $Day->getValidator();
if (!$Validator->isValid()) {
    while ($Error = $Validator->fetch()) {
        echo $Error->toString().'<br>';
    }
}
?>

日付をvalidateするというよりもadjust()メソッドを使って日付を自動的に調整するほうがよいことに注意してください。

<?php
$Day = new Calendar_Day(2003, 10, 32);

$Day->adjust();

echo $Day->thisYear();      // 2003
echo $Day->thisMonth();     // 11 (moved forward a month)
echo $Day->thisDay();       // 1 (the first of the month)
?>

ここでは、Decoratorクラスによって提供されるものを除くPEAR::Calendarで利用できるすべてのメソッドを要約しました。