W3cubDocs

Module strutils

This module contains various string utility routines. See the module re for regular expression support. See the module pegs for PEG support. This module is available for the JavaScript target.

Exports

toLower, toLower, toUpper, toUpper

Imports

parseutils, math, algorithm, unicode

Types

SkipTable = array[char, int]
FloatFormatMode = enum ffDefault, ## use the shorter floating point notation ffDecimal, ## use decimal floating point notation ffScientific ## use scientific notation (using ``e`` character): the different modes of floating point formating
BinaryPrefixMode = enum bpIEC, bpColloquial: the different names for binary prefixes

Consts

Whitespace = {' ', '\t', '\v', '\c', '\n', '\f'}

All the characters that count as whitespace.

Letters = {'A'..'Z', 'a'..'z'}

the set of letters

Digits = {'0'..'9'}

the set of digits

HexDigits = {'0'..'9', 'A'..'F', 'a'..'f'}

the set of hexadecimal digits

IdentChars = {'a'..'z', 'A'..'Z', '0'..'9', '_'}

the set of characters an identifier can consist of

IdentStartChars = {'a'..'z', 'A'..'Z', '_'}

the set of characters an identifier can start with

NewLines = {'\c', '\n'}

the set of characters a newline terminator can start with

AllChars = {'\x00'..'\xFF'}

A set with all the possible characters.

Not very useful by its own, you can use it to create inverted sets to make the find() proc find invalid characters in strings. Example:

let invalid = AllChars - Digits
doAssert "01234".find(invalid) == -1
doAssert "01A34".find(invalid) == 2

Procs

