VWED_server/docs/built_in_functions.md

# 内置函数使用说明文档

本文档描述了系统提供的内置函数及其用法。这些函数可以在任务编辑器中直接使用，为任务流程提供强大的字符串处理功能。

## 字符串检查函数

### isBlank(str)
检查字符串是否为null、空字符串或只包含空白字符。

**参数**:
- `str`: 要检查的字符串

**返回值**: 如果字符串为空，则返回 true；否则返回 false

**示例**:
```javascript
isBlank(null)     // 返回 true
isBlank("")       // 返回 true
isBlank(" ")      // 返回 true
isBlank("hello")  // 返回 false
```

### isNotBlank(str)
检查字符串是否不为空（不为 null 且不只包含空白字符）。

**参数**:
- `str`: 要检查的字符串

**返回值**: 如果字符串不为空，则返回 true；否则返回 false

**示例**:
```javascript
isNotBlank(null)     // 返回 false
isNotBlank("")       // 返回 false
isNotBlank(" ")      // 返回 false
isNotBlank("hello")  // 返回 true
```

### isAnyBlank(str1, str2, ...)
检查多个字符串中是否有任意一个为空。

**参数**:
- `str1, str2, ...`: 要检查的字符串列表

**返回值**: 如果任何一个字符串为空，则返回 true；否则返回 false

**示例**:
```javascript
isAnyBlank("hello", "world")  // 返回 false
isAnyBlank("hello", "")       // 返回 true
isAnyBlank("hello", " ")      // 返回 true
```

### isAllBlank(str1, str2, ...)
检查多个字符串是否全部为空。

**参数**:
- `str1, str2, ...`: 要检查的字符串列表

**返回值**: 如果所有字符串都为空，则返回 true；否则返回 false

**示例**:
```javascript
isAllBlank("", " ")          // 返回 true
isAllBlank("hello", "")      // 返回 false
isAllBlank("hello", "world") // 返回 false
```

### isNumeric(str)
检查字符串是否为数字（整数或浮点数）。

**参数**:
- `str`: 要检查的字符串

**返回值**: 如果字符串是数字，则返回 true；否则返回 false

**示例**:
```javascript
isNumeric("123")    // 返回 true
isNumeric("123.45") // 返回 true
isNumeric("abc")    // 返回 false
isNumeric("123abc") // 返回 false
```

### isAlpha(str)
检查字符串是否只包含字母。

**参数**:
- `str`: 要检查的字符串

**返回值**: 如果字符串只包含字母，则返回 true；否则返回 false

**示例**:
```javascript
isAlpha("abc") // 返回 true
isAlpha("123") // 返回 false
isAlpha("a1b") // 返回 false
```

## 字符串匹配函数

### startsWith(str, prefix)
检查字符串是否以指定前缀开头。

**参数**:
- `str`: 要检查的字符串
- `prefix`: 前缀字符串

**返回值**: 如果字符串以指定前缀开头，则返回 true；否则返回 false

**示例**:
```javascript
startsWith("hello world", "hello") // 返回 true
startsWith("hello world", "world") // 返回 false
```

### endsWith(str, suffix)
检查字符串是否以指定后缀结尾。

**参数**:
- `str`: 要检查的字符串
- `suffix`: 后缀字符串

**返回值**: 如果字符串以指定后缀结尾，则返回 true；否则返回 false

**示例**:
```javascript
endsWith("hello world", "world") // 返回 true
endsWith("hello world", "hello") // 返回 false
```

### contains(str, substr)
检查字符串是否包含指定子字符串。

**参数**:
- `str`: 要检查的字符串
- `substr`: 子字符串

**返回值**: 如果字符串包含指定子字符串，则返回 true；否则返回 false

**示例**:
```javascript
contains("hello world", "lo wo") // 返回 true
contains("hello world", "abc")   // 返回 false
```

### indexOf(str, substr, start, end)
查找子字符串在字符串中的索引位置。

**参数**:
- `str`: 要搜索的字符串
- `substr`: 要查找的子字符串
- `start`: 开始搜索的位置，可选，默认为0
- `end`: 结束搜索的位置，可选，默认为字符串末尾

**返回值**: 子字符串在字符串中的索引位置，如果找不到则返回 -1

**示例**:
```javascript
indexOf("hello world", "world")  // 返回 6
indexOf("hello world", "o")      // 返回 4
indexOf("hello world", "o", 5)   // 返回 7（从位置5开始查找）
```

