String.txt

*vital/Data/String.txt*		string utilities library.

Maintainer: ujihisa <ujihisa at gmail com>

==============================================================================
CONTENTS				*Vital.Data.String-contents*

INTRODUCTION			|Vital.Data.String-introduction|
INTERFACE			|Vital.Data.String-interface|
  Functions			  |Vital.Data.String-functions|

==============================================================================
INTRODUCTION				*Vital.Data.String-introduction*

*Vital.Data.String* is String Utilities Library.
It provides some functions to manipulate |String|.
>
	let s:V = vital#{plugin-name}#new()
	let s:S = s:V.import("Data.String")
<

==============================================================================
INTERFACE				*Vital.Data.String-interface*
------------------------------------------------------------------------------
FUNCTIONS				*Vital.Data.String-functions*

replace({str}, {from}, {to})		*Vital.Data.String.replace()*
	Returns string replaced {from} to {to} from {str}.
>
	echo s:S.replace("fooba.bazbar", "ba.", "zzz")
	" foozzzbazbar
<
replace_first({str}, {from}, {to})	*Vital.Data.String.replace_first()*
	Returns string replaced {from} to {to} from {str} only about the
	first-match.
>
	echo s:S.replace("foobarbazbar", "bar", "zzz")
	" foozzzbazzzz
	echo s:S.replace_first("foobarbazbar", "bar", "zzz")
	" foozzzbazbar
<
scan({str}, {pattern})			*Vital.Data.String.scan()*
	Returns |List| which matched {pattern} in {str}.

reverse({str})				*Vital.Data.String.reverse()*
	Returns a reversed string.  This works on character base.
>
	echo s:S.reverse("string")
	" gnirts
<
starts_with({str}, {prefix})		*Vital.Data.String.starts_with()*
	Returns true when {str} starts with {prefix}.
>
	echo s:S.starts_with('vital.vim', 'vi')
	" 1
	echo s:S.starts_with('vital.vim', 'vim')
	" 0
<
ends_with({str}, {suffix})		*Vital.Data.String.ends_with()*
	Returns true when {str} ends with {suffix}.
>
	echo s:S.ends_with('vital.vim', 'vim')
	" 1
	echo s:S.ends_with('vital.vim', 'vi')
	" 0
<
common_head({strs})			*Vital.Data.String.common_head()*
	Returns a common part of head of strings.
>
	echo s:S.common_head(['neocomplcache', 'neosnippet', 'neobundle'])
	" 'neo'
<
split_leftright({expr}, {pattern})	*Vital.Data.String.split_leftright()*
	Returns |List| that contains two |String| split by {pattern}.
>
	echo s:S.split_leftright('neocomplcache', 'neo\zs.....')
	" ['neo', 'cache']
<
split3({expr}, {pattern})		*Vital.Data.String.split3()*
	Like |Vital.Data.String.split_leftright()|, but this function returns
	[left, middle, right] not only [left, right].
>
	echo s:S.split3('neocomplcache', 'neo\zs.....')
	" ['neo', 'compl', 'cache']
<
					*Vital.Data.String.nsplit()*
nsplit({expr}, {n} [, {pattern} [, {keepempty}]])
	Behaves like |split()|.  Returns a list which is limited as {n}'th
	elements.

chop({str}) 				*Vital.Data.String.chop()*
	Removes last character from {str}.

chomp({str}) 				*Vital.Data.String.chomp()*
	Removes last \r,\n,\r\n from {str}.

trim({str})	                	*Vital.Data.String.trim()*
	Returns |String| removed spaces (|[:space:]|) from the beginning and end of a {str}.

trim_start({str})			*Vital.Data.String.trim_start()*
	Returns |String| removed spaces (|[:space:]|) from the beginning of a {str}.

trim_end({str})				*Vital.Data.String.trim_end()*
	Returns |String| removed spaces (|[:space:]|) from the end of a {str}.

wrap({str} [, {columns}])		*Vital.Data.String.wrap()*
	Returns |String| wrapped to fit to |columns| width.
        Default: {columns} = &columns

