PCRE2 API简单使用

PCRE2 API 简单使用

网络上没有足够好的中文资料，只有官网英文文档，有必要搞一个技术文档翻译工具！

API概述

编译正则表达式

pcre2_compile

函数原型：

pcre2_code *pcre2_compile(PCRE2_SPTR pattern, PCRE2_SIZE length, uint32_t options, int *errorcode, PCRE2_SIZE *erroroffset, pcre2_compile_context *ccontext);

该函数将正则表达式模式编译为内部形式。其参数是：

  • pattern 要编译的正则表达式字符串
  • length 正则字符串长度或者PCRE2_ZERO_TERMINATED
  • options 选项位
  • errorcode 错误代码存放处
  • erroffset 發生错误的偏移量
  • ccontext 指向一个编译上下文的指针或者NULL

正则表达式的长度和返回的任何错误偏移量均以 code unit 而不是字符为单位。需要编译上下文，仅当您想要提供自定义内存分配函数，或者提供用于系统堆栈大小检查的外部函数，或者更改以下一个或多个参数时：

\R 匹配什么 (Unicode换行符，或者仅匹配 CR, LF, CRLF);
PCRE2的字符表;
换行符序列;
编译时嵌套括号限制;
允许的最大正则表达式长度(以 code unit 为单位);
附加选项位(见pcre2_set_compile_extra_options())

选项位有：

  • PCRE2_ANCHORED 强制正则锚定
  • PCRE2_ALLOW_EMPTY_CLASS 允许空的类
  • PCRE2_ALT_BSUX \u, \U, 和 \x 的替代处理
  • PCRE2_ALT_CIRCUMFLEX 多行模式下 ^ 的替代处理
  • PCRE2_ALT_VERBNAMES 处理动词名称中的反斜杠
  • PCRE2_AUTO_CALLOUT 编译自动标注
  • PCRE2_CASELESS 大小写不敏感的匹配
  • PCRE2_DOLLAR_ENDONLY $ 不匹配行结束
  • PCRE2_DOTALL . 匹配任何字符也包括 NL
  • PCRE2_DUPNAMES 允许子正则重复名称
  • PCRE2_ENDANCHORED 正则表达式只能在主字符串末尾匹配
  • PCRE2_EXTENDED 忽略空格和 # 注释
  • PCRE2_FIRSTLINE 强制在换行符之前 做匹配
  • PCRE2_LITERAL 正则字符都是文字
  • PCRE2_MATCH_INVALID_UTF 启用对匹配无效 UTF 的支持
  • PCRE2_MATCH_UNSET_BACKREF 匹配未设置的反向引用
  • PCRE2_MULTILINE ^ 和 $ 匹配数据中的换行符
  • PCRE2_NEVER_BACKSLASH_C 在正则中锁定 \C 的使用
  • PCRE2_NEVER_UCP 锁定 PCRE2_UCP，例如: 以 (*UCP)
  • PCRE2_NEVER_UTF 锁定 PCRE2_UTF，例如: 以 (*UTF)
  • PCRE2_NO_AUTO_CAPTURE 禁用带编号的捕获括号(命名括号仍是可用)
  • PCRE2_NO_AUTO_POSSESS 禁用自动占有
  • PCRE2_NO_DOTSTAR_ANCHOR 禁用 .* 的自动锚定
  • PCRE2_NO_START_OPTIMIZE 禁用匹配时期启动优化
  • PCRE2_NO_UTF_CHECK 不检查正则的 UTF 有效性(仅当设置 PCRE2_UTF 时才涉及此选项)
  • PCRE2_UCP 对 \d, \w 等使用 Unicode 属性
  • PCRE2_UNGREEDY 量词的贪婪反转
  • PCRE2_USE_OFFSET_LIMIT 启用非锚定匹配的偏移限制
  • PCRE2_UTF 将正则和主字符串视为 UTF 字符串

PCRE2 必须使用 Unicode 支持（默认）构建，才能使用 PCRE2_UTF、PCRE2_UCP 和相关选项。

可以通过 pcre2_set_compile_extra_options 函数在编译上下文中设置其他选项。

该函数的返回值是一个指向包含已编译模式的私有数据结构的指针，如果检测到错误则为 NULL。

pcre2_get_error_message

函数原型：

int pcre2_get_error_message(int errorcode, PCRE2_UCHAR *buffer, PCRE2_SIZE bufflen);

此函数为每个 PCRE2 错误代码提供文本错误消息。编译错误代码为正数， UTF 格式错误代码和匹配错误代码均为负数。参数是：

  • errorcode 错误代码(正或负)
  • buffer 存放消息处
  • bufflen buffer的长度(以 code unit 为单位)

