langstring.langstring

The langstring module provides the LangString class to encapsulate a string with its language information.

This module is designed to work with text strings and their associated language tags, offering functionalities such as validation of language tags, handling of empty strings and language tags based on control flags. It optionally utilizes the langcodes library for validating language tags, enhancing the robustness of the language tag validation process.

Control flags from the controller module are used to enforce certain behaviors like ensuring non-empty text and valid language tags. These flags can be set externally to alter the behavior of the LangString class.

The LangString class aims to make user interaction as similar as possible to working with regular strings. To achieve this, many of the standard string methods have been overridden to return LangString objects, allowing seamless integration and extended functionality. Additionally, the class provides mechanisms for validating input types, matching language tags, and merging LangString objects.

Example:

# Create a LangString object
lang_str = LangString("Hello, World!", "en")

# Print the string representation
print(lang_str)  # Output: '"Hello, World!"@en'

# Convert to uppercase
upper_lang_str = lang_str.upper()
print(upper_lang_str)  # Output: '"HELLO, WORLD!"@en'

# Check if the text contains a substring
contains_substring = "World" in lang_str
print(contains_substring)  # Output: True

# Concatenate two LangString objects
lang_str2 = LangString(" How are you?", "en")
combined_lang_str = lang_str + lang_str2
print(combined_lang_str)  # Output: '"Hello, World! How are you?"@en'

Modules:: controller: Provides control flags that influence the behavior of the LangString class. flags: Defines the LangStringFlag class with various control flags for the LangString class. utils.validators: Provides validation methods used within the LangString class.

Classes

LangString

A class to encapsulate a string with its language information.

Module Contents

class langstring.langstring.LangString(text='', lang='')

A class to encapsulate a string with its language information.

This class provides functionality to associate a text string with a language tag, offering methods for string representation, equality comparison, and hashing. The behavior of this class is influenced by control flags from the Controller class, which can enforce non-empty text, valid language tags, and other constraints.

Many standard string methods are overridden to return LangString objects, allowing seamless integration and extended functionality. This design ensures that users can work with LangString instances similarly to regular strings.

Variables:

text (Optional[str]) – The text string.
lang (str) – The language tag of the text.

Raises:

ValueError – If control flags enforce non-empty text and the text is empty.
TypeError – If the types of parameters are incorrect based on validation.

Parameters:

text (str)
lang (str)

property text: str

Get the text string.

Returns:: The text string.
Return type:: str

property lang: str

Get the language tag.

Returns:: The language tag.
Return type:: str

capitalize()

Return a copy of the LangString with its first character capitalized and the rest lowercased.

This method mimics the behavior of the standard string’s capitalize method but returns a LangString object.

Returns:: A new LangString with the first character capitalized.
Return type:: LangString

Example:

>>> lang_str = LangString("hello, world!", "en")
>>> capitalized_lang_str = lang_str.capitalize()
>>> print(capitalized_lang_str)  # Output: "Hello, world!"@en

casefold()

Return a casefolded copy of the LangString. Casefolding is a more aggressive version of lowercasing.

This method mimics the behavior of the standard string’s casefold method but returns a LangString object.

Returns:: A new LangString that is casefolded.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, WORLD!", "en")
>>> casefolded_lang_str = lang_str.casefold()
>>> print(casefolded_lang_str)  # Output: "hello, world!"@en

center(width, fillchar=' ')

Return a centered LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s center method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString centered with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> centered_lang_str = lang_str.center(11, "*")
>>> print(centered_lang_str)  # Output: "***hello***"@en

count(sub, start=0, end=None)

Return the number of non-overlapping occurrences of substring sub in the LangString.

This method mimics the behavior of the standard string’s count method.

Parameters:

sub (str) – The substring to count.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The number of occurrences of the substring.

Return type:

int

Example:

>>> lang_str = LangString("hello, hello, hello!", "en")
>>> count_hello = lang_str.count("hello")
>>> print(count_hello)  # Output: 3

endswith(suffix, start=0, end=None)

Return True if the LangString ends with the specified suffix, otherwise return False.

This method mimics the behavior of the standard string’s endswith method.

Parameters:

suffix (str) – The suffix to check.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

True if the LangString ends with the suffix, otherwise False.

Return type:

bool

Example:

>>> lang_str = LangString("hello, world!", "en")
>>> ends_with_world = lang_str.endswith("world!")
>>> print(ends_with_world)  # Output: True

expandtabs(tabsize=8)

Return a copy of the LangString where all tab characters are expanded using spaces.

This method mimics the behavior of the standard string’s expandtabs method but returns a LangString object.

Parameters:: tabsize (int) – The number of spaces to use for each tab character.
Returns:: A new LangString with tabs expanded.
Return type:: LangString

Example:

>>> lang_str = LangString("hello\tworld", "en")
>>> expanded_lang_str = lang_str.expandtabs(4)
>>> print(expanded_lang_str)  # Output: "hello   world"@en

find(sub, start=0, end=None)

Return the lowest index in the LangString where substring sub is found.

This method mimics the behavior of the standard string’s find method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The lowest index where the substring is found, or -1 if not found.

Return type:

int

Example:

>>> lang_str = LangString("hello, world", "en")
>>> index = lang_str.find("world")
>>> print(index)  # Output: 7

format(*args, **kwargs)

Perform a string formatting operation on the LangString.

This method mimics the behavior of the standard string’s format method but returns a LangString object.

Parameters:

args (Any) – Positional arguments for formatting.
kwargs (Any) – Keyword arguments for formatting.

Returns:

A new LangString with the formatted text.

Return type:

LangString

Example:

>>> lang_str = LangString("Hello, {}!", "en")
>>> formatted_lang_str = lang_str.format("world")
>>> print(formatted_lang_str)  # Output: "Hello, world!"@en

format_map(mapping)

Perform a string formatting operation using a dictionary.

This method mimics the behavior of the standard string’s format_map method but returns a LangString object.

Parameters:: mapping (dict) – A dictionary for formatting.
Returns:: A new LangString with the formatted text.
Return type:: LangString
Raises:: TypeError – If the provided mapping is not a dictionary.

Example:

>>> lang_str = LangString("Hello, {name}!", "en")
>>> formatted_lang_str = lang_str.format_map({"name": "world"})
>>> print(formatted_lang_str)  # Output: "Hello, world!"@en

index(sub, start=0, end=None)

Return the lowest index in the LangString where substring sub is found.

This method mimics the behavior of the standard string’s index method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The lowest index where the substring is found.

Return type:

int

Raises:

ValueError – If the substring is not found.

Example:

>>> lang_str = LangString("hello, world", "en")
>>> index = lang_str.index("world")
>>> print(index)  # Output: 7

isalnum()

Return True if all characters in the LangString are alphanumeric and there is at least one character.

This method mimics the behavior of the standard string’s isalnum method.

Returns:: True if the LangString is alphanumeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello123", "en")
>>> is_alnum = lang_str.isalnum()
>>> print(is_alnum)  # Output: True

>>> lang_str = LangString("Hello 123", "en")
>>> is_alnum = lang_str.isalnum()
>>> print(is_alnum)  # Output: False

isalpha()

Return True if all characters in the LangString are alphabetic and there is at least one character.

This method mimics the behavior of the standard string’s isalpha method.

Returns:: True if the LangString is alphabetic, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello", "en")
>>> is_alpha = lang_str.isalpha()
>>> print(is_alpha)  # Output: True

>>> lang_str = LangString("Hello123", "en")
>>> is_alpha = lang_str.isalpha()
>>> print(is_alpha)  # Output: False

isascii()

Return True if all characters in the LangString are ASCII characters.

This method mimics the behavior of the standard string’s isascii method.

Returns:: True if the LangString is ASCII, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello", "en")
>>> is_ascii = lang_str.isascii()
>>> print(is_ascii)  # Output: True

>>> lang_str = LangString("Héllo", "en")
>>> is_ascii = lang_str.isascii()
>>> print(is_ascii)  # Output: False

isdecimal()

Return True if all characters in the LangString are decimal characters and there is at least one character.

This method mimics the behavior of the standard string’s isdecimal method.

Returns:: True if the LangString is decimal, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_decimal = lang_str.isdecimal()
>>> print(is_decimal)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_decimal = lang_str.isdecimal()
>>> print(is_decimal)  # Output: False

isdigit()

Return True if all characters in the LangString are digits and there is at least one character.

This method mimics the behavior of the standard string’s isdigit method.

Returns:: True if the LangString is numeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_digit = lang_str.isdigit()
>>> print(is_digit)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_digit = lang_str.isdigit()
>>> print(is_digit)  # Output: False

isidentifier()

Return True if the LangString is a valid identifier according to Python language definition.

This method mimics the behavior of the standard string’s isidentifier method.

Returns:: True if the LangString is a valid identifier, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("variable_name", "en")
>>> is_identifier = lang_str.isidentifier()
>>> print(is_identifier)  # Output: True

>>> lang_str = LangString("123variable", "en")
>>> is_identifier = lang_str.isidentifier()
>>> print(is_identifier)  # Output: False

islower()

Return True if all cased characters in the LangString are lowercase and there is at least one cased character.

This method mimics the behavior of the standard string’s islower method.

Returns:: True if the LangString is in lowercase, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("hello", "en")
>>> is_lower = lang_str.islower()
>>> print(is_lower)  # Output: True

>>> lang_str = LangString("Hello", "en")
>>> is_lower = lang_str.islower()
>>> print(is_lower)  # Output: False

isnumeric()

Return True if all characters in the LangString are numeric characters and there is at least one character.

This method mimics the behavior of the standard string’s isnumeric method.

Returns:: True if the LangString is numeric, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("12345", "en")
>>> is_numeric = lang_str.isnumeric()
>>> print(is_numeric)  # Output: True

>>> lang_str = LangString("123.45", "en")
>>> is_numeric = lang_str.isnumeric()
>>> print(is_numeric)  # Output: False

isprintable()

Return True if all characters in the LangString are printable or the LangString is empty.

This method mimics the behavior of the standard string’s isprintable method.

Returns:: True if the LangString is printable, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> is_printable = lang_str.isprintable()
>>> print(is_printable)  # Output: True

>>> lang_str = LangString("Hello,\tworld!", "en")
>>> is_printable = lang_str.isprintable()
>>> print(is_printable)  # Output: False

isspace()

Return True if there are only whitespace characters in the LangString and there is at least one character.

This method mimics the behavior of the standard string’s isspace method.

Returns:: True if the LangString is whitespace, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("   ", "en")
>>> is_space = lang_str.isspace()
>>> print(is_space)  # Output: True

>>> lang_str = LangString("Hello, world!", "en")
>>> is_space = lang_str.isspace()
>>> print(is_space)  # Output: False

istitle()

Return True if the LangString is a titlecased string and there is at least one character.

This method mimics the behavior of the standard string’s istitle method.

Returns:: True if the LangString is titlecased, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> is_title = lang_str.istitle()
>>> print(is_title)  # Output: True

>>> lang_str = LangString("hello, world!", "en")
>>> is_title = lang_str.istitle()
>>> print(is_title)  # Output: False

isupper()

Return True if all cased characters in the LangString are uppercase and there is at least one cased character.

This method mimics the behavior of the standard string’s isupper method.

Returns:: True if the LangString is in uppercase, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("HELLO, WORLD!", "en")
>>> is_upper = lang_str.isupper()
>>> print(is_upper)  # Output: True

>>> lang_str = LangString("Hello, World!", "en")
>>> is_upper = lang_str.isupper()
>>> print(is_upper)  # Output: False

join(iterable)

Join an iterable of strings with the LangString’s text.

This method mimics the behavior of the standard string’s join method but returns a LangString object.

Parameters:: iterable (Iterable[str]) – An iterable of strings to be joined.
Returns:: A new LangString with the joined text.
Return type:: LangString

Example:

>>> lang_str = LangString(", ", "en")
>>> joined_lang_str = lang_str.join(["Hello", "world"])
>>> print(joined_lang_str)  # Output: "Hello, world"@en

ljust(width, fillchar=' ')

Return a left-justified LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s ljust method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString left-justified with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> left_justified_lang_str = lang_str.ljust(10, "*")
>>> print(left_justified_lang_str)  # Output: "hello*****"@en

lower()

Return a copy of the LangString with all the cased characters converted to lowercase.

This method mimics the behavior of the standard string’s lower method but returns a LangString object.

Returns:: A new LangString with all characters in lowercase.
Return type:: LangString

Example:

>>> lang_str = LangString("HELLO, WORLD!", "en")
>>> lower_lang_str = lang_str.lower()
>>> print(lower_lang_str)  # Output: "hello, world!"@en

lstrip(chars=None)

Return a copy of the LangString with leading characters removed.

This method mimics the behavior of the standard string’s lstrip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with leading characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("   Hello, world!", "en")
>>> stripped_lang_str = lang_str.lstrip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("...Hello, world!", "en")
>>> stripped_lang_str = lang_str.lstrip(".")
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

partition(sep)

Split the LangString at the first occurrence of sep, and return a 3-tuple containing the part before the separator, the separator itself, and the part after the separator.

This method mimics the behavior of the standard string’s partition method but returns LangString objects.

Parameters:: sep (str) – The separator to split the LangString.
Returns:: A 3-tuple containing the part before the separator, the separator itself, and the part after the separator.
Return type:: tuple[LangString, LangString, LangString]

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> before, sep, after = lang_str.partition(", ")
>>> print(before)  # Output: "Hello"@en
>>> print(sep)     # Output: ", "@en
>>> print(after)   # Output: "world!"@en

replace(old, new, count=-1)

Return a copy of the LangString with all occurrences of substring old replaced by new.

This method mimics the behavior of the standard string’s replace method but returns a LangString object.

Parameters:

old (str) – The substring to be replaced.
new (str) – The substring to replace with.
count (int) – The maximum number of occurrences to replace. If -1, all occurrences are replaced.

Returns:

A new LangString with the replacements.

Return type:

LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> replaced_lang_str = lang_str.replace("world", "Python")
>>> print(replaced_lang_str)  # Output: "Hello, Python!"@en

>>> lang_str = LangString("abababab", "en")
>>> replaced_lang_str = lang_str.replace("ab", "cd", 2)
>>> print(replaced_lang_str)  # Output: "cdcdabab"@en

removeprefix(prefix)

Remove the specified prefix from the LangString’s text.

If the text starts with the prefix string, return a new LangString with the prefix string removed. Otherwise, return a copy of the original LangString.

This method mimics the behavior of the standard string’s removeprefix method but returns a LangString object.

Parameters:: prefix (str) – The prefix to remove from the text.
Returns:: A new LangString with the prefix removed, or the original LangString if the prefix is not found.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_prefix_lang_str = lang_str.removeprefix("Hello, ")
>>> print(removed_prefix_lang_str)  # Output: "world!"@en

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_prefix_lang_str = lang_str.removeprefix("Goodbye, ")
>>> print(removed_prefix_lang_str)  # Output: "Hello, world!"@en

removesuffix(suffix)

Remove the specified suffix from the LangString’s text.

If the text ends with the suffix string, return a new LangString with the suffix string removed. Otherwise, return a copy of the original LangString.

This method mimics the behavior of the standard string’s removesuffix method but returns a LangString object.

Parameters:: suffix (str) – The suffix to remove from the text.
Returns:: A new LangString with the suffix removed, or the original LangString if the suffix is not found.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_suffix_lang_str = lang_str.removesuffix(", world!")
>>> print(removed_suffix_lang_str)  # Output: "Hello"@en

>>> lang_str = LangString("Hello, world!", "en")
>>> removed_suffix_lang_str = lang_str.removesuffix("planet")
>>> print(removed_suffix_lang_str)  # Output: "Hello, world!"@en

rfind(sub, start=0, end=None)

Return the highest index in the LangString where substring sub is found, such that sub is contained within [start, end].

Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found.

This method mimics the behavior of the standard string’s rfind method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The highest index where the substring is found, or -1 if not found.

Return type:

int

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> index = lang_str.rfind("Hello")
>>> print(index)  # Output: 14

rindex(sub, start=0, end=None)

Return the highest index in the LangString where substring sub is found, such that sub is contained within [start, end].

Optional arguments start and end are interpreted as in slice notation. Raises ValueError when the substring is not found.

This method mimics the behavior of the standard string’s rindex method.

Parameters:

sub (str) – The substring to find.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

The highest index where the substring is found.

Return type:

int

Raises:

ValueError – If the substring is not found.

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> index = lang_str.rindex("Hello")
>>> print(index)  # Output: 14

>>> lang_str = LangString("Hello, world!", "en")
>>> index = lang_str.rindex("Hi")
>>> print(index)  # Output: ValueError

rjust(width, fillchar=' ')

Return a right-justified LangString of length width.

Padding is done using the specified fill character (default is a space).

This method mimics the behavior of the standard string’s rjust method but returns a LangString object.

Parameters:

width (int) – The total width of the resulting LangString.
fillchar (str) – The character to fill the padding with.

Returns:

A new LangString right-justified with padding.

Return type:

LangString

Example:

>>> lang_str = LangString("hello", "en")
>>> right_justified_lang_str = lang_str.rjust(10, "*")
>>> print(right_justified_lang_str)  # Output: "*****hello"@en

rpartition(sep)

Split the LangString at the last occurrence of sep, and return a 3-tuple containing the part before the separator, the separator itself, and the part after the separator.

This method mimics the behavior of the standard string’s rpartition method but returns LangString objects.

Parameters:: sep (str) – The separator to split the LangString.
Returns:: A 3-tuple containing the part before the separator, the separator itself, and the part after the separator.
Return type:: tuple[LangString, LangString, LangString]

Example:

>>> lang_str = LangString("Hello, world! Hello, universe!", "en")
>>> before, sep, after = lang_str.rpartition("Hello")
>>> print(before)  # Output: "Hello, world! "@en
>>> print(sep)     # Output: "Hello"@en
>>> print(after)   # Output: ", universe!"@en

rsplit(sep=None, maxsplit=-1)

Return a list of the words in the LangString, using sep as the delimiter string.

The list is split from the right starting from the end of the string.

This method mimics the behavior of the standard string’s rsplit method but returns a list of LangString objects.

Parameters:

sep (Optional[str]) – The delimiter string. If None, any whitespace string is a separator.
maxsplit (int) – Maximum number of splits. If -1, there is no limit.

Returns:

A list of LangString objects.

Return type:

list[LangString]

Example:

>>> lang_str = LangString("one two three", "en")
>>> split_lang_str = lang_str.rsplit()
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

>>> lang_str = LangString("one,two,three", "en")
>>> split_lang_str = lang_str.rsplit(",", 1)
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one,two"@en
>>> #         "three"@en

rstrip(chars=None)

Return a copy of the LangString with trailing characters removed.

This method mimics the behavior of the standard string’s rstrip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with trailing characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, world!   ", "en")
>>> stripped_lang_str = lang_str.rstrip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("Hello, world!!!", "en")
>>> stripped_lang_str = lang_str.rstrip("!")
>>> print(stripped_lang_str)  # Output: "Hello, world"@en

split(sep=None, maxsplit=-1)

Return a list of the words in the LangString, using sep as the delimiter string.

This method mimics the behavior of the standard string’s split method but returns a list of LangString objects.

Parameters:

sep (Optional[str]) – The delimiter string. If None, any whitespace string is a separator.
maxsplit (int) – Maximum number of splits. If -1, there is no limit.

Returns:

A list of LangString objects.

Return type:

list[LangString]

Example:

>>> lang_str = LangString("one two three", "en")
>>> split_lang_str = lang_str.split()
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

>>> lang_str = LangString("one,two,three", "en")
>>> split_lang_str = lang_str.split(",")
>>> for part in split_lang_str:
...     print(part)
...
>>> # Output: "one"@en
>>> #         "two"@en
>>> #         "three"@en

splitlines(keepends=False)

Return a list of the lines in the LangString, breaking at line boundaries.

This method mimics the behavior of the standard string’s splitlines method but returns a list of LangString objects.

Parameters:: keepends (bool) – If True, line breaks are included in the resulting list.
Returns:: A list of LangString objects.
Return type:: list[LangString]

Example:

>>> lang_str = LangString("Hello\\nworld", "en") # To test, remove one escape char before the line break.
>>> split_lang_str = lang_str.splitlines()
>>> print(split_lang_str)
# Output: [LangString(text='Hello', lang='en'), LangString(text='world', lang='en')]

>>> lang_str = LangString("Hello\\nworld", "en") # To test, remove one escape char before the line break.
>>> split_lang_str = lang_str.splitlines(True)
>>> print(split_lang_str)
# Output: [LangString(text='Hello\n', lang='en'), LangString(text='world', lang='en')]

startswith(prefix, start=0, end=None)

Return True if the LangString starts with the specified prefix, otherwise return False.

This method mimics the behavior of the standard string’s startswith method.

Parameters:

prefix (str) – The prefix to check.
start (int, optional) – The starting position (default is 0).
end (int, optional) – The ending position (default is the end of the string).

Returns:

True if the LangString starts with the prefix, otherwise False.

Return type:

bool

Example:

>>> lang_str = LangString("Hello, world!", "en")
>>> starts_with_hello = lang_str.startswith("Hello")
>>> print(starts_with_hello)  # Output: True

>>> lang_str = LangString("Hello, world!", "en")
>>> starts_with_hello = lang_str.startswith("world")
>>> print(starts_with_hello)  # Output: False

strip(chars=None)

Return a copy of the LangString with leading and trailing characters removed.

This method mimics the behavior of the standard string’s strip method but returns a LangString object.

Parameters:: chars (Optional[str]) – A string specifying the set of characters to be removed. If None, whitespace characters are removed.
Returns:: A new LangString with leading and trailing characters removed.
Return type:: LangString

Example:

>>> lang_str = LangString("   Hello, world!   ", "en")
>>> stripped_lang_str = lang_str.strip()
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

>>> lang_str = LangString("***Hello, world!***", "en")
>>> stripped_lang_str = lang_str.strip("*")
>>> print(stripped_lang_str)  # Output: "Hello, world!"@en

swapcase()

Return a copy of the LangString with uppercase characters converted to lowercase and vice versa.

This method mimics the behavior of the standard string’s swapcase method but returns a LangString object.

Returns:: A new LangString with swapped case.
Return type:: LangString

Example:

>>> lang_str = LangString("Hello, WORLD!", "en")
>>> swapcase_lang_str = lang_str.swapcase()
>>> print(swapcase_lang_str)  # Output: "hELLO, world!"@en

title()

Return a titlecased version of the LangString where words start with an uppercase character and the remaining characters are lowercase.

This method mimics the behavior of the standard string’s title method but returns a LangString object.

Returns:: A new LangString that is titlecased.
Return type:: LangString

Example:

