[Rd] pmatch inconsistency

[Justin Talbot]

The pmatch help (see also section 4.3.2 in the R Language Definition)
claims that pmatch with duplicates.ok=FALSE provides the same
functionality as R's argument matching algorithm, modulo how empty
strings are matched.

Here's an undocumented inconsistency between pmatch and R's argument
matching algorithm:

> sessionInfo()
R version 3.0.1 (2013-05-16)
Platform: x86_64-apple-darwin10.8.0 (64-bit)

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

> f <- function(abc, ax) 1
> f(ab=1,a=10)
Error in f(ab = 1, a = 10) :
  formal argument "abc" matched by multiple actual arguments

> pmatch(c('ab','a'), c('abc', 'ax'), duplicates.ok=FALSE)
[1] 1 2

That is, pmatch doesn't consider ambiguous partial matches to be an
error if the ambiguity is resolved by an earlier partial match.

This leads to an order dependency in pmatch that doesn't happen with
argument matching:

> pmatch(c('ab','a'), c('abc', 'ax'), duplicates.ok=FALSE)
[1] 1 2

> pmatch(c('a','ab'), c('abc', 'ax'), duplicates.ok=FALSE)
[1] NA 1

It would be great if this were documented.

At a higher level, is pmatch intended to be the same as the argument
matching algorithm or is it just supposed to be "close"?

Justin