feat: various methods to work with strings (#1112)

Closes #1108 ### Summary of Changes Add several methods to work with strings: * `contains` * `endsWith` * `indexOf` * `lastIndexOf` * `length` * `repeat` * `replace` * `split` * `startsWith` * `substring` * `toCasefolded` * `toLowercase` * `toUppercase` * `trim` * `trimEnd` * `trimStart` Also rename the `@PythonCall` annotation to `@PythonMacro` to better describe what it does.
Safe-DS · Apr 27, 2024 · b6d4f16 · b6d4f16
1 parent c7bd0fa
commit b6d4f16
Show file tree

Hide file tree

Showing 74 changed files with 1,508 additions and 418 deletions.
diff --git a/docs/api/SUMMARY.md b/docs/api/SUMMARY.md
@@ -46,7 +46,7 @@ search:
         - [Nothing](safeds/lang/Nothing.md)
         - [Number](safeds/lang/Number.md)
         - [Pure](safeds/lang/Pure.md)
-        - [PythonCall](safeds/lang/PythonCall.md)
+        - [PythonMacro](safeds/lang/PythonMacro.md)
         - [PythonModule](safeds/lang/PythonModule.md)
         - [PythonName](safeds/lang/PythonName.md)
         - [Repeatable](safeds/lang/Repeatable.md)

diff --git a/docs/api/safeds/lang/Any.md b/docs/api/safeds/lang/Any.md
@@ -13,28 +13,28 @@ The common superclass of all classes.
     class Any {
 
         /**
-         * Returns a string representation of the object.
+         * Return a string representation of the object.
          *
          * @example
          * pipeline example {
          *     val string = 1.toString(); // "1"
          * }
          */
         @Pure
-        @PythonCall("str($this)")
-        fun toString() -> s: String
+        @PythonMacro("str($this)")
+        fun toString() -> string: String
     }
     ```
 
 ## `#!sds fun` toString {#safeds.lang.Any.toString data-toc-label='toString'}
 
-Returns a string representation of the object.
+Return a string representation of the object.
 
 **Results:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `s` | [`String`][safeds.lang.String] | - |
+| `string` | [`String`][safeds.lang.String] | - |
 
 **Examples:**
 
@@ -48,6 +48,6 @@ pipeline example {
 
     ```sds linenums="16"
     @Pure
-    @PythonCall("str($this)")
-    fun toString() -> s: String
+    @PythonMacro("str($this)")
+    fun toString() -> string: String
     ```
diff --git a/docs/api/safeds/lang/Float.md b/docs/api/safeds/lang/Float.md
@@ -21,29 +21,30 @@ pipeline example {
 
     ```sds linenums="77"
     class Float sub Number {
+
         /**
-         * Converts this floating-point number to an integer by truncating the fractional part.
+         * Convert this floating-point number to an integer by truncating the fractional part.
          *
          * @example
          * pipeline example {
          *     val int = 1.0.toInt(); // 1
          * }
          */
         @Pure
-        @PythonCall("int($this)")
-        fun toInt() -> i: Int
+        @PythonMacro("int($this)")
+        fun toInt() -> int: Int
     }
     ```
 
 ## `#!sds fun` toInt {#safeds.lang.Float.toInt data-toc-label='toInt'}
 
-Converts this floating-point number to an integer by truncating the fractional part.
+Convert this floating-point number to an integer by truncating the fractional part.
 
 **Results:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `i` | [`Int`][safeds.lang.Int] | - |
+| `int` | [`Int`][safeds.lang.Int] | - |
 
 **Examples:**
 
@@ -55,8 +56,8 @@ pipeline example {
 
 ??? quote "Stub code in `coreClasses.sdsstub`"
 
-    ```sds linenums="86"
+    ```sds linenums="87"
     @Pure
-    @PythonCall("int($this)")
-    fun toInt() -> i: Int
+    @PythonMacro("int($this)")
+    fun toInt() -> int: Int
     ```
diff --git a/docs/api/safeds/lang/Impure.md b/docs/api/safeds/lang/Impure.md
@@ -1,6 +1,6 @@
 # :test_tube:{ title="Experimental" } `#!sds annotation` Impure {#safeds.lang.Impure data-toc-label='Impure'}
 
-Indicates that the function has side effects and/or does not always return the same results given the same arguments.
+The function has side effects and/or does not always return the same results given the same arguments.
 
 **Parameters:**
 
@@ -14,6 +14,6 @@ Indicates that the function has side effects and/or does not always return the s
 
 ??? quote "Stub code in `purity.sdsstub`"
 
-    ```sds linenums="22"
+    ```sds linenums="23"
     annotation Impure(allReasons: List<ImpurityReason>)
     ```
diff --git a/docs/api/safeds/lang/ImpurityReason.md b/docs/api/safeds/lang/ImpurityReason.md
@@ -4,7 +4,7 @@ A reason why a function is impure.
 
 ??? quote "Stub code in `purity.sdsstub`"
 
-    ```sds linenums="27"
+    ```sds linenums="28"
     enum ImpurityReason {
 
         /**

diff --git a/docs/api/safeds/lang/Int.md b/docs/api/safeds/lang/Int.md
@@ -23,28 +23,28 @@ pipeline example {
     class Int sub Number {
 
         /**
-         * Converts this integer to a floating-point number.
+         * Convert this integer to a floating-point number.
          *
          * @example
          * pipeline example {
          *     val float = 1.toFloat(); // 1.0
          * }
          */
         @Pure
-        @PythonCall("float($this)")
-        fun toFloat() -> f: Float
+        @PythonMacro("float($this)")
+        fun toFloat() -> float: Float
     }
     ```
 
 ## `#!sds fun` toFloat {#safeds.lang.Int.toFloat data-toc-label='toFloat'}
 
-Converts this integer to a floating-point number.
+Convert this integer to a floating-point number.
 
 **Results:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `f` | [`Float`][safeds.lang.Float] | - |
+| `float` | [`Float`][safeds.lang.Float] | - |
 
 **Examples:**
 
@@ -58,6 +58,6 @@ pipeline example {
 
     ```sds linenums="64"
     @Pure
-    @PythonCall("float($this)")
-    fun toFloat() -> f: Float
+    @PythonMacro("float($this)")
+    fun toFloat() -> float: Float
     ```
diff --git a/docs/api/safeds/lang/List.md b/docs/api/safeds/lang/List.md
@@ -23,26 +23,95 @@ pipeline example {
 
 ??? quote "Stub code in `coreClasses.sdsstub`"
 
-    ```sds linenums="99"
+    ```sds linenums="100"
     class List<out E> {
 
         /**
-         * Returns the number of elements in the list.
+         * Join the elements of the list into a string using the separator.
+         *
+         * @example
+         * pipeline example {
+         *     val string = [1, 2, 3].join(); // "1, 2, 3"
+         * }
+         *
+         * @example
+         * pipeline example {
+         *     val string = [1, 2, 3].join("-"); // "1-2-3"
+         * }
+         */
+        @Pure
+        @PythonMacro("$separator.join($this)")
+        fun join(separator: String = ", ") -> string: String
+
+        /**
+         * Return the slice of the list starting at the start index up to but excluding the end index.
+         *
+         * @param start The start index (inclusive).
+         * @param end The end index (exclusive). Negative indices count from the end of the list.
+         *
+         * @example
+         * pipeline example {
+         *     val slice = [1, 2, 3].slice(1, 3); // [2, 3]
+         * }
+         */
+        @Pure
+        @PythonMacro("$this[$start:$end]")
+        fun slice(start: Int = 0, end: Int = this.size()) -> slice: List<E>
+
+        /**
+         * Return the number of elements in the list.
          *
          * @example
          * pipeline example {
          *     val size = [1, 2, 3].size(); // 3
          * }
          */
         @Pure
-        @PythonCall("len($this)")
+        @PythonMacro("len($this)")
         fun size() -> size: Int
     }
     ```
 
+## `#!sds fun` join {#safeds.lang.List.join data-toc-label='join'}
+
+Join the elements of the list into a string using the separator.
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `separator` | [`String`][safeds.lang.String] | - | `#!sds ", "` |
+
+**Results:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `string` | [`String`][safeds.lang.String] | - |
+
+**Examples:**
+
+```sds hl_lines="2"
+pipeline example {
+    val string = [1, 2, 3].join(); // "1, 2, 3"
+}
+```
+```sds hl_lines="2"
+pipeline example {
+    val string = [1, 2, 3].join("-"); // "1-2-3"
+}
+```
+
+??? quote "Stub code in `coreClasses.sdsstub`"
+
+    ```sds linenums="115"
+    @Pure
+    @PythonMacro("$separator.join($this)")
+    fun join(separator: String = ", ") -> string: String
+    ```
+
 ## `#!sds fun` size {#safeds.lang.List.size data-toc-label='size'}
 
-Returns the number of elements in the list.
+Return the number of elements in the list.
 
 **Results:**
 
@@ -60,8 +129,41 @@ pipeline example {
 
 ??? quote "Stub code in `coreClasses.sdsstub`"
 
-    ```sds linenums="109"
+    ```sds linenums="142"
     @Pure
-    @PythonCall("len($this)")
+    @PythonMacro("len($this)")
     fun size() -> size: Int
     ```
+
+## `#!sds fun` slice {#safeds.lang.List.slice data-toc-label='slice'}
+
+Return the slice of the list starting at the start index up to but excluding the end index.
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+|------|------|-------------|---------|
+| `start` | [`Int`][safeds.lang.Int] | The start index (inclusive). | `#!sds 0` |
+| `end` | [`Int`][safeds.lang.Int] | The end index (exclusive). Negative indices count from the end of the list. | `#!sds this.size()` |
+
+**Results:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `slice` | [`List<E>`][safeds.lang.List] | - |
+
+**Examples:**
+
+```sds hl_lines="2"
+pipeline example {
+    val slice = [1, 2, 3].slice(1, 3); // [2, 3]
+}
+```
+
+??? quote "Stub code in `coreClasses.sdsstub`"
+
+    ```sds linenums="130"
+    @Pure
+    @PythonMacro("$this[$start:$end]")
+    fun slice(start: Int = 0, end: Int = this.size()) -> slice: List<E>
+    ```