nr2byte({nr})				*Vital.Data.String.nr2byte()*
	Returns utf-8 bytes which has the number value {nr}.

nr2enc_char({charcode})			*Vital.Data.String.nr2enc_char()*
	Returns a string which has the number value {nr}.  This function
	depends on |encoding| option.

nr2hex({nr})				*Vital.Data.String.nr2hex()*
	Returns a hex string which has the number value {nr}.

diffidx({str1}, {str2})			*Vital.Data.String.diffidx()*
	Returns first index of different character if two strings are not
	equal, otherwise returns number -1 if the strings are equal.

substitute_last({expr}, {pat}, {sub})	*Vital.Data.String.substitute_last()*
	Behaves like |substitute()|, but it only replaces the last matched
	string.

dstring({expr})				*Vital.Data.String.dstring()*
	Behaves like |string()|, but this wraps the result string not with
	single-quotes but with double-quotes.
>
	echo s:S.dstring(123)
	" 123
	echo s:S.dstring('abc')
	" '"abc"'
	echo s:S.dstring("abc")
	" '"abc"'
<
lines({str})				*Vital.Data.String.lines()*
	Splits into list of strings of each line of {str}.

strchars({str})				*Vital.Data.String.strchars()*
	Returns the number of characters in String {str}.
	This is a polyfill of |strchars()| when it was not provided.

contains_multibyte({str})	*Vital.Data.String.contains_multibyte()*
	Return Number 1 if String {str} contains a multi-byte character,
	otherwise zero.

pad_left({str}, {width} [, {char}])	*Vital.Data.String.pad_left()*
	It returns a string padded {str}'s left side until given
	{width} with the given half-width {char} or white-space,
	considering non-half-width characters.
	Default: {char} = ' '
>
	echo s:S.pad_left('test', 11)
	" '       test'
<

pad_right({str}, {width} [, {char}])	*Vital.Data.String.pad_right()*
	It returns a string padded {str}'s right side until given
	{width} with the given half-width {char} or white-space,
	considering non-half-width characters.
	Default: {char} = ' '
>
	echo s:S.pad_right('test', 11)
	" 'test       '
<

					*Vital.Data.String.pad_both_sides()*
pad_both_sides({str}, {width} [, {char}])
	It returns a string padded {str}'s left and right side until given
	{width} with the given half-width {char} or white-space,
	considering non-half-width characters.
	Default: {char} = ' '
>
	echo s:S.pad_both_sides('test', 11)
	" '   test    '
<

				*Vital.Data.String.pad_between_letters()*
pad_between_letters({str}, {width} [, {char}])
	It returns a string padded between {str}'s letters until given
	{width} with the given half-width {char} or white-space,
	considering non-half-width characters.
	Default: {char} = ' '
>
	echo s:S.pad_between_letters('test', 11)
	" '  t e s t  '
<

				*Vital.Data.String.justify_equal_spacing()*
justify_equal_spacing({str}, {width} [, {char}])
	It returns a string justified equal spacing until given
	{width} with the given half-width {char} or white-space,
	considering non-half-width characters.
	Default: {char} = ' '
>
	echo s:S.justify_equal_spacing('test', 11)
	" 't   e  s  t'
<

				*Vital.Data.String.levenshtein_distance()*
levenshtein_distance({str1}, {str2})
        It returns a minimum edit distance of two given strings {str1} and
        {str2}.
>
	echo s:S.levenshtein_distance('kitten', 'sitting')
	" 3
<

				*Vital.Data.String.padding_by_displaywidth()*
padding_by_displaywidth({expr}, {width}, {float})
        It returns a string padding {expr} with spaces of {width}.
        {float}:
          left padding: `-1`
          center padding: `0`
          right padding: `1`
>
        echo s:S.padding_by_displaywidth('abc', 5, -1)
        " 'abc  '
        echo s:S.padding_by_displaywidth('abc', 5, 0)
        " ' abc '
        echo s:S.padding_by_displaywidth('abc', 5, 1)
        " '  abc'
