Skip to content

StringCell

Bases: ABC

Namespace for operations on strings.

This class cannot be instantiated directly. It can only be accessed using the str attribute of a cell.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.transform(lambda cell: cell.str.to_uppercase())
+---------+
| example |
| ---     |
| str     |
+=========+
| AB      |
| BC      |
| CD      |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
class StringCell(ABC):
    """
    Namespace for operations on strings.

    This class cannot be instantiated directly. It can only be accessed using the `str` attribute of a cell.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.transform(lambda cell: cell.str.to_uppercase())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    | AB      |
    | BC      |
    | CD      |
    +---------+
    """

    @abstractmethod
    def contains(self, substring: str) -> Cell[bool]:
        """
        Check if the string value in the cell contains the substring.

        Parameters
        ----------
        substring:
            The substring to search for.

        Returns
        -------
        contains:
            Whether the string value contains the substring.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.count_if(lambda cell: cell.str.contains("b"))
        2
        """

    @abstractmethod
    def ends_with(self, suffix: str) -> Cell[bool]:
        """
        Check if the string value in the cell ends with the suffix.

        Parameters
        ----------
        suffix:
            The suffix to search for.

        Returns
        -------
        ends_with:
            Whether the string value ends with the suffix.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.count_if(lambda cell: cell.str.ends_with("c"))
        1
        """

    @abstractmethod
    def index_of(self, substring: str) -> Cell[int | None]:
        """
        Get the index of the first occurrence of the substring in the string value in the cell.

        Parameters
        ----------
        substring:
            The substring to search for.

        Returns
        -------
        index_of:
            The index of the first occurrence of the substring. If the substring is not found, None is returned.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.transform(lambda cell: cell.str.index_of("b"))
        +---------+
        | example |
        |     --- |
        |     u32 |
        +=========+
        |       1 |
        |       0 |
        |    null |
        +---------+
        """

    @abstractmethod
    def length(self, *, optimize_for_ascii: bool = False) -> Cell[int]:
        """
        Get the number of characters of the string value in the cell.

        Parameters
        ----------
        optimize_for_ascii:
            Greatly speed up this operation if the string is ASCII-only. If the string contains non-ASCII characters,
            this option will return incorrect results, though.

        Returns
        -------
        length:
            The length of the string value.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["", "a", "abc"])
        >>> column.transform(lambda cell: cell.str.length())
        +---------+
        | example |
        |     --- |
        |     u32 |
        +=========+
        |       0 |
        |       1 |
        |       3 |
        +---------+
        """

    @abstractmethod
    def replace(self, old: str, new: str) -> Cell[str]:
        """
        Replace occurrences of the old substring with the new substring in the string value in the cell.

        Parameters
        ----------
        old:
            The substring to replace.
        new:
            The substring to replace with.

        Returns
        -------
        replaced_string:
            The string value with the occurrences replaced.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.transform(lambda cell: cell.str.replace("b", "z"))
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        | az      |
        | zc      |
        | cd      |
        +---------+
        """

    @abstractmethod
    def starts_with(self, prefix: str) -> Cell[bool]:
        """
        Check if the string value in the cell starts with the prefix.

        Parameters
        ----------
        prefix:
            The prefix to search for.

        Returns
        -------
        starts_with:
            Whether the string value starts with the prefix.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.count_if(lambda cell: cell.str.starts_with("a"))
        1
        """

    @abstractmethod
    def substring(self, start: int = 0, length: int | None = None) -> Cell[str]:
        """
        Get a substring of the string value in the cell.

        Parameters
        ----------
        start:
            The start index of the substring.
        length:
            The length of the substring. If None, the slice contains all rows starting from `start`. Must greater than
            or equal to 0.

        Returns
        -------
        substring:
            The substring of the string value.

        Raises
        ------
        OutOfBoundsError
            If length is less than 0.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["abc", "def", "ghi"])
        >>> column.transform(lambda cell: cell.str.substring(1, 2))
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        | bc      |
        | ef      |
        | hi      |
        +---------+
        """

    @abstractmethod
    def to_date(self) -> Cell[datetime.date | None]:
        """
        Convert the string value in the cell to a date. Requires the string to be in the ISO 8601 format.

        Returns
        -------
        date:
            The date value. If the string cannot be converted to a date, None is returned.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["2021-01-01", "2021-02-01", "abc"])
        >>> column.transform(lambda cell: cell.str.to_date())
        +------------+
        | example    |
        | ---        |
        | date       |
        +============+
        | 2021-01-01 |
        | 2021-02-01 |
        | null       |
        +------------+
        """

    @abstractmethod
    def to_datetime(self) -> Cell[datetime.datetime | None]:
        """
        Convert the string value in the cell to a datetime. Requires the string to be in the ISO 8601 format.

        Returns
        -------
        datetime:
            The datetime value. If the string cannot be converted to a datetime, None is returned.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["2021-01-01T00:00:00z", "2021-02-01T00:00:00z", "abc"])
        >>> column.transform(lambda cell: cell.str.to_datetime())
        +-------------------------+
        | example                 |
        | ---                     |
        | datetime[μs, UTC]       |
        +=========================+
        | 2021-01-01 00:00:00 UTC |
        | 2021-02-01 00:00:00 UTC |
        | null                    |
        +-------------------------+
        """

    @abstractmethod
    def to_float(self) -> Cell[float | None]:
        """
        Convert the string value in the cell to a float.

        Returns
        -------
        float:
            The float value. If the string cannot be converted to a float, None is returned.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["1", "3.4", "5.6", "abc"])
        >>> column.transform(lambda cell: cell.str.to_float())
        +---------+
        | example |
        |     --- |
        |     f64 |
        +=========+
        | 1.00000 |
        | 3.40000 |
        | 5.60000 |
        |    null |
        +---------+
        """

    @abstractmethod
    def to_int(self, *, base: int = 10) -> Cell[int | None]:
        """
        Convert the string value in the cell to an integer.

        Parameters
        ----------
        base:
            The base of the integer.

        Returns
        -------
        int:
            The integer value. If the string cannot be converted to an integer, None is returned.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column1 = Column("example", ["1", "2", "3", "abc"])
        >>> column1.transform(lambda cell: cell.str.to_int())
        +---------+
        | example |
        |     --- |
        |     i64 |
        +=========+
        |       1 |
        |       2 |
        |       3 |
        |    null |
        +---------+

        >>> column2 = Column("example", ["1", "10", "11", "abc"])
        >>> column2.transform(lambda cell: cell.str.to_int(base=2))
        +---------+
        | example |
        |     --- |
        |     i64 |
        +=========+
        |       1 |
        |       2 |
        |       3 |
        |    null |
        +---------+
        """

    @abstractmethod
    def to_lowercase(self) -> Cell[str]:
        """
        Convert the string value in the cell to lowercase.

        Returns
        -------
        lowercase:
            The string value in lowercase.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["AB", "BC", "CD"])
        >>> column.transform(lambda cell: cell.str.to_lowercase())
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        | ab      |
        | bc      |
        | cd      |
        +---------+
        """

    @abstractmethod
    def to_uppercase(self) -> Cell[str]:
        """
        Convert the string value in the cell to uppercase.

        Returns
        -------
        uppercase:
            The string value in uppercase.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["ab", "bc", "cd"])
        >>> column.transform(lambda cell: cell.str.to_uppercase())
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        | AB      |
        | BC      |
        | CD      |
        +---------+
        """

    @abstractmethod
    def trim(self) -> Cell[str]:
        """
        Remove whitespace from the start and end of the string value in the cell.

        Returns
        -------
        trimmed:
            The string value without whitespace at the start and end.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["", " abc", "abc ", " abc "])
        >>> column.transform(lambda cell: cell.str.trim())
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        |         |
        | abc     |
        | abc     |
        | abc     |
        +---------+
        """

    @abstractmethod
    def trim_end(self) -> Cell[str]:
        """
        Remove whitespace from the end of the string value in the cell.

        Returns
        -------
        trimmed:
            The string value without whitespace at the end.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["", " abc", "abc ", " abc "])
        >>> column.transform(lambda cell: cell.str.trim_end())
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        |         |
        |  abc    |
        | abc     |
        |  abc    |
        +---------+
        """

    @abstractmethod
    def trim_start(self) -> Cell[str]:
        """
        Remove whitespace from the start of the string value in the cell.

        Returns
        -------
        trimmed:
            The string value without whitespace at the start.

        Examples
        --------
        >>> from safeds.data.tabular.containers import Column
        >>> column = Column("example", ["", " abc", "abc ", " abc "])
        >>> column.transform(lambda cell: cell.str.trim_start())
        +---------+
        | example |
        | ---     |
        | str     |
        +=========+
        |         |
        | abc     |
        | abc     |
        | abc     |
        +---------+
        """

    # ------------------------------------------------------------------------------------------------------------------
    # Internal
    # ------------------------------------------------------------------------------------------------------------------

    @abstractmethod
    def _equals(self, other: object) -> bool:
        """
        Check if this cell is equal to another object.

        This method is needed because the `__eq__` method is used for element-wise comparisons.
        """

