R语言【base】——match.arg通过部分匹配校正参数输入，参数的输入值从首字母开始，保持连续，宁缺勿错

Package base version 4.3.2

match.arg通过部分匹配校正参数输入

match.arg(arg, choices, several.ok = FALSE)

        match.arg 的功能是：将参数【arg】的传入值与参数【choices】的传入值进行匹配，参数choices的传入值可以视为一个候选值列表。

---

match.arg的参数

• 参数【arg】：当参数【serveral.ok】为 FALSE时，既可以传入一个长度为1的字符型向量，也可以传入NULL，NULL表示执行 choices[1]。当参数【serveral.ok】为 TRUE时，则传入的字符型向量的长度可以大于1。

• 参数【choices】：作为候选值列表的字符型向量，经常忽略。

• 参数【serveral.ok】：通过逻辑值判断参数【arg】拥有的元素个数是否可以超过1。

---

match.arg的使用技巧

        当使用match.arg时只给参数【arg】传入值，即match.arg(arg)，那么调用match.arg的函数中对参数【arg】定义的默认值就将作为参数【choices】的传入值。

        匹配过程通过pmatch完成，根据pmatch的特性：参数【arg】可以是缩写，但是当参数【arg】的传入值为空字符串("")时不会有任何匹配项，甚至不会匹配另一个空字符串。

        传入参数【arg】的简写必须是从首字母开始的连续字符串。

---

match.arg的返回值说明

        如果有完全匹配或唯一部分匹配，则是该匹配的未缩写版本；否则，如果 参数【several.ok】为 FALSE（默认值），则表示出错。当 参数【several.ok】为TRUE且参数【arg】中（至少）有一个元素匹配时，将返回所有未缩写的匹配结果。

---

match.arg的实例说明

        为了更直白地了解match.arg的功能用法，笔者将通过一个示例进行展示。

test_match.arg <- function(
    taxon_rank = c("species", "genus", "supragenus", "family", "order"))
{
  taxon_rank <- match.arg(taxon_rank)
  print(taxon_rank)
}

1. 测试完全匹配

> test_match.arg(taxon_rank = "species")
[1] "species"
> test_match.arg(taxon_rank = c("species"))
[1] "species"

2. 测试拼写错误

> test_match.arg(taxon_rank = c("specise"))
Error in match.arg(taxon_rank) : 
  'arg' should be one of “species”, “genus”, “supragenus”, “family”, “order”

3. 测试从首字母开始的连续字符串

> test_match.arg(taxon_rank = c("sp"))
[1] "species"
> test_match.arg(taxon_rank = c("s"))
Error in match.arg(taxon_rank) : 
  'arg' should be one of “species”, “genus”, “supragenus”, “family”, “order”

因为以"s"开头的候选值有两个："species"和"supragenus"，所以报错！

4. 测试从非首字母开始的连续字符串

> test_match.arg(taxon_rank = c("pecies"))
Error in match.arg(taxon_rank) : 
  'arg' should be one of “species”, “genus”, “supragenus”, “family”, “order”