>>> lang_str = LangString("hello world", "en")
>>> title_lang_str = lang_str.title()
>>> print(title_lang_str)  # Output: "Hello World"@en

translate(table)

Return a copy of the LangString in which each character has been mapped through the given translation table.

This method mimics the behavior of the standard string’s translate method but returns a LangString object.

Parameters:: table (dict[int, str]) – A translation table mapping Unicode ordinals to Unicode ordinals, strings, or None.
Returns:: A new LangString with the characters translated.
Return type:: LangString

Example:

>>> translation_table = str.maketrans("aeiou", "12345")
>>> lang_str = LangString("hello world", "en")
>>> translated_lang_str = lang_str.translate(translation_table)
>>> print(translated_lang_str) # Output: "h2ll4 w4rld"@en

upper()

Return a copy of the LangString with all the characters converted to uppercase.

This method mimics the behavior of the standard string’s upper method but returns a LangString object.

Returns:: A new LangString with all characters in uppercase.
Return type:: LangString

Example:

>>> lang_str = LangString("hello world", "en")
>>> upper_lang_str = lang_str.upper()
>>> print(upper_lang_str)  # Output: "HELLO WORLD"@en

zfill(width)

Return a copy of the LangString left filled with ASCII ‘0’ digits to make a string of length width.

This method mimics the behavior of the standard string’s zfill method but returns a LangString object.

Parameters:: width (int) – The total width of the resulting LangString.
Returns:: A new LangString left filled with ‘0’ digits.
Return type:: LangString

Example:

>>> lang_str = LangString("42", "en")
>>> zfilled_lang_str = lang_str.zfill(5)
>>> print(zfilled_lang_str)  # Output: "00042"@en

to_string(print_quotes=None, separator='@', print_lang=None)

Return a string representation of the LangString with options for including quotes and language tag.

Parameters:

print_quotes (Optional[bool]) – If True, wrap the text in quotes. If None, use the default setting from the Controller.
separator (str) – The separator to use between the text and language tag.
print_lang (Optional[bool]) – If True, include the language tag. If None, use the default setting from the Controller.

Returns:

A string representation of the LangString.

Return type:

str

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> print(lang_str.to_string())  # Output: '"Hello, World!"@en'
>>> print(lang_str.to_string(print_quotes=False))  # Output: 'Hello, World!@en'
>>> print(lang_str.to_string(print_lang=False))  # Output: '"Hello, World!"'

equals_str(other)

Compare the LangString’s text with a given string for equality.

Parameters:: other (str) – The string to compare with.
Returns:: True if the text matches the given string, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> print(lang_str.equals_str("Hello, World!"))  # Output: True
>>> print(lang_str.equals_str("hello, world!"))  # Output: False

equals_langstring(other)

Compare the LangString with another LangString for equality of text and language tag (case-insensitive).

Parameters:: other (LangString) – The LangString to compare with.
Returns:: True if both text and language tag match (case-insensitive), otherwise False.
Return type:: bool

Example:

>>> lang_str1 = LangString("Hello, World!", "en")
>>> lang_str2 = LangString("Hello, World!", "EN")
>>> print(lang_str1.equals_langstring(lang_str2))  # Output: True
>>> lang_str3 = LangString("Hello, World!", "fr")
>>> print(lang_str1.equals_langstring(lang_str3))  # Output: False

__add__(other)

Add another LangString or a string to this LangString.

The operation can only be performed if:

Both are LangString objects with the same language tag.
The other is a string, which will be concatenated to the text of this LangString.

Parameters:: other (Union[LangString, str]) – The LangString or string to add.
Returns:: A new LangString with the concatenated text.
Return type:: LangString
Raises:: TypeError – If the objects are not compatible for addition.

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString(" World", "en")
>>> result = lang_str1 + lang_str2
>>> print(result)  # Output: "Hello World"@en

>>> lang_str3 = LangString("Hello", "en")
>>> result = lang_str3 + " World"
>>> print(result)  # Output: "Hello World"@en

__contains__(item)

Check if a substring exists within the LangString’s text.

Parameters:: item (str) – The substring to check.
Returns:: True if the substring exists within the text, otherwise False.
Return type:: bool

Example:

>>> lang_str = LangString("Hello, World!", "en")
>>> contains = "World" in lang_str
>>> print(contains)  # Output: True

>>> contains = "Python" in lang_str
>>> print(contains)  # Output: False

__eq__(other)

Check equality of this LangString with another object.

Parameters:: other (object) – Another object to compare with.
Returns:: True if the objects are equal, otherwise False.
Return type:: bool

Example:

>>> lang_str1 = LangString("Hello, World!", "en")
>>> lang_str2 = LangString("Hello, World!", "en")
>>> is_equal = lang_str1 == lang_str2
>>> print(is_equal)  # Output: True

>>> lang_str3 = LangString("Hello, World!", "fr")
>>> is_equal = lang_str1 == lang_str3
>>> print(is_equal)  # Output: False

>>> is_equal = lang_str1 == "Hello, World!"
>>> print(is_equal)  # Output: True

>>> is_equal = lang_str1 == "Bonjour, Monde!"
>>> print(is_equal)  # Output: False

__ge__(other)

Check if this LangString is greater than or equal to another str or LangString object.

Parameters:

other (object) – The str or LangString object to compare with.

Returns:

True if this LangString is greater than or equal to the other, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("banana", "en")
>>> lang_str2 = LangString("apple", "en")
>>> is_ge = lang_str1 >= lang_str2
>>> print(is_ge)  # Output: True

>>> lang_str3 = LangString("apple", "en")
>>> is_ge = lang_str2 >= lang_str3
>>> print(is_ge)  # Output: True

>>> is_ge = lang_str1 >= "banana"
>>> print(is_ge)  # Output: True

>>> is_ge = lang_str2 >= "cherry"
>>> print(is_ge)  # Output: False

__getitem__(key)

Retrieve a substring or a reversed string from the LangString’s text.

Parameters:: key (Union[int, slice]) – The index or slice to access.
Returns:: A new LangString with the substring or single character.
Return type:: LangString

Example:

>>> lang_str = LangString("hello, world", "en")
>>> substring = lang_str[0:5]
>>> print(substring)  # Output: "hello"@en

>>> single_char = lang_str[1]
>>> print(single_char)  # Output: "e"@en

__gt__(other)

Check if this LangString is greater than another LangString object.

Parameters:

other (object) – The str or LangString object to compare with.

Returns:

True if this LangString is greater than the other, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("banana", "en")
>>> lang_str2 = LangString("apple", "en")
>>> is_gt = lang_str1 > lang_str2
>>> print(is_gt)  # Output: True

>>> lang_str3 = LangString("apple", "en")
>>> is_gt = lang_str2 > lang_str3
>>> print(is_gt)  # Output: False

>>> is_gt = lang_str1 > "apple"
>>> print(is_gt)  # Output: True

>>> is_gt = lang_str2 > "cherry"
>>> print(is_gt)  # Output: False

__hash__()

Generate a hash value for a LangString object.

The hash value is computed based on the text and a casefolded version of the language tag.

Returns:: The hash value of the LangString object, based on its text and language tag.
Return type:: int

Example:

>>> lang_str = LangString("hello", "en")
>>> hash_value = hash(lang_str)
>>> print(hash_value)  # Output: A unique integer representing the hash value

__iadd__(other)

Implement in-place addition for LangString objects.

This method allows the LangString’s text to be concatenated with another LangString’s text or a regular string. The operation is only allowed if both LangString objects have the same language tag or if the other operand is a string.

Parameters:

other (Union[LangString, str]) – The LangString or string to add.

Returns:

A new LangString instance with the concatenated text.

Return type:

LangString

Raises:

TypeError – If the objects are not compatible for addition.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString(" World", "en")
>>> lang_str1 += lang_str2
>>> print(lang_str1)  # Output: "Hello World"@en

>>> lang_str1 += "!"
>>> print(lang_str1)  # Output: "Hello World!"@en

__imul__(other)

Implement in-place multiplication of the LangString’s text.

This method allows the LangString’s text to be repeated a specified number of times.

Parameters:: other (int) – The number of times to repeat the text.
Returns:: The same LangString instance with the text repeated.
Return type:: LangString
Raises:: TypeError – If the operand is not an integer.

Example:

>>> lang_str = LangString("Hello", "en")
>>> lang_str *= 3
>>> print(lang_str)  # Output: "HelloHelloHello"@en

__iter__()

Enable iteration over the text part of the LangString.

This method allows the LangString to be iterable, returning each character in the text part one by one.

Returns:: An iterator over the characters in the text.
Return type:: Iterator[str]

Example:

>>> lang_str = LangString("Hello", "en")
>>> for char in lang_str:
...     print(char)
...
# Output:   H
#           e
#           l
#           l
#           o

__le__(other)

Check if this LangString is less than or equal to another LangString object or string.

This method compares the LangString’s text with another LangString’s text or a regular string.

Parameters:

other (object) – The LangString or string to compare with.

Returns:

True if this LangString’s text is less than or equal to the other text, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("apple", "en")
>>> lang_str2 = LangString("banana", "en")
>>> print(lang_str1 <= lang_str2)  # Output: True
>>> print(lang_str1 <= "apple")  # Output: True

