35.6. pgtypes 库

• 35 .6.1. 字串

• 35 .6.2. 数值类型

• 35 .6.3. 日期类型

• 35 .6.4. 时间戳类型

• 35 .6.5. 间隔类型

• 35 .6.6. 十进制类型

• 35 .6.7. pgtypeslib 的 errno 值

• 35 .6.8. pgtypeslib 的特殊常数

pgtypes 库将 PostgreSQL 数据库类型 Map 为可以在 C 程序中使用的 C 等价物。它还提供了使用 C 中的这些类型进行基本计算的功能，即无需 PostgreSQL 服务器的帮助。请参见以下示例：

EXEC SQL BEGIN DECLARE SECTION;
   date date1;
   timestamp ts1, tsout;
   interval iv1;
   char *out;
EXEC SQL END DECLARE SECTION;

PGTYPESdate_today(&date1);
EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
out = PGTYPEStimestamp_to_asc(&tsout);
printf("Started + duration: %s\n", out);
PGTYPESchar_free(out);

35 .6.1. 字串

诸如PGTYPESnumeric_to_asc之类的某些函数将指针返回到新分配的字符串。这些结果应使用PGTYPESchar_free而不是free释放。 (这仅在 Windows 上很重要，在 Windows 上有时需要由同一库完成内存分配和释放.)

35 .6.2. 数值类型

数值类型可以进行任意精度的计算。有关 PostgreSQL 服务器中的等效类型，请参见Section 8.1。由于具有任意精度，因此该变量需要能够动态扩展和收缩。这就是为什么只能通过PGTYPESnumeric_new和PGTYPESnumeric_free函数在堆上创建数字变量的原因。可以在堆栈以及堆上创建相似的十进制类型，但精度有所限制。

下列函数可用于数字类型：

• PGTYPESnumeric_new

  • 请求一个指向新分配的数字变量的指针。

numeric *PGTYPESnumeric_new(void);

• PGTYPESnumeric_free

  • 释放数字类型，释放其所有内存。

void PGTYPESnumeric_free(numeric *var);

• PGTYPESnumeric_from_asc

  • 从其字符串符号解析数字类型。

numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);

有效格式例如：-2，.794，+3.44，592.49E07或-32.84e-4。如果可以成功解析该值，则返回一个有效的指针，否则返回 NULL 指针。目前，ECPG 始终会解析完整的字符串，因此当前不支持将第一个无效字符的地址存储在*endptr中。您可以安全地将endptr设置为 NULL。

• PGTYPESnumeric_to_asc

  • 返回指向由malloc分配的字符串的指针，该指针包含数字类型num的字符串表示形式。

char *PGTYPESnumeric_to_asc(numeric *num, int dscale);

数值将以dscale个十进制数字打印，并在必要时进行四舍五入。必须使用PGTYPESchar_free()释放结果。

• PGTYPESnumeric_add

  • 将两个数值变量添加到第三个变量中。

int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);

该函数将变量var1和var2添加到结果变量result中。该函数在成功时返回 0，在错误情况下返回-1.

• PGTYPESnumeric_sub

  • 减去两个数值变量，然后将结果返回第三个。

int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);

该函数从变量var1减去变量var2。运算结果存储在变量result中。该函数在成功时返回 0，在错误情况下返回-1.

• PGTYPESnumeric_mul

  • 将两个数字变量相乘，然后将结果返回第三个变量。

int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);

该函数将变量var1和var2相乘。运算结果存储在变量result中。该函数在成功时返回 0，在错误情况下返回-1.

• PGTYPESnumeric_div

  • 除以两个数值变量，然后将结果返回第三个变量。

int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);

该函数将变量var1除以var2。运算结果存储在变量result中。该函数在成功时返回 0，在错误情况下返回-1.

• PGTYPESnumeric_cmp

  • 比较两个数值变量。

int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)