contains

Check if the string value in the cell contains the substring.

Parameters:

Name Type Description Default
substring str

The substring to search for.

 required

Returns:

Name Type Description
contains Cell[bool]

Whether the string value contains the substring.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.count_if(lambda cell: cell.str.contains("b"))
2
Source code in src/safeds/data/tabular/containers/_string_cell.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
@abstractmethod
def contains(self, substring: str) -> Cell[bool]:
    """
    Check if the string value in the cell contains the substring.

    Parameters
    ----------
    substring:
        The substring to search for.

    Returns
    -------
    contains:
        Whether the string value contains the substring.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.count_if(lambda cell: cell.str.contains("b"))
    2
    """

ends_with

Check if the string value in the cell ends with the suffix.

Parameters:

Name Type Description Default
suffix str

The suffix to search for.

 required

Returns:

Name Type Description
ends_with Cell[bool]

Whether the string value ends with the suffix.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.count_if(lambda cell: cell.str.ends_with("c"))
1
Source code in src/safeds/data/tabular/containers/_string_cell.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
@abstractmethod
def ends_with(self, suffix: str) -> Cell[bool]:
    """
    Check if the string value in the cell ends with the suffix.

    Parameters
    ----------
    suffix:
        The suffix to search for.

    Returns
    -------
    ends_with:
        Whether the string value ends with the suffix.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.count_if(lambda cell: cell.str.ends_with("c"))
    1
    """