<

				*Vital.Data.String.split_by_displaywidth()*
split_by_displaywidth({expr}, {width}, {float}, {is_wrap})
        It returns a list of string that split {expr} by line feed(LF)
        and apply `padding_by_displaywidth(v:val,{width},{float})` to these.
        {float}:
          left padding: `-1`
          center padding: `0`
          right padding: `1`
>
        echo s:S.split_by_displaywidth('あaいbうcえdおe', 5, -1, 1)
        " ['あaい', 'bうc ', 'えdお', 'e    ']
        echo s:S.split_by_displaywidth('あaいbうcえdおe', 5, -1, 0)
        " ['あaい']
        echo s:S.split_by_displaywidth('1234567890', 5, -1, 1)
        " ['12345', '67890']
        echo s:S.split_by_displaywidth("123\n4567890", 5, 1, 1)
        " ['  123', '45678', '   90']
<

        {is_wrap}:
          `1`: Considers line feed(LF) and does not consider wrap.
>
               " expr: "abcde\nfghijk"
               " width: 4
               " is_wrap: 1
               +----+
               |abcd|
               |e   |
               |fghi|
               |jk  |
               +----+
<
          `0`: Considers line feed(LF) and considers wrap.
>
               " expr: "abcde\nfghijk"
               " width: 4
               " is_wrap: 0
               +----+
               |abcd|
               |fghi|
               +----+


						*Vital.Data.String.hash()*
hash({str})
	This maps from arbitrary length string {str} to another string.
>
	echo s:S.hash('All your base are belong to us')
	" 'c46ec1b18ce8a878725a37e780dfb7351f68ed2e194c79fbc6aebee1a667975d'
<
	If the vim that evaluates this function has |sha256()| function, this
	uses it, otherwise it uses the algorithm to hash the string.
>
	let sum = 0
	for i in range(len(a:str))
	  let sum += char2nr(a:str[i]) * (i + 1)
	endfor
	
	return printf('%x', sum)
<
truncate({str}, {width})			*Vital.Data.String.truncate()*
	This function truncates the string {str} to the specified {width}.
	The width of the string is calculated as it is displayed.
>
	echo s:S.truncate('this is a pen', 2)
	" 'th'
	echo s:S.truncate('あいうえお', 2)
	" 'あ'
<
	If {width} is larger than the width {str} is displayed, spaces are
	appended.
>
	echo s:S.truncate('this is a pen', 20)
	" 'this is a pen       '
<
					*Vital.Data.String.truncate_skipping()*
truncate_skipping({str}, {max}, {footer-width}, {separator})
	This function splits the string {str} into two parts and joins with
	the given {separator}. The second argument {max} specifies the
	displayed width of the result string and the third argument
	{footer-width} specifies the displayed width of the string after the
	separator.
>
	echo s:S.truncate_skipping('this is a pen', 10, 3, '...')
	" 'this...pen'
	echo s:S.truncate_skipping('あいうえおかきくけこ', 10, 2, ' .. ')
	" 'あい .. こ'
<
strwidthpart({str}, {width})		*Vital.Data.String.strwidthpart()*
	This function returns the part of the string {str} the displayed width
	of which is narrower than the given {width}. This function does not
	append spaces as opposed to |Vital.Data.String.truncate()|.
>
	echo s:S.strwidthpart('this is a pen', 5)
	" 'this '
	echo s:S.strwidthpart('this is a pen', 20)
	" 'this is a pen'
	echo s:S.strwidthpart('あいうえお', 5)
	" 'あい'
	echo s:S.strwidthpart('あいうえお', 20)
	" 'あいうえお'
<
				*Vital.Data.String.strwidthpart_reverse()*
strwidthpart_reverse({str}, {width})
	This function returns the part of the string {str} like the function
	|Vital.Data.String.strwidthpart()|, but this function takes the part of
	the string from the right.