此函数比较两个数字变量。如果出现错误，则返回INT_MAX。成功后，该函数将返回以下三种可能的结果之一：

• 1，如果var1大于var2

• -1，如果var1小于var2

• 0，如果var1和var2相等

• PGTYPESnumeric_from_int

  • 将 int 变量转换为数字变量。

int PGTYPESnumeric_from_int(signed int int_val, numeric *var);

此函数接受带符号 int 类型的变量，并将其存储在数字变量var中。成功后，返回 0，失败则返回-1.

• PGTYPESnumeric_from_long

  • 将 long int 变量转换为数字变量。

int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);

此函数接受带符号的 long int 类型的变量，并将其存储在数字变量var中。成功后，返回 0，失败则返回-1.

• PGTYPESnumeric_copy

  • 将一个数字变量复制到另一个变量中。

int PGTYPESnumeric_copy(numeric *src, numeric *dst);

此函数将src指向的变量的值复制到dst指向的变量。成功返回 0，如果发生错误则返回-1.

• PGTYPESnumeric_from_double

  • 将类型为 double 的变量转换为数字。

int  PGTYPESnumeric_from_double(double d, numeric *dst);

此函数接受 double 类型的变量，并将结果存储在dst指向的变量中。成功返回 0，如果发生错误则返回-1.

• PGTYPESnumeric_to_double

  • 将数字类型的变量转换为双精度型。

int PGTYPESnumeric_to_double(numeric *nv, double *dp)

该函数将数字值从nv指向的变量转换为dp指向的 double 变量。成功返回 0，如果出现错误(包括溢出)，则返回-1.溢出时，全局变量errno将另外设置为PGTYPES_NUM_OVERFLOW。

• PGTYPESnumeric_to_int

  • 将数字类型的变量转换为 int。

int PGTYPESnumeric_to_int(numeric *nv, int *ip);

该函数将nv指向的变量的数值转换为ip指向的整数变量。成功返回 0，如果出现错误(包括溢出)，则返回-1.溢出时，全局变量errno将另外设置为PGTYPES_NUM_OVERFLOW。

• PGTYPESnumeric_to_long

  • 将数字类型的变量转换为 long。

int PGTYPESnumeric_to_long(numeric *nv, long *lp);

该函数将nv指向的变量的数值转换为lp指向的长整数变量。成功返回 0，如果出现错误(包括溢出)，则返回-1.溢出时，全局变量errno将另外设置为PGTYPES_NUM_OVERFLOW。

• PGTYPESnumeric_to_decimal

  • 将数字类型的变量转换为十进制。

int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);

该函数将src指向的变量的数值转换为dst指向的十进制变量。成功返回 0，如果出现错误(包括溢出)，则返回-1.溢出时，全局变量errno将另外设置为PGTYPES_NUM_OVERFLOW。

• PGTYPESnumeric_from_decimal

  • 将类型为十进制的变量转换为数字。

int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);

该函数将十进制值从src指向的变量转换为dst指向的数字变量。成功返回 0，如果发生错误则返回-1.由于十进制类型是数字类型的受限版本，因此此转换不会发生溢出。

35 .6.3. 日期类型

C 中的日期类型使您的程序可以处理 SQL 类型日期的数据。有关 PostgreSQL 服务器中的等效类型，请参见Section 8.5。

以下功能可用于日期类型：

• PGTYPESdate_from_timestamp
  • 从时间戳中提取日期部分。

date PGTYPESdate_from_timestamp(timestamp dt);

该函数接收时间戳作为其唯一参数，并从该时间戳返回提取的日期部分。

• PGTYPESdate_from_asc
  • 从文本表示中解析日期。

date PGTYPESdate_from_asc(char *str, char **endptr);

该函数接收一个 C char *字符串str和一个指向 C char *字符串endptr的指针。目前，ECPG 始终会解析完整的字符串，因此当前不支持将第一个无效字符的地址存储在*endptr中。您可以安全地将endptr设置为 NULL。

