# InStr

在一个字符串中向右或向左搜索指定内容.

    FoundPos := InStr(Haystack, Needle , CaseSense, StartingPos, Occurrence)

## 参数

Haystack

  类型: 字符串

  搜索其内容的字符串.

Needle

  类型: 字符串

  要搜索的字符串.

CaseSense

  类型: 整数或字符串

  下列值之一(如果省略, 默认为 0):

  `"On"` 或 `1`(`True`): 搜索区分大小写.

  `"Off"` 或 `0`(`False`): 字母 A-Z 被视为与其小写字母相同.

  `"Locale"`: 根据当前用户的区域设置规则, 搜索是不区分大小写的. 例如, 在大多数英语及西欧地区, 不仅将 A-Z 视为等同于它们的小写形式, 同时也将非-ASCII 字母(如 Ä 和 Ü) 视为等同的. 根据被比较字符串的性质, Locale 比 Off 慢 1 到 8 倍.

StartingPos

  类型: 整数

  如果省略, 搜索整个字符串. 否则, 指定开始搜索的位置, 其中 1 是第一个字符, 2 是第二个字符, 以此类推. 负值从 Haystack 的末尾开始计算, 所以 -1 是最后一个字符, -2 倒数第二个, 以此类推.

  如果省略 Occurrence, 负的 StartingPos 会导致搜索从右到左进行. 然而, 如果指定了 Occurrence, StartingPos 对搜索的方向没有影响.

  对于从右到左的搜索, StartingPos 指定了第一个可能出现的 Needle 的 最后 一个字符的位置. 例如, `InStr("abc", "bc",, 2, +1)` 会找到一个匹配, 但 `InStr("abc", "bc",, 2, -1)` 则不会.

  如果 StartingPos 的绝对值大于 Haystack 的长度, 将返回 0.

Occurrence

  类型: 整数

  如果省略, 它默认为 Haystack 中的第一个匹配. 如果 StartingPos 为负数, 搜索将从右向左进行; 否则将从左向右进行.

  如果 Occurrence 是正数, 搜索总是从左到右进行. 为 Occurrence 指定 2 来返回第二个匹配的位置, 3 来返回第三个匹配的位置, 等等.

  如果 Occurrence 是负数, 搜索总是从右到左进行. 例如, -2 搜索从右边开始的第二次出现.

## 返回值

类型: 整数

该函数返回字符串 Needle 在字符串 Haystack 中的出现位置. 位置 1 表示第一个字符; 因为 0 等同于 "false", 使它能提供直觉上 "没找到" 的意义.

不管 StartingPos 或 Occurrence 的值是多少, 返回值总是相对于 Haystack 中的第一个字符. 例如, "abc" 在 "123abc789" 中的位置始终是 4.

传统上, 空字符串(`""`) 的出现可以在任何位置找到. 然而, 由于空白的 Needle 通常只会被误传, 因此会被视为一个错误(抛出异常).

## 错误处理

在以下任何一种情况下都会抛出 ValueError:

- Needle 是一个空(零长度) 字符串.
- CaseSense 是无效的.
- Occurrence 或 StartingPos 为 0 或非数字.

## 备注

RegExMatch 可用于搜索字符串中的模式(正则表达式), 这使得它比 InStr 更为灵活. 但是, 在搜索简单的子字符串时, InStr 通常比 RegExMatch 更快.

InStr 只搜索到第一个二进制零(空终止符), 而 RegExMatch 搜索整个字符串的长度, 即使它包含二进制零.

## 相关

RegExMatch, Is 函数

## 示例

报告子字符串 "abc" 在字符串 "123abc789" 中以 1 开始的位置.

    MsgBox InStr("123abc789", "abc") ; 返回 4

在 Haystack 中搜索 Needle.

    Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
    Needle := "Fox"
    If InStr(Haystack, Needle)
        MsgBox "The string was found."
    Else
        MsgBox "The string was not found."

演示不区分大小写和区分大小写搜索的区别.

    Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
    Needle := "the"
    MsgBox InStr(Haystack, Needle, false, 1, 2) ; 不区分大小写的搜索, 返回第二次匹配的位置
    MsgBox InStr(Haystack, Needle, true) ; 区分大小写的搜索, 返回首次匹配的位置, 结果同上

dftg