.. _stdlib_archive:

=============================
通用 prupose 序列化
=============================

.. include:: detail/archive.rst

archive 模块实现了通用的序列化基础设施。

所有函数和交易品种都在 “archive” 模块中，使用 require 来访问它。 ::

    require daslib/archive

要正确支持特定类型的序列化，您需要为其定义并实现 `serialize` 方法。
例如，这是 DECS 实现组件序列化的方式：::

    def public serialize ( var arch:Archive; var src:Component )
        arch |> serialize(src.name)
        arch |> serialize(src.hash)
        arch |> serialize(src.stride)
        arch |> serialize(src.info)
        invoke(src.info.serializer, arch, src.data)


.. _struct-archive-Archive:

.. das:attribute:: Archive



存档字段为

+-------+---------------------------------------------------------+
+version+uint                                                     +
+-------+---------------------------------------------------------+
+reading+bool                                                     +
+-------+---------------------------------------------------------+
+stream + :ref:`archive::Serializer <struct-archive-Serializer>` ?+
+-------+---------------------------------------------------------+


存档是序列化、流和状态（版本和读取状态）的组合。

+++++++
Classes
+++++++

.. _struct-archive-Serializer:

.. das:attribute:: Serializer

序列化程序的基类。

它的定义如下


.. das:function:: Serializer.write(self: Serializer; bytes: void? const implicit; size: int const)

write returns bool

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+bytes   +void? const implicit                                    +
+--------+--------------------------------------------------------+
+size    +int const                                               +
+--------+--------------------------------------------------------+


将二进制数据写入流。

.. das:function:: Serializer.read(self: Serializer; bytes: void? const implicit; size: int const)

read returns bool

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+bytes   +void? const implicit                                    +
+--------+--------------------------------------------------------+
+size    +int const                                               +
+--------+--------------------------------------------------------+


从流中读取二进制数据。

.. das:function:: Serializer.error(self: Serializer; code: string const)

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+code    +string const                                            +
+--------+--------------------------------------------------------+


向存档报告错误

.. das:function:: Serializer.OK(self: Serializer)

OK 返回 bool

档案的返回状态

.. _struct-archive-MemSerializer:

.. das:attribute:: MemSerializer : Serializer

此序列化器将数据存储在内存中（在数组<uint8>中）

它的定义如下

  | data       : array<uint8>
  | readOffset : int
  | lastError  : string

.. das:function:: MemSerializer.write(self: Serializer; bytes: void? const implicit; size: int const)

write 返回 bool

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+bytes   +void? const implicit                                    +
+--------+--------------------------------------------------------+
+size    +int const                                               +
+--------+--------------------------------------------------------+


在数据末尾附加字节。

.. das:function:: MemSerializer.read(self: Serializer; bytes: void? const implicit; size: int const)

read 返回 bool

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+bytes   +void? const implicit                                    +
+--------+--------------------------------------------------------+
+size    +int const                                               +
+--------+--------------------------------------------------------+


从数据中读取字节，前进读取位置。

.. das:function:: MemSerializer.error(self: Serializer; code: string const)

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+self    + :ref:`archive::Serializer <struct-archive-Serializer>` +
+--------+--------------------------------------------------------+
+code    +string const                                            +
+--------+--------------------------------------------------------+


设置最后一个错误代码。

.. das:function:: MemSerializer.OK(self: Serializer)

OK 返回 bool

实现 'OK' 方法，如果序列化程序处于有效状态，则返回 true。

.. das:function:: MemSerializer.extractData(self: MemSerializer)

extractData returns array<uint8>

从序列化程序中提取数据。

.. das:function:: MemSerializer.getCopyOfData(self: MemSerializer)

getCopyOfData returns array<uint8>

返回 seiralizer 中的数据副本。

.. das:function:: MemSerializer.getLastError(self: MemSerializer)

getLastError returns string

返回最后一个序列化错误。

+++++++++++++
序列化
+++++++++++++

  *  :ref:`serialize (arch:archive::Archive -const;value:math::float3x3 -const) : void <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float3x3_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:math::float3x4 -const) : void <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float3x4_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:math::float4x4 -const) : void <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float4x4_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:string& -const) : void <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&s>` 
  *  :ref:`serialize_raw (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.>` 
  *  :ref:`read_raw (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_read_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.>` 
  *  :ref:`write_raw (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_write_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_((IsAnyEnumMacro_c_expect_any_enum(value_eq_true)||IsAnyWorkhorseNonPtrMacro_c_expect_any_workhorse_raw(value_eq_true))||IsValueHandle_c_expect_value_handle(value_eq_true))_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyFunctionNonPtrMacro_c_expect_any_function(value_eq_true)_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyStructMacro_c_expect_any_struct(value_eq_true)_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyTupleNonPtrMacro_c_expect_any_tuple(value_eq_true)_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)& -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyVariantNonPtrMacro_c_expect_any_variant(value_eq_true)_gr_>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)[] -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr___lb_-1_rb_Y_ls_TT_gr_.>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:array\<auto(TT)\> -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_TT_gr_._gr_A>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:table\<auto(KT);auto(VT)\> -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_KT_gr_._gr_2_ls_Y_ls_VT_gr_._gr_T>` 
  *  :ref:`serialize (arch:archive::Archive -const;value:auto(TT)? -const) : auto <function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_TT_gr_._gr__qm_>` 

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float3x3_gr_:

.. das:function:: serialize(arch: Archive; value: float3x3)

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   + :ref:`math::float3x3 <handle-math-float3x3>`     +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float3x4_gr_:

.. das:function:: serialize(arch: Archive; value: float3x4)

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   + :ref:`math::float3x4 <handle-math-float3x4>`     +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__H_ls_math_c__c_float4x4_gr_:

.. das:function:: serialize(arch: Archive; value: float4x4)

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   + :ref:`math::float4x4 <handle-math-float4x4>`     +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&s:

.. das:function:: serialize(arch: Archive; value: string&)

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +string&                                           +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.:

.. das:function:: serialize_raw(arch: Archive; value: auto(TT)&)

serialize_raw returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


序列化原始数据（原始 Pod 的直接字节数）

.. _function-_at_archive_c__c_read_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.:

.. das:function:: read_raw(arch: Archive; value: auto(TT)&)

read_raw returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


读取原始数据（原始 Pod 的直接字节数）

.. _function-_at_archive_c__c_write_raw_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_.:

.. das:function:: write_raw(arch: Archive; value: auto(TT)&)

write_raw returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


写入原始数据（原始 Pod 的直接字节数）

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_((IsAnyEnumMacro_c_expect_any_enum(value_eq_true)||IsAnyWorkhorseNonPtrMacro_c_expect_any_workhorse_raw(value_eq_true))||IsValueHandle_c_expect_value_handle(value_eq_true))_gr_:

.. das:function:: serialize(arch: Archive; value: auto(TT)&)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyFunctionNonPtrMacro_c_expect_any_function(value_eq_true)_gr_:

.. das:function:: serialize(arch: Archive; value: auto(TT)&)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyStructMacro_c_expect_any_struct(value_eq_true)_gr_:

.. das:function:: serialize(arch: Archive; value: auto(TT)&)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyTupleNonPtrMacro_c_expect_any_tuple(value_eq_true)_gr_:

.. das:function:: serialize(arch: Archive; value: auto(TT)&)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__&Y_ls_TT_gr_._%_ls_IsAnyVariantNonPtrMacro_c_expect_any_variant(value_eq_true)_gr_:

.. das:function:: serialize(arch: Archive; value: auto(TT)&)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)&                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr___lb_-1_rb_Y_ls_TT_gr_.:

.. das:function:: serialize(arch: Archive; value: auto(TT)[])

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)[-1]                                      +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_TT_gr_._gr_A:

.. das:function:: serialize(arch: Archive; value: array<auto(TT)>)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +array<auto(TT)>                                   +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_KT_gr_._gr_2_ls_Y_ls_VT_gr_._gr_T:

.. das:function:: serialize(arch: Archive; value: table<auto(KT);auto(VT)>)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +table<auto(KT);auto(VT)>                          +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

.. _function-_at_archive_c__c_serialize_S_ls_archive_c__c_Archive_gr__1_ls_Y_ls_TT_gr_._gr__qm_:

.. das:function:: serialize(arch: Archive; value: auto(TT)?)

serialize returns auto

+--------+--------------------------------------------------+
+argument+argument type                                     +
+========+==================================================+
+arch    + :ref:`archive::Archive <struct-archive-Archive>` +
+--------+--------------------------------------------------+
+value   +auto(TT)?                                         +
+--------+--------------------------------------------------+


todo: implement preallocat string with raii

++++++++++++++
Memory archive
++++++++++++++

  *  :ref:`mem_archive_save (t:auto& -const) : auto <function-_at_archive_c__c_mem_archive_save_&.>` 
  *  :ref:`mem_archive_load (data:array\<uint8\> -const;t:auto& -const;canfail:bool const) : bool <function-_at_archive_c__c_mem_archive_load_1_ls_u8_gr_A_&._Cb>` 

.. _function-_at_archive_c__c_mem_archive_save_&.:

.. das:function:: mem_archive_save(t: auto&)

mem_archive_save returns auto

+--------+-------------+
+argument+argument type+
+========+=============+
+t       +auto&        +
+--------+-------------+


将对象保存到内存存档。Result 是<uint8>包含序列化数据的数组。

.. _function-_at_archive_c__c_mem_archive_load_1_ls_u8_gr_A_&._Cb:

.. das:function:: mem_archive_load(data: array<uint8>; t: auto&; canfail: bool const)

mem_archive_load returns bool

+--------+-------------+
+argument+argument type+
+========+=============+
+data    +array<uint8> +
+--------+-------------+
+t       +auto&        +
+--------+-------------+
+canfail +bool const   +
+--------+-------------+


从内存存档中加载对象。`data`是从`mem_archive_save`返回的包含序列化数据的array<uint8>数组。