string.js

/**
 * wjs-js-toolkit - 字符串处理工具函数库
 * 
 * 包含字符串操作、转换、格式化等常用功能
 * 
 * @module string
 * @memberof wjs-js-toolkit
 */

/**
 * 去除字符串首尾空格
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-09-10
 */
function wjs_trim(str) {
  return String(str || '').trim()
}

/**
 * 去除字符串左侧空格
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-09-15
 */
function wjs_trimLeft(str) {
  return String(str || '').replace(/^\s+/, '')
}

/**
 * 去除字符串右侧空格
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-09-20
 */
function wjs_trimRight(str) {
  return String(str || '').replace(/\s+$/, '')
}

/**
 * 去除字符串中所有空格
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-10-01
 */
function wjs_removeSpaces(str) {
  return String(str || '').replace(/\s+/g, '')
}

/**
 * 字符串截断
 * @param {string} str - 待处理字符串
 * @param {number} maxLength - 最大长度
 * @param {string} suffix - 后缀
 * @returns {string} 截断后的字符串
 * 
 * wjs created by 2015-10-10
 */
function wjs_truncate(str, maxLength = 20, suffix = '...') {
  const s = String(str || '')
  if (s.length <= maxLength) return s
  return s.substring(0, maxLength) + suffix
}

/**
 * 获取字符串长度（支持中文）
 * @param {string} str - 字符串
 * @returns {number} 长度
 * 
 * wjs created by 2015-10-15
 */
function wjs_strLength(str) {
  const s = String(str || '')
  let length = 0
  for (let i = 0; i < s.length; i++) {
    const charCode = s.charCodeAt(i)
    if (charCode >= 0 && charCode <= 128) {
      length += 1
    } else {
      length += 2
    }
  }
  return length
}

/**
 * 字符串转大写
 * @param {string} str - 待处理字符串
 * @returns {string} 大写字符串
 * 
 * wjs created by 2015-11-01
 */
function wjs_toUpperCase(str) {
  return String(str || '').toUpperCase()
}

/**
 * 字符串转小写
 * @param {string} str - 待处理字符串
 * @returns {string} 小写字符串
 * 
 * wjs created by 2015-11-05
 */
function wjs_toLowerCase(str) {
  return String(str || '').toLowerCase()
}

/**
 * 首字母大写
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-11-10
 */
function wjs_capitalize(str) {
  const s = String(str || '')
  if (s.length === 0) return s
  return s.charAt(0).toUpperCase() + s.slice(1)
}

/**
 * 每个单词首字母大写
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2015-11-15
 */
function wjs_capitalizeEachWord(str) {
  const s = String(str || '')
  return s.replace(/\b\w/g, char => char.toUpperCase())
}

/**
 * HTML转义
 * @param {string} str - 待转义字符串
 * @returns {string} 转义后的字符串
 * 
 * wjs created by 2015-12-01
 */
function wjs_escapeHtml(str) {
  const s = String(str || '')
  const map = {
    '&': '&amp;',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#39;',
    '/': '&#x2F;'
  }
  return s.replace(/[&<>"'/]/g, char => map[char])
}

/**
 * HTML反转义
 * @param {string} str - 待反转义字符串
 * @returns {string} 反转义后的字符串
 * 
 * wjs created by 2015-12-05
 */
function wjs_unescapeHtml(str) {
  const s = String(str || '')
  const map = {
    '&amp;': '&',
    '&lt;': '<',
    '&gt;': '>',
    '&quot;': '"',
    '&#39;': "'",
    '&#x2F;': '/'
  }
  return s.replace(/&amp;|&lt;|&gt;|&quot;|&#39;|&#x2F;/g, char => map[char])
}

/**
 * URL编码
 * @param {string} str - 待编码字符串
 * @returns {string} 编码后的字符串
 * 
 * wjs created by 2015-12-10
 */
function wjs_encodeUrl(str) {
  return encodeURIComponent(String(str || ''))
}

/**
 * URL解码
 * @param {string} str - 待解码字符串
 * @returns {string} 解码后的字符串
 * 
 * wjs created by 2015-12-15
 */
function wjs_decodeUrl(str) {
  try {
    return decodeURIComponent(String(str || ''))
  } catch (e) {
    return String(str || '')
  }
}

/**
 * 字符串替换所有匹配项
 * @param {string} str - 原字符串
 * @param {string|RegExp} search - 搜索内容
 * @param {string} replace - 替换内容
 * @returns {string} 替换后的字符串
 * 
 * wjs created by 2016-01-10
 */
function wjs_replaceAll(str, search, replace) {
  const s = String(str || '')
  if (typeof search === 'string') {
    return s.split(search).join(replace)
  }
  return s.replace(search, replace)
}

/**
 * 字符串模板格式化
 * @param {string} template - 模板字符串
 * @param {Object} data - 数据对象
 * @returns {string} 格式化后的字符串
 * 
 * wjs created by 2016-01-15
 */
function wjs_format(template, data) {
  const s = String(template || '')
  return s.replace(/\{(\w+)\}/g, (match, key) => {
    return data[key] !== undefined ? data[key] : match
  })
}

/**
 * 生成随机字符串
 * @param {number} length - 长度
 * @returns {string} 随机字符串
 * 
 * wjs created by 2016-02-01
 */
function wjs_randomString(length = 16) {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
  let result = ''
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length))
  }
  return result
}