index_of

Get the index of the first occurrence of the substring in the string value in the cell.

Parameters:

Name Type Description Default
substring str

The substring to search for.

 required

Returns:

Name Type Description
index_of Cell[int | None]

The index of the first occurrence of the substring. If the substring is not found, None is returned.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.transform(lambda cell: cell.str.index_of("b"))
+---------+
| example |
|     --- |
|     u32 |
+=========+
|       1 |
|       0 |
|    null |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
@abstractmethod
def index_of(self, substring: str) -> Cell[int | None]:
    """
    Get the index of the first occurrence of the substring in the string value in the cell.

    Parameters
    ----------
    substring:
        The substring to search for.

    Returns
    -------
    index_of:
        The index of the first occurrence of the substring. If the substring is not found, None is returned.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.transform(lambda cell: cell.str.index_of("b"))
    +---------+
    | example |
    |     --- |
    |     u32 |
    +=========+
    |       1 |
    |       0 |
    |    null |
    +---------+
    """

length

Get the number of characters of the string value in the cell.

Parameters:

Name Type Description Default
optimize_for_ascii bool

Greatly speed up this operation if the string is ASCII-only. If the string contains non-ASCII characters, this option will return incorrect results, though.

 False

Returns:

Name Type Description
length Cell[int]

The length of the string value.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["", "a", "abc"])
>>> column.transform(lambda cell: cell.str.length())
+---------+
| example |
|     --- |
|     u32 |
+=========+
|       0 |
|       1 |
|       3 |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@abstractmethod
def length(self, *, optimize_for_ascii: bool = False) -> Cell[int]:
    """
    Get the number of characters of the string value in the cell.

    Parameters
    ----------
    optimize_for_ascii:
        Greatly speed up this operation if the string is ASCII-only. If the string contains non-ASCII characters,
        this option will return incorrect results, though.

    Returns
    -------
    length:
        The length of the string value.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["", "a", "abc"])
    >>> column.transform(lambda cell: cell.str.length())
    +---------+
    | example |
    |     --- |
    |     u32 |
    +=========+
    |       0 |
    |       1 |
    |       3 |
    +---------+
    """

replace

Replace occurrences of the old substring with the new substring in the string value in the cell.

Parameters:

Name Type Description Default
old str

The substring to replace.

 required
new str

The substring to replace with.

 required

Returns:

Name Type Description
replaced_string Cell[str]

The string value with the occurrences replaced.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.transform(lambda cell: cell.str.replace("b", "z"))
+---------+
| example |
| ---     |
| str     |
+=========+
| az      |
| zc      |
| cd      |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
@abstractmethod
def replace(self, old: str, new: str) -> Cell[str]:
    """
    Replace occurrences of the old substring with the new substring in the string value in the cell.

    Parameters
    ----------
    old:
        The substring to replace.
    new:
        The substring to replace with.

    Returns
    -------
    replaced_string:
        The string value with the occurrences replaced.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.transform(lambda cell: cell.str.replace("b", "z"))
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    | az      |
    | zc      |
    | cd      |
    +---------+
    """

starts_with

Check if the string value in the cell starts with the prefix.

Parameters:

Name Type Description Default
prefix str

The prefix to search for.

 required

Returns:

Name Type Description
starts_with Cell[bool]

Whether the string value starts with the prefix.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.count_if(lambda cell: cell.str.starts_with("a"))
1
Source code in src/safeds/data/tabular/containers/_string_cell.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
@abstractmethod
def starts_with(self, prefix: str) -> Cell[bool]:
    """
    Check if the string value in the cell starts with the prefix.

    Parameters
    ----------
    prefix:
        The prefix to search for.

    Returns
    -------
    starts_with:
        Whether the string value starts with the prefix.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.count_if(lambda cell: cell.str.starts_with("a"))
    1
    """

substring

Get a substring of the string value in the cell.

Parameters:

Name Type Description Default
start int

The start index of the substring.

 0
length int | None

The length of the substring. If None, the slice contains all rows starting from start. Must greater than or equal to 0.

 None

Returns:

Name Type Description
substring Cell[str]

The substring of the string value.

Raises:

Type Description
OutOfBoundsError

If length is less than 0.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["abc", "def", "ghi"])
>>> column.transform(lambda cell: cell.str.substring(1, 2))
+---------+
| example |
| ---     |
| str     |
+=========+
| bc      |
| ef      |
| hi      |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
@abstractmethod
def substring(self, start: int = 0, length: int | None = None) -> Cell[str]:
    """
    Get a substring of the string value in the cell.

    Parameters
    ----------
    start:
        The start index of the substring.
    length:
        The length of the substring. If None, the slice contains all rows starting from `start`. Must greater than
        or equal to 0.

    Returns
    -------
    substring:
        The substring of the string value.

    Raises
    ------
    OutOfBoundsError
        If length is less than 0.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["abc", "def", "ghi"])
    >>> column.transform(lambda cell: cell.str.substring(1, 2))
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    | bc      |
    | ef      |
    | hi      |
    +---------+
    """

to_date

Convert the string value in the cell to a date. Requires the string to be in the ISO 8601 format.

Returns:

Name Type Description
date Cell[date | None]

The date value. If the string cannot be converted to a date, None is returned.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["2021-01-01", "2021-02-01", "abc"])
>>> column.transform(lambda cell: cell.str.to_date())
+------------+
| example    |
| ---        |
| date       |
+============+
| 2021-01-01 |
| 2021-02-01 |
| null       |
+------------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
@abstractmethod
def to_date(self) -> Cell[datetime.date | None]:
    """
    Convert the string value in the cell to a date. Requires the string to be in the ISO 8601 format.

    Returns
    -------
    date:
        The date value. If the string cannot be converted to a date, None is returned.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["2021-01-01", "2021-02-01", "abc"])
    >>> column.transform(lambda cell: cell.str.to_date())
    +------------+
    | example    |
    | ---        |
    | date       |
    +============+
    | 2021-01-01 |
    | 2021-02-01 |
    | null       |
    +------------+
    """

