diff --git a/README.markdown b/README.markdown index e963a854..e01e61f5 100644 --- a/README.markdown +++ b/README.markdown @@ -4123,7 +4123,7 @@ This feature was introduced in the `v0.2.1rc11` release. ngx.re.find ----------- -**syntax:** *from, to, err = ngx.re.find(subject, regex, options?, ctx?)* +**syntax:** *from, to, err = ngx.re.find(subject, regex, options?, ctx?, nth?)* **context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.** @@ -4160,6 +4160,17 @@ This example produces the output Because this API function does not create new Lua strings nor new Lua tables, it is much faster than [ngx.re.match](#ngxrematch). It should be used wherever possible. +Since the `0.9.3` release, an optional 5th argument, `nth`, is supported to specify which (submatch) capture's indexes to return. When `nth` is 0 (which is the default), the indexes for the whole matched substring is returned; when `nth` is 1, then the 1st submatch capture's indexes are returned; when `nth` is 2, then the 2nd submatch capture is returned, and so on. When the specified submatch does not have a match, then two `nil` values will be returned. Below is an example for this: + +```lua + +local str = "hello, 1234" +local from, to = ngx.re.find(str, "([0-9])([0-9]+)", "jo", nil, 2) +if from then + ngx.say("matched 2nd submatch: ", string.sub(str, from, to)) -- yields "234" +end +``` + This API function was first introduced in the `v0.9.2` release. [Back to TOC](#table-of-contents) diff --git a/doc/HttpLuaModule.wiki b/doc/HttpLuaModule.wiki index da37091f..cfac726d 100644 --- a/doc/HttpLuaModule.wiki +++ b/doc/HttpLuaModule.wiki @@ -3428,7 +3428,7 @@ To confirm that PCRE JIT is enabled, activate the Nginx debug log by adding the This feature was introduced in the v0.2.1rc11 release. == ngx.re.find == -'''syntax:''' ''from, to, err = ngx.re.find(subject, regex, options?, ctx?)'' +'''syntax:''' ''from, to, err = ngx.re.find(subject, regex, options?, ctx?, nth?)'' '''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*'' @@ -3464,6 +3464,16 @@ This example produces the output Because this API function does not create new Lua strings nor new Lua tables, it is much faster than [[#ngx.re.match|ngx.re.match]]. It should be used wherever possible. +Since the 0.9.3 release, an optional 5th argument, nth, is supported to specify which (submatch) capture's indexes to return. When nth is 0 (which is the default), the indexes for the whole matched substring is returned; when nth is 1, then the 1st submatch capture's indexes are returned; when nth is 2, then the 2nd submatch capture is returned, and so on. When the specified submatch does not have a match, then two nil values will be returned. Below is an example for this: + + + local str = "hello, 1234" + local from, to = ngx.re.find(str, "([0-9])([0-9]+)", "jo", nil, 2) + if from then + ngx.say("matched 2nd submatch: ", string.sub(str, from, to)) -- yields "234" + end + + This API function was first introduced in the v0.9.2 release. == ngx.re.gmatch ==