该函数返回以 code unit 为单位的消息长度，不包括尾随零，或者如果缓冲区太小则返回负错误代码 PCRE2_ERROR_NOMEMORY。在这种情况下，返回的消息被截断（但仍带有尾随零）。如果错误代码不包含可识别的错误代码编号，则返回PCRE2_ERROR_BADDATA(值为负)。

pcre2_pattern_info

函数原型：

int pcre2_pattern_info(const pcre2_code *code, uint32_t what, void *where);

此函数返回有关已编译模式的信息。其参数是：

  • code 指向已编译正则表达式模式的指针
  • what 需要什么信息
  • where 信息放在哪里

what 参数的公认值及其请求的信息如下：

  • PCRE2_INFO_ALLOPTIONS 编译后的最终选项
  • PCRE2_INFO_ARGOPTIONS 传递给pcre2_compile()的选项
  • PCRE2_INFO_BACKREFMAX 反向引用的最大编号
  • PCRE2_INFO_BSR \R 匹配什么: PCRE2_BSR_UNICODE(Unicode行结束符), PCRE2_BSR_ANYCRLF(仅 CR, LF, 或 CRLF)
  • PCRE2_INFO_CAPTURECOUNT 捕获子正则的数量
  • PCRE2_INFO_DEPTHLIMIT 回溯深度限制(如果有)，否则得到 PCRE2_ERROR_UNSET
  • PCRE2_INFO_EXTRAOPTIONS 传递给编译上下文的额外选项
  • PCRE2_INFO_FIRSTBITMAP 首个 code unit 的位图，或者 NULL
  • PCRE2_INFO_FIRSTCODETYPE 匹配开始信息的类型: 0(未设置), 1(首个 code unit 已设置), 2(字符串开头或换行符之後)
  • PCRE2_INFO_FIRSTCODEUNIT 首个 code unit，当 PCRE2_INFO_FIRSTCODETYPE 类型是 1
  • PCRE2_INFO_FRAMESIZE 回溯帧尺寸
  • PCRE2_INFO_HASBACKSLASHC 请求信息 1 (如果正则包含 \C)
  • PCRE2_INFO_HASCRORLF 请求信息 1 (如果正则存在显式 CR 或 LF 匹配)
  • PCRE2_INFO_HEAPLIMIT 堆内存限制(如果有)，否则得到 PCRE2_ERROR_UNSET
  • PCRE2_INFO_JCHANGED 请求信息 1 (如果 (?J) 或 (?-J) 被使用)
  • PCRE2_INFO_JITSIZE JIT 编译的代码大小或者 0
  • PCRE2_INFO_LASTCODETYPE 必须提供的信息类型: 0(未设置), 1(已设置code unit)
  • PCRE2_INFO_LASTCODEUNIT 最後一个 code unit，当 PCRE2_INFO_LASTCODETYPE 类型是 1
  • PCRE2_INFO_MATCHEMPTY 请求信息 1(如果正则可以匹配空字符串), 0(其他情况)
  • PCRE2_INFO_MATCHLIMIT 匹配限制(如果有)，否则得到 PCRE2_ERROR_UNSET
  • PCRE2_INFO_MAXLOOKBEHIND 最长后行断言的长度（以字符为单位）
  • PCRE2_INFO_MINLENGTH 匹配字符串的下限长度
  • PCRE2_INFO_NAMECOUNT 命名子正则的数量
  • PCRE2_INFO_NAMEENTRYSIZE 名称表条目的大小
  • PCRE2_INFO_NAMETABLE 命名表的指针
  • PCRE2_CONFIG_NEWLINE 换行序列的代码: PCRE2_NEWLINE_CR, PCRE2_NEWLINE_LF, PCRE2_NEWLINE_CRLF, PCRE2_NEWLINE_ANY, PCRE2_NEWLINE_ANYCRLF, PCRE2_NEWLINE_NUL
  • PCRE2_INFO_RECURSIONLIMIT （此项已过时）同等于PCRE2_INFO_DEPTHLIMIT
  • PCRE2_INFO_SIZE 编译後正则的大小

如果 where 为 NULL，则该函数返回请求的信息所需的内存量（以字节为单位）。否则，当 where 参数必须指向所示类型的变量时，where 参数必须指向无符号 32 位整数（uint32_t 变量），以下 what 值除外：

  • PCRE2_INFO_FIRSTBITMAP const uint8_t *
  • PCRE2_INFO_JITSIZE size_t
  • PCRE2_INFO_NAMETABLE PCRE2_SPTR
  • PCRE2_INFO_SIZE size_t

