Interpolates a format string with the values from a.

The substitution operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation.

This is best explained by an example:

"$1 eats $2." % ["The cat", "fish"]

Results in:

"The cat eats fish."

The substitution variables (the thing after the $) are enumerated from 1 to a.len. To produce a verbatim $, use $$. The notation $# can be used to refer to the next substitution variable:

"$# eats $#." % ["The cat", "fish"]

Substitution variables can also be words (that is [A-Za-z_]+[A-Za-z0-9_]*) in which case the arguments in a with even indices are keys and with odd indices are the corresponding values. An example:

"$animal eats $food." % ["animal", "The cat", "food", "fish"]

Results in:

"The cat eats fish."

The variables are compared with cmpIgnoreStyle. ValueError is raised if an ill-formed format string has been passed to the % operator.

See also:

• strformat module for string interpolation and formatting

Returns the index of the first item in possibilities which starts with s, if not ambiguous.

Returns -1 if no item has been found and -2 if multiple items match.

Example:

doAssert abbrev("fac", ["college", "faculty", "industry"]) == 1
doAssert abbrev("foo", ["college", "faculty", "industry"]) == -1 # Not found
doAssert abbrev("fac", ["college", "faculty", "faculties"]) == -2 # Ambiguous
doAssert abbrev("college", ["college", "colleges", "industry"]) == 0

Adds a separator to dest only if its length is bigger than startLen.

A shorthand for:

if dest.len > startLen: add(dest, sep)

This is often useful for generating some code where the items need to be separated by sep. sep is only added if dest is longer than startLen. The following example creates a string describing an array of integers.

Example:

var arr = "["
for x in items([2, 3, 5, 7, 11]):
  addSep(arr, startLen = len("["))
  add(arr, $x)
add(arr, "]")
doAssert arr == "[2, 3, 5, 7, 11]"

Aligns a string s with padding, so that it is of length count.

padding characters (by default spaces) are added before s resulting in right alignment. If s.len >= count, no spaces are added and s is returned unchanged. If you need to left align a string use the alignLeft func.

See also:

• alignLeft func
• spaces func
• indent func
• center func

Example:

assert align("abc", 4) == " abc"
assert align("a", 0) == "a"
assert align("1232", 6) == "  1232"
assert align("1232", 6, '#') == "##1232"

Left-Aligns a string s with padding, so that it is of length count.

padding characters (by default spaces) are added after s resulting in left alignment. If s.len >= count, no spaces are added and s is returned unchanged. If you need to right align a string use the align func.

See also:

• align func
• spaces func
• indent func
• center func

Example:

assert alignLeft("abc", 4) == "abc "
assert alignLeft("a", 0) == "a"
assert alignLeft("1232", 6) == "1232  "
assert alignLeft("1232", 6, '#') == "1232##"

Example:

doAssert allCharsInSet("aeea", {'a', 'e'}) == true
doAssert allCharsInSet("", {'a', 'e'}) == true

Converts the first character of string s into upper case.

This works only for the letters A-Z. Use Unicode module for UTF-8 support.

See also:

• toUpperAscii func

Example:

doAssert capitalizeAscii("foo") == "Foo"
doAssert capitalizeAscii("-bar") == "-bar"

Return the contents of s centered in a string width long using fillChar (default: space) as padding.

The original string is returned if width is less than or equal to s.len.

See also:

• align func
• alignLeft func
• spaces func
• indent func

Example:

let a = "foo"
doAssert a.center(2) == "foo"
doAssert a.center(5) == " foo "
doAssert a.center(6) == " foo  "

0 if a == b
< 0 if a < b
> 0 if a > b

Example:

doAssert cmpIgnoreCase("FooBar", "foobar") == 0
doAssert cmpIgnoreCase("bar", "Foo") < 0
doAssert cmpIgnoreCase("Foo5", "foo4") > 0

Semantically the same as cmp(normalize(a), normalize(b)). It is just optimized to not allocate temporary strings. This should NOT be used to compare Nim identifier names. Use macros.eqIdent for that.

Returns:

0 if a == b
< 0 if a < b
> 0 if a > b

Example:

doAssert cmpIgnoreStyle("foo_bar", "FooBar") == 0
doAssert cmpIgnoreStyle("foo_bar_5", "FooBar4") > 0

