Improve data#string api (#2515)

- add fill_left and fill_middle function
- fix string api doc
- add string api cn doc

autoload/SpaceVim/api/data/string.vim

@@ -16,6 +16,14 @@
 " split(str [, sep [, keepempty[, max]]])
 "
 "   run vim command, and return the output of such command.
+"
+" trim(str)
+"
+"   remove space at the begin and end of a string, same as |trim()|
+"
+" fill(str, length[, char])
+"
+"   fill string to length with {char}, if {char} is omnit, a space is used.
 
 let s:self = {}
 
@@ -24,7 +32,7 @@ function! s:self.trim(str) abort
   return substitute(str, '^\s*', '', 'g')
 endfunction
 
-function! s:self.fill(str, length) abort
+function! s:self.fill(str, length, ...) abort
   if strwidth(a:str) <= a:length
     let l:string = a:str
   else
@@ -34,39 +42,43 @@ function! s:self.fill(str, length) abort
     endwhile
     let l:string = strcharpart(a:str, 0, l:rightmost)
   endif
-  let l:spaces = repeat(' ', a:length - strwidth(l:string))
+  let char = get(a:000, 0, ' ')
+  if type(char) !=# 1 || len(char) > 1
+    let char = ' '
+  endif
+  let l:spaces = repeat(char, a:length - strwidth(l:string))
   return l:string . l:spaces
 endfunction
 
-function! s:self.fill_left(str, length) abort
+function! s:self.fill_left(str, length, ...) abort
   if strwidth(a:str) <= a:length
     let l:string = a:str
   else
-    let l:rightmost = 0
+    let l:string = strcharpart(a:str, strwidth(a:str) - a:length, a:length)
-    while strwidth(strcharpart(a:str, 0, l:rightmost)) < a:length
-      let l:rightmost += 1
-    endwhile
-    let l:string = strcharpart(a:str, 0, l:rightmost)
   endif
-  let l:spaces = repeat(' ', a:length - strwidth(l:string))
+  let char = get(a:000, 0, ' ')
+  if type(char) !=# 1 || len(char) > 1
+    let char = ' '
+  endif
+  let l:spaces = repeat(char, a:length - strwidth(l:string))
   return l:spaces . l:string
 endfunction
 
-function! s:self.fill_middle(str, length) abort
+function! s:self.fill_middle(str, length, ...) abort
   if strwidth(a:str) <= a:length
     let l:string = a:str
   else
-    let l:rightmost = 0
+    let l:string = strcharpart(a:str, (a:length/2 < 1 ? 1 : a:length/2), a:length)
-    while strwidth(strcharpart(a:str, 0, l:rightmost)) < a:length
-      let l:rightmost += 1
-    endwhile
-    let l:string = strcharpart(a:str, 0, l:rightmost)
   endif
   let l:numofspaces = a:length - strwidth(l:string)
-  let l:halfspaces = repeat(' ', l:numofspaces/2)
+  let char = get(a:000, 0, ' ')
-  let l:rst = l:halfspaces . a:str . l:halfspaces
+  if type(char) !=# 1 || len(char) > 1
+    let char = ' '
+  endif
+  let l:halfspaces = repeat(char, l:numofspaces/2)
+  let l:rst = l:halfspaces . l:string . l:halfspaces
   if l:numofspaces % 2
-    let l:rst .= ' '
+    let l:rst .= char
   endif
   return l:rst
 endfunction
@@ -79,11 +91,17 @@ function! s:self.trim_end(str) abort
   return substitute(a:str, '\s*$', '', 'g')
 endfunction
 
+
+" note: this function only works when encoding is utf-8
+" ref: https://github.com/SpaceVim/SpaceVim/pull/2515
 function! s:self.string2chars(str) abort
+  let save_enc = &encoding
+  let &encoding = 'utf-8'
   let chars = []
-  for i in range(len(a:str))
+  for i in range(strchars(a:str))
-    call add(chars, a:str[i : i])
+    call add(chars, strcharpart(a:str,  i , 1))
   endfor
+  let &encoding = save_enc
   return chars
 endfunction
 
@@ -108,13 +126,15 @@ function! s:self.strAllIndex(str, need, use_expr) abort
 endfunction
 
 function! s:self.strQ2B(str) abort
+  let save_enc = &encoding
+  let &encoding = 'utf-8'
   let chars = self.string2chars(a:str)
   let bchars = []
   for char in chars
     let nr = char2nr(char)
     if nr == 12288
       call add(bchars, nr2char(32))
-    elseif nr == 8216 &&  nr == 8217
+    elseif nr == 8216 ||  nr == 8217
       call add(bchars, nr2char(39))
     elseif nr >= 65281 && nr <= 65374
       call add(bchars, nr2char(nr - 65248))
@@ -122,10 +142,13 @@ function! s:self.strQ2B(str) abort
       call add(bchars, char)
     endif
   endfor
+  let &encoding = save_enc
   return join(bchars, '')
 endfunction
 
 function! s:self.strB2Q(str) abort
