Skip to content

Commit 66442ed

Browse files
marc-mabemarc-mabe
committed
EnumMap: docblock comments + micro optimisations
1 parent 1621841 commit 66442ed

File tree

1 file changed

+137
-4
lines changed

1 file changed

+137
-4
lines changed

‎src/MabeEnum/EnumMap.php

Lines changed: 137 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,65 @@
66
use InvalidArgumentException;
77
use RuntimeException;
88

9+
/**
10+
* EnumMap implementation in base of SplObjectStorage
11+
*
12+
* @link http://github.com/marc-mabe/php-enum for the canonical source repository
13+
* @copyright Copyright (c) 2012 Marc Bennewitz
14+
* @license http://github.com/marc-mabe/php-enum/blob/master/LICENSE.txt New BSD License
15+
*/
916
class EnumMap extends SplObjectStorage
1017
{
1118

19+
/**
20+
* key()-behaviour: return the current iterator position
21+
*/
1222
const KEY_AS_INDEX = 1;
23+
24+
/**
25+
* key()-behaviour: return the current enum name
26+
*/
1327
const KEY_AS_NAME = 2;
28+
29+
/**
30+
* key()-behaviour: return the current enum value
31+
*/
1432
const KEY_AS_VALUE = 3;
33+
34+
/**
35+
* key()-behaviour: return the current enum ordinal
36+
*/
1537
const KEY_AS_ORDINAL = 4;
38+
39+
/**
40+
* current()-behaviour: return the current enum object
41+
*/
1642
const CURRENT_AS_ENUM = 8;
43+
44+
/**
45+
* current()-behaviour: return data mapped the current enum
46+
*/
1747
const CURRENT_AS_DATA = 16;
48+
49+
/**
50+
* current()-behaviour: return the current enum name
51+
*/
1852
const CURRENT_AS_NAME = 24;
53+
54+
/**
55+
* current()-behaviour: return the current enum value
56+
*/
1957
const CURRENT_AS_VALUE = 32;
58+
59+
/**
60+
* current()-behaviour: return the current enum ordinal
61+
*/
2062
const CURRENT_AS_ORDINAL = 40;
2163

64+
/**
65+
* The classname of an enumeration this map is for
66+
* @var string
67+
*/
2268
private $enumClass;
2369

2470
/**
@@ -28,6 +74,11 @@ class EnumMap extends SplObjectStorage
2874
*/
2975
private $flags = 9;
3076

77+
/**
78+
* Constructor
79+
* @param string $enumClass The classname of an enumeration the map is for
80+
* @param int|null $flags Behaviour flags, see KEY_AS_* and CURRENT_AS_* constants
81+
*/
3182
public function __construct($enumClass, $flags = null)
3283
{
3384
if (!is_subclass_of($enumClass, __NAMESPACE__ . '\Enum')) {
@@ -43,11 +94,22 @@ public function __construct($enumClass, $flags = null)
4394
}
4495
}
4596

97+
/**
98+
* Get the classname of enumeration this map is for
99+
* @return string
100+
*/
46101
public function getEnumClass()
47102
{
48103
return $this->enumClass;
49104
}
50105

106+
/**
107+
* Set behaviour flags
108+
* see KEY_AS_* and CURRENT_AS_* constants
109+
* @param int $flags
110+
* @return void
111+
* @throws InvalidArgumentException On invalid or unsupported flags
112+
*/
51113
public function setFlags($flags)
52114
{
53115
$flags = (int)$flags;
@@ -74,17 +136,33 @@ public function setFlags($flags)
74136
$this->flags = $keyFlag | $currentFlag;
75137
}
76138

139+
/**
140+
* Get the behaviour flags
141+
* @return int
142+
*/
77143
public function getFlags()
78144
{
79145
return $this->flags;
80146
}
81147

148+
/**
149+
* Attach a new enumeration or overwrite an existing one
150+
* @param Enum|scalar $enum
151+
* @param mixed $data
152+
* @return void
153+
* @throws InvalidArgumentException On an invalid given enum
154+
*/
82155
public function attach($enum, $data = null)
83156
{
84157
$this->initEnum($enum);
85158
parent::attach($enum, $data);
86159
}
87160

161+
/**
162+
* Test if the given enumeration exists
163+
* @param Enum|scalar $enum
164+
* @return boolean
165+
*/
88166
public function contains($enum)
89167
{
90168
try {
@@ -96,12 +174,24 @@ public function contains($enum)
96174
}
97175
}
98176

177+
/**
178+
* Detach an enumeration
179+
* @param Enum|scalar $enum
180+
* @return void
181+
* @throws InvalidArgumentException On an invalid given enum
182+
*/
99183
public function detach($enum)
100184
{
101185
$this->initEnum($enum);
102186
parent::detach($enum);
103187
}
104188

189+
/**
190+
* Get a unique identifier for the given enumeration
191+
* @param Enum|scalar $enum
192+
* @return string
193+
* @throws InvalidArgumentException On an invalid given enum
194+
*/
105195
public function getHash($enum)
106196
{
107197
$this->initEnum($enum);
@@ -110,63 +200,106 @@ public function getHash($enum)
110200
return spl_object_hash($enum);
111201
}
112202

203+
/**
204+
* Test if the given enumeration exists
205+
* @param Enum|scalar $enum
206+
* @return boolean
207+
* @see contains()
208+
*/
113209
public function offsetExists($enum)
114210
{
115211
return $this->contains($enum);
116212
}
117213

214+
/**
215+
* Get mapped data for this given enum
216+
* @param Enum|scalar $enum
217+
* @return mixed
218+
* @throws InvalidArgumentException On an invalid given enum
219+
*/
118220
public function offsetGet($enum)
119221
{
120222
$this->initEnum($enum);
121223
return parent::offsetGet($enum);
122224
}
123225

226+
/**
227+
* Attach a new enumeration or overwrite an existing one
228+
* @param Enum|scalar $enum
229+
* @param mixed $data
230+
* @return void
231+
* @throws InvalidArgumentException On an invalid given enum
232+
* @see attach()
233+
*/
124234
public function offsetSet($enum, $data = null)
125235
{
126236
$this->initEnum($enum);
127237
parent::offsetSet($enum, $data);
128238
}
129239

240+
/**
241+
* Detach an existing enumeration
242+
* @param Enum|scalar $enum
243+
* @return void
244+
* @throws InvalidArgumentException On an invalid given enum
245+
* @see detach()
246+
*/
130247
public function offsetUnset($enum)
131248
{
132249
$this->initEnum($enum);
133250
parent::offsetUnset($enum);
134251
}
135252

253+
/**
254+
* Get the current item
255+
* The return value varied by the behaviour of the current flag
256+
* @return mixed
257+
*/
136258
public function current()
137259
{
138260
switch ($this->flags & 120) {
139261
case self::CURRENT_AS_ENUM:
140262
return parent::current();
141263
case self::CURRENT_AS_DATA:
142264
return parent::getInfo();
143-
case self::CURRENT_AS_NAME:
144-
return parent::current()->getName();
145265
case self::CURRENT_AS_VALUE:
146266
return parent::current()->getValue();
267+
case self::CURRENT_AS_NAME:
268+
return parent::current()->getName();
147269
case self::CURRENT_AS_ORDINAL:
148270
return parent::current()->getOrdinal();
149271
default:
150272
throw new RuntimeException('Invalid current flag');
151273
}
152274
}
153275

276+
/**
277+
* Get the current item-key
278+
* The return value varied by the behaviour of the key flag
279+
* @return scalar
280+
*/
154281
public function key()
155282
{
156283
switch ($this->flags & 7) {
157284
case self::KEY_AS_INDEX:
158285
return parent::key();
159286
case self::KEY_AS_NAME:
160287
return parent::current()->getName();
161-
case self::KEY_AS_VALUE:
162-
return parent::current()->getValue();
163288
case self::KEY_AS_ORDINAL:
164289
return parent::current()->getOrdinal();
290+
case self::KEY_AS_VALUE:
291+
return parent::current()->getValue();
165292
default:
166293
throw new RuntimeException('Invalid key flag');
167294
}
168295
}
169296

297+
/**
298+
* Initialize an enumeration
299+
* @param Enum|scalar $enum
300+
* @return Enum
301+
* @throws InvalidArgumentException On an invalid given enum
302+
*/
170303
private function initEnum(&$enum)
171304
{
172305
// auto instantiate

0 commit comments

Comments
 (0)