1: <?php
2: /*
3: * Copyright (c) 2014 @trashtoy
4: * https://github.com/trashtoy/
5: *
6: * Permission is hereby granted, free of charge, to any person obtaining a copy of
7: * this software and associated documentation files (the "Software"), to deal in
8: * the Software without restriction, including without limitation the rights to use,
9: * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
10: * Software, and to permit persons to whom the Software is furnished to do so,
11: * subject to the following conditions:
12: *
13: * The above copyright notice and this permission notice shall be included in all
14: * copies or substantial portions of the Software.
15: *
16: * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17: * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
18: * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
19: * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
20: * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21: * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22: */
23: /**
24: * PHP class file.
25: * @auhtor trashtoy
26: * @since 2.0.0
27: */
28: namespace Peach\DT;
29: use Peach\Util\Comparable;
30:
31: /**
32: * ある特定の日付または時刻を表すインタフェースです.
33: * このインタフェースを実装したオブジェクトのことを「時間オブジェクト」と呼びます.
34: * 時間オブジェクトには以下の 3 種類の型があります.
35: *
36: * - DATE : 年・月・日のフィールドを持ちます
37: * - DATETIME : 年・月・日・時・分のフィールドを持ちます
38: * - TIMESTAMP : 年・月・日・時・分・秒のフィールドを持ちます
39: *
40: * とある時間オブジェクトについて, そのオブジェクトの型が何かを調べるには
41: * {@link Time::getType()} メソッドを使用してください.
42: *
43: * 時間オブジェクトを操作するための各種メソッド (get, add, set, setAll など)
44: * は文字列型の引数を指定して呼び出す仕様となっていますが,
45: * 具体的には "year", "month", "date", "hour", "minute", "second"
46: * などの値を指定してください. (大文字・小文字を問いません)
47: *
48: * 具体的には以下の仕様となっています.
49: *
50: * - 先頭が "Y" : 年
51: * - 先頭が "MO" : 月
52: * - 先頭が "D" : 日
53: * - 先頭が "H" : 時
54: * - 先頭が "M" で始まり, 直後に "O" が続かない場合 : 分
55: * - 先頭が "S" : 秒
56: *
57: * このクラスはイミュータブルであるため, 各種フィールド操作メソッド (add, set, setAll)
58: * は新しい時間オブジェクトを返すことに注意してください.
59: *
60: * このクラスは {@link Comparable} を実装しているため,
61: * {@link \Peach\Util\Arrays::sort} でソートすることが出来ます.
62: */
63: interface Time extends Comparable
64: {
65: /**
66: * このオブジェクトが年・月・日のフィールドをサポートしていることを示します.
67: */
68: const TYPE_DATE = 129;
69:
70: /**
71: * このオブジェクトが年・月・日・時・分のフィールドをサポートしていることを示します.
72: */
73: const TYPE_DATETIME = 130;
74:
75: /**
76: * このオブジェクトが年・月・日・時・分・秒のフィールドをサポートしていることを示します.
77: */
78: const TYPE_TIMESTAMP = 131;
79:
80: /**
81: * 日曜日をあらわす定数です.
82: * @var int
83: */
84: const SUNDAY = 0;
85:
86: /**
87: * 月曜日をあらわす定数です
88: * @var int
89: */
90: const MONDAY = 1;
91:
92: /**
93: * 火曜日をあらわす定数です
94: * @var int
95: */
96: const TUESDAY = 2;
97:
98: /**
99: * 水曜日をあらわす定数です
100: * @var int
101: */
102: const WEDNESDAY = 3;
103:
104: /**
105: * 木曜日をあらわす定数です
106: * @var int
107: */
108: const THURSDAY = 4;
109:
110: /**
111: * 金曜日をあらわす定数です
112: * @var int
113: */
114: const FRIDAY = 5;
115:
116: /**
117: * 土曜日をあらわす定数です
118: * @var int
119: */
120: const SATURDAY = 6;
121:
122: /**
123: * このオブジェクトの型を返します.
124: * 返り値の数値は, 上位の (より多くのフィールドをサポートしている) 型ほど大きくなります.
125: * そのため, 2 つの時間オブジェクトの getType の返り値を比較することにより,
126: * どちらのオブジェクトのほうがサポートしているフィールドが多いか調べることができます.
127: *
128: * @return int オブジェクトの型
129: *
130: * @see Time::TYPE_DATE
131: * @see Time::TYPE_DATETIME
132: * @see Time::TYPE_TIMESTAMP
133: */
134: public function getType();
135:
136: /**
137: * 指定されたフィールドの値を取得します.
138: * @param string $field フィールド名
139: * @return int 対象フィールドの値. ただしフィールド名が不正な場合は NULL
140: */
141: public function get($field);
142:
143: /**
144: * この時間オブジェクトの指定されたフィールドを上書きします.
145: *
146: * @param string $field フィールド名
147: * @param int $value 設定する値
148: * @return Time 設定後の時間オブジェクト
149: */
150: public function set($field, $value);
151:
152: /**
153: * この時間オブジェクトの複数のフィールドを一度に上書きします.
154: * 引数には,
155: * <code>
156: * array("year" => 2010, "month" => 8, "date" => 31)
157: * </code>
158: * などの配列か, または同様の Map オブジェクトを指定してください.
159: *
160: * @param \Peach\Util\Map|array $subject フィールドと値の一覧
161: * @return Time 設定後の時間オブジェクト
162: */
163: public function setAll($subject);
164:
165: /**
166: * 引数のフィールドを, $amount だけ増加 (負の場合は減少) させます.
167: * @param string $field 対象のフィールド
168: * @param int $amount 加算する量. マイナスの場合は過去方向に移動する.
169: * @return Time 設定後の時間オブジェクト
170: */
171: public function add($field, $amount);
172:
173: /**
174: * 指定されたフォーマットを使ってこの時間オブジェクトを書式化します.
175: * フォーマットを指定しない場合はデフォルトの方法 (SQL などで使われる慣用表現) で書式化を行ないます.
176: * @param Format $format Format オブジェクト (省略可)
177: * @return string このオブジェクトの書式化. 引数を指定しない場合は "YYYY-MM-DD" あるいは "YYYY-MM-DD hh:mm:ss" などの文字列
178: */
179: public function format(Format $format = null);
180:
181: /**
182: * 指定されたオブジェクトとこのオブジェクトを比較します.
183: * 二つのオブジェクトが等しいと判断された場合に TRUE を返します.
184: *
185: * @param mixed $obj 比較対象のオブジェクト
186: * @return boolean 二つのオブジェクトが等しい場合に TRUE, それ以外は FALSE
187: */
188: public function equals($obj);
189:
190: /**
191: * 指定された時間とこの時間を比較します.
192: *
193: * もしもこのオブジェクトが持つ時間フィールドすべてが
194: * 引数のオブジェクトの時間フィールドと一致した場合,
195: * より多くの時間フィールドを持つほうが「後」となります.
196: *
197: * 例: 2012-05-21 (Date) < 2012-05-21T00:00 (Datetime) < 2012-05-21T00:00:00 (Timestamp)
198: *
199: * @param Time $time 比較対象の時間
200: * @return bool この時間のほうが過去である場合は TRUE, それ以外は FALSE
201: */
202: public function before(Time $time);
203:
204: /**
205: * 指定された時間とこの時間を比較します.
206: *
207: * もしもこのオブジェクトが持つ時間フィールドすべてが
208: * 引数のオブジェクトの時間フィールドと一致した場合,
209: * より多くの時間フィールドを持つほうが「後」となります.
210: *
211: * 例: 2012-05-21 (Date) < 2012-05-21T00:00 (Datetime) < 2012-05-21T00:00:00 (Timestamp)
212: *
213: * @param Time $time 比較対象の時間
214: * @return bool この時間のほうが未来である場合は TRUE, それ以外は FALSE
215: */
216: public function after(Time $time);
217:
218: /**
219: * この年がうるう年かどうかを判定します.
220: *
221: * うるう年の判別ルールは以下の通りです.
222: * - 4 で割り切れるはうるう年である
223: * - ただし 100 で割り切れる年はうるう年ではない
224: * - ただし 400 で割り切れる年はうるう年である
225: *
226: * @return bool うるう年である場合に TRUE, それ以外は FALSE
227: */
228: public function isLeapYear();
229:
230: /**
231: * この日付の曜日を返します. 返される値は 0 から 6 までの整数で, 0 が日曜, 6 が土曜をあらわします.
232: * それぞれの整数は, このクラスで定義されている各定数に対応しています.
233: *
234: * @return int 曜日 (0 以上 6 以下の整数)
235: *
236: * @see Time::SUNDAY
237: * @see Time::MONDAY
238: * @see Time::TUESDAY
239: * @see Time::WEDNESDAY
240: * @see Time::THURSDAY
241: * @see Time::FRIDAY
242: * @see Time::SATURDAY
243: */
244: public function getDay();
245:
246: /**
247: * この月の日数を返します.
248: * @return int この月の日数. すなわち, 28 から 31 までの整数.
249: */
250: public function getDateCount();
251:
252: /**
253: * このオブジェクトを DATE 型にキャストします.
254: * このメソッドの返り値は以下の性質を持ちます.
255: *
256: * - 年・月・日のフィールドをサポートします.
257: * - {@link Time::getType} を実行した場合 {@link Time::TYPE_DATE} を返します.
258: *
259: * デフォルトの実装では {@link Date} 型にキャストします.
260: *
261: * @return Time DATE 型の時間オブジェクト
262: */
263: public function toDate();
264:
265: /**
266: * このオブジェクトを DATETIME 型にキャストします.
267: * このメソッドの返り値は以下の性質を持ちます.
268: *
269: * - 年・月・日・時・分のフィールドをサポートします.
270: * - {@link Time::getType} を実行した場合 {@link Time::TYPE_DATETIME} を返します.
271: *
272: * デフォルトの実装では {@link Datetime} オブジェクトを返します.
273: *
274: * @return Time DATETIME 型の時間オブジェクト
275: */
276: public function toDatetime();
277:
278: /**
279: * このオブジェクトを TIMESTAMP 型にキャストします.
280: * このメソッドの返り値は以下の性質を持ちます.
281: *
282: * - 年・月・日・時・分・秒のフィールドをサポートします.
283: * - {@link Time::getType} を実行した場合 {@link Time::TYPE_TIMESTAMP} を返します.
284: *
285: * デフォルトの実装では {@link Timestamp} オブジェクトを返します.
286: *
287: * @return Time TIMESTAMP 型の時間オブジェクト
288: */
289: public function toTimestamp();
290:
291: /**
292: * この時間の時刻 (時・分・秒) 部分を書式化します.
293: * 返される文字列はタイプによって以下の通りとなります.
294: *
295: * - DATE : 空文字列
296: * - DATETIME : "hh:mm"
297: * - TIMESTAMP : "hh:mm:ss"
298: *
299: * @return string 時刻部分の文字列. このオブジェクトが時刻をサポートしない場合は空文字列.
300: */
301: public function formatTime();
302: }
303: