PyLegendString

String expression type in the PyLegend expression language.

PyLegendString represents a string-valued column or computed expression within a PyLegend query. It provides a rich set of string operations: case conversion, trimming, searching, slicing, padding, concatenation (+), lexicographic comparisons (<, <=, >, >=), regex matching, parsing to other types, and more.

Instances are never constructed directly. They are produced by accessing a string column on a TDS frame — for example, frame["Ship Name"] — or by calling to_string() on another expression.

PyLegendString also inherits general-purpose methods from PyLegendPrimitive, including equality / inequality tests, null checks, and in_list.

__add__

PyLegendString.__add__(other)[source]

String concatenation (+).

Parameters:

other (Union[str, PyLegendString]) – The string to append.

Returns:

The concatenated expression.

Return type:

PyLegendString

Raises:

TypeError – If other is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["greeting"] = frame["Ship Name"] + " - OK"
frame.head(3).to_pandas()

__eq__

PyLegendPrimitive.__eq__(other)[source]

Test element-wise equality (==).

Compare this expression against another primitive value or expression. Returns a boolean expression that is True where the values are equal.

Parameters:

other (Union[int, float, bool, str, date, datetime, Decimal, PyLegendPrimitive]) – The value or expression to compare against.

Returns:

A boolean expression representing the equality test.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a supported primitive type.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Filter rows where Ship Name equals a literal
frame[frame["Ship Name"] == "Around the Horn"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10355 1996-11-15 1996-12-13 1996-11-20 Around the Horn
1 10383 1996-12-16 1997-01-13 1996-12-18 Around the Horn
2 10453 1997-02-21 1997-03-21 1997-02-26 Around the Horn

__ge__

PyLegendString.__ge__(other)[source]

Lexicographic greater than or equal (>=).

Parameters:

other (Union[str, PyLegendString]) – The right-hand operand.

Returns:

True where self >= other lexicographically.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"] >= "V"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier
1 10251 1996-07-08 1996-08-05 1996-07-15 Victuailles en stock
2 10256 1996-07-15 1996-08-12 1996-07-17 Wellington Importadora

__gt__

PyLegendString.__gt__(other)[source]

Lexicographic greater than (>).

Parameters:

other (Union[str, PyLegendString]) – The right-hand operand.

Returns:

True where self > other lexicographically.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"] > "V"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier
1 10251 1996-07-08 1996-08-05 1996-07-15 Victuailles en stock
2 10256 1996-07-15 1996-08-12 1996-07-17 Wellington Importadora

__le__

PyLegendString.__le__(other)[source]

Lexicographic less than or equal (<=).

Parameters:

other (Union[str, PyLegendString]) – The right-hand operand.

Returns:

True where self <= other lexicographically.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"] <= "C"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10265 1996-07-25 1996-08-22 1996-08-12 Blondel père et fils
1 10278 1996-08-12 1996-09-09 1996-08-16 Berglunds snabbköp
2 10280 1996-08-14 1996-09-11 1996-09-12 Berglunds snabbköp

__lt__

PyLegendString.__lt__(other)[source]

Lexicographic less than (<).

Parameters:

other (Union[str, PyLegendString]) – The right-hand operand.

Returns:

True where self < other lexicographically.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"] < "C"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10265 1996-07-25 1996-08-22 1996-08-12 Blondel père et fils
1 10278 1996-08-12 1996-09-09 1996-08-16 Berglunds snabbköp
2 10280 1996-08-14 1996-09-11 1996-09-12 Berglunds snabbköp

__ne__

PyLegendPrimitive.__ne__(other)[source]

Test element-wise inequality (!=).

Compare this expression against another primitive value or expression. Returns a boolean expression that is True where the values differ.

Parameters:

other (Union[int, float, bool, str, date, datetime, Decimal, PyLegendPrimitive]) – The value or expression to compare against.

Returns:

A boolean expression representing the inequality test.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a supported primitive type.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Filter rows where Ship Name is not a specific value
frame[frame["Ship Name"] != "Ship1"].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes

__radd__

PyLegendString.__radd__(other)[source]

Reflected string concatenation (str + expr).

Called when a Python str is on the left side of +.

Parameters:

other (Union[str, PyLegendString]) – The string to prepend.

Returns:

The concatenated expression.

Return type:

PyLegendString

Raises:

TypeError – If other is not a str or PyLegendString.

ascii

PyLegendString.ascii()[source]

ASCII code of the first character.

Returns:

The ASCII code expression.

Return type:

PyLegendInteger

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["first_ascii"] = frame["Ship Name"].ascii()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name first_ascii
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 86
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 84
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 72

coalesce

PyLegendString.coalesce(*other)[source]

Return the first non-null value among self and other.

Translates to SQL COALESCE(self, ...).

Parameters:

*other (Union[str, PyLegendString, None]) – Fallback values, checked in order.

Returns:

The first non-null expression.

Return type:

PyLegendString

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_or_default"] = frame["Ship Name"].coalesce("N/A")
frame.head(3).to_pandas()

contains

PyLegendString.contains(other)[source]

Test whether the string contains other.

Parameters:

other (str) – The substring to search for.

Returns:

True where the string contains other.

Return type:

PyLegendBoolean

Raises:

TypeError – If other is not a str.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"].contains("the")].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10355 1996-11-15 1996-12-13 1996-11-20 Around the Horn
1 10383 1996-12-16 1997-01-13 1996-12-18 Around the Horn
2 10453 1997-02-21 1997-03-21 1997-02-26 Around the Horn

endswith

PyLegendString.endswith(suffix)[source]

Test whether the string ends with suffix.

Parameters:

suffix (str) – The suffix to check.

Returns:

True where the string ends with suffix.

Return type:

PyLegendBoolean

Raises:

TypeError – If suffix is not a str.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"].endswith("Horn")].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10355 1996-11-15 1996-12-13 1996-11-20 Around the Horn
1 10383 1996-12-16 1997-01-13 1996-12-18 Around the Horn
2 10453 1997-02-21 1997-03-21 1997-02-26 Around the Horn

equals

PyLegendString.equals(other)[source]

Test string equality.

Alias for ==. Equivalent to __eq__().

Parameters:

other (Union[str, PyLegendString]) – The value to compare against.

Returns:

True where the strings are equal.

Return type:

PyLegendBoolean

See also

__eq__

Operator form (==).

full_match

PyLegendString.full_match(pattern)[source]

Test whether the entire string matches a regex pattern.

Parameters:

pattern (Union[str, PyLegendString]) – The regular expression pattern.

Returns:

True where the full string matches.

Return type:

PyLegendBoolean

Raises:

TypeError – If pattern is not a str or PyLegendString.

See also

match

Partial (substring) match.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"].full_match("Around%")].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10355 1996-11-15 1996-12-13 1996-11-20 Around the Horn
1 10383 1996-12-16 1997-01-13 1996-12-18 Around the Horn
2 10453 1997-02-21 1997-03-21 1997-02-26 Around the Horn

in_list

PyLegendPrimitive.in_list(lst)[source]

Test whether the value is contained in a list of values.

Returns a boolean expression equivalent to SQL IN (...).

Parameters:

lst (List[Union[int, float, bool, str, date, datetime, Decimal, PyLegendPrimitive]]) – A non-empty list of literal values or expressions to check membership against.

Returns:

True where the value matches any element in lst.

Return type:

PyLegendBoolean

Raises:

  • ValueError – If lst is not a list or is empty.

  • TypeError – If any element in lst is not a supported primitive type.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Keep rows where Ship Name is one of several values
frame[
    frame["Ship Name"].in_list(["Hanari Carnes", "Victuailles en stock", "Suprêmes délices"])
].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes
1 10251 1996-07-08 1996-08-05 1996-07-15 Victuailles en stock
2 10252 1996-07-09 1996-08-06 1996-07-11 Suprêmes délices

index

PyLegendString.index(other)[source]

Find the position of a substring.

Alias for index_of().

Parameters:

other (Union[str, PyLegendString]) – The substring to locate.

Returns:

The position expression.

Return type:

PyLegendInteger

See also

index_of

Canonical method.

index_of

PyLegendString.index_of(other)[source]

Find the position of a substring.

Returns the zero-based index of the first occurrence of other, or -1 if not found.

Parameters:

other (Union[str, PyLegendString]) – The substring to locate.

Returns:

The position expression.

Return type:

PyLegendInteger

Raises:

TypeError – If other is not a str or PyLegendString.

See also

index

Alias for index_of.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["pos"] = frame["Ship Name"].index_of("the")
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name pos
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 0
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 0
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 0

is_empty

PyLegendPrimitive.is_empty()[source]

Test whether the value is null / empty.

Returns a boolean expression that is True where the underlying column value is NULL.

Returns:

True where the value is null.

Return type:

PyLegendBoolean

See also

is_not_empty

The inverse test.

is_null

Alias for is_empty.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Keep only rows where Ship Name is null
frame[frame["Shipped Date"].is_empty()].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 11008 1998-04-08 1998-05-06 NaT Ernst Handel
1 11019 1998-04-13 1998-05-11 NaT Rancho grande
2 11039 1998-04-21 1998-05-19 NaT LINO-Delicateses

is_not_empty

PyLegendPrimitive.is_not_empty()[source]

Test whether the value is not null / not empty.

Returns a boolean expression that is True where the underlying column value is not NULL.

Returns:

True where the value is not null.

Return type:

PyLegendBoolean

See also

is_empty

The inverse test.

is_not_null

Alias for is_not_empty.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Keep only rows where Ship Name is present
frame[frame["Ship Name"].is_not_empty()].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes

is_not_null

PyLegendPrimitive.is_not_null()[source]

Test whether the value is not null.

Alias for is_not_empty().

Returns:

True where the value is not null.

Return type:

PyLegendBoolean

See also

is_not_empty

Canonical not-null-check method.

is_null

The inverse test.

is_null

PyLegendPrimitive.is_null()[source]

Test whether the value is null.

Alias for is_empty().

Returns:

True where the value is null.

Return type:

PyLegendBoolean

See also

is_empty

Canonical null-check method.

is_not_null

The inverse test.

left

PyLegendString.left(count)[source]

Return the leftmost count characters.

Parameters:

count (Union[int, PyLegendInteger]) – Number of characters to take from the left.

Returns:

The left-substring expression.

Return type:

PyLegendString

Raises:

TypeError – If count is not an int or PyLegendInteger.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["first_5"] = frame["Ship Name"].left(5)
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name first_5
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanar

len

PyLegendString.len()[source]

Length of the string.

Returns:

The number of characters.

Return type:

PyLegendInteger

See also

length

Alias for len.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_len"] = frame["Ship Name"].len()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_len
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 25
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 18
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 13

length

PyLegendString.length()[source]

Length of the string.

Alias for len().

Returns:

The number of characters.

Return type:

PyLegendInteger

See also

len

Canonical length method.

ljust

PyLegendString.ljust(length, fill_char=' ')[source]

Left-justify (right-pad) the string to length.

Parameters:

  • length (Union[int, PyLegendInteger]) – The target total length.

  • fill_char (Union[str, PyLegendString]) – The padding character.

Returns:

The padded expression.

Return type:

PyLegendString

Raises:

TypeError – If length is not an int or PyLegendInteger.

See also

rjust

Right-justify (left-pad).

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_lj"] = frame["Ship Name"].ljust(30, "*")
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_lj
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools Chevalier*****
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms Spezialitäten************
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari Carnes*****************

lower

PyLegendString.lower()[source]

Convert to lower case.

Returns:

The lower-cased expression.

Return type:

PyLegendString

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_lower"] = frame["Ship Name"].lower()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_lower
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier vins et alcools chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten toms spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes hanari carnes

lstrip

PyLegendString.lstrip()[source]

Strip leading whitespace.

Returns:

The left-trimmed expression.

Return type:

PyLegendString

See also

rstrip

Strip trailing whitespace.

strip

Strip both sides.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_ltrim"] = frame["Ship Name"].lstrip()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_ltrim
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari Carnes

match

PyLegendString.match(pattern)[source]

Test whether any part of the string matches a regex pattern.

Parameters:

pattern (Union[str, PyLegendString]) – The regular expression pattern.

Returns:

True where a substring matches.

Return type:

PyLegendBoolean

Raises:

TypeError – If pattern is not a str or PyLegendString.

See also

full_match

Full-string match.

parse_boolean

PyLegendString.parse_boolean()[source]

Parse the string as a boolean.

Returns:

The parsed boolean expression.

Return type:

PyLegendBoolean

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["is_long"] = (frame["Ship Name"].len() > 20).to_string()
frame["parsed"] = frame["is_long"].parse_boolean()
frame[["Ship Name", "is_long", "parsed"]].head(3).to_pandas()
Ship Name is_long parsed
0 Vins et alcools Chevalier TRUE True
1 Toms Spezialitäten FALSE False
2 Hanari Carnes FALSE False

parse_datetime

PyLegendString.parse_datetime()[source]

Parse the string as a datetime.

Returns:

The parsed datetime expression.

Return type:

PyLegendDateTime

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["date_str"] = frame["Shipped Date"].to_string() + " 00:00:00"
frame["parsed_dt"] = frame["date_str"].parse_datetime()
frame[["date_str", "parsed_dt"]].head(3).to_pandas()
date_str parsed_dt
0 1996-07-16 00:00:00 1996-07-16 00:00:00+00:00
1 1996-07-10 00:00:00 1996-07-10 00:00:00+00:00
2 1996-07-12 00:00:00 1996-07-12 00:00:00+00:00

parse_decimal

PyLegendString.parse_decimal(precision=None, scale=None)[source]

Parse the string as a decimal.

Optionally specify precision and scale for a PyLegendNumeric result; both must be provided together or neither.

Parameters:

  • precision (Optional[int]) – Total number of digits.

  • scale (Optional[int]) – Number of digits after the decimal point.

Returns:

The parsed decimal expression (or PyLegendNumeric when precision and scale are given).

Return type:

PyLegendDecimal

Raises:

TypeError – If only one of precision / scale is provided.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["id_dec"] = frame["Order Id"].to_string().parse_decimal()
frame.head(3).to_pandas()

parse_float

PyLegendString.parse_float()[source]

Parse the string as a float.

Returns:

The parsed float expression.

Return type:

PyLegendFloat

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["id_float"] = frame["Order Id"].to_string().parse_float()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name id_float
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 10248.0
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 10249.0
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 10250.0

parse_int

PyLegendString.parse_int()[source]

Parse the string as an integer.

Returns:

The parsed integer expression.

Return type:

PyLegendInteger

See also

parse_integer

Alias for parse_int.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["id_parsed"] = frame["Order Id"].to_string().parse_int()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name id_parsed
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 10248
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 10249
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 10250

parse_integer

PyLegendString.parse_integer()[source]

Parse the string as an integer.

Alias for parse_int().

Returns:

The parsed integer expression.

Return type:

PyLegendInteger

See also

parse_int

Canonical method.

repeat_string

PyLegendString.repeat_string(times)[source]

Repeat the string times times.

Parameters:

times (Union[int, PyLegendInteger]) – The number of repetitions.

Returns:

The repeated expression.

Return type:

PyLegendString

Raises:

TypeError – If times is not an int or PyLegendInteger.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["repeated"] = frame["Ship Name"].left(3).repeat_string(2)
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name repeated
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier VinVin
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten TomTom
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes HanHan

replace

PyLegendString.replace(to_replace, replacement)[source]

Replace occurrences of a substring.

Parameters:

  • to_replace (Union[str, PyLegendString]) – The substring to find.

  • replacement (Union[str, PyLegendString]) – The replacement string.

Returns:

The expression with replacements applied.

Return type:

PyLegendString

Raises:

TypeError – If to_replace or replacement is not a str or PyLegendString.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_replaced"] = frame["Ship Name"].replace("the", "THE")
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_replaced
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari Carnes

reverse

PyLegendString.reverse()[source]

Reverse the string.

Returns:

The reversed expression.

Return type:

PyLegendString

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_rev"] = frame["Ship Name"].reverse()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_rev
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier reilavehC sloocla te sniV
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten netätilaizepS smoT
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes senraC iranaH

rjust

PyLegendString.rjust(length, fill_char=' ')[source]

Right-justify (left-pad) the string to length.

Parameters:

  • length (Union[int, PyLegendInteger]) – The target total length.

  • fill_char (Union[str, PyLegendString]) – The padding character.

Returns:

The padded expression.

Return type:

PyLegendString

Raises:

TypeError – If length is not an int or PyLegendInteger.

See also

ljust

Left-justify (right-pad).

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_rj"] = frame["Ship Name"].rjust(30, "*")
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_rj
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier *****Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten ************Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes *****************Hanari Carnes

rstrip

PyLegendString.rstrip()[source]

Strip trailing whitespace.

Returns:

The right-trimmed expression.

Return type:

PyLegendString

See also

lstrip

Strip leading whitespace.

strip

Strip both sides.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_rtrim"] = frame["Ship Name"].rstrip()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_rtrim
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari Carnes

split_part

PyLegendString.split_part(sep, part)[source]

Split the string by sep and return the part-th element.

Parameters:

  • sep (Union[str, PyLegendString]) – The delimiter.

  • part (Union[int, PyLegendInteger]) – The one-based index of the part to return.

Returns:

The extracted part.

Return type:

PyLegendString | None

Raises:

TypeError – If sep or part is not a supported type.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["first_word"] = frame["Ship Name"].split_part(" ", 1)
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name first_word
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari

startswith

PyLegendString.startswith(prefix)[source]

Test whether the string starts with prefix.

Parameters:

prefix (str) – The prefix to check.

Returns:

True where the string starts with prefix.

Return type:

PyLegendBoolean

Raises:

TypeError – If prefix is not a str.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame[frame["Ship Name"].startswith("Around")].head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name
0 10355 1996-11-15 1996-12-13 1996-11-20 Around the Horn
1 10383 1996-12-16 1997-01-13 1996-12-18 Around the Horn
2 10453 1997-02-21 1997-03-21 1997-02-26 Around the Horn

string_contains

PyLegendString.string_contains(other)[source]

Test whether the string contains other.

Alias for contains().

Parameters:

other (str) – The substring to search for.

Returns:

True where the string contains other.

Return type:

PyLegendBoolean

See also

contains

Canonical contains method.

strip

PyLegendString.strip()[source]

Strip leading and trailing whitespace.

Returns:

The trimmed expression.

Return type:

PyLegendString

See also

lstrip

Strip leading whitespace only.

rstrip

Strip trailing whitespace only.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_trim"] = frame["Ship Name"].strip()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_trim
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari Carnes

substring

PyLegendString.substring(start, end=None)[source]

Extract a substring.

Parameters:

  • start (Union[int, PyLegendInteger]) – The starting position (zero-based).

  • end (Union[int, PyLegendInteger, None]) – The ending position (exclusive). If omitted, takes everything from start to the end.

Returns:

The substring expression.

Return type:

PyLegendString

Raises:

TypeError – If start or end is not an int or PyLegendInteger.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["sub"] = frame["Ship Name"].substring(0, 5)
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name sub
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins e
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms S
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari

to_lower_first_character

PyLegendString.to_lower_first_character()[source]

Convert only the first character to lower case.

Returns:

The expression with its first character lowered.

Return type:

PyLegendString

See also

to_upper_first_character

The inverse operation.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_lf"] = frame["Ship Name"].to_lower_first_character()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_lf
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier vins et alcools Chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten toms Spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes hanari Carnes

to_string

PyLegendPrimitive.to_string()[source]

Convert the value to its string representation.

Returns a string expression produced by applying the database’s CAST(... AS TEXT) (SQL) or ->toString() (Pure).

Returns:

The stringified expression.

Return type:

PyLegendString

See also

toString

Alias for to_string.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

# Convert an integer column to a string
frame["order_str"] = frame["Order Id"].to_string()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name order_str
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier 10248
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten 10249
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes 10250

toString

PyLegendPrimitive.toString()[source]

Convert the value to its string representation.

Alias for to_string().

Returns:

The stringified expression.

Return type:

PyLegendString

See also

to_string

Canonical string-conversion method.

to_upper_first_character

PyLegendString.to_upper_first_character()[source]

Convert only the first character to upper case.

Returns:

The expression with its first character uppercased.

Return type:

PyLegendString

See also

to_lower_first_character

The inverse operation.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_uf"] = frame["Ship Name"].lower().to_upper_first_character()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_uf
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier Vins et alcools chevalier
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten Toms spezialitäten
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes Hanari carnes

upper

PyLegendString.upper()[source]

Convert to upper case.

Returns:

The upper-cased expression.

Return type:

PyLegendString

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.pandas_api.northwind_orders_frame()

frame["name_upper"] = frame["Ship Name"].upper()
frame.head(3).to_pandas()
Order Id Order Date Required Date Shipped Date Ship Name name_upper
0 10248 1996-07-04 1996-08-01 1996-07-16 Vins et alcools Chevalier VINS ET ALCOOLS CHEVALIER
1 10249 1996-07-05 1996-08-16 1996-07-10 Toms Spezialitäten TOMS SPEZIALITÄTEN
2 10250 1996-07-08 1996-08-05 1996-07-12 Hanari Carnes HANARI CARNES