/**
 * 生成唯一ID
 * @returns {string} 唯一ID
 * 
 * wjs created by 2016-02-10
 */
function wjs_uniqueId() {
  return Date.now().toString(36) + Math.random().toString(36).substr(2)
}

/**
 * 字符串重复
 * @param {string} str - 字符串
 * @param {number} times - 重复次数
 * @returns {string} 重复后的字符串
 * 
 * wjs created by 2016-03-01
 */
function wjs_repeat(str, times) {
  return String(str || '').repeat(times || 1)
}

/**
 * 字符串分割为数组
 * @param {string} str - 字符串
 * @param {string} separator - 分隔符
 * @returns {Array} 分割后的数组
 * 
 * wjs created by 2016-03-10
 */
function wjs_split(str, separator = ',') {
  return String(str || '').split(separator)
}

/**
 * 判断字符串是否以指定前缀开头
 * @param {string} str - 字符串
 * @param {string} prefix - 前缀
 * @returns {boolean} 是否以指定前缀开头
 * 
 * wjs created by 2016-04-01
 */
function wjs_startsWith(str, prefix) {
  return String(str || '').startsWith(prefix)
}

/**
 * 判断字符串是否以指定后缀结尾
 * @param {string} str - 字符串
 * @param {string} suffix - 后缀
 * @returns {boolean} 是否以指定后缀结尾
 * 
 * wjs created by 2016-04-05
 */
function wjs_endsWith(str, suffix) {
  return String(str || '').endsWith(suffix)
}

/**
 * 判断字符串是否包含指定子串
 * @param {string} str - 字符串
 * @param {string} substr - 子串
 * @returns {boolean} 是否包含指定子串
 * 
 * wjs created by 2016-04-10
 */
function wjs_includes(str, substr) {
  return String(str || '').includes(substr)
}

/**
 * 获取字符串中指定子串出现的次数
 * @param {string} str - 字符串
 * @param {string} substr - 子串
 * @returns {number} 出现次数
 * 
 * wjs created by 2016-05-01
 */
function wjs_countOccurrences(str, substr) {
  const s = String(str || '')
  if (!substr) return 0
  let count = 0
  let index = 0
  while ((index = s.indexOf(substr, index)) !== -1) {
    count++
    index += substr.length
  }
  return count
}

/**
 * 全角转半角
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-05-15
 */
function wjs_fullWidthToHalfWidth(str) {
  const s = String(str || '')
  let result = ''
  for (let i = 0; i < s.length; i++) {
    const charCode = s.charCodeAt(i)
    if (charCode >= 65281 && charCode <= 65374) {
      result += String.fromCharCode(charCode - 65248)
    } else if (charCode === 12288) {
      result += ' '
    } else {
      result += s.charAt(i)
    }
  }
  return result
}

/**
 * 半角转全角
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-05-20
 */
function wjs_halfWidthToFullWidth(str) {
  const s = String(str || '')
  let result = ''
  for (let i = 0; i < s.length; i++) {
    const charCode = s.charCodeAt(i)
    if (charCode >= 33 && charCode <= 126) {
      result += String.fromCharCode(charCode + 65248)
    } else if (charCode === 32) {
      result += String.fromCharCode(12288)
    } else {
      result += s.charAt(i)
    }
  }
  return result
}

/**
 * 驼峰命名转下划线命名
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-06-01
 */
function wjs_camelToSnake(str) {
  const s = String(str || '')
  return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()
}

/**
 * 下划线命名转驼峰命名
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-06-05
 */
function wjs_snakeToCamel(str) {
  const s = String(str || '')
  return s.replace(/_(\w)/g, (match, char) => char.toUpperCase())
}

/**
 * 中划线命名转驼峰命名
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-06-10
 */
