This module provides support to handle the Unicode UTF-8 encoding.
There are no specialized insert, delete, add and contains procedures for seq[Rune] in this module because the generic variants of these procedures in the system module already work with it.
The current version is compatible with Unicode v12.0.0.
See also:
Procs
-
Aligns a unicode string s with padding, so that it has a rune-length of count.
padding characters (by default spaces) are added before s resulting in right alignment. If s.runelen >= count, no spaces are added and s is returned unchanged. If you need to left align a string use the alignLeft proc.
Example:
Source Editassert align("abc", 4) == " abc" assert align("a", 0) == "a" assert align("1232", 6) == " 1232" assert align("1232", 6, '#'.Rune) == "##1232" assert align("Åge", 5) == " Åge" assert align("×", 4, '_'.Rune) == "___×"
-
Aligns a unicode string s with padding, so that it has a rune-length of count.
padding characters (by default spaces) are added before s resulting in right alignment. If s.runelen >= count, no spaces are added and s is returned unchanged. If you need to left align a string use the alignLeft proc.
Example:
Source Editassert align("abc", 4) == " abc" assert align("a", 0) == "a" assert align("1232", 6) == " 1232" assert align("1232", 6, '#'.Rune) == "##1232" assert align("Åge", 5) == " Åge" assert align("×", 4, '_'.Rune) == "___×"
-
Left-aligns a unicode string s with padding, so that it has a rune-length of count.
padding characters (by default spaces) are added after s resulting in left alignment. If s.runelen >= count, no spaces are added and s is returned unchanged. If you need to right align a string use the align proc.
Example:
Source Editassert alignLeft("abc", 4) == "abc " assert alignLeft("a", 0) == "a" assert alignLeft("1232", 6) == "1232 " assert alignLeft("1232", 6, '#'.Rune) == "1232##" assert alignLeft("Åge", 5) == "Åge " assert alignLeft("×", 4, '_'.Rune) == "×___"
-
Left-aligns a unicode string s with padding, so that it has a rune-length of count.
padding characters (by default spaces) are added after s resulting in left alignment. If s.runelen >= count, no spaces are added and s is returned unchanged. If you need to right align a string use the align proc.
Example:
Source Editassert alignLeft("abc", 4) == "abc " assert alignLeft("a", 0) == "a" assert alignLeft("1232", 6) == "1232 " assert alignLeft("1232", 6, '#'.Rune) == "1232##" assert alignLeft("Åge", 5) == "Åge " assert alignLeft("×", 4, '_'.Rune) == "×___"
proc capitalize(s: openArray[char]): string {.noSideEffect, ...gcsafe, extern: "nuc$1", raises: [], tags: [], forbids: [].}
-
Converts the first character of s into an upper-case rune.
Example:
Source EditdoAssert capitalize("βeta") == "Βeta"
proc capitalize(s: string): string {.noSideEffect, ...raises: [], tags: [], forbids: [].}
-
Converts the first character of s into an upper-case rune.
Example:
Source EditdoAssert capitalize("βeta") == "Βeta"
proc cmpRunesIgnoreCase(a, b: openArray[char]): int {....gcsafe, extern: "nuc$1", raises: [], tags: [], forbids: [].}
-
Compares two UTF-8 strings and ignores the case. Returns:
0 if a == b
Source Edit
< 0 if a < b
> 0 if a > b proc cmpRunesIgnoreCase(a, b: string): int {.inline, ...raises: [], tags: [], forbids: [].}
-
Compares two UTF-8 strings and ignores the case. Returns:
0 if a == b
Source Edit
< 0 if a < b
> 0 if a > b proc graphemeLen(s: openArray[char]; i: Natural): Natural {....raises: [], tags: [], forbids: [].}
-
The number of bytes belonging to byte index s[i], including following combining code units.
Example:
Source Editlet a = "añyóng" doAssert a.graphemeLen(1) == 2 ## ñ doAssert a.graphemeLen(2) == 1 doAssert a.graphemeLen(4) == 2 ## ó
proc graphemeLen(s: string; i: Natural): Natural {.inline, ...raises: [], tags: [], forbids: [].}
-
The number of bytes belonging to byte index s[i], including following combining code unit.
Example:
Source Editlet a = "añyóng" doAssert a.graphemeLen(1) == 2 ## ñ doAssert a.graphemeLen(2) == 1 doAssert a.graphemeLen(4) == 2 ## ó
proc isCombining(c: Rune): bool {....gcsafe, extern: "nuc$1", raises: [], tags: [], forbids: [].}
-
Returns true if c is a Unicode combining code unit.
See also:
Source Edit proc isWhiteSpace(c: Rune): bool {....gcsafe, extern: "nuc$1", raises: [], tags: [], forbids: [].}
-
Returns true if c is a Unicode whitespace code point.
See also:
Source Edit -
Returns the reverse of s, interpreting it as runes.
Unicode combining characters are correctly interpreted as well.
Example:
Source Editassert reversed("Reverse this!") == "!siht esreveR" assert reversed("先秦兩漢") == "漢兩秦先" assert reversed("as⃝df̅") == "f̅ds⃝a" assert reversed("a⃞b⃞c⃞") == "c⃞b⃞a⃞"
-
Returns the rune in s at byte index i.
See also:
Example:
Source Editlet a = "añyóng" doAssert a.runeAt(1) == "ñ".runeAt(0) doAssert a.runeAt(2) == "ñ".runeAt(1) doAssert a.runeAt(3) == "y".runeAt(0)
-
Returns the rune at position pos.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Source Edit -
Returns the byte position of rune at position pos in s with an optional start byte position. Returns the special value -1 if it runs out of the string.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Example:
Source Editlet a = "añyóng" doAssert a.runeOffset(1) == 1 doAssert a.runeOffset(3) == 4 doAssert a.runeOffset(4) == 6
proc runeOffset(s: string; pos: Natural; start: Natural = 0): int {.inline, ...raises: [], tags: [], forbids: [].}
-
Returns the byte position of rune at position pos in s with an optional start byte position. Returns the special value -1 if it runs out of the string.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Example:
Source Editlet a = "añyóng" doAssert a.runeOffset(1) == 1 doAssert a.runeOffset(3) == 4 doAssert a.runeOffset(4) == 6
-
Returns a tuple with the byte offset of the rune at position rev in s, counting from the end (starting with 1) and the total number of runes in the string.
Returns a negative value for offset if there are too few runes in the string to satisfy the request.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Source Edit proc runeReverseOffset(s: string; rev: Positive): (int, int) {.inline, ...raises: [], tags: [], forbids: [].}
-
Returns a tuple with the byte offset of the rune at position rev in s, counting from the end (starting with 1) and the total number of runes in the string.
Returns a negative value for offset if there are too few runes in the string to satisfy the request.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Source Edit proc runeStrAtPos(s: openArray[char]; pos: Natural): string {....raises: [], tags: [], forbids: [].}
-
Returns the rune at position pos as UTF8 String.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Source Edit proc runeStrAtPos(s: string; pos: Natural): string {.inline, ...raises: [], tags: [], forbids: [].}
-
Returns the rune at position pos as UTF8 String.
Beware: This can lead to unoptimized code and slow execution! Most problems can be solved more efficiently by using an iterator or conversion to a seq of Rune.
See also:
Source Edit -
Returns the UTF-8 substring starting at code point pos with len code points.
If pos or len is negative they count from the end of the string. If len is not given it means the longest possible string.
Example:
Source Editlet s = "Hänsel ««: 10,00€" doAssert(runeSubStr(s, 0, 2) == "Hä") doAssert(runeSubStr(s, 10, 1) == ":") doAssert(runeSubStr(s, -6) == "10,00€") doAssert(runeSubStr(s, 10) == ": 10,00€") doAssert(runeSubStr(s, 12, 5) == "10,00") doAssert(runeSubStr(s, -6, 3) == "10,")
-
Returns the UTF-8 substring starting at code point pos with len code points.
If pos or len is negative they count from the end of the string. If len is not given it means the longest possible string.
Example:
Source Editlet s = "Hänsel ««: 10,00€" doAssert(runeSubStr(s, 0, 2) == "Hä") doAssert(runeSubStr(s, 10, 1) == ":") doAssert(runeSubStr(s, -6) == "10,00€") doAssert(runeSubStr(s, 10) == ": 10,00€") doAssert(runeSubStr(s, 12, 5) == "10,00") doAssert(runeSubStr(s, -6, 3) == "10,")
- The same as the split iterator, but is a proc that returns a sequence of substrings. Source Edit
- The same as the split iterator, but is a proc that returns a sequence of substrings. Source Edit
- The same as the split iterator, but is a proc that returns a sequence of substrings. Source Edit
proc splitWhitespace(s: openArray[char]): seq[string] {.noSideEffect, ...gcsafe, extern: "ncuSplitWhitespace", raises: [], tags: [], forbids: [].}
- The same as the splitWhitespace iterator, but is a proc that returns a sequence of substrings. Source Edit
proc splitWhitespace(s: string): seq[string] {.noSideEffect, inline, ...raises: [], tags: [], forbids: [].}
- The same as the splitWhitespace iterator, but is a proc that returns a sequence of substrings. Source Edit
-
Strips leading or trailing runes from s and returns the resulting string.
If leading is true (default), leading runes are stripped. If trailing is true (default), trailing runes are stripped. If both are false, the string is returned unchanged.
Example:
Source Editlet a = "\táñyóng " doAssert a.strip == "áñyóng" doAssert a.strip(leading = false) == "\táñyóng" doAssert a.strip(trailing = false) == "áñyóng "
-
Strips leading or trailing runes from s and returns the resulting string.
If leading is true (default), leading runes are stripped. If trailing is true (default), trailing runes are stripped. If both are false, the string is returned unchanged.
Example:
Source Editlet a = "\táñyóng " doAssert a.strip == "áñyóng" doAssert a.strip(leading = false) == "\táñyóng" doAssert a.strip(trailing = false) == "áñyóng "
-
Converts c into lower case. This works for any rune.
If possible, prefer toLower over toUpper.
See also:
Source Edit -
Converts c into upper case. This works for any rune.
If possible, prefer toLower over toUpper.
See also:
Source Edit -
Converts a rune into its UTF-8 representation.
See also:
- validateUtf8 proc
- $ proc alias for toUTF8
- utf8 iterator
- fastToUTF8Copy template
Example:
Source Editlet a = "añyóng" doAssert a.runeAt(1).toUTF8 == "ñ"
-
Translates words in a string using the replacements proc to substitute words inside s with their replacements.
replacements is any proc that takes a word and returns a new word to fill it's place.
Example:
Source Editproc wordToNumber(s: string): string = case s of "one": "1" of "two": "2" else: s let a = "one two three four" doAssert a.translate(wordToNumber) == "1 2 three four"
-
Translates words in a string using the replacements proc to substitute words inside s with their replacements.
replacements is any proc that takes a word and returns a new word to fill it's place.
Example:
Source Editproc wordToNumber(s: string): string = case s of "one": "1" of "two": "2" else: s let a = "one two three four" doAssert a.translate(wordToNumber) == "1 2 three four"
proc validateUtf8(s: openArray[char]): int {....raises: [], tags: [], forbids: [].}
-
Returns the position of the invalid byte in s if the string s does not hold valid UTF-8 data. Otherwise -1 is returned.
See also:
- toUTF8 proc
- $ proc alias for toUTF8
- fastToUTF8Copy template
proc validateUtf8(s: string): int {.inline, ...raises: [], tags: [], forbids: [].}
-
Returns the position of the invalid byte in s if the string s does not hold valid UTF-8 data. Otherwise -1 is returned.
See also:
- toUTF8 proc
- $ proc alias for toUTF8
- fastToUTF8Copy template
Iterators
-
Splits the unicode string s into substrings using a single separator. Substrings are separated by the rune sep.
Example:
Source Editimport std/sequtils assert toSeq(split(";;hÃllo;this;is;an;;example;;;是", ";".runeAt(0))) == @["", "", "hÃllo", "this", "is", "an", "", "example", "", "", "是"]
-
Splits the unicode string s into substrings using a group of separators.
Substrings are separated by a substring containing only seps.
Example:
Source Editimport std/sequtils assert toSeq("hÃllo\lthis\lis an\texample\l是".split) == @["hÃllo", "this", "is", "an", "example", "是"] # And the following code splits the same string using a sequence of Runes. assert toSeq(split("añyóng:hÃllo;是$example", ";:$".toRunes)) == @["añyóng", "hÃllo", "是", "example"] # example with a `Rune` separator and unused one `;`: assert toSeq(split("ab是de:f:", ";:是".toRunes)) == @["ab", "de", "f", ""] # Another example that splits a string containing a date. let date = "2012-11-20T22:08:08.398990" assert toSeq(split(date, " -:T".toRunes)) == @["2012", "11", "20", "22", "08", "08.398990"]
-
Splits the unicode string s into substrings using a single separator. Substrings are separated by the rune sep.
Example:
Source Editimport std/sequtils assert toSeq(split(";;hÃllo;this;is;an;;example;;;是", ";".runeAt(0))) == @["", "", "hÃllo", "this", "is", "an", "", "example", "", "", "是"]
-
Splits the unicode string s into substrings using a group of separators.
Substrings are separated by a substring containing only seps.
Example:
Source Editimport std/sequtils assert toSeq("hÃllo\lthis\lis an\texample\l是".split) == @["hÃllo", "this", "is", "an", "example", "是"] # And the following code splits the same string using a sequence of Runes. assert toSeq(split("añyóng:hÃllo;是$example", ";:$".toRunes)) == @["añyóng", "hÃllo", "是", "example"] # example with a `Rune` separator and unused one `;`: assert toSeq(split("ab是de:f:", ";:是".toRunes)) == @["ab", "de", "f", ""] # Another example that splits a string containing a date. let date = "2012-11-20T22:08:08.398990" assert toSeq(split(date, " -:T".toRunes)) == @["2012", "11", "20", "22", "08", "08.398990"]
iterator splitWhitespace(s: openArray[char]): string {....raises: [], tags: [], forbids: [].}
- Splits a unicode string at whitespace runes. Source Edit
iterator splitWhitespace(s: string): string {....raises: [], tags: [], forbids: [].}
- Splits a unicode string at whitespace runes. Source Edit
-
Iterates over any rune of the string s returning utf8 values.
See also:
- validateUtf8 proc
- toUTF8 proc
- $ proc alias for toUTF8
- fastToUTF8Copy template
-
Iterates over any rune of the string s returning utf8 values.
See also:
- validateUtf8 proc
- toUTF8 proc
- $ proc alias for toUTF8
- fastToUTF8Copy template
Templates
template fastToUTF8Copy(c: Rune; s: var string; pos: int; doInc = true)
-
Copies UTF-8 representation of c into the preallocated string s starting at position pos.
If doInc == true (default), pos is incremented by the number of bytes that have been processed.
To be the most efficient, make sure s is preallocated with an additional amount equal to the byte length of c.
See also:
- validateUtf8 proc
- toUTF8 proc
- $ proc alias for toUTF8