Serialization

Most values in Haxe can be serialized, which means that you can convert a runtime value into a simple String that you can either send on the network, store in a file, in memory or into a database for later usage. You can later unserialize the String in order to get back your original value.

(If you are using de/serialization cross-platform, see 'Troubleshoot' below regarding possible cross-platform gotchyas.)

Two classes can be used for this Serializer and Unserializer. Here's an example of how it works :

class Test {
    static function main() {
        var x = 456;
        var s = haxe.Serializer.run(x);
        trace(s); // "i456"
        var y : Int = haxe.Unserializer.run(s);
        trace(y); // 456
    }
}

The format used by both Serializer and Unserializer is cross-platform, which means that you can serialize a value on a given platform (in Haxe/Flash for example) and unserialize it on another platform (in Haxe/PHP for example).

The String produced by Haxe serialization can be easily transmitted among many protocols since only some common characters are allowed.

Supported Values

The following values are supported :

  • null
  • Int and Bool
  • Float, including NaN,+Inf and -Inf
  • String
    the string will be urlencoded as-it, so make sure that you use the same encoding (either ISO or UTF8) on both serialization and unserialization platforms
  • Date
  • haxe.io.Bytes
    the bytes are encoded into base64
  • Basic structures : Array, List, Hash, IntHash
    nulls in sparse arrays are optimized with a null counter
  • Anonymous objects (Structures) such as { x : 0, name : "Hi" }
  • Classes instances and Enums instances (see below)

Classes instances

When an unsupported class is serialized, the Serializer will by default serialize its class name and all its fields. The Unserializer will use the resolver ``resolveClass`` method to query the class by its name, create an instance of it without calling its constructor code (with Type.createEmptyInstance) and then fill its fields as they were serialized.

Enums instances

When an enum instance is found, the Serializer will serialize its enum name, the constructor name, and all its parameters. Storing the name enables you to reorder your enum constructors without breaking serialized data. You cannot however add or modify constructors parameters (unserializer behavior is unspecified in that case).

However, storing the constructor names can take some space in your serialized data, so you can also use the enum index mode (either globally by setting haxe.Serializer.USE_ENUM_INDEX=true) or for a single serializer instance by changing its useEnumIndex field.

Circular References

If the values you are serializing can contain circular references or objects repetitions, you should set haxe.Serializer.USE_CACHE to true to prevent infinite loops, or for a single serializer instance by changing its useCache field.

Enabling cache will slow down serialization quite a bit but might reduce serialized size since duplicated data might disappear.

Exceptions

You can also store an exception by using the following code :

var s = new haxe.Serializer();
s.serializeException("Error");
var str = s.toString();

This will have the effect of throwing the exception at the time it's unserialized automatically.

Custom Serialization

New in Haxe 2.06

You can have custom serialization for some of your classes. For this, you simply need to implement the two methods hxSerialize and hxUnserialize.

class MyCustomSerializer {
    var x : Int;
    var y : Int;
    public function new() {
    }
    function hxSerialize( s : haxe.Serializer ) {
        s.serialize(x);
        s.serialize(y);
    }
    function hxUnserialize( s : haxe.Unserializer ) {
        x = s.unserialize();
        y = s.unserialize();
    }
}

Resolvers

When unserializing some class/enum instances, you can use custom resolving functions that will enable you to remap the names differently. Use the unserializer.setResolver method for that.

Format

You can find the complete format of haxe serialized data here: Haxe Serialization Format

Troubleshoot

If the serialized string is passed from a target to another you might need to escape the string.
For instance, if setting a cookie with a serialized variable from Neko or Php to javascript, you'll need to escape the string using StringTools.urlEncode else you might not get the good string to unserialize.
See String Encoding and StringTools for more details.

version #14010, modified 2012-05-14 22:11:13 by foobar