请注意，该函数始终采用 MDY 格式的日期，并且 ECPG 中当前没有可更改该日期的变量。

Table 35.2显示允许的 Importing 格式。

表 35.2 PGTYPESdate_from_asc 的有效 Importing 格式

• PGTYPESdate_to_asc
  • 返回日期变量的文本表示形式。

char *PGTYPESdate_to_asc(date dDate);

该函数接收日期dDate作为其唯一参数。它将以1999-01-18格式(即YYYY-MM-DD格式)输出日期。结果必须用PGTYPESchar_free()释放。

• PGTYPESdate_julmdy
  • 从日期类型的变量中提取日，月和年的值。

void PGTYPESdate_julmdy(date d, int *mdy);

该函数接收日期d和指向 3 个整数值mdy的数组的指针。变量名称指示 Sequences：mdy[0]将设置为包含月份的数字，mdy[1]将被设置为 day 的值，mdy[2]将包含年份。

• PGTYPESdate_mdyjul
  • 从 3 个整数数组创建一个日期值，这些整数指定日期的日期，月份和年份。

void PGTYPESdate_mdyjul(int *mdy, date *jdate);

该函数将 3 个整数(mdy)的数组作为第一个参数，并将第二个参数作为指向类型为 date 的变量的指针，该变量应保存操作的结果。

• PGTYPESdate_dayofweek
  • 返回一个代表星期几的数字作为日期值。

int PGTYPESdate_dayofweek(date d);

该函数接收日期变量d作为其唯一参数，并返回一个整数，该整数指示该日期的星期几。

• 0 -周日

• 1 -星期一

• 2 -周二

• 3 -星期三

• 4 -星期四

• 5 -星期五

• 6 -周六

• PGTYPESdate_today

  • 获取当前日期。

void PGTYPESdate_today(date *d);

该函数接收指向其设置为当前日期的日期变量(d)的指针。

• PGTYPESdate_fmt_asc
  • 使用格式掩码将日期类型的变量转换为其文本表示形式。

int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);

该函数接收要转换的日期(dDate)，格式掩码(fmtstring)和用于保存日期文本表示的字符串(outbuf)。

成功时，返回 0，如果发生错误，则返回负值。

以下 Literals 是您可以使用的字段说明符：

• dd-每月的天数。

• mm-一年中的月份号。

• yy-年份数字(两位数)。

• yyyy-年份数字(四位数)。

• ddd-星期几的名称(缩写)。

• mmm-月份的名称(缩写)。

将所有其他字符 1：1 复制到输出字符串。

Table 35.3表示几种可能的格式。这将使您了解如何使用此功能。所有输出行均基于同一日期：1959 年 11 月 23 日。

表 35.3. PGTYPESdate_fmt_asc 的有效 Importing 格式

• PGTYPESdate_defmt_asc
  • 使用格式掩码将 C char*字符串转换为 date 类型的值。

int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);

该函数接收一个指向日期值的指针，该日期值应保存操作的结果(d)，用于解析日期的格式掩码(fmt)和包含日期的文本表示形式的 C char *字符串(str)。文本表示应与格式掩码匹配。但是，您无需将字符串与格式掩码进行 1：1Map。该函数仅分析 Sequences，并寻找表示年份位置的 Literalsyy或yyyy，mm指示月份的位置和dd指示日期的位置。

Table 35.4表示几种可能的格式。这将使您了解如何使用此功能。

表 35.4. rdefmtdate 的有效 Importing 格式

35 .6.4. 时间戳类型

C 中的时间戳类型使您的程序可以处理 SQL 类型的时间戳数据。有关 PostgreSQL 服务器中的等效类型，请参见Section 8.5。

以下函数可用于时间戳类型：

• PGTYPEStimestamp_from_asc
  • 将时间戳从其文本表示形式解析为时间戳变量。

timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);