proc isAlphaAscii(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsAlphaAsciiChar", raises: [], tags: [].}

Checks whether or not c is alphabetical.

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

proc isAlphaNumeric(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsAlphaNumericChar", raises: [], tags: [].}

Checks whether or not c is alphanumeric.

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

proc isDigit(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsDigitChar", raises: [], tags: [].}

Checks whether or not c is a number.

This checks 0-9 ASCII characters only.

proc isSpaceAscii(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsSpaceAsciiChar", raises: [], tags: [].}

Checks whether or not c is a whitespace character.

proc isLowerAscii(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsLowerAsciiChar", raises: [], tags: [].}

Checks whether or not c is a lower case character.

This checks ASCII characters only.

proc isUpperAscii(c: char): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsUpperAsciiChar", raises: [], tags: [].}

Checks whether or not c is an upper case character.

This checks ASCII characters only.

proc isAlphaAscii(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsAlphaAsciiStr", raises: [], tags: [].}

Checks whether or not s is alphabetical.

This checks a-z, A-Z ASCII characters only. Returns true if all characters in s are alphabetic and there is at least one character in s.

proc isAlphaNumeric(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsAlphaNumericStr", raises: [], tags: [].}

Checks whether or not s is alphanumeric.

This checks a-z, A-Z, 0-9 ASCII characters only. Returns true if all characters in s are alpanumeric and there is at least one character in s.

proc isDigit(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsDigitStr", raises: [], tags: [].}

Checks whether or not s is a numeric value.

This checks 0-9 ASCII characters only. Returns true if all characters in s are numeric and there is at least one character in s.

proc isSpaceAscii(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsSpaceAsciiStr", raises: [], tags: [].}

Checks whether or not s is completely whitespace.

Returns true if all characters in s are whitespace characters and there is at least one character in s.

proc isLowerAscii(s: string; skipNonAlpha: bool): bool {...}{.raises: [], tags: [].}

Checks whether s is lower case.

This checks ASCII characters only.

If skipNonAlpha is true, returns true if all alphabetical characters in s are lower case. Returns false if none of the characters in s are alphabetical.

If skipNonAlpha is false, returns true only if all characters in s are alphabetical and lower case.

For either value of skipNonAlpha, returns false if s is an empty string.

proc isUpperAscii(s: string; skipNonAlpha: bool): bool {...}{.raises: [], tags: [].}

Checks whether s is upper case.

This checks ASCII characters only.

If skipNonAlpha is true, returns true if all alphabetical characters in s are upper case. Returns false if none of the characters in s are alphabetical.

If skipNonAlpha is false, returns true only if all characters in s are alphabetical and upper case.

For either value of skipNonAlpha, returns false if s is an empty string.

proc toLowerAscii(c: char): char {...}{.noSideEffect, procvar, gcsafe, extern: "nsuToLowerAsciiChar", raises: [], tags: [].}

Converts c into lower case.

This works only for the letters A-Z. See unicode.toLower for a version that works for any Unicode character.

proc toLowerAscii(s: string): string {...}{.noSideEffect, procvar, gcsafe, extern: "nsuToLowerAsciiStr", raises: [], tags: [].}

Converts s into lower case.

This works only for the letters A-Z. See unicode.toLower for a version that works for any Unicode character.

proc toUpperAscii(c: char): char {...}{.noSideEffect, procvar, gcsafe, extern: "nsuToUpperAsciiChar", raises: [], tags: [].}

Converts c into upper case.

This works only for the letters A-Z. See unicode.toUpper for a version that works for any Unicode character.

proc toUpperAscii(s: string): string {...}{.noSideEffect, procvar, gcsafe, extern: "nsuToUpperAsciiStr", raises: [], tags: [].}

Converts s into upper case.

This works only for the letters A-Z. See unicode.toUpper for a version that works for any Unicode character.

proc capitalizeAscii(s: string): string {...}{.noSideEffect, procvar, gcsafe, extern: "nsuCapitalizeAscii", raises: [], tags: [].}

Converts the first character of s into upper case.

This works only for the letters A-Z.

proc normalize(s: string): string {...}{.noSideEffect, procvar, gcsafe, extern: "nsuNormalize", raises: [], tags: [].}

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.

proc cmpIgnoreCase(a, b: string): int {...}{.noSideEffect, gcsafe, extern: "nsuCmpIgnoreCase", procvar, raises: [], tags: [].}

Compares two strings in a case insensitive manner. Returns:

0 iff a == b
< 0 iff a < b
> 0 iff a > b

proc cmpIgnoreStyle(a, b: string): int {...}{.noSideEffect, gcsafe, extern: "nsuCmpIgnoreStyle", procvar, raises: [], tags: [].}

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 iff a == b
< 0 iff a < b
> 0 iff a > b

proc strip(s: string; leading = true; trailing = true; chars: set[char] = Whitespace): string {...}{. noSideEffect, gcsafe, extern: "nsuStrip", raises: [], tags: [].}

Strips leading or trailing chars from s and returns the resulting string.

If leading is true, leading chars are stripped. If trailing is true, trailing chars are stripped. If both are false, the string is returned unchanged.

proc toOctal(c: char): string {...}{.noSideEffect, gcsafe, extern: "nsuToOctal", raises: [], tags: [].}

Converts a character c to its octal representation.

The resulting string may not have a leading zero. Its length is always exactly 3.

proc isNilOrEmpty(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsNilOrEmpty", deprecated: "use \'x.len == 0\' instead", raises: [], tags: [].}

Checks if s is nil or empty.

proc isNilOrWhitespace(s: string): bool {...}{.noSideEffect, procvar, gcsafe, extern: "nsuIsNilOrWhitespace", raises: [], tags: [].}

Checks if s is nil or consists entirely of whitespace characters.

proc splitWhitespace(s: string; maxsplit: int = -1): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuSplitWhitespace", raises: [], tags: [].}

The same as the splitWhitespace iterator, but is a proc that returns a sequence of substrings.

proc splitLines(s: string; keepEol = false): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuSplitLines", raises: [], tags: [].}

The same as the splitLines iterator, but is a proc that returns a sequence of substrings.

proc countLines(s: string): int {...}{.noSideEffect, gcsafe, extern: "nsuCountLines", raises: [], tags: [].}

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 temporal objects. Every character literal newline combination (CR, LF, CR-LF) is supported.

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

proc split(s: string; seps: set[char] = Whitespace; maxsplit: int = -1): seq[string] {...}{. noSideEffect, gcsafe, extern: "nsuSplitCharSet", raises: [], tags: [].}

The same as the split iterator, but is a proc that returns a sequence of substrings.

Examples:

doAssert "a,b;c".split({',', ';'}) == @["a", "b", "c"]
doAssert "".split({' '}) == @[""]

proc split(s: string; sep: char; maxsplit: int = -1): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuSplitChar", raises: [], tags: [].}

The same as the split iterator, but is a proc that returns a sequence of substrings.

Examples:

doAssert "a,b,c".split(',') == @["a", "b", "c"]
doAssert "".split(' ') == @[""]

proc split(s: string; sep: string; maxsplit: int = -1): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuSplitString", raises: [], tags: [].}

Splits the string s into substrings using a string separator.

Substrings are separated by the string sep. This is a wrapper around the split iterator.

Examples:

doAssert "a,b,c".split(",") == @["a", "b", "c"]
doAssert "a man a plan a canal panama".split("a ") ==
    @["", "man ", "plan ", "canal panama"]
doAssert "".split("Elon Musk") == @[""]
doAssert "a  largely    spaced sentence".split(" ") ==
    @["a", "", "largely", "", "", "", "spaced", "sentence"]
doAssert "a  largely    spaced sentence".split(" ", maxsplit = 1) ==
    @["a", " largely    spaced sentence"]

proc rsplit(s: string; seps: set[char] = Whitespace; maxsplit: int = -1): seq[string] {...}{. noSideEffect, gcsafe, extern: "nsuRSplitCharSet", raises: [], tags: [].}

The same as the rsplit iterator, but is a proc that returns a sequence of substrings.

A possible common use case for rsplit is path manipulation, particularly on systems that don't use a common delimiter.

For example, if a system had # as a delimiter, you could do the following to get the tail of the path:

var tailSplit = rsplit("Root#Object#Method#Index", {'#'}, maxsplit=1)

Results in tailSplit containing:

@["Root#Object#Method", "Index"]

proc rsplit(s: string; sep: char; maxsplit: int = -1): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuRSplitChar", raises: [], tags: [].}

The same as the rsplit iterator, but is a proc that returns a sequence of substrings.

A possible common use case for rsplit is path manipulation, particularly on systems that don't use a common delimiter.

For example, if a system had # as a delimiter, you could do the following to get the tail of the path:

var tailSplit = rsplit("Root#Object#Method#Index", '#', maxsplit=1)

Results in tailSplit containing:

@["Root#Object#Method", "Index"]

proc rsplit(s: string; sep: string; maxsplit: int = -1): seq[string] {...}{.noSideEffect, gcsafe, extern: "nsuRSplitString", raises: [], tags: [].}

The same as the rsplit iterator, but is a proc that returns a sequence of substrings.

A possible common use case for rsplit is path manipulation, particularly on systems that don't use a common delimiter.

For example, if a system had # as a delimiter, you could do the following to get the tail of the path:

var tailSplit = rsplit("Root#Object#Method#Index", "#", maxsplit=1)

Results in tailSplit containing:

@["Root#Object#Method", "Index"]

Examples:

doAssert "a  largely    spaced sentence".rsplit(" ", maxsplit = 1) ==
    @["a  largely    spaced", "sentence"]
doAssert "a,b,c".rsplit(",") == @["a", "b", "c"]
doAssert "a man a plan a canal panama".rsplit("a ") ==
    @["", "man ", "plan ", "canal panama"]
doAssert "".rsplit("Elon Musk") == @[""]
doAssert "a  largely    spaced sentence".rsplit(" ") ==
    @["a", "", "largely", "", "", "", "spaced", "sentence"]

proc toHex(x: BiggestInt; len: Positive): string {...}{.noSideEffect, gcsafe, extern: "nsuToHex", raises: [], tags: [].}

Converts x to its hexadecimal representation.

The resulting string will be exactly len characters long. No prefix like 0x is generated. x is treated as an unsigned value.

proc toHex[T: SomeInteger](x: T): string

Shortcut for toHex(x, T.sizeOf * 2)

proc toHex(s: string): string {...}{.noSideEffect, gcsafe, raises: [], tags: [].}

Converts a bytes string to its hexadecimal representation.

The output is twice the input long. No prefix like 0x is generated.

proc intToStr(x: int; minchars: Positive = 1): string {...}{.noSideEffect, gcsafe, extern: "nsuIntToStr", raises: [], tags: [].}

Converts x to its decimal representation.

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

proc parseInt(s: string): int {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseInt", raises: [OverflowError, ValueError], tags: [].}

Parses a decimal integer value contained in s.

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

proc parseBiggestInt(s: string): BiggestInt {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseBiggestInt", raises: [ValueError], tags: [].}

Parses a decimal integer value contained in s.

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

proc parseUInt(s: string): uint {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseUInt", raises: [ValueError], tags: [].}

Parses a decimal unsigned integer value contained in s.

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

proc parseBiggestUInt(s: string): BiggestUInt {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseBiggestUInt", raises: [ValueError], tags: [].}

Parses a decimal unsigned integer value contained in s.

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

proc parseFloat(s: string): float {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseFloat", raises: [ValueError], tags: [].}

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).

proc parseBinInt(s: string): int {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseBinInt", raises: [ValueError], tags: [].}

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.

proc parseOctInt(s: string): int {...}{.noSideEffect, gcsafe, extern: "nsuParseOctInt", raises: [ValueError], tags: [].}

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.

proc parseHexInt(s: string): int {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseHexInt", raises: [ValueError], tags: [].}

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.

proc parseHexStr(s: string): string {...}{.noSideEffect, procvar, gcsafe, extern: "nsuParseHexStr", raises: [ValueError], tags: [].}

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

hexToStr("00ff") == "\0\255"

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

proc parseBool(s: string): bool {...}{.raises: [ValueError], tags: [].}

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.

proc parseEnum[T: enum](s: string): T

Parses an enum T.

Raises ValueError for an invalid value in s. The comparison is done in a style insensitive way.

proc parseEnum[T: enum](s: string; default: T): T

Parses an enum T.

Uses default for an invalid value in s. The comparison is done in a style insensitive way.

proc repeat(c: char; count: Natural): string {...}{.noSideEffect, gcsafe, extern: "nsuRepeatChar", raises: [], tags: [].}

Returns a string of length count consisting only of the character c. You can use this proc to left align strings. Example:

proc tabexpand(indent: int, text: string, tabsize: int = 4) =
  echo '\t'.repeat(indent div tabsize), ' '.repeat(indent mod tabsize),
      text

tabexpand(4, "At four")
tabexpand(5, "At five")
tabexpand(6, "At six")

proc repeat(s: string; n: Natural): string {...}{.noSideEffect, gcsafe, extern: "nsuRepeatStr", raises: [], tags: [].}

Returns String s concatenated n times. Example:

echo "+++ STOP ".repeat(4), "+++"

proc align(s: string; count: Natural; padding = ' '): string {...}{.noSideEffect, gcsafe, extern: "nsuAlignString", raises: [], tags: [].}

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 proc. Example:

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

proc alignLeft(s: string; count: Natural; padding = ' '): string {...}{.noSideEffect, raises: [], tags: [].}

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 proc. Example:

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

proc wordWrap(s: string; maxLineWidth = 80; splitLongWords = true; seps: set[char] = Whitespace; newLine = "\n"): string {...}{.noSideEffect, gcsafe, extern: "nsuWordWrap", raises: [], tags: [].}

Word wraps s.

proc indent(s: string; count: Natural; padding: string = " "): string {...}{.noSideEffect, gcsafe, extern: "nsuIndent", raises: [], tags: [].}

Indents each line in s by count amount of padding.

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

proc unindent(s: string; count: Natural; padding: string = " "): string {...}{.noSideEffect, gcsafe, extern: "nsuUnindent", raises: [], tags: [].}

Unindents each line in s by count amount of padding.

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

proc unindent(s: string): string {...}{.noSideEffect, gcsafe, extern: "nsuUnindentAll", raises: [], tags: [].}

Removes all indentation composed of whitespace from each line in s.

For example:

const x = """
  Hello
  There
""".unindent()

doAssert x == "Hello\nThere\n"

proc startsWith(s, prefix: string): bool {...}{.noSideEffect, gcsafe, extern: "nsuStartsWith", raises: [], tags: [].}

Returns true iff s starts with prefix.

If prefix == "" true is returned.

proc startsWith(s: string; prefix: char): bool {...}{.noSideEffect, inline, raises: [], tags: [].}

Returns true iff s starts with prefix.

proc endsWith(s, suffix: string): bool {...}{.noSideEffect, gcsafe, extern: "nsuEndsWith", raises: [], tags: [].}

Returns true iff s ends with suffix.

If suffix == "" true is returned.

proc endsWith(s: string; suffix: char): bool {...}{.noSideEffect, inline, raises: [], tags: [].}

Returns true iff s ends with suffix.

proc continuesWith(s, substr: string; start: Natural): bool {...}{.noSideEffect, gcsafe, extern: "nsuContinuesWith", raises: [], tags: [].}

Returns true iff s continues with substr at position start.

If substr == "" true is returned.

proc addSep(dest: var string; sep = ", "; startLen: Natural = 0) {...}{.noSideEffect, inline, raises: [], tags: [].}

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.

Examples:

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

proc allCharsInSet(s: string; theSet: set[char]): bool {...}{.raises: [], tags: [].}

Returns true iff each character of s is in the set theSet.

proc abbrev(s: string; possibilities: openArray[string]): int {...}{.raises: [], tags: [].}

Returns the index of the first item in possibilities if not ambiguous.

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

proc join(a: openArray[string]; sep: string = ""): string {...}{.noSideEffect, gcsafe, extern: "nsuJoinSep", raises: [], tags: [].}

Concatenates all strings in a separating them with sep.

proc join[T: not string](a: openArray[T]; sep: string = ""): string {...}{.noSideEffect, gcsafe.}

Converts all elements in a to strings using $ and concatenates them with sep.

proc initSkipTable(a: var SkipTable; sub: string) {...}{.noSideEffect, gcsafe, extern: "nsuInitSkipTable", raises: [], tags: [].}

Preprocess table a for sub.

proc find(a: SkipTable; s, sub: string; start: Natural = 0; last = 0): int {...}{.noSideEffect, gcsafe, extern: "nsuFindStrA", raises: [], tags: [].}

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