TA-Lib C/C++ API文档

1.0 简介

本文档包含了提供给最终用户的所有函数。

2.0 如何编译连接TA-Lib 库

在C/C++项目中使用TA-Lib库，你只需包含“ta_libc.h”头文件，并根据应用类型连接到相应的静态库。

ta-lib/include目录包含了所需的所有头文件。其它目录的头文件绝不能被应用直接包含。

2.1 Windows - MSVC andVisual Studio

目前支持的静态库列表:

 

静态库名称	是否使用运行时DLL？	是否多线程？	是否包含调试信息？
ta_libc_csr.lib	-	-	-
ta_libc_csd.lib	-	-	是
ta_libc_cmr.lib	-	是	-
ta_libc_cmd.lib	-	是	是
ta_libc_cdr.lib	是	是	-
ta_libc_cdd.lib	是	是	是

 

MSVC包中包含这些库的预编译版本。如果你想重新编译这些静态库， ta-lib/c/make/<ENV>/win32/msvc目录下有makefile。这些makefile也适用于Visual Studio 2005。

其中 <ENV>是指3个字母的子目录 (cmd, cmr, csd, csr, cdd and cdr) ，用于匹配应用程序的运行时环境。

运行“nmake”或“nmake /A”，编译所有目标。生成的目标文件位于ta-lib/c/lib 目录和ta-lib/c/bin目录。

如果需要重新构建，可以运行“nmake clean”来清理项目，然后再次运行“nmake”。

• 不包含调试信息速度有所优化，但是不能跟踪调试。 
• Visual Studio 2005项目文件位于ta-lib/c/ide/vs2005 目录
• 如果在Windows上发现链接错误，检查“配置属性->C/C++->代码生成->运行库” 选项是否匹配选择的静态库类型。 
• 如果你的应用程序没有链接wininet和odbc32库，将显示链接错误。这些库一般和MSVC和Borland一起提供，在系统中应该可以找到。

2.2 Windows- Free C++ Borland Compiler

• 与Microsoft Visual C++相同，惟以下情况除外： Makefile位于 ta-lib/c/make/<ENV>/win32/borland 目录；并且不提供cdd和cdr库。 
• 编译使用Borland的“make”命令，而不是微软的“nmake” 命令。
• 如需要重新构建，运行“make clean”命令。由于Borland和MSVC的目标文件不同，MSVC使用COFF格式，Borland使用OMF格式，在这两个编译器间切换时，必须运行“make clean”，重新构建。

2.3 其它平台

2.3.1 Linux 静态链接库

SVN代码库和Win32包中有多个平台的makefile，包括Linux平台。Linux平台makefile位于ta-lib/c/make/<ENV>/linux/g++目录。

其中<ENV>是3个字符的子目录（cmd，cmr，csd，csr），具体含义参加2.1。其中cdd和cdr不适用于Linux。

运行“make clean”和“make”命令构建目标。生成目标位于ta-lib/c/lib and ta-lib/c/bin目录。编译应用程序时，需要连接到3个静态库： ta-abstract， ta-func 和 ta-common。

2.3.2 类Unix 系统共享链接库

下载tar.gz源码包，以root身份运行下列命令：

./configure
./make
./make install

TA-Lib包含在一个单独的共享库“libta-lib”（具体名字取决于平台）。

对gcc 编译器，使用“-lta-lib”选项，链接TA-Lib库。

2.4 回归测试（全平台）

当编译完整的源码树时，将会生成一个名为“ta_regtest”的程序，位于ta-lib/c/bin目录。这是一组测试套件，用于确认库是否构建成功。因此，每次重新编译TA-Lib库后，建议都运行ta_regtest程序。使用ta_regtest回归测试时，因为需要测试网络数据抓取功能，所以需要连接互联网。

3.0 技术分析函数

在调用其它API函数前，需要调用且仅调用一次TA_Initialize函数。

用户可以直接调用单个TA函数。如果用户想要整合多个TA函数，但又不知晓它们的参数，应该考虑使用抽象层接口。

源码中的所TA函数包含于ta-lib/src/ta_func目录。

3.1 直接调用TA函数

直接调用函数通过ta-lib/c/include/ta_func.h中定义的接口实现。所有的TA函数，都是简单的数学函数。用户提供一个输入数组，函数将结果保存在用户指定的输出数组中。TA函数并不为用户分配空间。产生的结果的数，不会超过输入数组中要求计算的元素个数。下面是一个例子：

我们将要解析TA_MA函数，这个函数用于计算移动平均数。

TA_RetCode TA_MA( int         startIdx,
                  int         endIdx,
                  constdouble inReal[],
                  int         optInTimePeriod,
                  int         optInMAType,
                  int        *outBegIdx,
                  int        *outNbElement,
                  double      outReal[],
                )

初看似乎有很多参数，不必担心，所有的函数都是一致的，拥有相同的参数结构。参数可划分为4部分：

• 输入数据计算范围：函数只计算从startIdx 到 endIdx参数范围内的输入数据；
• 一个或多个输入数组。在上面的例子中只有一个输入数组。所有的输入参数名都已“in”开头；
• 0个或多个可选输入。在这个例子中，有2个可选输入。这些可选输入，用于对函数进行微调。如果不关心以“optIn”开头的参数，只需指定TA_INTEGER_DEFAULT或TA_REAL_DEFAULT（取决于参数类型）；
• 最后这个区指定一个或多个输出。在这个例子中，只有一个输出outReal。其中outBegIdx和outNbElement参数用于指定输出范围，位于输出数组前。

这种参数结构提供了很大的灵活性，可以使函数只计算输入数组的一部分数据。这稍微有些复杂，但它可以允许有需求的用户高效管理内存和CPU处理。