该函数接收要解析的字符串(str)和指向 C char *(endptr)的指针。目前，ECPG 始终会解析完整的字符串，因此当前不支持将第一个无效字符的地址存储在*endptr中。您可以安全地将endptr设置为 NULL。

函数成功返回解析的时间戳。错误时，将返回PGTYPESInvalidTimestamp并将errno设置为PGTYPES_TS_BAD_TIMESTAMP。有关此值的重要说明，请参见PGTYPESInvalidTimestamp。

通常，Importing 字符串可以包含允许的日期规范，空格字符和允许的时间规范的任意组合。请注意，ECPG 不支持时区。它可以解析它们，但是不应用任何计算，例如 PostgreSQL 服务器。时区说明符被静默丢弃。

Table 35.5包含一些 Importing 字符串的示例。

表 35.5. PGTYPEStimestamp_from_asc 的有效 Importing 格式

• PGTYPEStimestamp_to_asc
  • 将日期转换为 C char *字符串。

char *PGTYPEStimestamp_to_asc(timestamp tstamp);

该函数将时间戳tstamp作为唯一参数接收，并返回一个分配的字符串，其中包含时间戳的文本表示形式。必须使用PGTYPESchar_free()释放结果。

• PGTYPEStimestamp_current
  • 检索当前时间戳。

void PGTYPEStimestamp_current(timestamp *ts);

该函数检索当前时间戳并将其保存到ts指向的时间戳变量中。

• PGTYPEStimestamp_fmt_asc
  • 使用格式掩码将时间戳变量转换为 C char *。

int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);

该函数接收指向时间戳的指针以将其转换为第一个参数(ts)，指向输出缓冲区(output)的指针，已分配给输出缓冲区的最大长度(str_len)和用于该缓冲区的格式掩码转换(fmtstr)。

成功后，函数将返回 0，如果发生错误，则返回负值。

您可以使用以下格式说明符作为格式掩码。格式说明符与 libc 的strftime函数中使用的说明符相同。任何非格式说明符都将被复制到输出缓冲区中。

• %A-由工作日全名的国家代表代替。

• %a-由缩写的工作日名称的国家/地区表示代替。

• %B-由全月名称的国家/地区表示代替。

• %b-由缩写月份名称的国家/地区表示代替。

• %C-替换为(年/ 100)作为十进制数字；单个数字后跟零。

• %c-由时间和日期的国家表示代替。

• %D-等效于%m/%d/%y。

• %d-替换为月份中的十进制数字(01-31)。

• %E* %O*-POSIX 语言环境扩展。序列%Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy应该被提供替代表示。

此外，还实现了%OB来表示其他月份的名称(独立使用，未提及日期)。

• %e-用一个月的日期替换为十进制数字(1-31)；单个数字后跟一个空格。

• %F-等效于%Y-%m-%d。

• %G-用世纪代替十进制数字形式的年份。今年是一周中大部分时间的月份(星期一为一周的第一天)。

• %g-替换为与%G相同的年份，但替换为不含世纪的十进制数字(00-99)。

• %H-由小时(24 小时制)代替十进制数字(00-23)。

• %h-与%b相同。

• %I-由小时(12 小时制)替换为十进制数字(01-12)。

• %j-由一年中的日期替换为十进制数字(001-366)。

• %k-由小时(24 小时制)替换为十进制数字(0-23)；单个数字后跟一个空格。

• %l-由小时(12 小时制)替换为十进制数字(1-12)；单个数字后跟一个空格。

• %M-由分钟代替十进制数字(00-59)。

• %m-替换为月份的十进制数字(01-12)。

• %n-用换行符代替。

• %O*-与%E*相同。

• %p-酌情由“前子午线”或“后子午线”的国家代表代替。

• %R-等效于%H:%M。

• %r-等效于%I:%M:%S %p。

• %S-由第二个十进制数字(00-60)代替。

• %s-被 UTC 以来的秒数代替。

• %T-等同于%H:%M:%S

• %t-替换为标签。

