Merge dabef054883e95bc35444af369fd6132332bc1a7 into 36ecbb2c8dccc1a31c43fee1466f1425844d8607

crates/typst-library/src/foundations/func.rs

@@ -20,7 +20,7 @@ use crate::foundations::{
 ///
 /// You can call a function by writing a comma-separated list of function
 /// _arguments_ enclosed in parentheses directly after the function name.
-/// Additionally, you can pass any number of trailing content blocks arguments
+/// Additionally, you can pass any number of trailing content block arguments
 /// to a function _after_ the normal argument list. If the normal argument list
 /// would become empty, it can be omitted. Typst supports positional and named
 /// arguments. The former are identified by position and type, while the latter

crates/typst-library/src/foundations/str.rs

@@ -178,25 +178,39 @@ impl Str {
         self.0.len()
     }
 
-    /// Extracts the first grapheme cluster of the string.
-    /// Fails with an error if the string is empty.
+    /// Extracts the first grapheme cluster of the string. Fails with an error
+    /// if the string is empty. Returns the default value if the string is empty
+    /// or fails with an error is no default value was specified.
     #[func]
-    pub fn first(&self) -> StrResult<Str> {
+    pub fn first(
+        &self,
+        /// A default value to return if the string is empty.
+        #[named]
+        default: Option<Str>,
+    ) -> StrResult<Str> {
         self.0
             .graphemes(true)
             .next()
             .map(Into::into)
+            .or(default)
             .ok_or_else(string_is_empty)
     }
 
-    /// Extracts the last grapheme cluster of the string.
-    /// Fails with an error if the string is empty.
+    /// Extracts the last grapheme cluster of the string. Fails with an error if
+    /// the string is empty. Returns the default value if the string is empty or
+    /// fails with an error is no default value was specified.
     #[func]
-    pub fn last(&self) -> StrResult<Str> {
+    pub fn last(
+        &self,
+        /// A default value to return if the string is empty.
+        #[named]
+        default: Option<Str>,
+    ) -> StrResult<Str> {
         self.0
             .graphemes(true)
             .next_back()
             .map(Into::into)
+            .or(default)
             .ok_or_else(string_is_empty)
     }
 

docs/reference/groups.yml

@@ -205,7 +205,7 @@
       single or double quotes.
 
       The value is always of type [string]($str). More complex data
-      may be parsed manually using functions like [`json.decode`]($json.decode).
+      may be parsed manually using functions like [`json`]($json).
 
 - name: sym
   title: General

tests/suite/foundations/str.typ

@@ -103,6 +103,10 @@
 #test("Hello".last(), "o")
 #test("🏳️‍🌈A🏳️‍⚧️".first(), "🏳️‍🌈")
 #test("🏳️‍🌈A🏳️‍⚧️".last(), "🏳️‍⚧️")
+#test("hey".first(default: "d"), "h")
+#test("".first(default: "d"), "d")
+#test("hey".last(default: "d"), "y")
+#test("".last(default: "d"), "d")
 
 --- string-first-empty ---
 // Error: 2-12 string is empty