---
source_url: https://docs.dolphindb.cn/zh/funcs/c/clip.html
fetched_at: 2026-05-19T09:15:21Z
category: funcs
title: clip
sha1: 664a00a2ddf169058d1c782935963fffe5ad97af
---

# clip

## 语法

`clip(X,Y,Z)`

## 详情

返回一个与 X 数据形式和数据类型完全相同的 X'。

X' 的值满足以下规则（当 X 为字典时，下述"X'的元素"表示字典 X' 的 value）：

- 当 Y 和 Z 为标量时，X' 的元素被限制在 [Y, Z] 区间内：

  - 1.1 Y 或 Z 为 NULL 表示对区间下界或上界不做限制。
  - 1.2 若 Y 大于 Z，则 X' 中所有元素设为 Z。
  - 1.3 对于 X 中落在 [Y, Z] 范围内的元素，其在 X' 中保留原值；对于超出该范围的元素，X'
    中相应位置的值将被替换为最近的边界值，即小于 Y 的元素被设为 Y，大于 Z 的元素被设为 Z。
- 当 Y 和 Z 为向量、矩阵或表时，对 X 中每个元素 x，根据相应位置的 [y, z] 组成的范围进行限制：

  - 2.1 超出该范围的 x 依然按照上述规则进行处理。
  - 2.2 若 Y 或 Z 某个位置元素为 NULL，则 X' 对应位置元素也为 NULL。
  - 2.3 若 Y 或 Z 某个位置元素满足 y >z，则 X' 对应位置元素设为 z。
- 当 Y 或 Z 其中之一为标量，另一个为向量、矩阵或表时：

  - 3.1 标量值代表区间下界或上界固定，向量、矩阵或表中的元素代表不同位置的限制区间的下界或上界。
  - 3.2 标量值为 NULL 表示对下界或上界不做限制，向量、矩阵或表的某一元素为 NULL 代表将 X‘ 对应位置元素设置为空值。
  - 3.3 某个位置元素满足 y >z，则 X' 对应位置元素设为 z。

注：

与 [numpy.clip](https://numpy.org/doc/stable/reference/generated/numpy.clip.html) 函数的核心功能相同，区别如下：

- DolphinDB 中，`clip` 函数的原地修改版本为 [clip!](clip_.html)；而在 `numpy.clip` 函数中，原地修改通过参数 *out*
  实现。
- DolphinDB 中，`clip` 函数不支持 `numpy.clip` 函数中的
  *out*、*min*、*max* 等参数。

## 参数

**X** 是一个数值型或时间类型的标量、向量、矩阵、表或 value 为数值型或时间类型的字典。

**Y** 是一个数值型或时间类型的标量、向量、矩阵或表。

**Z** 是一个数值型或时间类型的标量、向量、矩阵或表。

*X*, *Y*, *Z* 数据类型必须匹配：

- 若 *X* 为整型，*Y*、*Z* 必须为整型。
- 若 *X* 为浮点型或 DECIMAL，*Y*、*Z* 可以为整型、浮点型或 DECIMAL 类型。
- 若 *X* 为时间类型，*Y*、*Z* 必须为同类型的时间类型。

X, Y, Z 的数据形式须满足以下要求：

- 当 *X* 是标量或字典时，*Y* 和 *Z* 必须为标量。
- 当 *X* 是向量时，*Y* 和 *Z* 可以是标量或与 *X*维度相同的向量。
- 当 *X* 是矩阵时，*Y* 和 *Z* 可以是标量或与 *X* 维度相同的矩阵。
- 当 *X* 是表时，*Y* 和 *Z* 可以是标量或与 *X* 维度相同的表。

## 返回值

返回一个与输入 *X* 相同数据类型和形式的对象。

## 例子

### Y 和 Z 是标量

Y = NULL ，Z = 5 ，根据规则1.1，表示不限制下界，上界为 5，此时仅将表中大于 5 的值置为
5。

```dolphindb
X = table(1..10 as val1, 10..1 as val2)
Y = NULL
Z = 5
clip(X,Y,Z)
```

| val1 | val2 |
| --- | --- |
| 1 | 5 |
| 2 | 5 |
| 3 | 5 |
| 4 | 5 |
| 5 | 5 |
| 5 | 5 |
| 5 | 4 |
| 5 | 3 |
| 5 | 2 |
| 5 | 1 |

Y 大于 Z （6>3），根据规则1.2， X' 中所有元素被置为
3。

```dolphindb
X = 1..10
Y = 6
Z = 3
clip(X,Y,Z)
// output:[3,3,3,3,3,3,3,3,3,3]
```

Y 和 Z 组成区间 [3,5]，根据规则1.3，X’ 中 value
小于3的值（1和2）被置为3，大于5的值（6）被置为5，其他元素得到保留。

```dolphindb
X = dict(`a`b`c`d`e`f,[1,2,3,4,5,6])
Y = 3
Z = 5
clip(X,Y,Z)
/*
output:
a->3
b->3
c->3
d->4
e->5
f->5
*/
```

### Y 和 Z 是向量、矩阵或表

Y 和 Z 为与 X 维度相同的向量，用区间 [y[i], z[i]] 对 X[i] 进行限制：

- X[0] 在 [Y[0],Z[0]] 区间内（1属于[0,3]），根据规则2.1，保留其值
- X[3] 小于 Y[3]（4<5），根据规则2.1，X'[3] 置为 5（Y[3]）
- X[9] 大于 Z[9]（10>9），根据规则2.1，X'[9] 置为 9（Z[9]）
- Y[7] 和 Z[6] 为 NULL，根据规则2.2 ，X'[6] 和 X'[7] 为 NULL
- Y[8] 大于 Z[8]（7>5），根据规则2.3，X'[8] 置为 5（Z[8]）

```dolphindb
X = [1,2,3,4,5,6,7,8,9,10]
Y = [0,1,2,5,6,6,6,NULL,7,7]
Z = [3,4,5,6,7,8,NULL,5,5,9]
clip(X,Y,Z)
// output:[1,2,3,5,6,6,,,5,9]
```

### Y 或 Z 其中之一为标量，另一个为向量、矩阵或表

下例中 Y 为 4，Z 为与 X 维度相同的矩阵，对 X 中元素 x[i,j]，用区间 [4,Z[i,j]] 对其进行限制：

- X[0,0] 小于 Y（1<4），根据规则3.1， X'[0,0] 置为 4
- Z[0,2] 为 NULL，根据规则3.2，X'[0,2] 置为 NULL
- Y 大于 Z[1,2]（4>3），根据规则3.3， X'[1,2] 置为 3（Z[1,2]）

```dolphindb
X = 1..8$2:4
Y = 4
Z = [5,6,5,6,NULL,3,5,6]$2:4
clip(X,Y,Z)
// output:
#0 #1 #2 #3
-- -- -- --
4  4     5 
4  4  3  6
```
