数据类型说明
=============================================

.. _xresloader: https://github.com/xresloader/xresloader

数组、repeated和数据结构
---------------------------------------------

因为Excel配置很多情况下都会留空，所以默认情况下如果Excel里的单元格被删除（空值不算），我们不会转出数据到数组结构中。也就是我们的数组时动态长度的。这样可以最大化压缩掉空值项。
同样对于optional的字段，空单元格也不会生成数据在二进制结构里。

比如：

+-----------------+----------------+------------+
| 第一排          | 第二排         | 第三排     |
+-----------------+----------------+------------+
| col[0]          | col[1]         | col[2]     |
+=================+================+============+
| 123             |                | 456        |
+-----------------+----------------+------------+

这样转出来的数据 ``col`` 的数组长度是2，其中： ``col[0]=123, col[1]=456`` 。

.. _data-types-stable-array:

定长数组
---------------------------------------------

有些情况我们使用数组来表示位置。比如：

+-----------------+----------------+------------+
| 第一排          | 第二排         | 第三排     |
+-----------------+----------------+------------+
| row[0]          | row[1]         | row[2]     |
+=================+================+============+
| 123             |                | 456        |
+-----------------+----------------+------------+

这种情况，我们希望。能够保持结构，即让row[1]转出为0（默认值）。
这时候 `xresloader`_ 提供了一个选项 ``--enable-empty-list`` 。在转表的时候使用这个选项，这样转出的数据就会是: 
``row`` 的数组长度是3，其中 ``row[0]=123, row[1]=0, row[2]=456`` 。


无符号整数
---------------------------------------------
请注意有些语言（比如Java）没有无符号类型，但是协议层支持。转换这种类型的时候请确保Excel里填写的数值不会超出有符号类型的长度。否则可能导致裁剪。
在转表工具里，整数一律使用Long类型，所以注意即便协议类型是uint64，填写的数据也不要超过int64的范围。


日期和时间类型
---------------------------------------------

如果Excel的单元格的类型设置为日期时间类型则会使用日期时间类型的数据转换规则。

由于POI内部是使用格式来判定是否是日期时间类型的，所以如果要使用日期时间类型，最好把格式设置成 ``年-月-日 时:分:秒`` 这种形式。

Excel里只保存绝对值时间，如果格式设置为 ``时:分:秒`` 那么 ``10:11:12`` 转出的时间是 ``1900-01-01 10:11:12`` 或 ``1902-01-01 10:11:12`` 。
但是我们使用的时候很多情况下需要配置一天的某个时间段，为了满足这种需求，我们假设所有的绝对值时间都在1970年以后。那么年份在 **1970年或1970年之前** 的时间，我们都会只取时、分、秒的部分计算时间戳。
比如上面的 ``10:11:12`` 会被转成 ``10*3600+11*60+12=36672``  。

如果协议里的类型是字符串，那么时间转换的时候会检查时间格式，如果有“-”，则会按 ``yyyy-MM-dd`` 转换年月日部分；如果格式里有分号":"，则会按 ``HH:mm:ss`` 转换时分秒部分。
如果两者都有我们会按 ``yyyy-MM-dd HH:mm:ss`` 转换年月日时分秒。