函数返回值是零(成功时)或者：

  • PCRE2_ERROR_NULL code 参数是 NULL
  • PCRE2_ERROR_BADMAGIC "magic number"未找到
  • PCRE2_ERROR_BADOPTION what 的值无效
  • PCRE2_ERROR_BADMODE 正则以错误模式编译
  • PCRE2_ERROR_UNSET 请求信息未设置

创建匹配数据体

pcre2_match_data_create

函数原型：

pcre2_match_data *pcre2_match_data_create(uint32_t ovecsize, pcre2_general_context *gcontext);

该函数创建一个新的匹配数据块，用于保存匹配结果。第一个参数指定所需的偏移对的数量。这形成在匹配数据块内的"输出向量"(ovector)，并用于在 pcre2_match() 匹配时识别匹配的字符串和任何捕获的子字符串，或者用于在 pcre2_dfa_match() 时在同一点上识别不同的匹配数量。总会有一对偏移量；如果 ovecsize 为零，则将其视为 1。

第二个参数指向一般上下文，使用自定义内存管理，或者为 NULL (使用系统内存管理)。如果无法获得该块的内存，则该函数的返回结果为 NULL。

pcre2_match_data_create_from_pattern

函数原型：

pcre2_match_data *pcre2_match_data_create_from_pattern( const pcre2_code *code, pcre2_general_context *gcontext);

该函数创建一个新的匹配数据块，用于保存匹配结果。第一个参数指向已编译正则。正则内捕获括号的数量用于计算匹配数据块中所需的偏移对的数量。这形成在匹配数据块内的"输出向量"(ovector)，并用于在 pcre2_match() 匹配时识别匹配的字符串和任何捕获的子字符串。如果使用 pcre2_dfa_match()，它以不同的方式使用输出向量，你应使用 pcre2_match_data_create() 而不是此函数。

第二个参数指向一般上下文，使用自定义内存管理，或者为 NULL (使用已编译正则同样的内存管理)。如果无法获得该块的内存，则该函数的返回结果为 NULL。

获取匹配数据

pcre2_match

函数原型：

int pcre2_match(const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *mcontext);

该函数使用类似于 Perl 的匹配算法，将已编译的正则表达式与给定的主字符串进行匹配。它返回已匹配的偏移对个数，并通过 match_data 捕获子字符串，该子字符串可由函数名称以 pcre2_get_ovector_...() 或 pcre2_substring_...() 开头的函数处理。 pcre2_match() 的返回值比已设置的捕获组的最高编号多 1（例如，如果没有捕获，则为 1）；如果存放偏移量的向量太小，则返回零；如果不匹配或有其他错误，则返回值为负的错误代码。此函数参数是：

  • code 指向已编译的正则
  • subject 指向主字符串
  • length 主字符串的长度
  • startoffset 主字符串开始匹配位置的偏移量
  • options 选项位
  • match_data 指向匹配数据块，用于存放结果
  • mcontext 指向匹配上下文或为 NULL

仅当您想要执行以下操作时才需要匹配上下文：

  • 设置标注函数
  • 设置匹配的偏移限制
  • 更改堆内存限制
  • 更改回溯匹配限制
  • 更改回溯深度限制
  • 专门为匹配设置自定义内存管理

length 和 startoffset 是以 code unit 为单位，而不是字符为单位。对于由二进制零 code unit 终止的主字符串，length 可以为 PCRE2_ZERO_TERMINATED。options 选项有：

  • PCRE2_ANCHORED 仅在第一个位置匹配
  • PCRE2_COPY_MATCHED_SUBJECT 成功後，制作私有子字符串拷贝
  • PCRE2_ENDANCHORED 正则只能在主字符串末尾匹配
  • PCRE2_NOTBOL 子字符串不是行的开头
  • PCRE2_NOTEOL 子字符串不是行的结尾
  • PCRE2_NOTEMPTY 空字符串不是有效匹配
  • PCRE2_NOTEMPTY_ATSTART 子字符串开头的空字符串不是有效匹配
  • PCRE2_NO_JIT 不使用 JIT 匹配
  • PCRE2_NO_UTF_CHECK 不检查子字符串的 UTF 有效性（仅在编译时设置 PCRE2_UTF 时，才涉及此选项）
  • PCRE2_PARTIAL_HARD 即使存在完全匹配，也返回 PCRE2_ERROR_PARTIAL 表示部分匹配
  • PCRE2_PARTIAL_SOFT 如果未找到完全匹配，则返回 PCRE2_ERROR_PARTIAL 表示部分匹配

pcre2_dfa_match

函数原型：

int pcre2_dfa_match(const pcre2_code *code, PCRE2_SPTR subject, PCRE2_SIZE length, PCRE2_SIZE startoffset, uint32_t options, pcre2_match_data *match_data, pcre2_match_context *mcontext, int *workspace, PCRE2_SIZE wscount);

