StringExt API - lifedever/kt-speedy-toolbox GitHub Wiki

字符串扩展 API (StringExt)

字符串扩展提供了丰富的字符串处理功能，包括验证、格式化、转换、加密等。

📋 目录

字符串验证

isPresent()

检查字符串是否不为空且不为空白。

fun String?.isPresent(): Boolean

示例:

val text1 = "Hello"
val text2 = ""
val text3: String? = null

println(text1.isPresent()) // true
println(text2.isPresent()) // false
println(text3.isPresent()) // false

isNotPresent()

检查字符串是否为空或空白。

fun String?.isNotPresent(): Boolean

示例:

val text = ""
if (text.isNotPresent()) {
    println("字符串为空")
}

nullIfBlank()

如果字符串为空白则返回 null，否则返回原字符串。

fun String?.nullIfBlank(): String?

示例:

val text1 = "  "
val text2 = "Hello"

println(text1.nullIfBlank()) // null
println(text2.nullIfBlank()) // "Hello"

字符串转换

toFile()

将字符串路径转换为 File 对象。

fun String.toFile(): File

示例:

val filePath = "/path/to/file.txt"
val file = filePath.toFile()

toDate() / toDateTime()

将字符串转换为日期对象。

fun String.toDate(pattern: String): Date
fun String.toDate(): Date // 自动识别格式
fun String.toDateTime(pattern: String = "yyyy-MM-dd"): DateTime

示例:

val dateStr = "2024-01-15"
val date1 = dateStr.toDate("yyyy-MM-dd")
val date2 = dateStr.toDate() // 自动识别
val dateTime = dateStr.toDateTime()

toDateOrNull()

安全地转换日期，失败时返回 null。

fun String.toDateOrNull(): Date?

示例:

val invalidDate = "invalid-date"
val date = invalidDate.toDateOrNull() // null

字符串格式化

substringMax()

截取指定最大长度的字符串。

fun String.substringMax(count: Int): String

示例:

val text = "Hello World"
println(text.substringMax(5)) // "Hello"

lowerFirstChat() / upperFirstChat()

首字母大小写转换。

fun String.lowerFirstChat(): String
fun String.upperFirstChat(): String

示例:

val text = "Hello"
println(text.lowerFirstChat()) // "hello"
println(text.upperFirstChat()) // "Hello"

trimForce()

强制去除所有空白字符（包括空格、制表符、换行符等）。

fun String.trimForce(): String

示例:

val text = "Hello\n\t World\r"
println(text.trimForce()) // "HelloWorld"

加密和哈希

md5() / sha1()

计算字符串的 MD5 或 SHA1 哈希值。

fun String.md5(): String
fun String.sha1(): String

示例:

val text = "Hello World"
println(text.md5())  // "b10a8db164e0754105b7a99be72e3fe5"
println(text.sha1()) // "0a4d55a8d778e5022fab701977c5d840bbc486d0"

路径操作

pathAppend()

安全地拼接路径。

fun String.pathAppend(path: String): String

示例:

val basePath = "/api/v1/"
val endpoint = "/users/"
val fullPath = basePath.pathAppend(endpoint) // "/api/v1/users"

getFileType()

获取文件扩展名。

fun String.getFileType(): String

示例:

val filename = "document.pdf"
println(filename.getFileType()) // "pdf"

查询相关

toLikeQuery()

转换为 SQL LIKE 查询格式。

fun String.toLikeQuery(): String
fun String.toLeftLikeQuery(): String
fun String.toRightLikeQuery(): String

示例:

val keyword = "kotlin"
println(keyword.toLikeQuery())      // "%kotlin%"
println(keyword.toLeftLikeQuery())  // "%kotlin"
println(keyword.toRightLikeQuery()) // "kotlin%"

文件类型检测

isImage()

检查是否为图片文件。

fun String.isImage(): Boolean

示例:

val filename1 = "photo.jpg"
val filename2 = "document.pdf"

println(filename1.isImage()) // true
println(filename2.isImage()) // false

isAudioFile()

检查是否为音频文件。

fun String.isAudioFile(): Boolean

示例:

val filename = "song.mp3"
println(filename.isAudioFile()) // true

字符串清理

clearHtmlTag()

清除 HTML 标签。

fun String.clearHtmlTag(): String

示例:

val html = "<p>Hello <b>World</b></p>"
println(html.clearHtmlTag()) // "Hello World"

htmlUnescape()

还原 HTML 转义字符。

fun String.htmlUnescape(): String

示例:

val escaped = "&lt;div&gt;Hello&lt;/div&gt;"
println(escaped.htmlUnescape()) // "<div>Hello</div>"

escapeSpecialWordForMongoQuery()

转义 MongoDB 查询特殊字符。

fun String.escapeSpecialWordForMongoQuery(): String

示例:

val query = "user.name"
println(query.escapeSpecialWordForMongoQuery()) // "user\\.name"

高级功能

findBetween()

查找两个字符串之间的内容。

fun String.findBetween(start: String, end: String, includeEnd: Boolean = true): String?

示例:

val text = "Hello [World] Test"
val result = text.findBetween("[", "]", false) // "World"

containsAnyOf()

检查是否包含任意指定字符串。

fun String.containsAnyOf(vararg keywords: String, ignoreCase: Boolean = false): Boolean

示例:

val text = "Hello World"
val hasKeyword = text.containsAnyOf("Hello", "Hi") // true

replaceBatch()

批量替换多个字符串。

fun String.replaceBatch(oldValues: List<String>, newValue: String): String

示例:

val text = "Hello World Test"
val result = text.replaceBatch(listOf("Hello", "World"), "Hi") // "Hi Hi Test"

chunkedRealSizeByCharset()

按实际字符集大小分割字符串。

fun String.chunkedRealSizeByCharset(size: Int, charset: Charset = Charsets.UTF_8): List<String>

示例:

val text = "这是一个测试文本"
val chunks = text.chunkedRealSizeByCharset(10)

条件执行

ifPresent()

当字符串不为空时执行操作。

inline fun String?.ifPresent(doIfPresent: (String) -> Unit)
inline fun String?.ifPresent(doIfPresent: (String) -> Unit, doIfNotPresent: () -> Unit)

示例:

val text: String? = "Hello"
text.ifPresent(
    doIfPresent = { println("文本内容: $it") },
    doIfNotPresent = { println("文本为空") }
)

ifPresentOrElse()

当字符串为空时返回默认值。

fun String?.ifPresentOrElse(other: String): String

示例:

val text: String? = null
val result = text.ifPresentOrElse("默认值") // "默认值"

📝 注意事项

  1. 大部分扩展函数都是空安全的，可以在可空字符串上调用
  2. 日期转换函数支持多种常见格式的自动识别
  3. 加密函数返回的是十六进制字符串
  4. 路径拼接会自动处理斜杠，避免重复或缺失

🔗 相关链接

⚠️ **GitHub.com Fallback** ⚠️