strutils

nimony/lib/std/strutils.nim

ASCII-focused helpers for splitting, searching, comparing, replacing, escaping, percent-formatting (%, format), float rendering (formatFloat, formatBiggestFloat), and human-readable sizes (formatSize).

Shared set[char] constants (Whitespace, Letters, …) describe common character classes; see each constant for details.

const Whitespace: set[char]
All the characters that count as whitespace (space, tab, vertical tab, carriage return, new line, form feed).
const Letters: set[char]
The set of letters.
const UppercaseLetters: set[char]
The set of uppercase ASCII letters.
const LowercaseLetters: set[char]
The set of lowercase ASCII letters.
const PunctuationChars: set[char]
The set of all ASCII punctuation characters.
const Digits: set[char]
The set of digits.
const HexDigits: set[char]
The set of hexadecimal digits.
const IdentChars: set[char]
The set of characters an identifier can consist of.
const IdentStartChars: set[char]
The set of characters an identifier can start with.
const Newlines: set[char]
The set of characters a newline terminator can start with (carriage return, line feed).
const PrintableChars: set[char]
The set of all printable ASCII characters (letters, digits, whitespace, and punctuation characters).
const AllChars: set[char]
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 func<#find,string,set[char],Natural,int>_ find invalid characters in strings. Example: nim let invalid = AllChars - Digits doAssert "01234".find(invalid) == -1 doAssert "01A34".find(invalid) == 2
func spaces(n: int64): string
Returns a string with n space characters.
func repeat(c: char; n: int64): string
Returns a string made of c repeated n times.
func repeat(s: string; n: int64): string
Returns s repeated n times.
func isAlphaAscii(c: char): bool
Checks whether or not character c is alphabetical.
This checks a-z, A-Z ASCII characters only. Use Unicode module<unicode.html>_ for UTF-8 support.
func isAlphaNumeric(c: char): bool
Checks whether or not c is alphanumeric.
This checks a-z, A-Z, 0-9 ASCII characters only.
func isDigit(c: char): bool
Checks whether or not c is a number.
This checks 0-9 ASCII characters only.
func isSpaceAscii(c: char): bool
Checks whether or not c is a whitespace character.
func isLowerAscii(c: char): bool
Checks whether or not c is a lower case character.
This checks ASCII characters only. Use Unicode module<unicode.html>_ for UTF-8 support.
See also:
- toLowerAscii func<#toLowerAscii,char>_
func isUpperAscii(c: char): bool
Checks whether or not c is an upper case character.
This checks ASCII characters only. Use Unicode module<unicode.html>_ for UTF-8 support.
See also:
- toUpperAscii func<#toUpperAscii,char>_
func allCharsInSet(s: string; theSet: set[char]): bool
Returns true if every character of s is in the set theSet.
func isEmptyOrWhitespace(s: string): bool
Checks if s is empty or consists entirely of whitespace characters.
func endsWith(s: string; c: char): bool
True if s is non-empty and its last character is c.
func strlen(x: cstring): int64
Length of the C string x (not counting the terminating zero). Freestanding (nimony n, libc-free): scan for the NUL terminator directly.
func $(x: cstring): string
Copies a nil-terminated C string into a Nim string.
func $(x: char): string
Returns a one-character string containing x.
iterator split(s: string; seps: set[char]; maxsplit: int64): string
Splits the string s into substrings using a group of separators.
Substrings are separated by a substring containing only seps.
nim for word in split("this\lis an\texample"): writeLine(stdout, word)
...generates this output:
"this" "is" "an" "example"
And the following code:
nim for word in split("this:is;an$example", {';', ':', '$'}): writeLine(stdout, word)
...produces the same output as the first example. The code:
nim let date = "2012-11-20T22:08:08.398990" let separators = {' ', '-', ':', 'T'} for number in split(date, separators): writeLine(stdout, number)
...results in:
"2012" "11" "20" "22" "08" "08.398990"
.. note:: Empty separator set results in returning an original string, following the interpretation "split by no element".
iterator split(s: string; sep: char; maxsplit: int64): string
Splits the string s into substrings using the separator sep.
Substrings are separated by the character sep.
iterator split(s: string; sep: string; maxsplit: int64): string
Splits the string s into substrings using the separator sep.
iterator splitLines(s: string; keepEol: bool): string
Splits the string s into its containing lines. Supports LF, CR, and CR-LF line endings.
iterator splitWhitespace(s: string; maxsplit: int64): string
Splits the string s at whitespace, stripping leading and trailing whitespace and collapsing runs of whitespace (no empty substrings are produced). If maxsplit is positive, at most maxsplit splits are made.
nim for word in splitWhitespace(" foo \t bar baz "): writeLine(stdout, word)
...generates "foo", "bar", "baz".
func split(s: string; seps: set[char]; maxsplit: int64): seq
The same as the split iterator, but returns a sequence of substrings.
func split(s: string; sep: char; maxsplit: int64): seq
The same as the split iterator, but returns a sequence of substrings.
func split(s: string; sep: string; maxsplit: int64): seq
The same as the split iterator, but returns a sequence of substrings.
func splitLines(s: string; keepEol: bool): seq
The same as the splitLines iterator, but returns a sequence of substrings.
func splitWhitespace(s: string; maxsplit: int64): seq
The same as the splitWhitespace iterator, but returns a sequence of substrings.
func join(a: openArray; sep: string): string
Concatenates all strings in a, separating them with sep.
func delete(s: var string; slice: HSlice)
Deletes the items s[slice].
This operation moves all elements after s[slice] in linear time, and is the string analog to sequtils.delete.
func continuesWith(s: string; prefix: string; start: int64): bool
Returns true if s continues with prefix at position start.
If prefix == "" true is returned.
See also:
- startsWith func<#startsWith,string,string>_
- endsWith func<#endsWith,string,string>_
func startsWith(s: string; prefix: string): bool
Returns true if s starts with string prefix.
If prefix == "" true is returned.
See also:
- endsWith func<#endsWith,string,string>_
- continuesWith func<#continuesWith,string,string,Natural>_
- removePrefix func<#removePrefix,string,string>_
func endsWith(s: string; suffix: string): bool
Returns true if s ends with suffix.
If suffix == "" true is returned.
See also:
- startsWith func<#startsWith,string,string>_
- continuesWith func<#continuesWith,string,string,Natural>_
- removeSuffix func<#removeSuffix,string,string>_
func toLowerAscii(c: char): char
Returns the lower case version of character c.
This works only for the letters A-Z. See unicode.toLower for a version that works for any Unicode character.
See also:
- isLowerAscii func<#isLowerAscii,char>_
- toLowerAscii func<#toLowerAscii,string>_ for converting a string
func toLowerAscii(s: string): string
Converts string s into lower case.
This works only for the letters A-Z. See unicode.toLower for a version that works for any Unicode character.
See also:
- normalize func<#normalize,string>_
func toUpperAscii(c: char): char
Converts character c into upper case.
This works only for the letters A-Z. See unicode.toUpper for a version that works for any Unicode character.
See also:
- isUpperAscii func<#isUpperAscii,char>_
- toUpperAscii func<#toUpperAscii,string>_ for converting a string
- capitalizeAscii func<#capitalizeAscii,string>_
func toUpperAscii(s: string): string
Converts string s into upper case.
This works only for the letters A-Z. See unicode.toUpper for a version that works for any Unicode character.
See also:
- capitalizeAscii func<#capitalizeAscii,string>_
func capitalizeAscii(s: string): string
Converts the first character of string s into upper case.
This works only for the letters A-Z. Use Unicode module<unicode.html>_ for UTF-8 support.
See also:
- toUpperAscii func<#toUpperAscii,char>_
func normalize(s: string): string
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<#toLowerAscii,string>_
func cmpIgnoreCase(a: string; b: string): int64
Compares two strings in a case insensitive manner. Returns:
| 0 if a == b
| < 0 if a < b
| > 0 if a > b
func cmpIgnoreStyle(a: string; b: string): int64
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<macros.html#eqIdent,string,string>_ for that.
Returns:
| 0 if a == b
| < 0 if a < b
| > 0 if a > b
func find(s: string; sub: char; start: int64; last: int64): int64
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:
- replace func<#replace,string,char,char>_
func find(s: string; chars: set[char]; start: int64; last: int64): int64
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:
- multiReplace func<#multiReplace,string,varargs[]>_
type SkipTable = array[0..255, int64]
Character table for efficient substring search.
func initSkipTable(a: var array[0..255, int64]; sub: string)
Initializes table a for efficient search of substring sub.
See also:
- initSkipTable func<#initSkipTable,string>_
- find func<#find,SkipTable,string,string,Natural,int>_
func initSkipTable(sub: string): array[0..255, int64]
Returns a new table initialized for sub.
See also:
- initSkipTable func<#initSkipTable,SkipTable,string>_
- find func<#find,SkipTable,string,string,Natural,int>_
func find(a: array[0..255, int64]; s: string; sub: string; start: int64; last: int64): int64
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,string>_
- initSkipTable func<#initSkipTable,SkipTable,string>_
func find(s: string; sub: string; start: int64; last: int64): int64
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:
- replace func<#replace,string,string,string>_
func replace(s: string; sub: char; by: char): string
Returns a copy of s where every sub is replaced by by.
func replace(s: string; sub: string; by: string): string
Replaces every occurrence of the string sub in s with the string by.
See also:
- find func<#find,string,string,Natural,int>_
- replace func<#replace,string,char,char>_ for replacing
single characters
- replaceWord func<#replaceWord,string,string,string>_
- multiReplace func<#multiReplace,string,varargs[]>_ for substrings
- multiReplace func<#multiReplace,openArray[char],varargs[]>_ for single characters
func replaceWord(s: string; sub: string; by: string): string
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.
func multiReplace(s: string; replacements: openArray): string
Same as replace<#replace,string,string,string>_, 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.
func multiReplace(s: openArray; replacements: openArray): string
Performs multiple character replacements in a single pass through the input.
multiReplace scans the input s from left to right and replaces characters based on character sets, applying the first matching replacement at each position. Useful for sanitizing or transforming strings with predefined character mappings.
The order of the replacements matters: - First matching replacement is applied - Subsequent replacements are not considered for the same character
See also:
- multiReplace(s: string; replacements: varargs[(string, string)]),
func toHex(x: int64; len: int64): string
Converts x to a hexadecimal string exactly len uppercase digits wide (no 0x prefix). Negative values render in two's complement, and a value needing more than len digits keeps only its least-significant len nibbles.
func toHex(x: T): string
Full-width hex for x: 2 * sizeof(T) uppercase digits, e.g. toHex(0'u16) == "0000", toHex(255'u8) == "FF".
func escape(s: string; prefix: string; suffix: string): string
Escapes a string s.
.. note:: The escaping scheme is different from system.addEscapedChar.
- 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 func<system.html#addEscapedChar,string,char>_
- unescape func<#unescape,string,string,string>_ for the opposite
operation
func unescape(s: string; prefix: string; suffix: string): string
Unescapes a string s.
This complements escape func<#escape,string,string,string>_ as it performs the opposite operations.
If s does not begin with prefix and end with suffix a ValueError exception will be raised.

