.. _设计思想:

##################
matopy 的设计思想
##################

.. contents::

设计思路
======================

通过 matlabarray 类模仿 matlab 中的矩阵、数组，以便在 python 代码中使用 matlab 的各种约定，例如“下标从1开始”等。

通过 cellarray 类模仿 matlab 中的 cell array 元胞数组，用来存放类型各异的元素。

以此达到 python 转译代码和原始 matlab 代码基本一样的目的。

如何解决 matlab 中可以将单个数字作为 1x1 矩阵使用的问题？

答：有几种方案：

1、在需要单个数字的时候将 matlabarray 对象转换为单个数字，这需要修改所有的函数，显然是比较低效的。

2、由用户在具体使用 matopy-lib 的 python 代码中进行转换，但这会给调试、转换代码带来一定的工作量，对 matopy-lib 的使用者不友好。

3、在 matopy-lib 库函数中处理，这样对 matopy-lib 的用户很友好，目前我们采用这种处理方式，遇到一个处理一个。


============================
matlab 的重要规则
============================

matlab 中的向量
----------------------------

matlab 中的 **向量** 都是横向排列的、是一行而不是一列，并且 ``size=[1 n]``，如果要表示列则用 **列向量**。

**列向量** 是竖向排列的数组，``size=[n 1]``。


matlab 的字符数组 vs. 字符串数组
---------------------------------
matlab中的 **字符数组** 与 **字符串数组** 的区别是:

1. 创建方式不一样。**字符数组** 用单引号 ``''`` 创建，而 **字符串数组** 用双引号 ``""`` 创建。
例如::

    c_arr = '字符数组'
    str_arr = "字符串数组"

    注意：这里的 str_arr 虽然称为字符串数组，但它的 size 是 [1 1]，即数组只有一个元素。

2. 基本单元不一样。**字符数组** 的最小单元是一个字符，而 **字符串数组** 的最小单元是 **字符串**，因此体现在 size 上也不一样。
例如::

    c_arr = '字符数组'
    size(c_arr)
    >>> [1 4]

    str_arr = "字符串数组"
    size(c_arr)
    >>> [1 1]

因此可以用 **字符串数组** 存放不同长度的 *字符串*，例如::

    str_arr = ["字符串1" "字符串2"
               "短串"    "超长字符串也可以"]
    size(str_arr)
    >>> [ 2 2 ]

但这对于 **字符数组** 就不行，例如::

    c_arr = ['字符串1' '字符串2'
             '短串'    '超长字符串也可以']
    >>> 错误使用 vertcat
    >>> 要串联的数组的维度不一致。


参数解析规则
----------------
在matlab中，参数规则非常灵活，这对使用者方便，但对开发者不利。主要体现在可选参数上，必须依靠明确的‘语法’才能确定具体的参数含义。
例如 fread 的参数有下面的语法：

    A = fread(fileID)
    A = fread(fileID,sizeA)
    A = fread(fileID,precision)
    A = fread(fileID,sizeA,precision)
    A = fread(___,skip)
    A = fread(___,machinefmt)
    [A,count] = fread(___)

如果调用形式是 ``A=fread(fid, "uint8")`` 那么开发者在实现 fread 函数时如何确定第二个位置参数是 precision 而不是 sizeA 呢？
答案是依靠参数类型确定。因为 sizeA 的类型是 ``Inf （默认） | 整数 | 二元素行向量`` 而 precision 的类型是 ``'uint8=>double' （默认） | 字符向量或字符串标量``。

这就需要我们开发一种依靠‘语法规则’解析参数的统一机制，简化 python 中开发 matlab 函数的工作量。

===========================================
Matlab fopen() 的 permission 参数的区别
===========================================

python 中的 mode 参数：

+------------+-------------------------------------------------------------------+
| Character  | Meaning                                                           |
+============+===================================================================+
| 'r'        | open for reading (default)                                        |
+------------+-------------------------------------------------------------------+
| 'w'        | open for writing, truncating the file first                        |
+------------+-------------------------------------------------------------------+
| 'x'        | open for exclusive creation, failing if the file already exists   |
+------------+-------------------------------------------------------------------+
| 'a'        | open for writing, appending to the end of file if it exists       |
+------------+-------------------------------------------------------------------+
| 'b'        | binary mode                                                       |
+------------+-------------------------------------------------------------------+
| 't'        | text mode (default)                                               |
+------------+-------------------------------------------------------------------+
| '+'        | open for updating (reading and writing)                           |
+------------+-------------------------------------------------------------------+

matlab 中的 permission 参数：

+------+--------------------------------------------+
| 模式 |                意义                         |
+======+============================================+
| 'r'  | 打开要读取的文件。                            |
+------+--------------------------------------------+
| 'w'  | 打开或创建要写入的新文件。                     |
|      | 放弃现有内容（如果有）。                       |
+------+--------------------------------------------+
| 'a'  | 打开或创建要写入的新文件。                     |
|      | 追加数据到文件末尾。                          |
+------+--------------------------------------------+
| 'r+' | 打开要读写的文件。                            |
+------+--------------------------------------------+
| 'w+' | 打开或创建要读写的新文件。                     |
|      | 放弃现有内容（如果有）。                       |
+------+--------------------------------------------+
| 'a+' | 打开或创建要读写的新文件。                     |
|      | 追加数据到文件末尾。                          |
+------+--------------------------------------------+
| 'A'  | 打开文件以追加（但不自动刷新）当前输出           |
|      | 缓冲区。                                    |
+------+--------------------------------------------+
| 'W'  | 打开文件以写入（但不自动刷新）当前输出           |
|      | 缓冲区。                                    |
+------+--------------------------------------------+

要以文本模式打开文件，请将字母 't' 附加到 permission 参数，例如 'rt' 或 'wt+'。

模式差异
-----------

1. Matlab 的 permission 没有 'x' 参数。open for exclusive creation, failing if the file already exists.
2. python 的 mode 可以用 '+' 替代 matlab 中的 'r+'.
3. python 没有 matlab 的 'A', 'W' 模式。
4. 注意：matlab 和 python 中 'w' 模式都会将文件清零，要更新文件，需要用 'r+' 模式、'a'模式。其中 'r+' 模式打开文件后文件指针在第一个字节，
而 'a' 模式打开文件后，文件指针在最后一个字节。
5. 因为 python 支持 'w+' 模式，表示‘清空文件、读写’，所以 matlab 的 permission 可以直接用于 python 的 mode 参数，只需要：

    1. matlab 的 permission 中如果没有 't'，就表示二进制模式，那么 python 的 mode 参数要添加 'b' 字母。
    2. matlab 的 permission 中如果有 't'，那么 python 的 mode 参数也要保留 't' 参数。

.. vim: tw=70:sw=2