比如，你希望计算收盘价30天移动平均线。可以如下调用此函数：

TA_Real    closePrice[400];

TA_Real    out[400];

TA_Integer outBeg;

TA_IntegeroutNbElement;

/* ... initializeyour closing price here... */

retCode = TA_MA( 0, 399,

                 &closePrice[0],

                 30,TA_MAType_SMA,

                 &outBeg,&outNbElement, &out[0] );

/* The output isdisplayed here */

for( i=0; i <outNbElement; i++ )

   printf( "Day %d = %f\n", outBeg+i,out[i] );

关于输出，需要注意一下这两个参数：outBeg 和 outNbElement。尽管要求计算数据范围为0到399，但是移动平均数直到第30个数才有意义。因此，outBeg将会赋值为29（从0开始索引），而outNbElement将会赋值为400-29=371。意思是前371个输出元素是有意义的。

再举一个例子，假设要求计算从125到225（startIdx和endIdx）范围内的移动平均数，outBeg将会返回125，outNbElement将会返回101。而输出数组out中只有前101个是有意义的。

如果提供的数据不足以计算哪怕一个结果，outNbElement将返回0，outBeg将被忽略。

如果TA函数的输入和输出类型相同，用户可以重用输入数组空间，来存储其中某个输出。下面的例子可以很好的运行：

#define BUFFER_SIZE 100

TA_Real buffer[BUFFER_SIZE];

...

retCode = TA_MA( 0, BUFFER_SIZE-1,

                 &buffer[0],

                 30, TA_MAType_SMA,

                 &outBeg, &outNbElement,&buffer[0] );

当然，输入被覆盖了，不过这个特性可以减少临时空间的分配。可以假定这个特性对所有TA函数都成立。

3.2 输出大小

有足够大的输出数组大小是很重要的。取决于你的需要，下面这些方法可以帮助你决定所需输出的大小。所有这些方法都是一致的，并适用于所有的TA函数：

方法	描述
匹配输入	allocationSize = endIdx + 1; 优点：易于理解和实现 缺点：指定范围很小时，可能会浪费很多空间
匹配计算范围	allocationSize = endIdx - startIdx + 1; 优点：易于实现 缺点：分配略大于需要。例如，计算区间为30的SMA，由于需要回溯（lookback），会浪费29个元素的存储空间。
精确分配	lookback = TA_XXXX_Lookback( ... ) ; temp = max( lookback, startIdx ); if( temp > endIdx )    allocationSize = 0; // No output else     allocationSize = endIdx - temp + 1; 优点：优化分配空间算法； 缺点：实现略显复杂

 

为每一个TA函数都提供了一个TA_XXXX_Lookback 回溯函数。例如：对于 TA_SMA，有一个 TA_SMA_Lookback回溯函数。

回溯函数返回在第一个结果被计算出前，已经消耗的输入元素个数。例如区间为10的SMA，将返回数值为9的回溯。

4.0 高级特性

4.1 抽象层

所有的TA函数可以使用ta-lib/c/include/ta_abstrac.h中定义的接口调用。如果你希望你的应用支持所有的TA函数，并且在在TA-Lib增加函数时，不想重新写代码，那么可以使用抽象层。但是如果你只想在你的应用中集成某些特定的TA函数，最好直接调用TA函数（参见前一小节）。

例子：

比方说你正在做一个图表软件。当用户选择一个price bar，在旁边将显示所有能够应用在price bar上的TA 函数。用户选择一个函数，将弹出一个对话框，允许用户调整可选参数（TA-LIB将告诉软件需要哪些参数，以及参数的可选择范围）。当所有参数都设置好后，就可以调用相应的TA函数了。函数的结果也可以绘制在图表上（一些输出标识可以提示数据如何绘制）。同样的“抽象”逻辑可以应用到所有TA函数。一些TA函数只能应用于数量，或可应用于任何时间序列数据（开盘价，收盘价，其它指标……）。这个“虚”接口可以决定所有可以应用到当前选定数据上的函数。

抽象层是一个十分复杂，但功能强大的接口。

4.2 不稳定时期

一些TA函数由于输入数据起始点不同提供了不同的运算结果。这通常被称为函数具有记忆。指数移动平均数是这样函数的一个例子。使用TA_SetUnstablePeriod和TA_GetUnstatablePeriod函数可以控制不稳定时期（丢掉数据的数量）。

4.3 输入类型：floatvs. double

对于每个技术分析算法，都提供了两个版本的函数：一个接受float类型的输入数组，一个接受double类型的输入数组。其中flaot版本的函数有一个TA_S_后缀。例如，对于TA_MA函数，有一个对应TA_S_MA函数。

TA_RetCode TA_MA( int   startIdx,
                 int    endIdx,
                  const double  inReal[],
                 int          optInTimePeriod, 
                 TA_MAType     optInMAType,
                 int          *outBegIdx,
                 int          *outNbElement,
                 double        outReal[] );

TA_RetCode TA_S_MA( int    startIdx,
                   int    endIdx,
                    const float inReal[],
                   int         optInTimePeriod,
                   TA_MAType   optInMAType,
                   int        *outBegIdx,
                   int        *outNbElement,
                   double      outReal[] );
 

两个版本都是用double类型进行计算，因此两个版本的函数会得到相同的结果。

典型的，用户使用float存储price bar数据，使用double存储中间计算结果。TA-Lib直接支持两种输入类型，在内存使用上更高效。如果只有一种类型，用户将不得不在调用TA函数前，将一种类型的输入数据，拷贝到另一种类型的数组中。