• %U-替换为年份的周号(星期日为一周的第一天)作为十进制数字(00-53)。

• %u-由工作日(星期一作为一周的第一天)替换为十进制数字(1-7)。

• %V-替换为年份的周号(星期一为一周的第一天)作为十进制数字(01-53)。如果包含 1 月 1 日的一周在新年中有四天或更多天，则为第一周；否则是上一年的最后一周，下周是第 1 周。

• %v-等效于%e-%b-%Y。

• %W-替换为年份的星期数(星期一作为星期的第一天)作为十进制数字(00-53)。

• %w-由工作日(星期日为一周的第一天)替换为十进制数字(0-6)。

• %X-由时间的国家代表代替。

• %x-由日期的国家代表代替。

• %Y-由年份代替，以世纪作为十进制数字。

• %y-被不带世纪的年份替换为十进制数字(00-99)。

• %Z-替换为时区名称。

• %z-由与 UTC 的时区偏移量代替；前导加号表示 UTC 的东部，负号表示 UTC 的西部，小时和分钟后跟两个数字，并且两者之间没有定界符(RFC 822 日期 Headers 的通用格式)。

• %+-由日期和时间的国家表示代替。

• %-*-GNU libc 扩展。执行数字输出时，请勿进行任何填充。

• $ _ *-GNU libcextensions。明确指定用于填充的空间。

• %0*-GNU libc 扩展。明确指定零填充。

• %%-替换为%。

• PGTYPEStimestamp_sub

  • 从另一个时间戳中减去一个时间戳，并将结果保存在类型为 interval 的变量中。

int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);

该函数将从ts1指向的 timestamp 变量中减去ts2指向的 timestamp 变量，并将结果存储在iv指向的 interval 变量中。

成功后，函数将返回 0，如果发生错误，则返回负值。

• PGTYPEStimestamp_defmt_asc
  • 使用格式掩码从其文本表示形式解析时间戳记值。

int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);

该函数在变量str中接收时间戳的文本表示形式，并在变量fmt中使用格式化掩码。结果将存储在d指向的变量中。

如果格式掩码fmt为 NULL，则该函数将退回到默认格式掩码%Y-%m-%d %H:%M:%S。

这是PGTYPEStimestamp_fmt_asc的反向功能。请参阅此处的文档，以了解有关可能的格式掩码条目的信息。

• PGTYPEStimestamp_add_interval
  • 将时间间隔变量添加到时间戳变量。

int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);

该函数接收指向时间戳变量tin的指针和指向间隔变量span的指针。它将间隔添加到时间戳，并将生成的时间戳保存在tout指向的变量中。

成功后，函数将返回 0，如果发生错误，则返回负值。

• PGTYPEStimestamp_sub_interval
  • 从时间戳变量中减去间隔变量。

int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);

该函数从tin指向的时间戳变量中减去span指向的间隔变量，并将结果保存到tout指向的变量中。

成功后，函数将返回 0，如果发生错误，则返回负值。

35 .6.5. 间隔类型

C 中的间隔类型使您的程序能够处理 SQL 类型间隔的数据。有关 PostgreSQL 服务器中的等效类型，请参见Section 8.5。

以下功能可用于间隔类型：

• PGTYPESinterval_new
  • 返回指向新分配的时间间隔变量的指针。

interval *PGTYPESinterval_new(void);

• PGTYPESinterval_free
  • 释放先前分配的时间间隔变量的内存。

void PGTYPESinterval_new(interval *intvl);

• PGTYPESinterval_from_asc
  • 从文本表示中解析一个间隔。

interval *PGTYPESinterval_from_asc(char *str, char **endptr);

该函数解析 Importing 字符串str，并返回指向分配的时间间隔变量的指针。目前，ECPG 始终会解析完整的字符串，因此当前不支持将第一个无效字符的地址存储在*endptr中。您可以安全地将endptr设置为 NULL。