## 字符串操作函数

### split(str, separator, maxsplit)
按指定分隔符拆分字符串。

**参数**:
- `str`: 要拆分的字符串
- `separator`: 分隔符
- `maxsplit`: 最大拆分次数，可选，默认为 -1（无限制）

**返回值**: 拆分后的字符串列表

**示例**:
```javascript
split("a,b,c", ",")      // 返回 ["a", "b", "c"]
split("a b c")           // 返回 ["a", "b", "c"]
split("a,b,c,d", ",", 2) // 返回 ["a", "b", "c,d"]
```

### chop(str)
去掉字符串的最后一个字符。

**参数**:
- `str`: 要处理的字符串

**返回值**: 处理后的字符串

**示例**:
```javascript
chop("hello") // 返回 "hell"
chop("h")     // 返回 ""
chop("")      // 返回 ""
```

### chomp(str)
去掉字符串末尾的换行符（\n、\r 或 \r\n）。

**参数**:
- `str`: 要处理的字符串

**返回值**: 处理后的字符串

**示例**:
```javascript
chomp("hello\n")  // 返回 "hello"
chomp("hello\r")  // 返回 "hello"
chomp("hello\r\n") // 返回 "hello"
chomp("hello")    // 返回 "hello"（保持不变）
```

### difference(str1, str2)
获取第二个字符串在第一个字符串中不一样的部分。
从第二个字符串第一位去匹配第一个字符串，按照顺序比较。

**参数**:
- `str1`: 第一个字符串
- `str2`: 第二个字符串

**返回值**: 不一样的部分，如果完全匹配则返回空字符串

**示例**:
```javascript
difference("abc", "abd")  // 返回 "d"
difference("abc", "abcd") // 返回 "d"
difference("abc", "a")    // 返回 ""
```

### replace(str, old, new, count)
替换字符串中的指定子串。

**参数**:
- `str`: 原字符串
- `old`: 要替换的子串
- `new`: 替换后的子串
- `count`: 替换次数，可选，默认为 -1（全部替换）

**返回值**: 替换后的字符串

**示例**:
```javascript
replace("hello", "l", "x")    // 返回 "hexxo"
replace("hello", "l", "x", 1) // 返回 "hexlo"（只替换第一个）
```

### remove(str, substr)
从字符串中删除所有指定的子串。

**参数**:
- `str`: 原字符串
- `substr`: 要删除的子串

**返回值**: 删除后的字符串

**示例**:
```javascript
remove("hello", "l")  // 返回 "heo"
remove("hello", "he") // 返回 "llo"
```

### right(str, length)
从右边获取指定长度的子字符串。

**参数**:
- `str`: 原字符串
- `length`: 要获取的长度

**返回值**: 截取的子字符串

**示例**:
```javascript
right("hello", 2) // 返回 "lo"
right("hello", 5) // 返回 "hello"
right("hello", 0) // 返回 ""
```

### left(str, length)
从左边获取指定长度的子字符串。

**参数**:
- `str`: 原字符串
- `length`: 要获取的长度

**返回值**: 截取的子字符串

**示例**:
```javascript
left("hello", 2) // 返回 "he"
left("hello", 5) // 返回 "hello"
left("hello", 0) // 返回 ""
```

### length(str)
获取字符串的长度。

**参数**:
- `str`: 要测量的字符串

**返回值**: 字符串的长度，如果为 null 则返回 0

**示例**:
```javascript
length("hello") // 返回 5
length("")      // 返回 0
length(null)    // 返回 0
```

### reverse(str)
反转字符串。

**参数**:
- `str`: 要反转的字符串

**返回值**: 反转后的字符串

**示例**:
```javascript
reverse("hello") // 返回 "olleh"
reverse("a")     // 返回 "a"
reverse("")      // 返回 ""
```

## 使用场景

这些内置函数在以下场景中特别有用：

1. **输入验证** - 使用 `isBlank`、`isNumeric` 等函数验证输入参数
2. **字符串处理** - 使用 `replace`、`remove` 等函数处理字符串
3. **条件判断** - 使用 `startsWith`、`contains` 等函数进行条件判断
4. **数据格式化** - 使用 `split`、`right`、`left` 等函数格式化数据

## 注意事项

1. 所有函数对 null 值都有保护处理，不会引发异常
2. 字符串索引从 0 开始
3. 在使用函数时，请确保参数类型正确，避免类型错误