+  let save_enc = &encoding
+  let &encoding = 'utf-8'
   let chars = self.string2chars(a:str)
   let bchars = []
   for char in chars
@@ -138,6 +161,7 @@ function! s:self.strB2Q(str) abort
       call add(bchars, char)
     endif
   endfor
+  let &encoding = save_enc
   return join(bchars, '')
   
 endfunction

autoload/SpaceVim/layers/tools/zeal.vim

@@ -10,6 +10,7 @@
 " @section tools#zeal, layer-tools-zeal
 " @parentsection layers
 " This layer provides Zeal integration for SpaceVim
+
 function! SpaceVim#layers#tools#zeal#plugins() abort
   return [
         \ ['KabbAmine/zeavim.vim', {

doc/SpaceVim.txt

@@ -76,6 +76,7 @@ CONTENTS                                                   *SpaceVim-contents*
       31. shell.........................................|SpaceVim-layer-shell|
       32. tmux...........................................|SpaceVim-layer-tmux|
       33. tools#dash...............................|SpaceVim-layer-tools-dash|
+      34. tools#zeal...............................|SpaceVim-layer-tools-zeal|
   7. API........................................................|SpaceVim-api|
       1. cmdlinemenu................................|SpaceVim-api-cmdlinemenu|
       2. data#dict....................................|SpaceVim-api-data-dict|
@@ -1362,6 +1363,11 @@ TOOLS#DASH                                         *SpaceVim-layer-tools-dash*
 
 This layer provides Dash integration for SpaceVim
 
+==============================================================================
+TOOLS#ZEAL                                         *SpaceVim-layer-tools-zeal*
+
+This layer provides Zeal integration for SpaceVim
+
 ==============================================================================
 API                                                             *SpaceVim-api*
 
@@ -1450,6 +1456,14 @@ split(str [, sep [, keepempty[, max]]])
 
   run vim command, and return the output of such command.
 
+trim(str)
+
+  remove space at the begin and end of a string, same as |trim()|
+
+fill(str, length[, char])
+
+  fill string to length with {char}, if {char} is omnit, a space is used.
+
 ==============================================================================
 JOB                                                         *SpaceVim-api-job*
 

docs/api/data/string.md

@@ -27,5 +27,15 @@ echo str1
 ## functions
 
 | name                            | description                                                              |
-| ----------- | ------------------------------------------------------------------------ |
+| ------------------------------- | ------------------------------------------------------------------------ |
 | `trim(str)`                     | remove spaces from the beginning and end of a string, return the resuilt |
+| `trim_start(str)`               | remove spaces from the beginning a string, return the resuilt            |
+| `trim_end(str)`                 | remove spaces from the end of a string, return the resuilt               |
+| `fill(str, len[, char])`        | fill the char after string                                               |
+| `fill_left(str, len[, char])`   | same as fill(), but the char will be append on the left                  |
+| `fill_middle(str, len[, char])` | same as fill(), but the char will be append arround the string           |
+| `string2chars(str)`             | return a list of chars in the string                                     |
+| `strALLIndex(str, )`            | return a list of position found in this string                           |
+| `strQ2B(str)`                   | change string form Q 2 B                                                 |
+| `strB2Q(str)`                   | change string form B 2 Q                                                 |
+| `split(str)`                    | split string into list                                                   |

docs/cn/api.md

@@ -44,12 +44,13 @@ echom s:file.pathSeparator
 ## 可用 APIs
 
 | 名称                                  | 描述                                                                    |
-| ------------------------------------- | ------------------------------------------------------------------------- |
+| ------------------------------------- | ----------------------------------------------------------------------- |
 | [data#dict](data/dict/)               | data#dict API 提供了一些处理字典变量的常用方法，包括基础的增删改查。    |
+| [data#string](data/string/)           | data#string 函数库主要提供一些操作字符串的常用函数。                    |
 | [file](file/)                         | 文件函数提供了基础的文件读写相关函数，兼容不同系统平台。                |
-| [job](job/)                           | 兼容 Neovim 和 Vim 的异步协同 API，对于旧版 Vim 采用非异步机制。          |
+| [job](job/)                           | 兼容 neovim 和 vim 的异步协同 API，对于旧版 vim 采用非异步机制          |
 | [system](system/)                     | system 函数提供了系统相关函数，包括判断当前系统平台，文件格式等函数。   |
-| [unicode#spinners](unicode/spinners/) | unicode#spinners API 可启用一个定时器，根据指定的名称定时更新进度条符号。 |
+| [unicode#spinners](unicode/spinners/) | unicode#spinners API 可启用一个定时器，根据指定的名称定时更新进度条符号 |
 | [vim#command](vim/command/)           | vim#command API 提供一些设置和获取 Vim 命令的基础函数。                 |
 | [vim#highlight](vim/highlight/)       | vim#highlight API 提供一些设置和获取 Vim 高亮信息的基础函数。           |
 

docs/cn/api/data/string.md

@@ -0,0 +1,42 @@
+---
+title: "data#string 函数库"
+description: "data#string 函数库主要提供一些操作字符串的常用函数。"
+lang: cn
+---
+
+# [可用函数库](../../) >> data#string
+
+<!-- vim-markdown-toc GFM -->
+
+- [简介](#简介)
+- [函数](#函数)
+
+<!-- vim-markdown-toc -->
+
+## 简介
+
+`data#string` 函数提供了一些操作字符串的工具方法，以下为使用这一函数的示例：
+
+```vim
+let s:STR = SpaceVim#api#import('data#string')
+let str1 = '  hello world   '
+let str2 = s:STR.trim(str1)
+echo str1
+" 此时将看到打印 `hello world`
+```
+
+## 函数
+
+| 名称                            | 功能描述                                             |
+| ------------------------------- | ---------------------------------------------------- |
+| `trim(str)`                     | 移除字符串首尾空白字符，包括空格、制表符等，返回结果 |
+| `trim_start(str)`               | 移除字符串首部空白字符，包括空格、制表符等，返回结果 |
+| `trim_end(str)`                 | 移除字符串尾部空白字符，包括空格、制表符等，返回结果 |
+| `fill(str, len[, char])`        | 字符串尾部填充或删除字符以达到指定可视长度           |
+| `fill_left(str, len[, char])`   | 类似于`fill()`, 但是在首部填充或删除字符             |
+| `fill_middle(str, len[, char])` | 类似于`fill()`, 但是在两次同时填充或删除字符         |
+| `string2chars(str)`             | 将字符串转换成一组字符列表并返回                     |
+| `strALLIndex(str, )`            | 在字符串中查询某个表达式，并返回一组匹配位置列表     |
+| `strQ2B(str)`                   | 将字符串从全角转化为半角                             |
+| `strB2Q(str)`                   | 将字符串从半角转化为全角                             |
+| `split(str)`                    | 拆分字符串                                           |

test/api/data/string.vader

@@ -1,13 +1,43 @@
 Execute ( SpaceVim api: data#string ):
   let str = SpaceVim#api#import('data#string')
-  AssertEqual str.split('   20   281   23 -invalid-', '', 0, 4)[2], '23'
+  Log 'test trim()'
   AssertEqual str.trim(' s b '), 's b'
-  AssertEqual str.trim_start(' s b '), 's b '
+  Log 'test fill()'
-  AssertEqual str.trim_end(' s b '), ' s b'
   AssertEqual str.fill('s b', 10), 's b       '
-  AssertEqual str.fill_middle('s b', 10), '   s b    '
+  Log 'test fill() len < strlen'
+  AssertEqual str.fill('s b', 2), 's '
+  Log 'test fill() with char'
+  AssertEqual str.fill('s b', 10, '*'), 's b*******'
+  Log 'test fill_left()'
+  AssertEqual str.fill_left('s b', 10, '*'), '*******s b'
+  Log 'test fill_left() len = strlen'
+  AssertEqual str.fill_left('s b', 3, '*'), 's b'
+  Log 'test fill_left() len < strlen'
+  AssertEqual str.fill_left('s b', 2, '*'), ' b'
+  Log 'test fill_middle()'
+  AssertEqual str.fill_middle('s b', 9, '*'), '***s b***'
+  Log 'test fill_middle() fill number % 2  = 1'
+  AssertEqual str.fill_middle('s b', 10, '*'), '***s b****'
+  Log 'test fill_middle() len = strlen'
+  AssertEqual str.fill_middle('s b', 3, '*'), 's b'
+  Log 'test fill_middle() len < strlen'
+  AssertEqual str.fill_middle('s b', 2, '*'), ' b'
+  AssertEqual str.fill_middle('s b', 1, '*'), ' '
+  Log 'test split()'
+  AssertEqual str.split('   20   281   23 -invalid-', '', 0, 4)[2], '23'
+  Log 'test trim_start()'
+  AssertEqual str.trim_start(' s b '), 's b '
+  Log 'test string2chars()'
   AssertEqual str.string2chars(' a b '), [' ', 'a', ' ', 'b', ' ']
+  AssertEqual str.string2chars('你好'), ['你', '好']
+  Log 'test strQ2B()'
+  AssertEqual str.strQ2B('％'), '%'
+  Log 'test strB2Q()'
+  AssertEqual str.strB2Q('%'), '％'
+  AssertEqual str.trim_end(' s b '), ' s b'
+  AssertEqual str.fill_middle('s b', 10), '   s b    '
   AssertEqual str.strAllIndex('hello spacevim hello', 'hello', 0), [[0, 5], [15, 20]]
   AssertEqual str.strAllIndex('hello spacevim hello', 'he.*', 1), [[0, 20]]
   AssertEqual str.strAllIndex('hello spacevim hello', 'he[^ ]*', 1), [[0, 5], [15, 20]]
   AssertEqual str.strAllIndex('let s:cursor_stack[i].end = s:cursor_stack[i].cursor . s:cursor_stack[i].end', 's.cursor[^_]*', 1), [[4, 12], [28, 36], [55, 63]]
+  unlet str