function wjs_kebabToCamel(str) {
  const s = String(str || '')
  return s.replace(/-(\w)/g, (match, char) => char.toUpperCase())
}

/**
 * 驼峰命名转中划线命名
 * @param {string} str - 待转换字符串
 * @returns {string} 转换后的字符串
 * 
 * wjs created by 2016-06-15
 */
function wjs_camelToKebab(str) {
  const s = String(str || '')
  return s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
}

/**
 * 生成指定长度的填充字符串
 * @param {number} length - 长度
 * @param {string} char - 填充字符
 * @returns {string} 填充后的字符串
 * 
 * wjs created by 2016-07-01
 */
function wjs_pad(length, char = ' ') {
  return char.repeat(length)
}

/**
 * 字符串左侧填充
 * @param {string} str - 字符串
 * @param {number} length - 目标长度
 * @param {string} char - 填充字符
 * @returns {string} 填充后的字符串
 * 
 * wjs created by 2016-07-10
 */
function wjs_padStart(str, length, char = ' ') {
  return String(str || '').padStart(length, char)
}

/**
 * 字符串右侧填充
 * @param {string} str - 字符串
 * @param {number} length - 目标长度
 * @param {string} char - 填充字符
 * @returns {string} 填充后的字符串
 * 
 * wjs created by 2016-07-15
 */
function wjs_padEnd(str, length, char = ' ') {
  return String(str || '').padEnd(length, char)
}

/**
 * 移除字符串中的HTML标签
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2016-08-01
 */
function wjs_removeHtmlTags(str) {
  const s = String(str || '')
  return s.replace(/<[^>]*>/g, '')
}

/**
 * 移除字符串中的特殊字符
 * @param {string} str - 待处理字符串
 * @param {string} allowed - 允许保留的字符
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2016-08-10
 */
function wjs_removeSpecialChars(str, allowed = '') {
  const s = String(str || '')
  const allowedChars = allowed.split('').map(c => `\\${c}`).join('')
  const regex = new RegExp(`[^a-zA-Z0-9\u4e00-\u9fa5${allowedChars}]`, 'g')
  return s.replace(regex, '')
}

/**
 * 生成随机颜色值（十六进制）
 * @returns {string} 颜色值
 * 
 * wjs created by 2016-09-01
 */
function wjs_randomColor() {
  return '#' + Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0')
}

/**
 * 生成随机颜色值（rgb）
 * @returns {string} rgb颜色值
 * 
 * wjs created by 2016-09-05
 */
function wjs_randomRgbColor() {
  const r = Math.floor(Math.random() * 256)
  const g = Math.floor(Math.random() * 256)
  const b = Math.floor(Math.random() * 256)
  return `rgb(${r}, ${g}, ${b})`
}

/**
 * 十六进制颜色转rgb颜色
 * @param {string} hex - 十六进制颜色
 * @returns {string} rgb颜色
 * 
 * wjs created by 2016-09-10
 */
function wjs_hexToRgb(hex) {
  const h = String(hex || '#000000').replace('#', '')
  const r = parseInt(h.substring(0, 2), 16)
  const g = parseInt(h.substring(2, 4), 16)
  const b = parseInt(h.substring(4, 6), 16)
  return `rgb(${r}, ${g}, ${b})`
}

/**
 * rgb颜色转十六进制颜色
 * @param {string} rgb - rgb颜色
 * @returns {string} 十六进制颜色
 * 
 * wjs created by 2016-09-15
 */
function wjs_rgbToHex(rgb) {
  const match = String(rgb || '').match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/)
  if (!match) return '#000000'
  const r = parseInt(match[1]).toString(16).padStart(2, '0')
  const g = parseInt(match[2]).toString(16).padStart(2, '0')
  const b = parseInt(match[3]).toString(16).padStart(2, '0')
  return '#' + r + g + b
}

/**
 * 字符串反转
 * @param {string} str - 待反转字符串
 * @returns {string} 反转后的字符串
 * 
 * wjs created by 2017-01-01
 */
function wjs_reverseString(str) {
  return String(str || '').split('').reverse().join('')
}

/**
 * 生成UUID
 * @returns {string} UUID
 * 
 * wjs created by 2017-02-15
 */
function wjs_uuid() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0
    const v = c === 'x' ? r : (r & 0x3 | 0x8)
    return v.toString(16)
  })
}

/**
 * 隐藏字符串中间部分（如手机号、身份证号）
 * @param {string} str - 原字符串
 * @param {number} start - 开始保留长度
 * @param {number} end - 结束保留长度
 * @param {string} mask - 掩码字符
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2017-03-10
 */