to_datetime

Convert the string value in the cell to a datetime. Requires the string to be in the ISO 8601 format.

Returns:

Name Type Description
datetime Cell[datetime | None]

The datetime value. If the string cannot be converted to a datetime, None is returned.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["2021-01-01T00:00:00z", "2021-02-01T00:00:00z", "abc"])
>>> column.transform(lambda cell: cell.str.to_datetime())
+-------------------------+
| example                 |
| ---                     |
| datetime[μs, UTC]       |
+=========================+
| 2021-01-01 00:00:00 UTC |
| 2021-02-01 00:00:00 UTC |
| null                    |
+-------------------------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
@abstractmethod
def to_datetime(self) -> Cell[datetime.datetime | None]:
    """
    Convert the string value in the cell to a datetime. Requires the string to be in the ISO 8601 format.

    Returns
    -------
    datetime:
        The datetime value. If the string cannot be converted to a datetime, None is returned.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["2021-01-01T00:00:00z", "2021-02-01T00:00:00z", "abc"])
    >>> column.transform(lambda cell: cell.str.to_datetime())
    +-------------------------+
    | example                 |
    | ---                     |
    | datetime[μs, UTC]       |
    +=========================+
    | 2021-01-01 00:00:00 UTC |
    | 2021-02-01 00:00:00 UTC |
    | null                    |
    +-------------------------+
    """

to_float

Convert the string value in the cell to a float.

Returns:

Name Type Description
float Cell[float | None]

The float value. If the string cannot be converted to a float, None is returned.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["1", "3.4", "5.6", "abc"])
>>> column.transform(lambda cell: cell.str.to_float())
+---------+
| example |
|     --- |
|     f64 |
+=========+
| 1.00000 |
| 3.40000 |
| 5.60000 |
|    null |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
@abstractmethod
def to_float(self) -> Cell[float | None]:
    """
    Convert the string value in the cell to a float.

    Returns
    -------
    float:
        The float value. If the string cannot be converted to a float, None is returned.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["1", "3.4", "5.6", "abc"])
    >>> column.transform(lambda cell: cell.str.to_float())
    +---------+
    | example |
    |     --- |
    |     f64 |
    +=========+
    | 1.00000 |
    | 3.40000 |
    | 5.60000 |
    |    null |
    +---------+
    """

to_int

Convert the string value in the cell to an integer.

Parameters:

Name Type Description Default
base int

The base of the integer.

 10

Returns:

Name Type Description
int Cell[int | None]

The integer value. If the string cannot be converted to an integer, None is returned.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column1 = Column("example", ["1", "2", "3", "abc"])
>>> column1.transform(lambda cell: cell.str.to_int())
+---------+
| example |
|     --- |
|     i64 |
+=========+
|       1 |
|       2 |
|       3 |
|    null |
+---------+

>>> column2 = Column("example", ["1", "10", "11", "abc"])
>>> column2.transform(lambda cell: cell.str.to_int(base=2))
+---------+
| example |
|     --- |
|     i64 |
+=========+
|       1 |
|       2 |
|       3 |
|    null |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
@abstractmethod
def to_int(self, *, base: int = 10) -> Cell[int | None]:
    """
    Convert the string value in the cell to an integer.

    Parameters
    ----------
    base:
        The base of the integer.

    Returns
    -------
    int:
        The integer value. If the string cannot be converted to an integer, None is returned.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column1 = Column("example", ["1", "2", "3", "abc"])
    >>> column1.transform(lambda cell: cell.str.to_int())
    +---------+
    | example |
    |     --- |
    |     i64 |
    +=========+
    |       1 |
    |       2 |
    |       3 |
    |    null |
    +---------+

    >>> column2 = Column("example", ["1", "10", "11", "abc"])
    >>> column2.transform(lambda cell: cell.str.to_int(base=2))
    +---------+
    | example |
    |     --- |
    |     i64 |
    +=========+
    |       1 |
    |       2 |
    |       3 |
    |    null |
    +---------+
    """

to_lowercase