type FloatFormatMode = enum
  ffDefault = (0, "ffDefault")
  ffDecimal = (1, "ffDecimal")
  ffScientific = (2, "ffScientific")

func dollar`.FloatFormatMode(e: FloatFormatMode): string
func formatBiggestFloat(f: float64; format: FloatFormatMode; precision: -1..32; decimalSep: char): string
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.
func formatFloat(f: float64; format: FloatFormatMode; precision: -1..32; decimalSep: char): string
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.
func %(formatstr: string; a: openArray): string
Interpolates a format string with the values from a.
The substitution:idx: operator performs string substitutions in formatstr and returns a modified formatstr. This is often called string interpolation:idx:.
This is best explained by an example:
nim "$1 eats $2." % ["The cat", "fish"]
Results in:
nim "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:
nim "$# 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:
nim "$animal eats $food." % ["animal", "The cat", "food", "fish"]
Results in:
nim "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.
func format(formatstr: string; a: openArray): string
This is the same as formatstr % a (see % func<#%25,string,openArray[string]>_)
func strip(s: string; leading: bool; trailing: bool; chars: set[char]): string
Strips leading or trailing chars (default: whitespace characters) from s and returns the resulting string.
If leading is true (default), leading chars are stripped. If trailing is true (default), trailing chars are stripped. If both are false, the string is returned unchanged.
func trimZeros(x: var string; decimalSep: char)
Trim trailing zeros from a formatted floating point value x (must be declared as var).
This modifies x itself, it does not return a copy.

type BinaryPrefixMode = enum
  bpIEC = (0, "bpIEC")
  bpColloquial = (1, "bpColloquial")

func dollar`.BinaryPrefixMode(e: BinaryPrefixMode): string
func formatSize(bytes: int64; decimalSep: char; prefix: BinaryPrefixMode; includeSpace: bool): string
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<strformat.html>_ for string interpolation and formatting
func contains(s: string; sub: string): bool
Same as find(s, sub) >= 0.
See also:
- find func<#find,string,string,Natural,int>_
func contains(s: string; chars: set[char]): bool
Same as find(s, chars) >= 0.
See also:
- find func<#find,string,set[char],Natural,int>_
func parseBiggestInt(s: string): int64
Parses a decimal integer value contained in s.
ValueError is raised if s is not a valid integer.
func parseInt(s: string): int64
Parses a decimal integer value contained in s.
ValueError is raised if s is not a valid integer. nim assert parseInt("-0042") == -42