BUG #5469: regexp_matches() has poor behaviour and more poor documentation

The following bug has been logged online:

Bug reference: 5469
Logged by: Daniele Varrazzo
Email address: daniele(dot)varrazzo(at)gmail(dot)com
PostgreSQL version: 8.4
Operating system: any
Description: regexp_matches() has poor behaviour and more poor
documentation
Details:

regexp_matches() has been recently discussed
(http://archives.postgresql.org/pgsql-bugs/2010-04/msg00026.php): it is a
setof function and as such it can drop results.

Unfortunately it is an useful function to newcomers who use SQL, use regexps
but don't arrive to read the chapter 34.4.7. (i.e. Extending SQL -> Query
Language (SQL) Functions -> SQL Functions Returning Sets) and are not so
enlightened to know that "setof text[]" means "if it doesn't match, it drops
the record". They just expect the function to be a LIKE on steroids.

Please describe the behavior in the documentation of the function (i.e.
table 9-6. and section 9.7.3), possibly provide a function with a saner
interface, i.e. returning a text[] of the first match or NULL on no match,
or document a workaround (suitable for an user knowing regexps but not
setof-returning functions) to make the function not dropping record (e.g. I
fixed the "bug" adding a "|" at the end of the pattern, so that the function
returns an array of NULL in case of no match: I don't think it is a trivial
workaround).