function wjs_maskString(str, start = 3, end = 4, mask = '*') {
  const s = String(str || '')
  if (s.length <= start + end) return s
  return s.substring(0, start) + mask.repeat(s.length - start - end) + s.substring(s.length - end)
}

/**
 * 格式化电话号码
 * @param {string} phone - 电话号码
 * @returns {string} 格式化后的电话号码
 * 
 * wjs created by 2017-04-01
 */
function wjs_formatPhone(phone) {
  const s = wjs_removeSpaces(phone)
  if (s.length === 11) {
    return s.replace(/(\d{3})(\d{4})(\d{4})/, '$1 $2 $3')
  }
  return s
}

/**
 * 格式化身份证号
 * @param {string} idCard - 身份证号
 * @returns {string} 格式化后的身份证号
 * 
 * wjs created by 2017-04-10
 */
function wjs_formatIdCard(idCard) {
  const s = wjs_removeSpaces(idCard)
  if (s.length === 18) {
    return s.replace(/(\d{6})(\d{8})(\d{4})/, '$1 $2 $3')
  }
  return s
}

/**
 * 生成指定长度的随机数字字符串
 * @param {number} length - 长度
 * @returns {string} 随机数字字符串
 * 
 * wjs created by 2017-05-01
 */
function wjs_randomDigits(length = 6) {
  let result = ''
  for (let i = 0; i < length; i++) {
    result += Math.floor(Math.random() * 10)
  }
  return result
}

/**
 * 生成指定长度的验证码
 * @param {number} length - 长度
 * @param {boolean} includeLetters - 是否包含字母
 * @returns {string} 验证码
 * 
 * wjs created by 2017-05-15
 */
function wjs_generateCaptcha(length = 4, includeLetters = true) {
  let chars = '0123456789'
  if (includeLetters) {
    chars += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
  }
  let result = ''
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length))
  }
  return result
}

/**
 * 判断字符串是否为空或空白
 * @param {string} str - 字符串
 * @returns {boolean} 是否为空或空白
 * 
 * wjs created by 2018-01-15
 */
function wjs_isBlankString(str) {
  return wjs_trim(str) === ''
}

/**
 * 字符串去重
 * @param {string} str - 字符串
 * @returns {string} 去重后的字符串
 * 
 * wjs created by 2018-03-10
 */
function wjs_uniqueString(str) {
  const s = String(str || '')
  return [...new Set(s.split(''))].join('')
}

/**
 * 获取字符串中出现频率最高的字符
 * @param {string} str - 字符串
 * @returns {string} 频率最高的字符
 * 
 * wjs created by 2018-04-20
 */
function wjs_mostFrequentChar(str) {
  const s = String(str || '')
  const counts = {}
  let maxChar = ''
  let maxCount = 0
  
  for (const char of s) {
    counts[char] = (counts[char] || 0) + 1
    if (counts[char] > maxCount) {
      maxCount = counts[char]
      maxChar = char
    }
  }
  
  return maxChar
}

/**
 * 字符串转数组（按字符）
 * @param {string} str - 字符串
 * @returns {Array} 字符数组
 * 
 * wjs created by 2018-06-15
 */
function wjs_stringToArray(str) {
  return String(str || '').split('')
}

/**
 * 数组转字符串
 * @param {Array} arr - 数组
 * @param {string} separator - 分隔符
 * @returns {string} 字符串
 * 
 * wjs created by 2018-07-01
 */
function wjs_arrayToString(arr, separator = '') {
  return Array.isArray(arr) ? arr.join(separator) : String(arr)
}

/**
 * 生成随机Emoji
 * @returns {string} Emoji字符
 * 
 * wjs created by 2019-01-10
 */
function wjs_randomEmoji() {
  const emojis = ['😀', '😎', '🚀', '💡', '🎯', '🔥', '⭐', '💪', '🎉', '✨']
  return emojis[Math.floor(Math.random() * emojis.length)]
}

/**
 * 移除字符串中的重复字符
 * @param {string} str - 字符串
 * @param {boolean} caseSensitive - 是否区分大小写
 * @returns {string} 去重后的字符串
 * 
 * wjs created by 2020-03-15
 */
function wjs_removeDuplicateChars(str, caseSensitive = true) {
  const s = caseSensitive ? String(str || '') : String(str || '').toLowerCase()
  const seen = new Set()
  let result = ''
  
  for (const char of s) {
    if (!seen.has(char)) {
      seen.add(char)
      result += char
    }
  }
  
  return result
}

