From 220f2a7d15adc6ca811a3cbe5fee79ce4904cd91 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 18 Oct 2005 20:38:58 +0000 Subject: Code review for regexp_replace patch. Improve documentation and comments, fix problems with replacement-string backslashes that aren't followed by one of the expected characters, avoid giving the impression that replace_text_regexp() is meant to be called directly as a SQL function, etc. --- doc/src/sgml/func.sgml | 73 +++++++++++++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 27 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index a641db7ee74..4ef1696c8c9 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ @@ -1193,9 +1193,6 @@ PostgreSQL documentation quote_literal - - regexp_replace - repeat @@ -1419,26 +1416,6 @@ PostgreSQL documentation 'O''Reilly' - - regexp_replace(source text, - pattern text, - replacement text - , flags text) - text - Replace string that matches the regular expression - pattern in source to - replacement. - replacement can use \1-\9 and \&. - \1-\9 is a back reference to the n'th subexpression, and - \& is the entire matched string. - flags can use g(global) and i(ignore case). - When flags is not specified, case sensitive matching is used, and it replaces - only the instance. - - regexp_replace('1112223333', '(\\d{3})(\\d{3})(\\d{4})', '(\\1) \\2-\\3') - (111) 222-3333 - - repeat(string text, number int) text @@ -2821,10 +2798,12 @@ cast(-44 as bit(12)) 111111010100 SIMILAR TO - substring + + regexp_replace + string SIMILAR TO pattern ESCAPE escape-character @@ -3002,7 +2981,7 @@ substring('foobar' from '#"o_b#"%' for '#') NULL A regular expression is a character sequence that is an abbreviated definition of a set of strings (a regular - set). A string is said to match a regular expression + set). A string is said to match a regular expression if it is a member of the regular set described by the regular expression. As with LIKE, pattern characters match string characters exactly unless they are special characters @@ -3027,7 +3006,8 @@ substring('foobar' from '#"o_b#"%' for '#') NULL The substring function with two parameters, substring(string from - pattern), provides extraction of a substring + pattern), provides extraction of a + substring that matches a POSIX regular expression pattern. It returns null if there is no match, otherwise the portion of the text that matched the pattern. But if the pattern contains any parentheses, the portion @@ -3048,6 +3028,45 @@ substring('foobar' from 'o(.)b') o + + The regexp_replace function provides substitution of + new text for substrings that match POSIX regular expression patterns. + It has the syntax + regexp_replace(source, + pattern, replacement + , flags ). + The source string is returned unchanged if + there is no match to the pattern. If there is a + match, the source string is returned with the + replacement string substituted for the matching + substring. The replacement string can contain + \n, where n is 1 + through 9, to indicate that the source substring matching the + n'th parenthesized subexpression of the pattern should be + inserted, and it can contain \& to indicate that the + substring matching the entire pattern should be inserted. Write + \\ if you need to put a literal backslash in the replacement + text. (As always, remember to double backslashes written in literal + constant strings.) + The flags parameter is an optional text + string containing zero or more single-letter flags that change the + function's behavior. Flag i specifies case-insensitive + matching, while flag g specifies replacement of each matching + substring rather than only the first one. + + + + Some examples: + +regexp_replace('foobarbaz', 'b..', 'X') + fooXbaz +regexp_replace('foobarbaz', 'b..', 'X', 'g') + fooXX +regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g') + fooXarYXazY + + + PostgreSQL's regular expressions are implemented using a package written by Henry Spencer. Much of -- cgit v1.2.3