xp-framework/rfc — Issue #148: Bytes type
Author: thekid
Created: 2011-10-17 16:00:46+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
A new type wrapper class lang.types.Bytes will be added. It represents
an array of bytes (byte[] in Java).

Rationale
====
* Type to detect binary data to be used in numerous APIs (SOAP, XMLRPC,
EASC, ...)
* Forward-compatibility with Unicode version

Functionality
====

Bytes class
----
The public API is as follows:

```php

```

Examples
----

```php

```

Overloading
----
The bytes class overloads array access operations:

```php

```

The bytes class also overloads the string conversion so it will work
with any of PHP's string functions:

```php

```

Furthermore, iteration is supported. The following example prints
"72,101,108,108,111,END" (without the quote signs).

```php
intValue(), ',';
}
echo 'END';
?>
```

Further lang.types API integration
----
The lang.types.String's and lang.types.Character's getBytes() methods are
changed to return a Bytes instance instead of a primitive string.

```php
getBytes('utf-8');

// b = lang.types.Bytes{\303 \274}
$b= create(new Character('ü', 'iso-8859-1'))->getBytes('utf-8');

// s= lang.types.String{übercoder}
$s= new String(new Bytes("\303\274bercoder"), 'utf-8');

// c= lang.types.Character{ü}
$c= new Character(new Bytes("\303\274"), 'utf-8');
?>
```

Integration with other APIs: SOAP
----
The SOAP API will recognize lang.types.Bytes objects and render them as
SOAP:Base64Binary during serialization. SOAP:Base64Binary data will be
returned as lang.types.Bytes objects during deserialization.

Integration with other APIs: XMLRPC
----
The XMLRPC API will recognize lang.types.Bytes objects and render them as
Base64 during serialization. Base64 data will be returned as lang.types.Bytes
objects during deserialization.

Integration with other APIs: EASC
----
EASC will map lang.types.Bytes objects to byte[] on the Java-Side and
byte[] from the Java-Side to lang.types.Bytes objects. At the moment, byte
arrays are mapped to an array of Byte[] objects, which is significantly
larger in storage space.

The token used for byte arrays will be "Y" (because "B" and "b" are
already taken for lang.type.Byte and lang.type.Boolean).

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====

BC break in EASC API for byte[]
----
Suppose we have a method called getByteArray() returning (Java notation used)
new byte[] { (byte)1, (byte)2 }.

This is what will be returned:

```php
getByteArray();

// After: lang.types.Bytes(2) { \1, \2 }
$after= $remote->getByteArray();
?>
```

Related documents
====
- xp-framework/rfc #146
Unicode RFC

- http://xp-framework.net/rfc/contrib/rfc0148.diff
Implementing patch