ValUtil - 类型转换

---

ValUtil 提供"有界宽容"的类型转换：输入为 null → 返回 null（或默认值），类型不同但能转换 → 自动转换，内容无法转换 → 抛异常。

基本类型转换

// 转 Integer
Integer val = ValUtil.toInt(obj);                    // null → null, "25" → 25
Integer val = ValUtil.toInt(obj, 0);                 // 带默认值
Integer val = ValUtil.toIntZero(obj);                // null → 0

// 转 Long
Long val = ValUtil.toLong(obj);
Long val = ValUtil.toLongZero(obj);                  // null → 0

// 转 Double
Double val = ValUtil.toDouble(obj);
Double val = ValUtil.toDoubleZero(obj);              // null → 0.0

// 转 Float
Float val = ValUtil.toFloat(obj);
Float val = ValUtil.toFloatZero(obj);                // null → 0.0f

// 转 BigDecimal（金额计算用）
BigDecimal val = ValUtil.toBigDecimal(obj);
BigDecimal val = ValUtil.toBigDecimalZero(obj);      // null → 0

// 转 Boolean
Boolean val = ValUtil.toBoolean(obj);                // "true"/"1" → true, else false

// 转 String
String val = ValUtil.toStr(obj);                     // null → null, 其他 → toString()
String val = ValUtil.toStr(obj, "默认值");
String val = ValUtil.toStrBlank(obj);                // null → ""
String val = ValUtil.toStrWithEmpty(obj, "默认值");  // null/空字符串 → 默认值

// 字节数组转字符串
String val = ValUtil.toStr(bytes, Charset.forName("UTF-8"));
String val = ValUtil.toStr(bytes);                   // 默认 UTF-8

集合/数组转换

// 转 JSONList
JSONList list = ValUtil.toList(obj);
JSONList list = ValUtil.toListEmpty(obj);           // null → 空列表

// 转 List<T>
List<Integer> ids = ValUtil.toList("1,2,3", Integer.class);  // → [1,2,3]

// 转 T[]
Integer[] arr = ValUtil.toArray("1,2,3", Integer.class);

日期转换

// String → Date
Date date = ValUtil.toDate("2024-01-01 12:00:00");
Date date = ValUtil.toDate("2024/01/01", "yyyy/MM/dd");
Date date = ValUtil.toDateNow(obj);                  // null → 当前时间

// String → LocalDateTime
LocalDateTime ldt = ValUtil.toLocalDateTime("2024-01-01 12:00:00");
LocalDateTime ldt = ValUtil.toLocalDateTime(obj, "yyyy-MM-dd HH:mm:ss");

// 日期格式化输出
String str = ValUtil.toDateStr(obj);
String str = ValUtil.toDateStr(obj, "yyyy-MM-dd");
String str = ValUtil.toDateStrNow(obj);              // null → 当前时间字符串

对象转换

// 跨类型转换（通过 Jackson）
User user = ValUtil.toObj(jsonMap, User.class);
User user = ValUtil.toObj(sourceObj, JavaType);

// 原生类型转换（不通过 Jackson）
User user = ValUtil.toNativeObj(sourceObj, User.class);

路径取值与设值

ValUtil 提供 at() 和 set() 方法，支持路径表达式操作任意对象（Map / Bean / List / 数组 / JSON 字符串）：

// 路径取值——支持点分隔与数组索引
String city = ValUtil.at(user, "profile.address.city");    // Map/Bean 通用
Object item = ValUtil.at(list, "[1].name");                // List + 对象属性
Object elem = ValUtil.at(jsonStr, "data.items[0].id");     // JSON 字符串

// 路径设值——自动创建中间层级（Map 模式）
ValUtil.set(map, "a.b.c", value, false);                   // ignore=false，路径不存在抛异常
ValUtil.set(map, "a.b.c", value, true);                    // ignore=true，路径不存在静默跳过

路径语法与 JSONMap 的 getStr() / set() 一致：a.b.c（对象属性）、[1]（数组索引）、a.b[1].c（混合）。

空值判断

// 判断对象是否为空（支持 CharSequence, Collection, Map, Array 等）
boolean empty = ValUtil.isEmpty(obj);

转换规则

输入	目标	结果
null	任意	null 或默认值
"25"	Integer	25
"99.9"	BigDecimal	99.9
"true"	Boolean	true
"abc"	Integer	抛异常（内容不可转换）
"1,2,3"	List<Integer>	[1,2,3]（逗号分隔自动拆分）

---