/**
 * 生成指定长度的星号字符串
 * @param {number} length - 长度
 * @returns {string} 星号字符串
 * 
 * wjs created by 2021-05-20
 */
function wjs_generateStars(length = 5) {
  return '*'.repeat(length)
}

/**
 * 字符串加密（简单混淆）
 * @param {string} str - 待加密字符串
 * @returns {string} 加密后的字符串
 * 
 * wjs created by 2022-01-10
 */
function wjs_encryptString(str) {
  const s = String(str || '')
  let result = ''
  for (let i = 0; i < s.length; i++) {
    result += String.fromCharCode(s.charCodeAt(i) + 1)
  }
  return result
}

/**
 * 字符串解密
 * @param {string} str - 待解密字符串
 * @returns {string} 解密后的字符串
 * 
 * wjs created by 2022-01-15
 */
function wjs_decryptString(str) {
  const s = String(str || '')
  let result = ''
  for (let i = 0; i < s.length; i++) {
    result += String.fromCharCode(s.charCodeAt(i) - 1)
  }
  return result
}

/**
 * 判断字符串是否是回文
 * @param {string} str - 字符串
 * @returns {boolean} 是否是回文
 * 
 * wjs created by 2023-06-10
 */
function wjs_isPalindrome(str) {
  const s = wjs_removeSpaces(wjs_toLowerCase(str))
  return s === s.split('').reverse().join('')
}

/**
 * 首字母小写
 * @param {string} str - 待处理字符串
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2024-02-15
 */
function wjs_lowerCaseFirst(str) {
  const s = String(str || '')
  if (s.length === 0) return s
  return s.charAt(0).toLowerCase() + s.slice(1)
}

/**
 * 交换字符串中两个位置的字符
 * @param {string} str - 字符串
 * @param {number} index1 - 第一个位置
 * @param {number} index2 - 第二个位置
 * @returns {string} 交换后的字符串
 * 
 * wjs created by 2025-04-20
 */
function wjs_swapChars(str, index1, index2) {
  const arr = String(str || '').split('')
  if (index1 >= 0 && index1 < arr.length && index2 >= 0 && index2 < arr.length) {
    [arr[index1], arr[index2]] = [arr[index2], arr[index1]]
  }
  return arr.join('')
}

/**
 * 移除字符串中指定位置的字符
 * @param {string} str - 字符串
 * @param {number} index - 位置
 * @returns {string} 处理后的字符串
 * 
 * wjs created by 2026-01-25
 */
function wjs_removeCharAt(str, index) {
  const s = String(str || '')
  if (index < 0 || index >= s.length) return s
  return s.substring(0, index) + s.substring(index + 1)
}

// ============================================================
// 导出模块
// ============================================================
if (typeof module !== 'undefined' && module.exports) {
  module.exports = {
    wjs_trim,
    wjs_trimLeft,
    wjs_trimRight,
    wjs_removeSpaces,
    wjs_truncate,
    wjs_strLength,
    wjs_toUpperCase,
    wjs_toLowerCase,
    wjs_capitalize,
    wjs_capitalizeEachWord,
    wjs_escapeHtml,
    wjs_unescapeHtml,
    wjs_encodeUrl,
    wjs_decodeUrl,
    wjs_replaceAll,
    wjs_format,
    wjs_randomString,
    wjs_uniqueId,
    wjs_repeat,
    wjs_split,
    wjs_startsWith,
    wjs_endsWith,
    wjs_includes,
    wjs_countOccurrences,
    wjs_fullWidthToHalfWidth,
    wjs_halfWidthToFullWidth,
    wjs_camelToSnake,
    wjs_snakeToCamel,
    wjs_kebabToCamel,
    wjs_camelToKebab,
    wjs_pad,
    wjs_padStart,
    wjs_padEnd,
    wjs_removeHtmlTags,
    wjs_removeSpecialChars,
    wjs_randomColor,
    wjs_randomRgbColor,
    wjs_hexToRgb,
    wjs_rgbToHex,
    wjs_reverseString,
    wjs_uuid,
    wjs_maskString,
    wjs_formatPhone,
    wjs_formatIdCard,
    wjs_randomDigits,
    wjs_generateCaptcha,
    wjs_isBlankString,
    wjs_uniqueString,
    wjs_mostFrequentChar,
    wjs_stringToArray,
    wjs_arrayToString,
    wjs_randomEmoji,
    wjs_removeDuplicateChars,
    wjs_generateStars,
    wjs_encryptString,
    wjs_decryptString,
    wjs_isPalindrome,
    wjs_lowerCaseFirst,
    wjs_swapChars,
    wjs_removeCharAt
  }
}