lib.strings: string manipulation functions

lib.strings.concatStrings

Type: concatStrings :: [string] -> string

Concatenate a list of strings.

concatStrings ["foo" "bar"]
=> "foobar"

Located at lib/strings.nix:50 in <nixpkgs>.

lib.strings.concatMapStrings

Type: concatMapStrings :: (a -> string) -> [a] -> string

Map a function over a list and concatenate the resulting strings.

f

Function argument

list

Function argument

concatMapStrings (x: "a" + x) ["foo" "bar"]
=> "afooabar"

Located at lib/strings.nix:60 in <nixpkgs>.

lib.strings.concatImapStrings

Type: concatImapStrings :: (int -> a -> string) -> [a] -> string

Like concatMapStrings except that the f functions also gets the position as a parameter.

f

Function argument

list

Function argument

concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
=> "1-foo2-bar"

Located at lib/strings.nix:71 in <nixpkgs>.

lib.strings.intersperse

Type: intersperse :: a -> [a] -> [a]

Place an element between each element of a list

separator

Separator to add between elements

list

Input list

intersperse "/" ["usr" "local" "bin"]
=> ["usr" "/" "local" "/" "bin"].

Located at lib/strings.nix:81 in <nixpkgs>.

lib.strings.concatStringsSep

Type: concatStringsSep :: string -> [string] -> string

Concatenate a list of strings with a separator between each element

concatStringsSep "/" ["usr" "local" "bin"]
=> "usr/local/bin"

Located at lib/strings.nix:98 in <nixpkgs>.

lib.strings.concatMapStringsSep

Type: concatMapStringsSep :: string -> (a -> string) -> [a] -> string

Maps a function over a list of strings and then concatenates the result with the specified separator interspersed between elements.

sep

Separator to add between elements

f

Function to map over the list

list

List of input strings

concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
=> "FOO-BAR-BAZ"

Located at lib/strings.nix:111 in <nixpkgs>.

lib.strings.concatImapStringsSep

Type: concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string

Same as concatMapStringsSep, but the mapping function additionally receives the position of its argument.

sep

Separator to add between elements

f

Function that receives elements and their positions

list

List of input strings

concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
=> "6-3-2"

Located at lib/strings.nix:128 in <nixpkgs>.

lib.strings.concatLines

Type: concatLines :: [string] -> string

Concatenate a list of strings, adding a newline at the end of each one. Defined as concatMapStrings (s: s + "\n").

concatLines [ "foo" "bar" ]
=> "foo\nbar\n"

Located at lib/strings.nix:145 in <nixpkgs>.

lib.strings.makeSearchPath

Type: makeSearchPath :: string -> [string] -> string

Construct a Unix-style, colon-separated search path consisting of the given subDir appended to each of the given paths.

subDir

Directory name to append

paths

List of base paths

makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"
makeSearchPath "bin" [""]
=> "/bin"

Located at lib/strings.nix:158 in <nixpkgs>.

lib.strings.makeSearchPathOutput

Type: string -> string -> [package] -> string

Construct a Unix-style search path by appending the given subDir to the specified output of each of the packages. If no output by the given name is found, fallback to .out and then to the default.

output

Package output to use

subDir

Directory name to append

pkgs

List of packages

makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"

Located at lib/strings.nix:176 in <nixpkgs>.

lib.strings.makeLibraryPath

Construct a library search path (such as RPATH) containing the libraries for a set of packages

makeLibraryPath [ "/usr" "/usr/local" ]
=> "/usr/lib:/usr/local/lib"
pkgs = import <nixpkgs> { }
makeLibraryPath [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"

Located at lib/strings.nix:194 in <nixpkgs>.

lib.strings.makeBinPath

Construct a binary search path (such as $PATH) containing the binaries for a set of packages.

makeBinPath ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"

Located at lib/strings.nix:203 in <nixpkgs>.

lib.strings.normalizePath

Type: normalizePath :: string -> string

Normalize path, removing extraneous /s

s

Function argument

normalizePath "/a//b///c/"
=> "/a/b/c/"

Located at lib/strings.nix:213 in <nixpkgs>.

lib.strings.optionalString

Type: optionalString :: bool -> string -> string

Depending on the boolean `cond', return either the given string or the empty string. Useful to concatenate against a bigger string.

cond

Condition

string

String to return if condition is true

optionalString true "some-string"
=> "some-string"
optionalString false "some-string"
=> ""

Located at lib/strings.nix:239 in <nixpkgs>.

lib.strings.hasPrefix

Type: hasPrefix :: string -> string -> bool

Determine whether a string has given prefix.

pref

Prefix to check for

str

Input string

hasPrefix "foo" "foobar"
=> true
hasPrefix "foo" "barfoo"
=> false

Located at lib/strings.nix:255 in <nixpkgs>.

lib.strings.hasSuffix

Type: hasSuffix :: string -> string -> bool

Determine whether a string has given suffix.

suffix

Suffix to check for

content

Input string

hasSuffix "foo" "foobar"
=> false
hasSuffix "foo" "barfoo"
=> true

Located at lib/strings.nix:282 in <nixpkgs>.

lib.strings.hasInfix

Type: hasInfix :: string -> string -> bool

Determine whether a string contains the given infix

infix

Function argument

content

Function argument

hasInfix "bc" "abcd"
=> true
hasInfix "ab" "abcd"
=> true
hasInfix "cd" "abcd"
=> true
hasInfix "foo" "abcd"
=> false

Located at lib/strings.nix:319 in <nixpkgs>.

lib.strings.stringToCharacters

Type: stringToCharacters :: string -> [string]

Convert a string to a list of characters (i.e. singleton strings). This allows you to, e.g., map a function over each character. However, note that this will likely be horribly inefficient; Nix is not a general purpose programming language. Complex string manipulations should, if appropriate, be done in a derivation. Also note that Nix treats strings as a list of bytes and thus doesn't handle unicode.

s

Function argument

stringToCharacters ""
=> [ ]
stringToCharacters "abc"
=> [ "a" "b" "c" ]
stringToCharacters "🦄"
=> [ "�" "�" "�" "�" ]

Located at lib/strings.nix:349 in <nixpkgs>.

lib.strings.stringAsChars

Type: stringAsChars :: (string -> string) -> string -> string

Manipulate a string character by character and replace them by strings before concatenating the results.

f

Function to map over each individual character

s

Input string

stringAsChars (x: if x == "a" then "i" else x) "nax"
=> "nix"

Located at lib/strings.nix:361 in <nixpkgs>.

lib.strings.charToInt

Type: charToInt :: string -> int

Convert char to ascii value, must be in printable range

c

Function argument

charToInt "A"
=> 65
charToInt "("
=> 40

Located at lib/strings.nix:380 in <nixpkgs>.

lib.strings.escape

Type: escape :: [string] -> string -> string

Escape occurrence of the elements of list in string by prefixing it with a backslash.

list

Function argument

escape ["(" ")"] "(foo)"
=> "\\(foo\\)"

Located at lib/strings.nix:391 in <nixpkgs>.

lib.strings.escapeC

Type: escapeC = [string] -> string -> string

Escape occurrence of the element of list in string by converting to its ASCII value and prefixing it with \x. Only works for printable ascii characters.

list

Function argument

escapeC [" "] "foo bar"
=> "foo\\x20bar"

Located at lib/strings.nix:404 in <nixpkgs>.

lib.strings.escapeURL

Type: escapeURL :: string -> string

Escape the string so it can be safely placed inside a URL query.

escapeURL "foo/bar baz"
=> "foo%2Fbar%20baz"

Located at lib/strings.nix:415 in <nixpkgs>.

lib.strings.escapeShellArg

Type: escapeShellArg :: string -> string

Quote string to be used safely within the Bourne shell.

arg

Function argument

escapeShellArg "esc'ape\nme"
=> "'esc'\\''ape\nme'"

Located at lib/strings.nix:429 in <nixpkgs>.

lib.strings.escapeShellArgs

Type: escapeShellArgs :: [string] -> string

Quote all arguments to be safely passed to the Bourne shell.

escapeShellArgs ["one" "two three" "four'five"]
=> "'one' 'two three' 'four'\\''five'"

Located at lib/strings.nix:439 in <nixpkgs>.

lib.strings.isValidPosixName

Type: string -> bool

Test whether the given name is a valid POSIX shell variable name.

name

Function argument

isValidPosixName "foo_bar000"
=> true
isValidPosixName "0-bad.jpg"
=> false

Located at lib/strings.nix:451 in <nixpkgs>.

lib.strings.toShellVar

Type: string -> (string | listOf string | attrsOf string) -> string

Translate a Nix value into a shell variable declaration, with proper escaping.

The value can be a string (mapped to a regular variable), a list of strings (mapped to a Bash-style array) or an attribute set of strings (mapped to a Bash-style associative array). Note that "string" includes string-coercible values like paths or derivations.

Strings are translated into POSIX sh-compatible code; lists and attribute sets assume a shell that understands Bash syntax (e.g. Bash or ZSH).

name

Function argument

value

Function argument

''
  ${toShellVar "foo" "some string"}
  [[ "$foo" == "some string" ]]
''

Located at lib/strings.nix:471 in <nixpkgs>.

lib.strings.toShellVars

Type: attrsOf (string | listOf string | attrsOf string) -> string

Translate an attribute set into corresponding shell variable declarations using toShellVar.

vars

Function argument

let
  foo = "value";
  bar = foo;
in ''
  ${toShellVars { inherit foo bar; }}
  [[ "$foo" == "$bar" ]]
''

Located at lib/strings.nix:499 in <nixpkgs>.

lib.strings.escapeNixString

Type: string -> string

Turn a string into a Nix expression representing that string

s

Function argument

escapeNixString "hello\${}\n"
=> "\"hello\\\${}\\n\""

Located at lib/strings.nix:509 in <nixpkgs>.

lib.strings.escapeRegex

Type: string -> string

Turn a string into an exact regular expression

escapeRegex "[^a-z]*"
=> "\\[\\^a-z]\\*"

Located at lib/strings.nix:519 in <nixpkgs>.

lib.strings.escapeNixIdentifier

Type: string -> string

Quotes a string if it can't be used as an identifier directly.

s

Function argument

escapeNixIdentifier "hello"
=> "hello"
escapeNixIdentifier "0abc"
=> "\"0abc\""

Located at lib/strings.nix:531 in <nixpkgs>.

lib.strings.escapeXML

Type: string -> string

Escapes a string such that it is safe to include verbatim in an XML document.

escapeXML ''"test" 'test' < & >''
=> "&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;"

Located at lib/strings.nix:545 in <nixpkgs>.

lib.strings.toLower

Type: toLower :: string -> string

Converts an ASCII string to lower-case.

toLower "HOME"
=> "home"

Located at lib/strings.nix:564 in <nixpkgs>.

lib.strings.toUpper

Type: toUpper :: string -> string

Converts an ASCII string to upper-case.

toUpper "home"
=> "HOME"

Located at lib/strings.nix:574 in <nixpkgs>.

lib.strings.addContextFrom

Appends string context from another string. This is an implementation detail of Nix and should be used carefully.

Strings in Nix carry an invisible context which is a list of strings representing store paths. If the string is later used in a derivation attribute, the derivation will properly populate the inputDrvs and inputSrcs.

a

Function argument

b

Function argument

pkgs = import <nixpkgs> { };
addContextFrom pkgs.coreutils "bar"
=> "bar"

Located at lib/strings.nix:589 in <nixpkgs>.

lib.strings.splitString

Cut a string with a separator and produces a list of strings which were separated by this separator.

sep

Function argument

s

Function argument

splitString "." "foo.bar.baz"
=> [ "foo" "bar" "baz" ]
splitString "/" "/usr/local/bin"
=> [ "" "usr" "local" "bin" ]

Located at lib/strings.nix:600 in <nixpkgs>.

lib.strings.removePrefix

Type: string -> string -> string

Return a string without the specified prefix, if the prefix matches.

prefix

Prefix to remove if it matches

str

Input string

removePrefix "foo." "foo.bar.baz"
=> "bar.baz"
removePrefix "xxx" "foo.bar.baz"
=> "foo.bar.baz"

Located at lib/strings.nix:616 in <nixpkgs>.

lib.strings.removeSuffix

Type: string -> string -> string

Return a string without the specified suffix, if the suffix matches.

suffix

Suffix to remove if it matches

str

Input string

removeSuffix "front" "homefront"
=> "home"
removeSuffix "xxx" "homefront"
=> "homefront"

Located at lib/strings.nix:649 in <nixpkgs>.

lib.strings.versionOlder

Return true if string v1 denotes a version older than v2.

v1

Function argument

v2

Function argument

versionOlder "1.1" "1.2"
=> true
versionOlder "1.1" "1.1"
=> false

Located at lib/strings.nix:680 in <nixpkgs>.

lib.strings.versionAtLeast

Return true if string v1 denotes a version equal to or newer than v2.

v1

Function argument

v2

Function argument

versionAtLeast "1.1" "1.0"
=> true
versionAtLeast "1.1" "1.1"
=> true
versionAtLeast "1.1" "1.2"
=> false

Located at lib/strings.nix:692 in <nixpkgs>.

lib.strings.getName

This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the name part from that argument.

x

Function argument

getName "youtube-dl-2016.01.01"
=> "youtube-dl"
getName pkgs.youtube-dl
=> "youtube-dl"

Located at lib/strings.nix:704 in <nixpkgs>.

lib.strings.getVersion

This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the version part from that argument.

x

Function argument

getVersion "youtube-dl-2016.01.01"
=> "2016.01.01"
getVersion pkgs.youtube-dl
=> "2016.01.01"

Located at lib/strings.nix:721 in <nixpkgs>.

lib.strings.nameFromURL

Extract name with version from URL. Ask for separator which is supposed to start extension.

url

Function argument

sep

Function argument

nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-"
=> "nix"
nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_"
=> "nix-1.7-x86"

Located at lib/strings.nix:737 in <nixpkgs>.

lib.strings.mesonOption

Type:

mesonOption :: string -> string -> string

@param feature The feature to be set
@param value The desired value

Create a -D= string that can be passed to typical Meson invocations.

feature

Function argument

value

Function argument

mesonOption "engine" "opengl"
=> "-Dengine=opengl"

Located at lib/strings.nix:756 in <nixpkgs>.

lib.strings.mesonBool

Type:

mesonBool :: string -> bool -> string

@param condition The condition to be made true or false
@param flag The controlling flag of the condition

Create a -D={true,false} string that can be passed to typical Meson invocations.

condition

Function argument

flag

Function argument

mesonBool "hardened" true
=> "-Dhardened=true"
mesonBool "static" false
=> "-Dstatic=false"

Located at lib/strings.nix:775 in <nixpkgs>.

lib.strings.mesonEnable

Type:

mesonEnable :: string -> bool -> string

@param feature The feature to be enabled or disabled
@param flag The controlling flag

Create a -D={enabled,disabled} string that can be passed to typical Meson invocations.

feature

Function argument

flag

Function argument

mesonEnable "docs" true
=> "-Ddocs=enabled"
mesonEnable "savage" false
=> "-Dsavage=disabled"

Located at lib/strings.nix:794 in <nixpkgs>.

lib.strings.enableFeature

Create an --{enable,disable}- string that can be passed to standard GNU Autoconf scripts.

enable

Function argument

feat

Function argument

enableFeature true "shared"
=> "--enable-shared"
enableFeature false "shared"
=> "--disable-shared"

Located at lib/strings.nix:808 in <nixpkgs>.

lib.strings.enableFeatureAs

Create an --{enable-=,disable-} string that can be passed to standard GNU Autoconf scripts.

enable

Function argument

feat

Function argument

value

Function argument

enableFeatureAs true "shared" "foo"
=> "--enable-shared=foo"
enableFeatureAs false "shared" (throw "ignored")
=> "--disable-shared"

Located at lib/strings.nix:821 in <nixpkgs>.

lib.strings.withFeature

Create an --{with,without}- string that can be passed to standard GNU Autoconf scripts.

with_

Function argument

feat

Function argument

withFeature true "shared"
=> "--with-shared"
withFeature false "shared"
=> "--without-shared"

Located at lib/strings.nix:832 in <nixpkgs>.

lib.strings.withFeatureAs

Create an --{with-=,without-} string that can be passed to standard GNU Autoconf scripts.

with_

Function argument

feat

Function argument

value

Function argument

withFeatureAs true "shared" "foo"
=> "--with-shared=foo"
withFeatureAs false "shared" (throw "ignored")
=> "--without-shared"

Located at lib/strings.nix:845 in <nixpkgs>.

lib.strings.fixedWidthString

Type: fixedWidthString :: int -> string -> string -> string

Create a fixed width string with additional prefix to match required width.

This function will fail if the input string is longer than the requested length.

width

Function argument

filler

Function argument

str

Function argument

fixedWidthString 5 "0" (toString 15)
=> "00015"

Located at lib/strings.nix:859 in <nixpkgs>.

lib.strings.fixedWidthNumber

Format a number adding leading zeroes up to fixed width.

width

Function argument

n

Function argument

fixedWidthNumber 5 15
=> "00015"

Located at lib/strings.nix:876 in <nixpkgs>.

lib.strings.floatToString

Convert a float to a string, but emit a warning when precision is lost during the conversion

float

Function argument

floatToString 0.000001
=> "0.000001"
floatToString 0.0000001
=> trace: warning: Imprecise conversion from float to string 0.000000
   "0.000000"

Located at lib/strings.nix:888 in <nixpkgs>.

lib.strings.isCoercibleToString

Soft-deprecated function. While the original implementation is available as isConvertibleWithToString, consider using isStringLike instead, if suitable.

Located at lib/strings.nix:896 in <nixpkgs>.

lib.strings.isConvertibleWithToString

Check whether a list or other value can be passed to toString.

Many types of value are coercible to string this way, including int, float, null, bool, list of similarly coercible values.

x

Function argument

Located at lib/strings.nix:905 in <nixpkgs>.

lib.strings.isStringLike

Check whether a value can be coerced to a string. The value must be a string, path, or attribute set.

String-like values can be used without explicit conversion in string interpolations and in most functions that expect a string.

x

Function argument

Located at lib/strings.nix:916 in <nixpkgs>.

lib.strings.isStorePath

Check whether a value is a store path.

x

Function argument

isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python"
=> false
isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11"
=> true
isStorePath pkgs.python
=> true
isStorePath [] || isStorePath 42 || isStorePath {} || …
=> false

Located at lib/strings.nix:934 in <nixpkgs>.

lib.strings.toInt

Type: string -> int

Parse a string as an int. Does not support parsing of integers with preceding zero due to ambiguity between zero-padded and octal numbers. See toIntBase10.

str

Function argument

toInt "1337"
=> 1337

toInt "-4"
=> -4

toInt " 123 "
=> 123

toInt "00024"
=> error: Ambiguity in interpretation of 00024 between octal and zero padded integer.

toInt "3.14"
=> error: floating point JSON numbers are not supported

Located at lib/strings.nix:964 in <nixpkgs>.

lib.strings.toIntBase10

Type: string -> int

Parse a string as a base 10 int. This supports parsing of zero-padded integers.

str

Function argument

toIntBase10 "1337"
=> 1337

toIntBase10 "-4"
=> -4

toIntBase10 " 123 "
=> 123

toIntBase10 "00024"
=> 24

toIntBase10 "3.14"
=> error: floating point JSON numbers are not supported

Located at lib/strings.nix:1015 in <nixpkgs>.

lib.strings.readPathsFromFile

Read a list of paths from file, relative to the rootPath. Lines beginning with # are treated as comments and ignored. Whitespace is significant.

NOTE: This function is not performant and should be avoided.

readPathsFromFile /prefix
  ./pkgs/development/libraries/qt-5/5.4/qtbase/series
=> [ "/prefix/dlopen-resolv.patch" "/prefix/tzdir.patch"
     "/prefix/dlopen-libXcursor.patch" "/prefix/dlopen-openssl.patch"
     "/prefix/dlopen-dbus.patch" "/prefix/xdg-config-dirs.patch"
     "/prefix/nix-profiles-library-paths.patch"
     "/prefix/compose-search-path.patch" ]

Located at lib/strings.nix:1058 in <nixpkgs>.

lib.strings.fileContents

Type: fileContents :: path -> string

Read the contents of a file removing the trailing \n

file

Function argument

$ echo "1.0" > ./version

fileContents ./version
=> "1.0"

Located at lib/strings.nix:1078 in <nixpkgs>.

lib.strings.sanitizeDerivationName

Type: sanitizeDerivationName :: String -> String

Creates a valid derivation name from a potentially invalid one.

sanitizeDerivationName "../hello.bar # foo"
=> "-hello.bar-foo"
sanitizeDerivationName ""
=> "unknown"
sanitizeDerivationName pkgs.hello
=> "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10"

Located at lib/strings.nix:1093 in <nixpkgs>.

lib.strings.levenshtein

Type: levenshtein :: string -> string -> int

Computes the Levenshtein distance between two strings. Complexity O(n*m) where n and m are the lengths of the strings. Algorithm adjusted from https://stackoverflow.com/a/9750974/6605742

a

Function argument

b

Function argument

levenshtein "foo" "foo"
=> 0
levenshtein "book" "hook"
=> 1
levenshtein "hello" "Heyo"
=> 3

Located at lib/strings.nix:1132 in <nixpkgs>.

lib.strings.commonPrefixLength

Returns the length of the prefix common to both strings.

a

Function argument

b

Function argument

Located at lib/strings.nix:1153 in <nixpkgs>.

lib.strings.commonSuffixLength

Returns the length of the suffix common to both strings.

a

Function argument

b

Function argument

Located at lib/strings.nix:1161 in <nixpkgs>.

lib.strings.levenshteinAtMost

Type: levenshteinAtMost :: int -> string -> string -> bool

Returns whether the levenshtein distance between two strings is at most some value Complexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise

levenshteinAtMost 0 "foo" "foo"
=> true
levenshteinAtMost 1 "foo" "boa"
=> false
levenshteinAtMost 2 "foo" "boa"
=> true
levenshteinAtMost 2 "This is a sentence" "this is a sentense."
=> false
levenshteinAtMost 3 "This is a sentence" "this is a sentense."
=> true

Located at lib/strings.nix:1185 in <nixpkgs>.