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\Util;
29:
30: /**
31: * キーと値のマッピングを管理するインタフェースです. API は
32: * {@link http://docs.oracle.com/javase/jp/7/api/java/util/Map.html java.util.Map}
33: * を参考にして作られています.
34: *
35: * このインタフェースを使うと, 今まで配列を使って
36: *
37: * <code>
38: * $value = isset($arr[$name]) ? $arr[$name] : NULL;
39: * </code>
40: *
41: * と書かなければならなかったコードが
42: *
43: * <code>
44: * $value = $map->get($name);
45: * </code>
46: *
47: * に簡略化できます. (※ E_NOTICE を無視する場合はこの限りではありません)
48: *
49: * PHP の配列機能との違いはその他に以下のものがあります.
50: *
51: * - 実装クラスによっては Java の Map のように任意のオブジェクトをキーとして利用できる. ({@link HashMap} など)
52: * - 値を取得する際, マッピングが存在しない場合にデフォルト値を適用できる.
53: * - 配列の操作に多態性 (ポリモーフィズム) を持たせることが出来る.
54: *
55: * 原則として, キーに可変オブジェクトを使わないでください.
56: * キーに設定した可変オブジェクトが外部から変更された場合の動作は保証されません.
57: */
58: interface Map
59: {
60: /**
61: * 指定されたキーにマッピングされている値を返します.
62: * マッピングが存在しない場合は $defaultValue を返します.
63: *
64: * @param mixed $key キー
65: * @param mixed $defaultValue マッピングが存在しない場合の代替値
66: * (デフォルトは NULL)
67: * @return mixed 指定したキーに関連づけられた値.
68: * 存在しない場合は引数のデフォルト値.
69: */
70: public function get($key, $defaultValue = null);
71:
72: /**
73: * 指定されたキーと値を関連づけます.
74: * @param mixed $key キー
75: * @param mixed $value 指定されたキーに関連づける値
76: */
77: public function put($key, $value);
78:
79: /**
80: * 指定されたマップのマッピングすべてを登録します.
81: *
82: * @param Map $map 登録対象のマップ
83: */
84: public function putAll(Map $map);
85:
86: /**
87: * 指定されたキーによるマッピングが存在するかどうかを調べます.
88: * マッピングが存在する場合に TRUE を返します.
89: *
90: * @param mixed $key キー
91: * @return bool マッピングが存在する場合に TRUE
92: */
93: public function containsKey($key);
94:
95: /**
96: * 指定されたキー名によるマッピングが存在する場合に, そのマッピングを削除します.
97: * @param mixed $key キー
98: */
99: public function remove($key);
100:
101: /**
102: * このマップを空にします.
103: */
104: public function clear();
105:
106: /**
107: * 登録されているマッピングの個数を返します.
108: * @return int
109: */
110: public function size();
111:
112: /**
113: * このマップに登録されているすべての値を配列で返します.
114: * 返される配列に対する操作はこのオブジェクトに反映されません.
115: * @return array
116: */
117: public function values();
118:
119: /**
120: * このマップに登録されているすべてのキーを配列で返します.
121: * 返される配列に対する操作はこのオブジェクトに反映されません.
122: * @return array
123: */
124: public function keys();
125:
126: /**
127: * このマップのすべてのエントリーを {@link MapEntry} オブジェクトの配列で返します.
128: *
129: * @return array
130: * @see MapEntry
131: */
132: public function entryList();
133: }
134: