is_nan

EVOCOSMOS2026/4/15大约 4 分钟

最后同步日期：2026-04-15 | Godot 官方原文 — is_nan

is_nan

定义

is_nan 是一个用来判断一个浮点数是否是 NaN（Not a Number，即"非数字"）的函数。

NaN 是什么？打个比方：你拿计算器算 0 ÷ 0，计算器会显示"错误"或"无效输入"——这个"错误"在编程世界里就是 NaN。它不是一个具体的数值，而是计算机表达"这个运算没有意义"的方式。

其他会产生 NaN 的常见运算：

0.0 / 0.0 — 零除以零
Mathf.Sqrt(-1.0) — 对负数开平方
Mathf.Asin(2.0) — 反正弦函数的参数超出范围（有效范围是 -1 到 1）

什么时候需要用到它？

检测数学运算是否产生了无意义的结果
在数据处理中过滤掉无效值
调试时定位计算错误的位置

函数签名

// 方式一：通过 Mathf 类调用（Godot 封装）
public static bool IsNaN(float x)

// 方式二：使用 .NET 原生方法
// float.IsNaN(x)

GDScript

# 全局函数，无需前缀直接调用
func is_nan(x: float) -> bool

参数说明

参数名	类型	说明
`x`	float	要检查是否为 NaN 的浮点数

返回值

bool — 如果 x 是 NaN（Not a Number），返回 true；否则返回 false。

代码示例

基本用法：检测 NaN

using Godot;

public partial class MyNode : Node
{
    public override void _Ready()
    {
        float a = 42.0f;
        float b = float.NaN;
        float c = 0.0f / 0.0f;       // 除法产生 NaN

        GD.Print(Mathf.IsNaN(a));     // 输出: False （正常的数）
        GD.Print(Mathf.IsNaN(b));     // 输出: True  （是 NaN）
        GD.Print(Mathf.IsNaN(c));     // 输出: True  （0/0 产生 NaN）
    }
}

GDScript

extends Node

func _ready():
    var a = 42.0
    var b = NAN
    var c = 0.0 / 0.0           # 除法产生 NaN

    print(is_nan(a))             # 输出: False （正常的数）
    print(is_nan(b))             # 输出: True  （是 NaN）
    print(is_nan(c))             # 输出: True  （0/0 产生 NaN）

实际场景：验证数学运算结果

using Godot;

public partial class AngleUtils : Node
{
    /// <summary>
    /// 安全计算角度的正弦值，确保参数在有效范围内
    /// </summary>
    public float SafeAsin(float value)
    {
        // 限制在 [-1, 1] 范围内，防止产生 NaN
        value = Mathf.Clamp(value, -1.0f, 1.0f);
        return Mathf.Asin(value);
    }

    /// <summary>
    /// 安全计算距离比例，检测 NaN 防止错误传播
    /// </summary>
    public float CalculateDistanceRatio(float distance, float maxDistance)
    {
        float ratio = distance / maxDistance;

        // 检查结果是否为 NaN
        if (float.IsNaN(ratio))
        {
            GD.PrintErr("距离比例计算失败：产生了 NaN，返回默认值 0.0");
            return 0.0f;
        }

        return ratio;
    }

    public override void _Ready()
    {
        // 正常计算
        float angle = SafeAsin(0.5f);
        GD.Print($"asin(0.5) = {angle}");  // 正常输出

        // 不安全的反正弦（参数超出范围）
        float badAngle = Mathf.Asin(2.0f);
        GD.Print($"asin(2.0) 是 NaN 吗？{float.IsNaN(badAngle)}");  // 输出: True

        // 安全的距离比例
        float ratio = CalculateDistanceRatio(5.0f, 0.0f);
        GD.Print($"距离比例: {ratio}");  // 输出: 0.0（安全处理了除零）
    }
}

GDScript

extends Node

## 安全计算角度的正弦值，确保参数在有效范围内
func safe_asin(value: float) -> float:
    # 限制在 [-1, 1] 范围内，防止产生 NaN
    value = clampf(value, -1.0, 1.0)
    return asin(value)

## 安全计算距离比例，检测 NaN 防止错误传播
func calculate_distance_ratio(distance: float, max_distance: float) -> float:
    var ratio = distance / max_distance

    # 检查结果是否为 NaN
    if is_nan(ratio):
        push_error("距离比例计算失败：产生了 NaN，返回默认值 0.0")
        return 0.0

    return ratio

func _ready():
    # 正常计算
    var angle = safe_asin(0.5)
    print("asin(0.5) = ", angle)  # 正常输出

    # 不安全的反正弦（参数超出范围）
    var bad_angle = asin(2.0)
    print("asin(2.0) 是 NaN 吗？", is_nan(bad_angle))  # 输出: True

    # 安全的距离比例
    var ratio = calculate_distance_ratio(5.0, 0.0)
    print("距离比例: ", ratio)  # 输出: 0.0（安全处理了除零）

注意事项

NaN 不等于任何值（包括它自己）：这是 NaN 最特别的属性——NaN == NaN 返回 false！这也是为什么不能直接用 == 来检测 NaN，而必须使用 is_nan 函数。
NaN 具有传染性：任何与 NaN 进行运算的结果都是 NaN。比如 NaN + 1.0 = NaN，NaN * 2.0 = NaN。如果你不加以处理，NaN 会一步步污染后续的所有计算结果。
C# 中有两种写法：Mathf.IsNaN(x) 和 float.IsNaN(x) 效果完全一样，可以互换使用。
NaN 与无穷大的区别：NaN 是"运算无意义"（如 0/0），而无穷大是"运算结果太大"（如 1/0）。两者是完全不同的东西，用 is_nan 检测 NaN，用 is_inf 检测无穷大。
NaN 的常见来源：0/0、对负数开平方、反三角函数参数越界。养成在做这些运算后检查结果的习惯。