Same as find(s, sub) >= 0.

See also:

• find func

Same as find(s, chars) >= 0.

See also:

• find func

Returns true if s continues with substr at position start.

If substr == "" true is returned.

See also:

• startsWith func
• endsWith func

Example:

let a = "abracadabra"
doAssert a.continuesWith("ca", 4) == true
doAssert a.continuesWith("ca", 5) == false
doAssert a.continuesWith("dab", 6) == true

Counts the occurrences of the character sub in the string s.

See also:

• countLines func

Counts the occurrences of a substring sub in the string s. Overlapping occurrences of sub only count when overlapping is set to true (default: false).

See also:

• countLines func

Counts the occurrences of the group of character subs in the string s.

See also:

• countLines func

Returns the number of lines in the string s.

This is the same as len(splitLines(s)), but much more efficient because it doesn't modify the string creating temporary objects. Every character literal newline combination (CR, LF, CR-LF) is supported.

In this context, a line is any string separated by a newline combination. A line can be an empty string.

See also:

• splitLines func

Example:

doAssert countLines("First line\l and second line.") == 2

Unindents each line in s by count amount of padding. The only difference between this and the unindent func is that this by default only cuts off the amount of indentation that all lines of s share as opposed to all indentation. It only supports spaces as padding.

Note: This does not preserve the new line characters used in s.

See also:

• unindent func
• align func
• alignLeft func
• spaces func
• indent func

Example:

let x = """
      Hello
        There
    """.dedent()

doAssert x == "Hello\n  There\n"

Example: cmd: --warning:deprecated:off

var a = "abracadabra"

a.delete(4, 5)
doAssert a == "abradabra"

a.delete(1, 6)
doAssert a == "ara"

a.delete(2, 999)
doAssert a == "ar"

Deletes the items s[slice], raising IndexDefect if the slice contains elements out of range.

This operation moves all elements after s[slice] in linear time, and is the string analog to sequtils.delete.

Example:

var a = "abcde"
doAssertRaises(IndexDefect): a.delete(4..5)
assert a == "abcde"
a.delete(4..4)
assert a == "abcd"
a.delete(1..2)
assert a == "ad"
a.delete(1..<1) # empty slice
assert a == "ad"

Returns true if s ends with suffix.

If suffix == "" true is returned.

See also:

• startsWith func
• continuesWith func
• removeSuffix func

Example:

let a = "abracadabra"
doAssert a.endsWith("abra") == true
doAssert a.endsWith("dab") == false

Returns true if s ends with suffix.

See also:

• startsWith func
• continuesWith func
• removeSuffix func

Example:

let a = "abracadabra"
doAssert a.endsWith('a') == true
doAssert a.endsWith('b') == false

• replaces '\0'..'\31' and '\127'..'\255' by \xHH where HH is its hexadecimal value
• replaces \ by \\
• replaces ' by \'
• replaces " by \"

The resulting string is prefixed with prefix and suffixed with suffix. Both may be empty strings.

See also:

• addEscapedChar proc
• unescape func for the opposite operation

Searches for sub in s inside range start..last using preprocessed table a. If last is unspecified, it defaults to s.high (the last element).

Searching is case-sensitive. If sub is not in s, -1 is returned.

See also:

• initSkipTable func
• initSkipTable func

Searches for sub in s inside range start..last (both ends included). If last is unspecified or negative, it defaults to s.high (the last element).

Searching is case-sensitive. If sub is not in s, -1 is returned. Otherwise the index returned is relative to s[0], not start. Subtract start from the result for a start-origin index.

See also:

• rfind func
• replace func

Searches for chars in s inside range start..last (both ends included). If last is unspecified or negative, it defaults to s.high (the last element).

If s contains none of the characters in chars, -1 is returned. Otherwise the index returned is relative to s[0], not start. Subtract start from the result for a start-origin index.

See also:

• rfind func
• multiReplace func

Searches for sub in s inside range start..last (both ends included). If last is unspecified or negative, it defaults to s.high (the last element).

Searching is case-sensitive. If sub is not in s, -1 is returned. Otherwise the index returned is relative to s[0], not start. Subtract start from the result for a start-origin index.

See also:

• rfind func
• replace func

This is the same as formatstr % a (see % func) except that it supports auto stringification.

See also:

• strformat module for string interpolation and formatting

Converts a floating point value f to a string.

If format == ffDecimal then precision is the number of digits to be printed after the decimal point. If format == ffScientific then precision is the maximum number of significant digits to be printed. precision's default value is the maximum number of meaningful digits after the decimal point for Nim's biggestFloat type.

If precision == -1, it tries to format it nicely.

Example:

let x = 123.456
doAssert x.formatBiggestFloat() == "123.4560000000000"
doAssert x.formatBiggestFloat(ffDecimal, 4) == "123.4560"
doAssert x.formatBiggestFloat(ffScientific, 2) == "1.23e+02"

Converts a floating point value f to a string using engineering notation.

Numbers in of the range -1000.0<f<1000.0 will be formatted without an exponent. Numbers outside of this range will be formatted as a significand in the range -1000.0<f<1000.0 and an exponent that will always be an integer multiple of 3, corresponding with the SI prefix scale k, M, G, T etc for numbers with an absolute value greater than 1 and m, μ, n, p etc for numbers with an absolute value less than 1.

The default configuration (trim=true and precision=10) shows the shortest form that precisely (up to a maximum of 10 decimal places) displays the value. For example, 4.100000 will be displayed as 4.1 (which is mathematically identical) whereas 4.1000003 will be displayed as 4.1000003.

If trim is set to true, trailing zeros will be removed; if false, the number of digits specified by precision will always be shown.

precision can be used to set the number of digits to be shown after the decimal point or (if trim is true) the maximum number of digits to be shown.

 formatEng(0, 2, trim=false) == "0.00"
 formatEng(0, 2) == "0"
 formatEng(0.053, 0) == "53e-3"
 formatEng(52731234, 2) == "52.73e6"
 formatEng(-52731234, 2) == "-52.73e6"

If siPrefix is set to true, the number will be displayed with the SI prefix corresponding to the exponent. For example 4100 will be displayed as "4.1 k" instead of "4.1e3". Note that u is used for micro- in place of the greek letter mu (μ) as per ISO 2955. Numbers with an absolute value outside of the range 1e-18<f<1000e18 (1a<f<1000E) will be displayed with an exponent rather than an SI prefix, regardless of whether siPrefix is true.

If useUnitSpace is true, the provided unit will be appended to the string (with a space as required by the SI standard). This behaviour is slightly different to appending the unit to the result as the location of the space is altered depending on whether there is an exponent.

 formatEng(4100, siPrefix=true, unit="V") == "4.1 kV"
 formatEng(4.1, siPrefix=true, unit="V") == "4.1 V"
 formatEng(4.1, siPrefix=true) == "4.1" # Note lack of space
 formatEng(4100, siPrefix=true) == "4.1 k"
 formatEng(4.1, siPrefix=true, unit="") == "4.1 " # Space with unit=""
 formatEng(4100, siPrefix=true, unit="") == "4.1 k"
 formatEng(4100) == "4.1e3"
 formatEng(4100, unit="V") == "4.1e3 V"
 formatEng(4100, unit="", useUnitSpace=true) == "4.1e3 " # Space with useUnitSpace=true

decimalSep is used as the decimal separator.

See also:

• strformat module for string interpolation and formatting

Converts a floating point value f to a string.

If format == ffDecimal then precision is the number of digits to be printed after the decimal point. If format == ffScientific then precision is the maximum number of significant digits to be printed. precision's default value is the maximum number of meaningful digits after the decimal point for Nim's float type.

If precision == -1, it tries to format it nicely.

Example:

let x = 123.456
doAssert x.formatFloat() == "123.4560000000000"
doAssert x.formatFloat(ffDecimal, 4) == "123.4560"
doAssert x.formatFloat(ffScientific, 2) == "1.23e+02"

Rounds and formats bytes.

By default, uses the IEC/ISO standard binary prefixes, so 1024 will be formatted as 1KiB. Set prefix to bpColloquial to use the colloquial names from the SI standard (e.g. k for 1000 being reused as 1024).

includeSpace can be set to true to include the (SI preferred) space between the number and the unit (e.g. 1 KiB).

See also:

• strformat module for string interpolation and formatting

Example:

doAssert formatSize((1'i64 shl 31) + (300'i64 shl 20)) == "2.293GiB"
doAssert formatSize((2.234*1024*1024).int) == "2.234MiB"
doAssert formatSize(4096, includeSpace = true) == "4 KiB"
doAssert formatSize(4096, prefix = bpColloquial, includeSpace = true) == "4 kB"
doAssert formatSize(4096) == "4KiB"
doAssert formatSize(5_378_934, prefix = bpColloquial, decimalSep = ',') == "5,13MB"

Parses a binary integer value from a string s.

If s is not a valid binary integer, ValueError is raised. s can have one of the following optional prefixes: 0b, 0B. Underscores within s are ignored.

Does not check for overflow. If the value represented by s is too big to fit into a return type, only the value of the rightmost binary digits of s is returned without producing an error.

Example:

let s = "0b_0100_1000_1000_1000_1110_1110_1001_1001"
doAssert fromBin[int](s) == 1216933529
doAssert fromBin[int8](s) == 0b1001_1001'i8
doAssert fromBin[int8](s) == -103'i8
doAssert fromBin[uint8](s) == 153
doAssert s.fromBin[:int16] == 0b1110_1110_1001_1001'i16
doAssert s.fromBin[:uint64] == 1216933529'u64

Parses a hex integer value from a string s.

If s is not a valid hex integer, ValueError is raised. s can have one of the following optional prefixes: 0x, 0X, #. Underscores within s are ignored.

Does not check for overflow. If the value represented by s is too big to fit into a return type, only the value of the rightmost hex digits of s is returned without producing an error.

Example:

let s = "0x_1235_8df6"
doAssert fromHex[int](s) == 305499638
doAssert fromHex[int8](s) == 0xf6'i8
doAssert fromHex[int8](s) == -10'i8
doAssert fromHex[uint8](s) == 246'u8
doAssert s.fromHex[:int16] == -29194'i16
doAssert s.fromHex[:uint64] == 305499638'u64

Parses an octal integer value from a string s.

If s is not a valid octal integer, ValueError is raised. s can have one of the following optional prefixes: 0o, 0O. Underscores within s are ignored.

Does not check for overflow. If the value represented by s is too big to fit into a return type, only the value of the rightmost octal digits of s is returned without producing an error.

Example:

let s = "0o_123_456_777"
doAssert fromOct[int](s) == 21913087
doAssert fromOct[int8](s) == 0o377'i8
doAssert fromOct[int8](s) == -1'i8
doAssert fromOct[uint8](s) == 255'u8
doAssert s.fromOct[:int16] == 24063'i16
doAssert s.fromOct[:uint64] == 21913087'u64

Indents each line in s by count amount of padding.

Note: This does not preserve the new line characters used in s.

See also:

• align func
• alignLeft func
• spaces func
• unindent func
• dedent func

Example:

doAssert indent("First line\c\l and second line.", 2) ==
         "  First line\l   and second line."

Initializes table a for efficient search of substring sub.

See also:

• initSkipTable func
• find func

Returns a new table initialized for sub.

See also:

• initSkipTable func
• find func

Inserts the separator sep after digits characters (default: 3) from right to left.

Even though the algorithm works with any string s, it is only useful if s contains a number.

Example:

doAssert insertSep("1000000") == "1_000_000"

Converts x to its decimal representation.

The resulting string will be minimally minchars characters long. This is achieved by adding leading zeros.

Example:

doAssert intToStr(1984) == "1984"
doAssert intToStr(1984, 6) == "001984"

Checks whether or not character c is alphabetical.

This checks a-z, A-Z ASCII characters only. Use Unicode module for UTF-8 support.

Example:

doAssert isAlphaAscii('e') == true
doAssert isAlphaAscii('E') == true
doAssert isAlphaAscii('8') == false

Checks whether or not c is alphanumeric.

This checks a-z, A-Z, 0-9 ASCII characters only.

Example:

doAssert isAlphaNumeric('n') == true
doAssert isAlphaNumeric('8') == true
doAssert isAlphaNumeric(' ') == false

Checks whether or not c is a number.

This checks 0-9 ASCII characters only.

Example:

doAssert isDigit('n') == false
doAssert isDigit('8') == true

Checks whether or not c is a lower case character.

This checks ASCII characters only. Use Unicode module for UTF-8 support.

See also:

• toLowerAscii func

Example:

doAssert isLowerAscii('e') == true
doAssert isLowerAscii('E') == false
doAssert isLowerAscii('7') == false

Example:

doAssert isSpaceAscii('n') == false
doAssert isSpaceAscii(' ') == true
doAssert isSpaceAscii('\t') == true

Checks whether or not c is an upper case character.

This checks ASCII characters only. Use Unicode module for UTF-8 support.

See also:

• toUpperAscii func

Example:

doAssert isUpperAscii('e') == false
doAssert isUpperAscii('E') == true
doAssert isUpperAscii('7') == false

Example:

doAssert join(["A", "B", "Conclusion"], " -> ") == "A -> B -> Conclusion"

Example:

doAssert join([1, 2, 3], " -> ") == "1 -> 2 -> 3"

Same as replace, but specialized for doing multiple replacements in a single pass through the input string.

multiReplace scans the input string from left to right and replaces the matching substrings in the same order as passed in the argument list.

The implications of the order of scanning the string and matching the replacements:

• In case of multiple matches at a given position, the earliest replacement is applied.
• Overlaps are not handled. After performing a replacement, the scan continues from the character after the matched substring. If the resulting string then contains a possible match starting in a newly placed substring, the additional replacement is not performed.

If the resulting string is not longer than the original input string, only a single memory allocation is required.

Example:

# Swapping occurrences of 'a' and 'b':
doAssert multireplace("abba", [("a", "b"), ("b", "a")]) == "baab"

# The second replacement ("ab") is matched and performed first, the scan then
# continues from 'c', so the "bc" replacement is never matched and thus skipped.
doAssert multireplace("abc", [("bc", "x"), ("ab", "_b")]) == "_bc"

Normalizes the string s as a Nim identifier.

That means to convert to lower case and remove any '_' on all characters except first one.

Example:

doAssert nimIdentNormalize("Foo_bar") == "Foobar"

Normalizes the string s.

That means to convert it to lower case and remove any '_'. This should NOT be used to normalize Nim identifier names.

See also:

• toLowerAscii func

Example:

doAssert normalize("Foo_bar") == "foobar"
doAssert normalize("Foo Bar") == "foo bar"

Parses a decimal integer value contained in s.

If s is not a valid integer, ValueError is raised.

Parses a decimal unsigned integer value contained in s.

If s is not a valid integer, ValueError is raised.

Parses a binary integer value contained in s.

If s is not a valid binary integer, ValueError is raised. s can have one of the following optional prefixes: 0b, 0B. Underscores within s are ignored.

Example:

let
  a = "0b11_0101"
  b = "111"
doAssert a.parseBinInt() == 53
doAssert b.parseBinInt() == 7

Parses a value into a bool.

If s is one of the following values: y, yes, true, 1, on, then returns true. If s is one of the following values: n, no, false, 0, off, then returns false. If s is something else a ValueError exception is raised.

Example:

let a = "n"
doAssert parseBool(a) == false

Parses an enum T. This errors at compile time, if the given enum type contains multiple fields with the same string value.

Raises ValueError for an invalid value in s. The comparison is done in a style insensitive way (first letter is still case-sensitive).

Example:

type
  MyEnum = enum
    first = "1st",
    second,
    third = "3rd"

doAssert parseEnum[MyEnum]("1_st") == first
doAssert parseEnum[MyEnum]("second") == second
doAssertRaises(ValueError):
  echo parseEnum[MyEnum]("third")

Parses an enum T. This errors at compile time, if the given enum type contains multiple fields with the same string value.

Uses default for an invalid value in s. The comparison is done in a style insensitive way (first letter is still case-sensitive).

Example:

type
  MyEnum = enum
    first = "1st",
    second,
    third = "3rd"

doAssert parseEnum[MyEnum]("1_st") == first
doAssert parseEnum[MyEnum]("second") == second
doAssert parseEnum[MyEnum]("last", third) == third

Parses a decimal floating point value contained in s.

If s is not a valid floating point number, ValueError is raised. NAN, INF, -INF are also supported (case insensitive comparison).

Example:

doAssert parseFloat("3.14") == 3.14
doAssert parseFloat("inf") == 1.0/0

Parses a hexadecimal integer value contained in s.

If s is not a valid hex integer, ValueError is raised. s can have one of the following optional prefixes: 0x, 0X, #. Underscores within s are ignored.

Converts hex-encoded string to byte string, e.g.:

Raises ValueError for an invalid hex values. The comparison is case-insensitive.

See also:

• toHex func for the reverse operation

Example:

let
  a = "41"
  b = "3161"
  c = "00ff"
doAssert parseHexStr(a) == "A"
doAssert parseHexStr(b) == "1a"
doAssert parseHexStr(c) == "\0\255"

Parses a decimal integer value contained in s.

If s is not a valid integer, ValueError is raised.

Example:

doAssert parseInt("-0042") == -42

Parses an octal integer value contained in s.

If s is not a valid oct integer, ValueError is raised. s can have one of the following optional prefixes: 0o, 0O. Underscores within s are ignored.

Parses a decimal unsigned integer value contained in s.

If s is not a valid integer, ValueError is raised.

Removes all occurrences of a single character (in-place) from the start of a string.

See also:

• removeSuffix func
• startsWith func

Example:

var ident = "pControl"
ident.removePrefix('p')
doAssert ident == "Control"

Removes all characters from chars from the start of the string s (in-place).

See also:

• removeSuffix func

Example:

var userInput = "\r\n*~Hello World!"
userInput.removePrefix
doAssert userInput == "*~Hello World!"
userInput.removePrefix({'~', '*'})
doAssert userInput == "Hello World!"

var otherInput = "?!?Hello!?!"
otherInput.removePrefix({'!', '?'})
doAssert otherInput == "Hello!?!"

Remove the first matching prefix (in-place) from a string.

See also:

• removeSuffix func
• startsWith func

Example:

var answers = "yesyes"
answers.removePrefix("yes")
doAssert answers == "yes"

Removes all occurrences of a single character (in-place) from the end of a string.

See also:

• removePrefix func
• endsWith func

Example:

var table = "users"
table.removeSuffix('s')
doAssert table == "user"

var dots = "Trailing dots......."
dots.removeSuffix('.')
doAssert dots == "Trailing dots"

Removes all characters from chars from the end of the string s (in-place).

See also:

• removePrefix func

Example:

var userInput = "Hello World!*~\r\n"
userInput.removeSuffix
doAssert userInput == "Hello World!*~"
userInput.removeSuffix({'~', '*'})
doAssert userInput == "Hello World!"

var otherInput = "Hello!?!"
otherInput.removeSuffix({'!', '?'})
doAssert otherInput == "Hello"

Remove the first matching suffix (in-place) from a string.

See also:

• removePrefix func
• endsWith func

Example:

var answers = "yeses"
answers.removeSuffix("es")
doAssert answers == "yes"

Example:

let a = 'z'
doAssert a.repeat(5) == "zzzzz"

Example:

doAssert "+ foo +".repeat(3) == "+ foo ++ foo ++ foo +"

Replaces every occurrence of the string sub in s with the string by.

See also:

• find func
• replace func for replacing single characters
• replaceWord func
• multiReplace func

Replaces every occurrence of the character sub in s with the character by.

Optimized version of replace for characters.

See also:

• find func
• replaceWord func
• multiReplace func

Replaces every occurrence of the string sub in s with the string by.

Each occurrence of sub has to be surrounded by word boundaries (comparable to \b in regular expressions), otherwise it is not replaced.

Searches for sub in s inside range start..last (both ends included) included) in reverse -- starting at high indexes and moving lower to the first character or start. If last is unspecified, it defaults to s.high (the last element).

Searching is case-sensitive. If sub is not in s, -1 is returned. Otherwise the index returned is relative to s[0], not start. Subtract start from the result for a start-origin index.

See also:

• find func

Searches for chars in s inside range start..last (both ends included) in reverse -- starting at high indexes and moving lower to the first character or start. If last is unspecified, it defaults to s.high (the last element).

If s contains none of the characters in chars, -1 is returned. Otherwise the index returned is relative to s[0], not start. Subtract start from the result for a start-origin index.