此函数使用另一种匹配算法将已编译的正则表达式与给定的主字符串进行匹配，该算法仅扫描主字符串一次（处理环视断言时除外）。该函数与 Perl 不兼容（与 Perl 兼容的匹配函数是 pcre2_match()）。该函数的参数是：

  • code 指向已编译的正则
  • subject 指向主字符串
  • length 主字符串的长度
  • startoffset 主字符串开始匹配位置的偏移量
  • options 选项位
  • match_data 指向匹配数据块，用于存放结果
  • mcontext 指向匹配上下文或为 NULL
  • workspace 指向用作工作空间的整数向量
  • wscount 向量中的元素数量

包含所有结果所需的输出向量的大小取决于同时匹配的数量，而不是模式中括号的数量。因此，在使用此函数时，不建议使用 pcre2_match_data_create_from_pattern() 创建匹配数据块。

仅当您想要设置标注函数或指定堆限制或匹配深度限制或递归深度限制时，才需要匹配上下文。 length 和 startoffset 是以 code unit 为单位，而不是字符为单位。options 选项有：

  • PCRE2_ANCHORED 仅在第一个位置匹配
  • PCRE2_COPY_MATCHED_SUBJECT 成功後，制作私有子字符串拷贝
  • PCRE2_ENDANCHORED 正则只能在主字符串末尾匹配
  • PCRE2_NOTBOL 子字符串不是行的开头
  • PCRE2_NOTEOL 子字符串不是行的结尾
  • PCRE2_NOTEMPTY 空字符串不是有效匹配
  • PCRE2_NOTEMPTY_ATSTART 子字符串开头的空字符串不是有效匹配
  • PCRE2_NO_UTF_CHECK 不检查子字符串的 UTF 有效性（仅在编译时设置 PCRE2_UTF 时，才涉及此选项）
  • PCRE2_PARTIAL_HARD 即使存在完全匹配，也返回 PCRE2_ERROR_PARTIAL 表示部分匹配
  • PCRE2_PARTIAL_SOFT 如果未找到完全匹配，则返回 PCRE2_ERROR_PARTIAL 表示部分匹配
  • PCRE2_DFA_RESTART 部分匹配後重新开始
  • PCRE2_DFA_SHORTEST 只返回最短的匹配

pcre2_get_startchar

函数原型：

PCRE2_SIZE pcre2_get_startchar(pcre2_match_data *match_data);

成功调用 pcre2_match() 获取的匹配块作为参数传递给此函数，此函数返回成功匹配开始的字符的 code unit 偏移量。对于非部分匹配，如果模式包含 \K 转义序列，则这可能与 ovector[0] 的值不同。然而，在部分匹配之后，该值始终与 ovector[0] 相同，因为 \K 不会影响部分匹配的结果。

pcre2_get_ovector_pointer

函数原型：

PCRE2_SIZE *pcre2_get_ovector_pointer(pcre2_match_data *match_data);

该函数返回一个指向偏移量向量的指针，该偏移量构成给定匹配数据块的一部分。可以通过调用 pcre2_get_ovector_count() 获取偏移对的数量。

pcre2_get_ovector_count

函数原型：

uint32_t pcre2_get_ovector_count(pcre2_match_data *match_data);

此函数返回构成给定匹配数据块一部分的 ovector 中偏移对的数量。

释放资源

pcre2_code_free

函数原型：

void pcre2_code_free(pcre2_code *code);

如果 code 为 NULL，则该函数不执行任何操作。否则，code 必须指向已编译的正则。此函数释放其内存，包括 JIT 编译器使用的任何内存。如果已编译的正则是通过调用 pcre2_code_copy_with_tables() 创建的，则字符表的内存也会被释放。

pcre2_match_data_free

函数原型：

void pcre2_match_data_free(pcre2_match_data *match_data);

如果 match_data 为 NULL，则该函数不执行任何操作。否则，match_data 必须指向一个匹配数据块，该函数使用一般上下文或创建它的编译模式中的内存释放函数来释放该数据块，如果未设置，则使用 free() 。

如果使用了 PCRE2_COPY_MATCHED_SUBJECT 且用此匹配数据块做了成功匹配，则也会释放随该块记住的子字符串的副本。

技术 > 计算机 > 软件 > C/C++ > 第三方库
#C/C++ #正则表达式
PCRE2 API简单使用
https://blog.siantao.top/技术/计算机/软件/C-C/第三方库/PCRE2 API简单使用/
作者
玉水仙楊
发布于
2023年10月4日
许可协议