thekid/rfc — Issue #184: RFC 0184: ArrayMap and ArrayList
Author: thekid
Created: 2011-10-09 15:39:27+00:00
State: open
Labels: rfc

Scope of Change
====
Create a new class called `ArrayMap` in the `lang.types`
package which will represent a map.

Rationale
====
Lists and maps need to be distinguishable. PHP arrays are one or the
other, or even both. For a more detailled explanation, see the blog entry
http://news.xp-framework.net/article/293/2009/04/05/.

Functionality
====

5.7.3
----
* A new class named "ArrayMap" will be introduced.
* The existing class "ArrayList" will be changed for consistency.

5.8.0
----
* APIs will be changed to return and/or accept these classes.

Usage examples
----
The array operations are overloaded to give this class the typical "array"
usability:

```php
1, 'two' => 2));

// Size
$s= $m->size; // := 2

// Reading
$n= $m['one']; // := 1
$four= $m['four']); // *** lang.IndexOutOfBoundsException

// Writing
$m['one']= 10; // Overwrites existing value
$m['three']= 3; // Adds new mapping
$m[]= 7; // *** lang.IllegalArgumentException

// Removing
unset($m['one']); // Map now: { "two" => 2 }
unset($m['four']); // *** lang.IndexOutOfBoundsException

// Testing
isset($m['one']); // := true
isset($m['zero']); // := false

// Iteration
foreach ($m as $key => $value) {
Console::writeLine($key, ' => ', $value);
}
?>
```

Refactoring
----
Although this class behaves like a typical PHP array, it isn't one. Keep
this in mind when code uses `sizeof` or any of the array functions
such as `array_keys`, `asort` or `array_map`. The
places where a real array is required need to be passed the ArrayMap's
`array` member.

Example:

```php
'Timm', 'id' => 1549);
ksort($a);

// New code
$a= new ArrayMap(array('name' => 'Timm', 'id' => 1549));
ksort($a->array);
?>
```
Code that uses `foreach()` or array access syntax as shown above
does not need to be changed.

StringOf
----
The `xp::stringOf()` function will be extended to produce the
following output:

```php
'value', 'color' => 'green')));
// [
// "key" : "value"
// "color" : "green"
// ]
?>
```

XP language integration
----
The XP language will use these two types as backing for the array and map
literals.

```php
1, 'two' => 2));
$m= [ 'one' : 1, 'two' : 2 ];
?>
```

Consistency
----
The `ArrayList` class will be changed to adapt the `array`
member (instead of `values`). Also, to follow the general strategy
of replacing native arrays by the wrapper types provided in the XP framework,
the restriction of not being able to add elements to an ArrayList will be
removed:

```php

```

This used to throw an `IllegalArgumentException` and will now be allowed,
resulting in a list with four elements.

Security considerations
====
None.

Speed impact
====
Slower than native array implementation.

Dependencies
====
BC break for public member "value" in ArrayList class, renamed to "array".

Related documents
====
* http://de3.php.net/types.array - Arrays
* http://docs.xp-framework.net/xml/api/package?util.collections - XP Collections
* http://msdn.microsoft.com/en-us/library/system.collections.ienumerable.aspx - IEnumerable
* xp-framework/rfc #168: Integrate lang.types
* http://xp-framework.net/rfc/contrib/rfc0184.diff - Implementing patch

Comments
====
friebe, Mon Apr 6 08:19:04 2009
----
What additional methods should this class provide? What comes to my mind
would be `keys()` and `values()` methods returning ArrayLists.
I don't think this class should be a full-featured "swiss-army knife"-style
hashtable implementation, there's `util.collections.HashTable` for
this and we could also think about extension methods.

friebe, Mon Apr 6 08:23:16 2009
----
In the same course I think the `util.Hashmap` class could be
deprecated.