lib.strings: init toSentenceCase (#381802)

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

lib/strings.nix

@@ -1424,6 +1424,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`.
 

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