Convert the string value in the cell to lowercase.

Returns:

Name Type Description
lowercase Cell[str]

The string value in lowercase.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["AB", "BC", "CD"])
>>> column.transform(lambda cell: cell.str.to_lowercase())
+---------+
| example |
| ---     |
| str     |
+=========+
| ab      |
| bc      |
| cd      |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
@abstractmethod
def to_lowercase(self) -> Cell[str]:
    """
    Convert the string value in the cell to lowercase.

    Returns
    -------
    lowercase:
        The string value in lowercase.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["AB", "BC", "CD"])
    >>> column.transform(lambda cell: cell.str.to_lowercase())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    | ab      |
    | bc      |
    | cd      |
    +---------+
    """

to_uppercase

Convert the string value in the cell to uppercase.

Returns:

Name Type Description
uppercase Cell[str]

The string value in uppercase.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["ab", "bc", "cd"])
>>> column.transform(lambda cell: cell.str.to_uppercase())
+---------+
| example |
| ---     |
| str     |
+=========+
| AB      |
| BC      |
| CD      |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
@abstractmethod
def to_uppercase(self) -> Cell[str]:
    """
    Convert the string value in the cell to uppercase.

    Returns
    -------
    uppercase:
        The string value in uppercase.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["ab", "bc", "cd"])
    >>> column.transform(lambda cell: cell.str.to_uppercase())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    | AB      |
    | BC      |
    | CD      |
    +---------+
    """

trim

Remove whitespace from the start and end of the string value in the cell.

Returns:

Name Type Description
trimmed Cell[str]

The string value without whitespace at the start and end.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["", " abc", "abc ", " abc "])
>>> column.transform(lambda cell: cell.str.trim())
+---------+
| example |
| ---     |
| str     |
+=========+
|         |
| abc     |
| abc     |
| abc     |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
@abstractmethod
def trim(self) -> Cell[str]:
    """
    Remove whitespace from the start and end of the string value in the cell.

    Returns
    -------
    trimmed:
        The string value without whitespace at the start and end.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["", " abc", "abc ", " abc "])
    >>> column.transform(lambda cell: cell.str.trim())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    |         |
    | abc     |
    | abc     |
    | abc     |
    +---------+
    """

trim_end

Remove whitespace from the end of the string value in the cell.

Returns:

Name Type Description
trimmed Cell[str]

The string value without whitespace at the end.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["", " abc", "abc ", " abc "])
>>> column.transform(lambda cell: cell.str.trim_end())
+---------+
| example |
| ---     |
| str     |
+=========+
|         |
|  abc    |
| abc     |
|  abc    |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
@abstractmethod
def trim_end(self) -> Cell[str]:
    """
    Remove whitespace from the end of the string value in the cell.

    Returns
    -------
    trimmed:
        The string value without whitespace at the end.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["", " abc", "abc ", " abc "])
    >>> column.transform(lambda cell: cell.str.trim_end())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    |         |
    |  abc    |
    | abc     |
    |  abc    |
    +---------+
    """

trim_start

Remove whitespace from the start of the string value in the cell.

Returns:

Name Type Description
trimmed Cell[str]

The string value without whitespace at the start.

Examples:

>>> from safeds.data.tabular.containers import Column
>>> column = Column("example", ["", " abc", "abc ", " abc "])
>>> column.transform(lambda cell: cell.str.trim_start())
+---------+
| example |
| ---     |
| str     |
+=========+
|         |
| abc     |
| abc     |
| abc     |
+---------+
Source code in src/safeds/data/tabular/containers/_string_cell.py 
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
@abstractmethod
def trim_start(self) -> Cell[str]:
    """
    Remove whitespace from the start of the string value in the cell.

    Returns
    -------
    trimmed:
        The string value without whitespace at the start.

    Examples
    --------
    >>> from safeds.data.tabular.containers import Column
    >>> column = Column("example", ["", " abc", "abc ", " abc "])
    >>> column.transform(lambda cell: cell.str.trim_start())
    +---------+
    | example |
    | ---     |
    | str     |
    +=========+
    |         |
    | abc     |
    | abc     |
    | abc     |
    +---------+
    """