>
	echo s:S.strwidthpart_reverse('this is a pen', 5)
	" 'a pen'
	echo s:S.strwidthpart_reverse('this is a pen', 20)
	" 'this is a pen'
	echo s:S.strwidthpart_reverse('あいうえお', 5)
	" 'えお'
	echo s:S.strwidthpart_reverse('あいうえお', 20)
	" 'あいうえお'
<
wcswidth({str})					*Vital.Data.String.wcswidth()*
	This function returns the displayed width of the string {str}.
>
	echo s:S.wcswidth('this is a pen')
	" 13
	echo s:S.wcswidth('あいうえお')
	" 10
<
remove_ansi_sequences({text})	*Vital.Data.String.remove_ansi_sequences()*
	Remove ANSI sequences from {text}
>
	echo s:S.remove_ansi_sequences("\033[47m\033[32mGreen\033[0m")
	" 'Green'
<
escape_pattern({str})		*Vital.Data.String.escape_pattern()*
	Escape pattern involved characters ("^$~.*[]\) in {str}.
	Note that it over escape characters when {str} contains escaped
	characters.
>
	echo s:S.escape_pattern('^\a\b.*$')
	" '\^\\a\\b\.\*\$'
	echo s:S.escape_pattern(s:S.escape_pattern('^\a\b.*$'))
        " '\\\^\\\\a\\\\b\\\.\\\*\\\$'
<
unescape_pattern({str})		*Vital.Data.String.unescape_pattern()*
	Unescape pattern involved characters, namely characters escaped by
	|Vital.Data.String.escape_pattern()| function.
>
	echo s:S.unescape_pattern('\\\^\\\\a\\\\b\\\.\\\*\\\$')
	" '\^\\a\\b\.\*\$'
	echo s:S.unescape_pattern('\^\\a\\b\.\*\$')
	" '^\a\b.*$'
	echo s:S.unescape_pattern('^\a\b.*$')
	" '^\a\b.*$'
<
unescape({str}, {chars})	*Vital.Data.String.unescape()*
	Unescape {chars} in {str}.
>
	echo s:S.unescape('\*n\n\\n', '*\')
	" '*n\n\n'
<
				*Vital.Data.String.iconv()*
iconv({expr}, {from}, {to})
	An alternate function of builtin |iconv()| which fail silently.
	It returns {expr} when conversion has failed.

				*Vital.Data.String.repair_posix_text()*
repair_posix_text({text}[, {newline}])
	It returns {text} with a trailing {newline} if no trailing {newline}
	exists. If {newline} is omitted, "\n" will be used.
>
	echo s:S.repair_posix_text("A\nB\nC")
	" => A\nB\nC\n
	echo s:S.repair_posix_text("A\nB\nC\n")
	" => A\nB\nC\n
	echo s:S.repair_posix_text("A\nB\nC\n\n")
	" => A\nB\nC\n\n
<
				*Vital.Data.String.join_posix_lines()*
join_posix_lines({lines}[, {newline}])
	It returns a {newline} joined |String| of {lines} with a trailing
	{newline}. If {newline} is omitted, "\n" will be used.
>
	echo s:S.join_posix_lines(['A', 'B', 'C'])
	" => A\nB\nC\n
	echo s:S.join_posix_lines(['A', 'B', 'C', ''])
	" => A\nB\nC\n\n
<
				*Vital.Data.String.split_posix_text()*
split_posix_text({text}[, {newline}])
	It returns a {newline} separated |List| of {text} without an item for
	trailing {newline} in {text}.
	While POSIX text has a trailing {newline}, splitting text directly
	with |split()| function returns a |List| with an additional empty
	line. This function automatically remove a trailing {newline} when
	exists, indicating that if {text} does not have a trailing {newline},
	it is equal to 'split({text}, {newline}, 1)'.
	If {newline} is omitted, "\r\?\n" will be used.
>
	echo s:S.split_posix_text("A\nB\nC\n")
	" => ['A', 'B', 'C']
	echo s:S.split_posix_text("A\nB\nC")
	" => ['A', 'B', 'C']
	echo s:S.split_posix_text("A\nB\nC\n\n")
	" => ['A', 'B', 'C', '']
<
==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl