lib.strings: init toSentenceCase (#381802)

3 files changed, 46 insertions, 1 deletions

diff --git a/lib/default.nix b/lib/default.nix
index a978f29065de..e69a1cc3860c 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -141,7 +141,7 @@ let
       isStorePath isStringLike
       isValidPosixName toShellVar toShellVars trim trimWith
       escapeRegex escapeURL escapeXML replaceChars lowerChars
-      upperChars toLower toUpper addContextFrom splitString
+      upperChars toLower toUpper toSentenceCase addContextFrom splitString
       removePrefix removeSuffix versionOlder versionAtLeast
       getName getVersion match split
       cmakeOptionType cmakeBool cmakeFeature
diff --git a/lib/strings.nix b/lib/strings.nix
index 5ea86e0d7e07..bcaaab9af4fb 100644
--- a/lib/strings.nix
+++ b/lib/strings.nix
@@ -1425,6 +1425,42 @@ rec {
   toUpper = replaceStrings lowerChars upperChars;
 
   /**
+    Converts the first character of a string `s` to upper-case.
+
+    # Inputs
+
+    `str`
+    : The string to convert to sentence case.
+
+    # Type
+
+    ```
+    toSentenceCase :: string -> string
+    ```
+
+    # Examples
+    :::{.example}
+    ## `lib.strings.toSentenceCase` usage example
+
+    ```nix
+    toSentenceCase "home"
+    => "Home"
+    ```
+
+    :::
+  */
+  toSentenceCase = str:
+    lib.throwIfNot (isString str)
+      "toSentenceCase does only accepts string values, but got ${typeOf str}"
+      (
+        let
+          firstChar = substring 0 1 str;
+          rest = substring 1 (stringLength str) str;
+        in
+        addContextFrom str (toUpper firstChar + toLower rest)
+      );
+
+  /**
     Appends string context from string like object `src` to `target`.
 
     :::{.warning}
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index 8238391d3f0b..498f9064d2ff 100644
--- a/lib/tests/misc.nix
+++ b/lib/tests/misc.nix
@@ -678,6 +678,15 @@ runTests {
     ("%20%3F%26%3D%23%2B%25%21%3C%3E%23%22%7B%7D%7C%5C%5E%5B%5D%60%09%3A%2F%40%24%27%28%29%2A%2C%3B" == strings.escapeURL " ?&=#+%!<>#\"{}|\\^[]`\t:/@$'()*,;")
   ];
 
+  testToSentenceCase = {
+    expr = strings.toSentenceCase "hello world";
+    expected = "Hello world";
+  };
+
+  testToSentenceCasePath = testingThrow (
+    strings.toSentenceCase ./.
+  );
+
   testToInt = testAllTrue [
     # Naive
     (123 == toInt "123")