__len__()

Return the length of the LangString’s text.

Returns:: The length of the text.
Return type:: int

Example:

>>> lang_str = LangString("hello", "en")
>>> length = len(lang_str)
>>> print(length)  # Output: 5

__lt__(other)

Check if this LangString is less than another LangString object or string.

This method compares the LangString’s text with another LangString’s text or a regular string.

Parameters:

other (object) – The LangString or string to compare with.

Returns:

True if this LangString’s text is less than the other text, otherwise False.

Return type:

bool

Raises:

TypeError – If the objects are not compatible for comparison.
ValueError – If the language tags are incompatible.

Example:

>>> lang_str1 = LangString("apple", "en")
>>> lang_str2 = LangString("banana", "en")
>>> print(lang_str1 < lang_str2)  # Output: True
>>> print(lang_str1 < "banana")  # Output: True

__mul__(other)

Multiply the LangString’s text a specified number of times.

This method repeats the LangString’s text a specified number of times and returns a new LangString.

Parameters:: other (int) – The number of times to repeat the text.
Returns:: A new LangString with the text repeated.
Return type:: LangString
Raises:: TypeError – If the operand is not an integer.

Example:

>>> lang_str = LangString("hello", "en")
>>> multiplied_lang_str = lang_str * 3
>>> print(multiplied_lang_str)  # Output: "hellohellohello"@en

__radd__(other)

Handle concatenation when LangString is on the right side of the ‘+’ operator.

This method is only defined for ‘other’ of type string because the __add__ method is used when ‘other’ is a LangString. It concatenates the other’s text to the LangString’s text (in this order) and returns a string, which loses its language tag.

Parameters:: other (str) – The string to concatenate with.
Returns:: A new string with the concatenated text.
Return type:: str
Raises:: TypeError – If ‘other’ is not a string.

Example:

>>> lang_str = LangString("world", "en")
>>> result = "hello " + lang_str
>>> print(result)  # Output: 'hello world'

__repr__()

Return an unambiguous string representation of the LangString.

Returns:: The unambiguous string representation of the LangString.
Return type:: str

Example:

>>> lang_str = LangString("hello", "en")
>>> print(repr(lang_str))  # Output: 'LangString(text="hello", lang="en")'

__rmul__(other)

Implement right multiplication.

This method is called for the reversed operation of multiplication, i.e., when LangString is on the right side. It is typically used for repeating the LangString’s text a specified number of times.

Parameters:: other (int) – The number of times the LangString’s text should be repeated.
Returns:: A new LangString with the text repeated.
Return type:: LangString
Raises:: TypeError – If ‘other’ is not an integer.

Example:

>>> lang_str = LangString("hello", "en")
>>> multiplied_lang_str = 3 * lang_str
>>> print(multiplied_lang_str)  # Output: "hellohellohello"@en

__str__()

Define the string representation of the LangString object.

Returns:: The string representation of the LangString object.
Return type:: str

Example:

>>> lang_str = LangString("hello", "en")
>>> print(lang_str)  # Output: '"hello"@en'

static merge_langstrings(langstrings)

Merge duplicated LangStrings in a list based on content and language tags.

This method processes a list of LangString instances, identifying and merging duplicates based on their text and language tags. If there are multiple LangStrings with the same text but different language tag casings, the resulting LangString will use a casefolded version of the language tag.

Parameters:: langstrings (list[LangString]) – List of LangString instances to be merged.
Returns:: A list of merged LangString instances without duplicates.
Return type:: list[LangString]

Example:

>>> lang_str1 = LangString("Hello", "en")
>>> lang_str2 = LangString("Hello", "EN")
>>> lang_str3 = LangString("Bonjour", "fr")
>>> merged_list = LangString.merge_langstrings([lang_str1, lang_str2, lang_str3])
>>> for ls in merged_list:
...     print(ls)
...
>>> # Output: '"Hello"@en'
>>> #         '"Bonjour"@fr'

static print_list(langstring_list, print_quotes=None, separator='@', print_lang=None)

Print a string representation of a list of LangString instances using the to_string method with specified formatting options.

Parameters:

langstring_list (list[LangString]) – The list of LangString instances.
print_quotes (Optional[bool]) – If True, wrap the text in quotes. If None, use the default setting from the Controller.
separator (str) – The separator to use between the text and language tag.
print_lang (Optional[bool]) – If True, include the language tag. If None, use the default setting from the Controller.

Return type:

None

Example:

>>> lang_str1 = LangString("a", "b")
>>> lang_str2 = LangString("c", "d")
>>> ls_list = [lang_str1, lang_str2]
>>> LangString.print_list(ls_list)  # Output: ['"a"@b', '"c"@d']