• PGTYPESinterval_to_asc
  • 将类型为 interval 的变量转换为其文本表示形式。

char *PGTYPESinterval_to_asc(interval *span);

该函数将span指向的间隔变量转换为 C char *。输出如下例所示：@ 1 day 12 hours 59 mins 10 secs。结果必须用PGTYPESchar_free()释放。

• PGTYPESinterval_copy
  • 复制一个类型为 interval 的变量。

int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);

该函数将intvlsrc指向的时间间隔变量复制到intvldest指向的变量。请注意，您需要先为目标变量分配内存。

35 .6.6. 十进制类型

十进制类型类似于数字类型。但是，它的最大精度限制为 30 个有效数字。与只能在堆上创建的数字类型相反，十进制类型可以在堆栈或堆上创建(通过PGTYPESdecimal_new和PGTYPESdecimal_free函数)。在Section 35.15中描述的 Informix 兼容模式下，还有许多其他函数处理十进制类型。

以下函数可用于十进制类型，并且不仅包含在libcompat库中。

• PGTYPESdecimal_new

  • 请求一个指向新分配的十进制变量的指针。

decimal *PGTYPESdecimal_new(void);

• PGTYPESdecimal_free

  • 释放一个十进制类型，释放其所有内存。

void PGTYPESdecimal_free(decimal *var);

35 .6.7. pgtypeslib 的 errno 值

• PGTYPES_NUM_BAD_NUMERIC

  • 参数应包含数字变量(或指向数字变量)，但实际上其内存中表示形式无效。

• PGTYPES_NUM_OVERFLOW

  • 发生溢出。由于数字类型几乎可以处理任意精度，因此将数字变量转换为其他类型可能会导致溢出。

• PGTYPES_NUM_UNDERFLOW

  • 发生下溢。由于数字类型几乎可以处理任意精度，因此将数字变量转换为其他类型可能会导致下溢。

• PGTYPES_NUM_DIVIDE_ZERO

  • 试图除以零。

• PGTYPES_DATE_BAD_DATE

  • 无效的日期字符串传递给PGTYPESdate_from_asc函数。

• PGTYPES_DATE_ERR_EARGS

  • 无效的参数已传递给PGTYPESdate_defmt_asc函数。

• PGTYPES_DATE_ERR_ENOSHORTDATE

  • PGTYPESdate_defmt_asc函数在 Importing 字符串中找到了无效的标记。

• PGTYPES_INTVL_BAD_INTERVAL

  • 无效的间隔字符串传递给PGTYPESinterval_from_asc函数，或者无效的间隔值传递给PGTYPESinterval_to_asc函数。

• PGTYPES_DATE_ERR_ENOTDMY

  • PGTYPESdate_defmt_asc函数中的日/月/年分配不匹配。

• PGTYPES_DATE_BAD_DAY

  • PGTYPESdate_defmt_asc函数发现一个无效的月份值。

• PGTYPES_DATE_BAD_MONTH

  • PGTYPESdate_defmt_asc函数发现无效的月份值。

• PGTYPES_TS_BAD_TIMESTAMP

  • 无效的时间戳字符串传递给PGTYPEStimestamp_from_asc函数，或者无效的时间戳值传递给PGTYPEStimestamp_to_asc函数。

• PGTYPES_TS_ERR_EINFTIME

  • 在无法处理的上下文中遇到了无限的时间戳记值。

35 .6.8. pgtypeslib 的特殊常数

• PGTYPESInvalidTimestamp
  • timestamp 类型的值，表示无效的时间戳记。这是由函数PGTYPEStimestamp_from_asc在解析错误时返回的。请注意，由于内部表示timestamp数据类型，因此PGTYPESInvalidTimestamp同时也是有效时间戳。设置为1899-12-31 23:59:59。为了检测错误，请确保您的应用程序在每次调用PGTYPEStimestamp_from_asc之后，不仅要测试PGTYPESInvalidTimestamp，还要测试errno != 0。