From b109863c255f8c84ee3e3452400f4702bd20121c Mon Sep 17 00:00:00 2001
From: isabel <isabel@isabelroses.com>
Date: Thu, 13 Feb 2025 15:28:35 +0000
Subject: [PATCH] lib.strings: init toSentenceCase

---
 lib/default.nix    |  2 +-
 lib/strings.nix    | 36 ++++++++++++++++++++++++++++++++++++
 lib/tests/misc.nix |  9 +++++++++
 3 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/lib/default.nix b/lib/default.nix
index f931524002f2..910a4aeb0770 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -109,7 +109,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
@@ -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`.
 
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index 7618fd23383d..e886a2777b5b 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")