string.lua

local type = type
local select = select
local assert = assert
local tonumber = tonumber

local string = string
local ssub = string.sub
local srep = string.rep
local sfind = string.find
local sbyte = string.byte
local sgsub = string.gsub
local sgmatch = string.gmatch

local tconcat = table.concat

---comment 计算`pattern`在`text`中pos位置开始出现的总次数.
---@param text    string   @实际内容
---@param pattern string   @匹配内容
---@param pos     integer  @字符串
---@return string @返回拼接好的字符串
function string.count (text, pattern, pos)
  local count = 0
  if not pos then
    pos = 1
  end
  while true do
    local s, e = sfind(text, pattern, pos)
    if not s or not e then
      break
    end
    count = count + 1
    pos = e + 1
  end
  return count
end

---comment 以`text`为中心拼接`count`个`fill`在两侧.
---@param text   string   @实际内容
---@param fill   string   @填充字符
---@param count  integer  @填充数量
---@return string @返回拼接好的字符串
function string.center (text, fill, count)
  assert(type(text) == 'string' and type(fill) == 'string' , "Invalid string `text` or `fill`.")
  assert(type(count) == 'number' and tonumber(count) or count > 0, "Invalid fill `count`")
  local fill_text = srep(fill, count)
  return tconcat{ fill_text, text, fill_text }
end

---comment 判断指定字符串内容是否全部空格
---@param text string   @判断内容
---@return boolean      @如果`text`全是空格返回`true`, 否则返回`false`.
function string.allspace (text)
  return sfind(text or '', "^[ ]+$") and true or false
end

---comment 连接`1`个或`N`个字符串, 非可转换字符串的对象会抛出异常
---@return string
function string.join (...)
  if select("#", ...) <= 1 then
    return (...) or ''
  end
  return tconcat{...}
end

---comment 根据`sep`分割`text`字符串.
---@param text   string   @待分割的字符串
---@param sep    string   @分割用的分隔符
---@return table          @分割后的数组
function string.split(text, sep)
  assert(type(text) == 'string', "Invalid string `text`.")
  if not sep or type(sep) ~= 'string' or sep == ''  then
    sep = '%,'
  end
  local index = 1
  local list = {}
  for sub in sgmatch(text, "([^" .. sep .. "]*)") do
    list[index] = sub
    index = index + 1
  end
  if index == 1 then
    list[index] = text
  end
  return list
end

local function strip(text, sep, left, right)
  if left then
    text = sgsub(text, "^[" .. sep .."]+", "", 1)
  end
  if right then
    text = sgsub(text, "[" .. sep .."]+$", "", 1)
  end
  return text
end

---comment 移除字符串头、尾指定的字符
---@param text   string   @待分割的字符串
---@param sep    string   @移除用的分隔符
function string.strip (text, sep)
  assert(type(text) == 'string', "Invalid string `text`.")
  if not sep or type(sep) ~= 'string' or sep == ''  then
    sep = ' '
  end
  return strip(text, sep, true, true)
end

---comment 移除字符串头部指定的字符
---@param text   string   @待分割的字符串
---@param sep    string   @移除用的分隔符
function string.lstrip (text, sep)
  assert(type(text) == 'string', "Invalid string `text`.")
  if not sep or type(sep) ~= 'string' or sep == ''  then
    sep = ' '
  end
  return strip(text, sep, true, false)
end

---comment 移除字符串尾部指定的字符
---@param text string   @待分割的字符串
---@param sep  string   @移除用的分隔符
function string.rstrip (text, sep)
  assert(type(text) == 'string', "Invalid string `text`.")
  if not sep or type(sep) ~= 'string' or sep == ''  then
    sep = ' '
  end
  return strip(text, sep, false, true)
end

---comment 判断起始位置是否指定内容
---@param text    string  @待匹配内容
---@param sstring string  @其实内容
---@param start   integer @起始位置
function string.startswith(text, sstring, start)
  assert(type(text) == 'string', "Invalid string `text`.")
  assert(type(sstring) == 'string', "Invalid start string.")
  return sfind(text, '^' .. sstring,  start) and true or false
end

---comment 判断结束位置是否指定内容
---@param text    string  @待匹配内容
---@param estring string  @结束内容
---@param over    integer @结束位置
function string.endswith(text, estring, over)
  assert(type(text) == 'string', "Invalid string `text`.")
  assert(type(estring) == 'string', "Invalid end string.")
  return sfind(text, estring .. '$',  over) and true or false
end

---comment 将`text`里的`s1`替换为`s2`(最多`count`此)
---@param text  string  @原始内容
---@param s1    string  @匹配字符串
---@param s2    string  @替换字符串
---@param count number  @替换次数
---@return string       @替换后内容
function string.replace (text, s1, s2, count)
  assert(type(text) == 'string' and text ~= '', "Invalid text string.")
  assert(type(s1) == 'string' and s1 ~= '', "Invalid s1 string.")
  assert(type(s2) == 'string' and s2 ~= '', "Invalid s2 string.")
  local s = sgsub(text, s1, s2, count)
  return s
end

---comment 字符串转换为字节数组
---@param  text string  @待转换的字符串
---@return table        @转换后的字节数组
function string.tobytes(text)
  assert(type(text) == 'string' and text ~= '', "Invalid text string.")
  local list = {}
  for idx = 1, #text do
    list[#list+1] = sbyte(text, idx)
  end
  return list
end

---comment 向指定位置的字符串后插入字符串.
---@param text   string  @原始字符串
---@param pos    integer @待插入的位置
---@param str    string  @待插入的字符串
---@return string        @返回插入后的字符串内容
function string.insert(text, pos, str)
  assert(type(text) == 'string' and text ~= '', "Invalid text string.")
  assert(type(pos) == 'number', "Invalid pos integer.")
  assert(type(str) == 'string' and str ~= '', "Invalid text string.")
  return tconcat{ssub(text, 1, pos), str, ssub(text, pos + 1, -1)}
end

local _, liconv = pcall(require, "liconv")

---comment 替换iconv函数, 错误的实现会出现运行时错误.
---@param module table
---@param encode string  @需保证`module[encode]`行为与`liconv.to`行为一致
---@param decode string  @需保证`module[decode]`行为与`liconv.from`行为一致
function string.iconv(module, encode, decode)
  liconv = { to = module[encode], from = module[decode] }
end

---comment 使用iconv进行编码转换
---@param text     string  @文本内容
---@param encoding string  @目标编码
---@return string          @转换后的文本
function string.encode (text, encoding)
  assert(type(text) == 'string', "Invalid string `text`.")
  assert(type(encoding) == 'string', "Invalid string encoding.")
  return assert(type(liconv) == 'table' and liconv, "Lua iconv is not supported.").to(encoding, text)
end

---comment 使用iconv进行编码转换
---@param text     string  @文本内容
---@param decoding string  @原始编码
---@return string          @转换后的文本
function string.decode (text, decoding)
  assert(type(text) == 'string', "Invalid string `text`.")
  assert(type(decoding) == 'string', "Invalid string encoding.")
  return assert(type(liconv) == 'table' and liconv, "Lua iconv is not supported.").from(decoding, text)
end