orionis.support.types.Stringable

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Stringable(str): (source)

View In Hierarchy

Undocumented

Method	`__getitem__`	Return a substring or character by index or slice.
Method	`__str__`	Return the string representation of the object.
Method	`after`	Return the substring after the first occurrence of a value.
Method	`afterLast`	Return the substring after the last occurrence of a value.
Method	`apa`	Convert to APA-style title case.
Method	`append`	Append one or more string values to the end of the string.
Method	`ascii`	Transliterate to ASCII using Unicode normalization.
Method	`basename`	Return the trailing name component of the path.
Method	`before`	Return the substring before the first occurrence of a value.
Method	`beforeLast`	Return the substring before the last occurrence of a value.
Method	`between`	Return substring between two delimiters.
Method	`betweenFirst`	Return the substring between the first pair of delimiters.
Method	`camel`	Convert the string to camel case.
Method	`charAt`	Return the character at a given index.
Method	`chopEnd`	Remove the given string(s) from the end if present.
Method	`chopStart`	Remove the given string(s) from the start if present.
Method	`contains`	Check if the string contains any of the given values.
Method	`containsAll`	Check if the string contains all specified substrings.
Method	`convertCase`	Convert string case using specified mode.
Method	`decrypt`	Decrypt the string using a placeholder implementation.
Method	`deduplicate`	Replace consecutive occurrences of a character with a single instance.
Method	`dirname`	Return the parent directory path.
Method	`doesntContain`	Determine if the string doesn't contain any given substring.
Method	`doesntEndWith`	Determine if string doesn't end with any given substring.
Method	`doesntStartWith`	Determine if the string doesn't start with any given substring.
Method	`encrypt`	Encrypt the string using the Crypt facade.
Method	`endsWith`	Determine if the string ends with any of the given substrings.
Method	`exactly`	Return True if the string exactly matches the given value.
Method	`excerpt`	Extract an excerpt containing the first occurrence of a phrase.
Method	`explode`	Split the string into a list using a delimiter.
Method	`finish`	Ensure the string ends with a single instance of the given value.
Method	`fromBase64`	Decode the string from Base64.
Method	`hash`	Hash the string using the specified algorithm.
Method	`headline`	Convert to headline case.
Method	`isAlnum`	Check if all characters are alphanumeric.
Method	`isAlpha`	Check if all characters in the string are alphabetic.
Method	`isAscii`	Check if the string contains only 7-bit ASCII characters.
Method	`isDecimal`	Check if all characters in the string are decimal characters.
Method	`isDigit`	Check if all characters are digits.
Method	`isEmpty`	Check if the string is empty.
Method	`isIdentifier`	Check if the string is a valid Python identifier.
Method	`isJson`	Check if the string is valid JSON.
Method	`isLower`	Check if all cased characters in the string are lowercase.
Method	`isMatch`	Determine if the string matches any regular expression pattern.
Method	`isNotEmpty`	Return True if the string is not empty.
Method	`isNumeric`	Check if all characters in the string are numeric.
Method	`isPattern`	Check if the string matches any of the given patterns.
Method	`isPrintable`	Return True if all characters in the string are printable.
Method	`isSpace`	Determine if the string contains only whitespace characters.
Method	`isTitle`	Check if the string is titlecased.
Method	`isUlid`	Check if the string is a valid ULID.
Method	`isUpper`	Check if all cased characters in the string are uppercase.
Method	`isUrl`	Determine if the string is a valid URL.
Method	`isUuid`	Determine if the string is a valid UUID.
Method	`jsonSerialize`	Convert the object to a string when JSON encoded.
Method	`kebab`	Convert the string to kebab case.
Method	`lcfirst`	Convert the first character of the string to lowercase.
Method	`length`	Return the number of characters in the string.
Method	`limit`	Limit the string to a maximum number of characters.
Method	`lower`	Convert to lowercase.
Method	`lStrip`	Remove leading characters from the string.
Method	`ltrim`	Remove leading characters from the string.
Method	`mask`	Mask a portion of the string with a repeated character.
Method	`match`	Return the first substring matching the given regular expression pattern.
Method	`matchAll`	Find all substrings matching the given regular expression pattern.
Method	`md5`	Compute the MD5 hash of the string.
Method	`newLine`	Append newline characters to the end of the string.
Method	`numbers`	Remove all non-numeric characters from the string.
Method	`offsetExists`	Determine if the given offset exists in the string.
Method	`offsetGet`	Get the character at the specified offset.
Method	`padBoth`	Pad both sides of the string to a specified total length.
Method	`padLeft`	Pad the left side of the string to a specified total length.
Method	`padRight`	Pad the right side of the string to a specified total length.
Method	`parseCallback`	Parse a Class@method style callback into class and method.
Method	`pascal`	Convert the string to PascalCase.
Method	`pipe`	Pass the string through the given callback and return the result.
Method	`plural`	Get the plural form of an English word.
Method	`pluralPascal`	Pluralize the last word of an English Pascal case string.
Method	`pluralStudly`	Pluralize the last word of an English, studly caps case string.
Method	`position`	Find the position of the first occurrence of a substring.
Method	`prepend`	Prepend values to the beginning of the string.
Method	`remove`	Remove all occurrences of specified substrings from the string.
Method	`repeat`	Repeat the string a specified number of times.
Method	`replace`	Replace occurrences of substrings with replacements.
Method	`replaceArray`	Replace a substring sequentially with elements from a list.
Method	`replaceEnd`	Replace the last occurrence of a value at the end of the string.
Method	`replaceFirst`	Replace the first occurrence of a substring with a replacement.
Method	`replaceLast`	Replace the last occurrence of a substring with a replacement.
Method	`replaceMatches`	Replace pattern matches in the string using regular expressions.
Method	`replaceStart`	Replace the first occurrence of a value at the start of the string.
Method	`reverse`	Reverse the string.
Method	`rStrip`	Remove trailing characters from the string.
Method	`rtrim`	Remove trailing characters from the string.
Method	`scan`	Parse input from a string according to a format pattern.
Method	`sha1`	Compute the SHA1 hash of the string.
Method	`sha256`	Generate a SHA256 hash of the string.
Method	`singular`	Get the singular form of an English word.
Method	`slug`	Generate a URL-friendly slug from the string.
Method	`snake`	Convert the string to snake_case using the specified delimiter.
Method	`split`	Split the string by a regular expression or by length.
Method	`squish`	Normalize whitespace in the string.
Method	`start`	Ensure the string starts with a single instance of the given prefix.
Method	`startsWith`	Determine if the string starts with any of the given substrings.
Method	`stripTags`	Remove HTML and PHP tags from the string.
Method	`studly`	Convert to StudlyCase (PascalCase).
Method	`substr`	Return the portion of the string specified by start and length parameters.
Method	`substrCount`	Count the number of substring occurrences in the string.
Method	`substrReplace`	Replace text within a portion of a string.
Method	`swap`	Swap multiple keywords in a string with other keywords.
Method	`swapCase`	Swap the case of each character in the string.
Method	`take`	Take a specified number of characters from the start or end.
Method	`tap`	Call the callback with the string and return the string.
Method	`test`	Test whether the string matches a regular expression pattern.
Method	`title`	Convert the string to title case.
Method	`toBase64`	Encode the string as Base64.
Method	`toBoolean`	Convert to a boolean value.
Method	`toDate`	Convert string to a datetime object.
Method	`toFloat`	Convert the string to a float.
Method	`toHtmlString`	Escape HTML entities in the string.
Method	`toInteger`	Convert the string to an integer.
Method	`transliterate`	Transliterate a string to its closest ASCII representation.
Method	`trim`	Trim characters from both ends of the string.
Method	`ucfirst`	Capitalize the first character of the string.
Method	`ucsplit`	Split the string by uppercase characters.
Method	`unwrap`	Remove the specified prefix and suffix from the string.
Method	`upper`	Convert all characters to uppercase.
Method	`value`	Return the string value.
Method	`when`	Execute the given callback if condition is true.
Method	`whenContains`	Execute callback if the string contains a given substring.
Method	`whenContainsAll`	Execute callback if the string contains all specified substrings.
Method	`whenDoesntEndWith`	Execute callback if the string does not end with the given substring(s).
Method	`whenDoesntStartWith`	Execute callback if the string does not start with the given substring(s).
Method	`whenEmpty`	Execute callback if the string is empty.
Method	`whenEndsWith`	Execute the callback if the string ends with the given substring(s).
Method	`whenExactly`	Execute callback if the string exactly matches the given value.
Method	`whenIs`	Execute the callback if the string matches the given pattern.
Method	`whenIsAscii`	Execute the callback if the string is 7-bit ASCII.
Method	`whenIsUlid`	Execute the callback if the string is a valid ULID.
Method	`whenIsUuid`	Execute the callback if the string is a valid UUID.
Method	`whenNotEmpty`	Execute the callback if the string is not empty.
Method	`whenNotExactly`	Execute callback if string does not exactly match the given value.
Method	`whenStartsWith`	Execute callback if the string starts with a given substring.
Method	`whenTest`	Execute callback if the string matches the given regular expression.
Method	`wordCount`	Count words in the string.
Method	`words`	Limit the string to a maximum number of words.
Method	`wordWrap`	Wrap text to a specified line width.
Method	`wrap`	Wrap the string with a prefix and suffix.
Method	`zFill`	Pad the string with leading zeros to a given width.
Class Variable	`__slots__`	Undocumented

def __getitem__(self, key: int | slice) -> Stringable: (source) ¶

Return a substring or character by index or slice.

Parameters
key:`int or slice`	Index or slice to retrieve.

Returns
`Stringable`	Stringable instance for the selected item(s).

def __str__(self) -> str: (source) ¶

Return the string representation of the object.

Returns
`str`	String representation of the object.

def after(self, search: str) -> Stringable: (source) ¶

Return the substring after the first occurrence of a value.

Parameters
search:`str`	Substring to search for in the current string.

Returns
`Stringable`	New Stringable containing the substring after the first occurrence of the search string, or the original string if not found.

def afterLast(self, search: str) -> Stringable: (source) ¶

Return the substring after the last occurrence of a value.

Parameters
search:`str`	Substring to search for within the current string.

Returns
`Stringable`	New Stringable containing the substring after the last occurrence of the search string, or the original string if not found.

def apa(self) -> Stringable: (source) ¶

Convert to APA-style title case.

Parameters
None

Returns
`Stringable`	A new Stringable instance in APA title case.

def append(self, *values: str) -> Stringable: (source) ¶

Append one or more string values to the end of the string.

Parameters
*values:`str`	One or more string values to append.

Returns
`Stringable`	A new Stringable instance with all provided values appended.

def ascii(self) -> Stringable: (source) ¶

Transliterate to ASCII using Unicode normalization.

Uses Unicode normalization to remove accents and non-ASCII characters.

Returns
`Stringable`	A new Stringable instance containing only ASCII characters.

def basename(self, suffix: str = '') -> Stringable: (source) ¶

Return the trailing name component of the path.

Parameters
suffix:`str, optional`	Suffix to remove from the basename. Default is "".

Returns
`Stringable`	A new Stringable instance containing the basename with the suffix removed if present.

def before(self, search: str) -> Stringable: (source) ¶

Return the substring before the first occurrence of a value.

Parameters
search:`str`	Substring to search for within the current string.

Returns
`Stringable`	New Stringable instance containing the substring before the first occurrence of the search string, or the original string if not found.

def beforeLast(self, search: str) -> Stringable: (source) ¶

Return the substring before the last occurrence of a value.

Searches for the last occurrence of the specified substring and returns everything before it. If the substring is not found, returns the original string unchanged.

Parameters
search:`str`	Substring to search for within the current string.

Returns
`Stringable`	New Stringable instance containing the substring before the last occurrence of the search string, or the original string if not found.

def between(self, from_str: str, to_str: str) -> Stringable: (source) ¶

Return substring between two delimiters.

Parameters
from_str:`str`	Starting delimiter.
to_str:`str`	Ending delimiter.

Returns
`Stringable`	New Stringable containing text between delimiters, or empty if not found.

def betweenFirst(self, from_str: str, to_str: str) -> Stringable: (source) ¶

Return the substring between the first pair of delimiters.

Parameters
from_str:`str`	Starting delimiter.
to_str:`str`	Ending delimiter.

Returns
`Stringable`	Stringable containing text between the first pair of delimiters, or an empty Stringable if not found.

def camel(self) -> Stringable: (source) ¶

Convert the string to camel case.

Parameters
None

Returns
`Stringable`	A new Stringable instance in camelCase.

def charAt(self, index: int) -> str | bool: (source) ¶

Return the character at a given index.

Parameters
index:`int`	Index of the character to retrieve.

Returns
`str or bool`	The character at the specified index, or False if out of bounds.

def chopEnd(self, needle: str | list[str]) -> Stringable: (source) ¶

Remove the given string(s) from the end if present.

Parameters
needle:`str \| list[str]`	String or list of strings to remove from the end.

Returns
`Stringable`	New Stringable with the needle removed from the end if present.

def chopStart(self, needle: str | list[str]) -> Stringable: (source) ¶

Remove the given string(s) from the start if present.

Parameters
needle:`str \| list[str]`	String or list of strings to remove from the start.

Returns
`Stringable`	New Stringable with the needle removed from the start if present.

def contains(self, needles: str | Iterable[str], *, ignore_case: bool = False) -> bool: (source) ¶

Check if the string contains any of the given values.

Parameters
needles:`str \| Iterable[str]`	Value or values to search for within the string.
ignore_case:`bool, optional`	If True, perform case-insensitive search. Default is False.

Returns
`bool`	True if the string contains any of the needle values, otherwise False.

Raises
`TypeError`	If needles is not a string or an iterable of strings.

def containsAll(self, needles: list[str], *, ignore_case: bool = False) -> bool: (source) ¶

Check if the string contains all specified substrings.

Parameters
needles:`list[str]`	List of substrings to search for.
ignore_case:`bool`	If True, perform case-insensitive search. Default is False.

Returns
`bool`	True if all needles are found in the string, otherwise False.

def convertCase(self, mode: int | None = None) -> Stringable: (source) ¶

Convert string case using specified mode.

Parameters
mode:`int \| None, optional`	Case conversion mode: 0 or None - casefold (default) 1 - uppercase 2 - lowercase 3 - titlecase

Returns
`Stringable`	New Stringable instance with converted case.

def decrypt(self) -> Stringable: (source) ¶

Decrypt the string using a placeholder implementation.

This is a placeholder. In a real implementation, use a proper decryption library such as cryptography.

Returns
`Stringable`	The decrypted string as a Stringable instance.

def deduplicate(self, character: str = ' ') -> Stringable: (source) ¶

Replace consecutive occurrences of a character with a single instance.

Parameters
character:`str, optional`	Single character string to deduplicate. Default is a space.

Returns
`Stringable`	Stringable with consecutive characters replaced by a single instance.

def dirname(self, levels: int = 1) -> Stringable: (source) ¶

Return the parent directory path.

Parameters
levels:`int, optional`	Number of directory levels to ascend. Defaults to 1.

Returns
`Stringable`	Stringable instance containing the parent directory path.

def doesntContain(self, needles: str | list[str], *, ignore_case: bool = False) -> bool: (source) ¶

Determine if the string doesn't contain any given substring.

Parameters
needles:`str \| list[str]`	The substring(s) to search for within the string.
ignore_case:`bool, optional`	If True, perform case-insensitive search. Default is False.

Returns
`bool`	True if the string doesn't contain any of the needle values, otherwise False.

Raises
`TypeError`	If needles is not a string or list of strings, or if ignore_case is not a boolean.

def doesntEndWith(self, needles: str | list[str]) -> bool: (source) ¶

Determine if string doesn't end with any given substring.

Parameters
needles:`str \| list[str]`	The substring(s) to check.

Returns
`bool`	True if string doesn't end with any needle, False otherwise.

Raises
`TypeError`	If needles is not a string or list of strings.

def doesntStartWith(self, needles: str | list[str]) -> bool: (source) ¶

Determine if the string doesn't start with any given substring.

Parameters
needles:`str \| list[str]`	The substring(s) to check at the start of the string.

Returns
`bool`	True if the string doesn't start with any needle, False otherwise.

Raises
`TypeError`	If needles is not a string or list of strings.

def encrypt(self) -> Stringable: (source) ¶

Encrypt the string using the Crypt facade.

This is a placeholder. In a real implementation, use a proper encryption library such as cryptography.

Returns
`Stringable`	The encrypted string as a Stringable instance.

def endsWith(self, needles: str | Iterable[str]) -> bool: (source) ¶

Determine if the string ends with any of the given substrings.

Parameters
needles:`str \| Iterable[str]`	Substring or substrings to check at the end of the string.

Returns
`bool`	True if the string ends with any of the needle values, otherwise False.

def exactly(self, value: str) -> bool: (source) ¶

Return True if the string exactly matches the given value.

Parameters
value:`str`	Value to compare against the current string.

Returns
`bool`	True if the string exactly matches the given value, otherwise False.

def excerpt(self, phrase: str = '', options: dict | None = None) -> str | None: (source) ¶

Extract an excerpt containing the first occurrence of a phrase.

Parameters
phrase:`str, optional`	Phrase to search for in the string. Default is "".
options:`dict \| None, optional`	Options for excerpt extraction. Supported keys: "radius": int, number of characters around the phrase (default 100). "omission": str, string to indicate omitted text (default "...").

Returns
`str \| None`	Excerpt containing the phrase and surrounding context, or None if not found.

def explode(self, delimiter: str, limit: int = -1) -> list[str]: (source) ¶

Split the string into a list using a delimiter.

Parameters
delimiter:`str`	The delimiter to split the string on.
limit:`int`	The maximum number of elements to return. If -1, no limit is applied.

Returns
`list of str`	List of substrings after splitting by the delimiter.

def finish(self, cap: str) -> Stringable: (source) ¶

Ensure the string ends with a single instance of the given value.

Parameters
cap:`str`	String to append as a cap if not already present.

Returns
`Stringable`	Stringable instance ending with the specified cap.

def fromBase64(self, *, strict: bool = False) -> Stringable: (source) ¶

Decode the string from Base64.

Parameters
strict:`bool, optional`	If True, raise an exception on decode errors. Default is False.

Returns
`Stringable`	A new Stringable instance with Base64-decoded content. If decoding fails and strict is False, returns an empty Stringable.

def hash(self, algorithm: str) -> Stringable: (source) ¶

Hash the string using the specified algorithm.

Parameters
algorithm:`str`	Hash algorithm name (md5, sha1, sha256, etc.)

Returns
`Stringable`	A new Stringable instance containing the hexadecimal hash.

Raises
`ValueError`	If the specified algorithm is not supported.

def headline(self) -> Stringable: (source) ¶

Convert to headline case.

Splits the string into words and capitalizes the first letter of each word.

Returns
`Stringable`	A new Stringable instance with each word capitalized.

def isAlnum(self) -> bool: (source) ¶

Check if all characters are alphanumeric.

Returns
`bool`	True if all characters in the string are alphanumeric, otherwise False.

def isAlpha(self) -> bool: (source) ¶

Check if all characters in the string are alphabetic.

Returns
`bool`	True if all characters are alphabetic, otherwise False.

def isAscii(self) -> bool: (source) ¶

Check if the string contains only 7-bit ASCII characters.

Returns
`bool`	True if the string is ASCII, otherwise False.

def isDecimal(self) -> bool: (source) ¶

Check if all characters in the string are decimal characters.

Returns
`bool`	True if all characters are decimal, otherwise False.

def isDigit(self) -> bool: (source) ¶

Check if all characters are digits.

Returns
`bool`	True if all characters in the string are digits, otherwise False.

def isEmpty(self) -> bool: (source) ¶

Check if the string is empty.

Returns
`bool`	True if the string has zero length, otherwise False.

def isIdentifier(self) -> bool: (source) ¶

Check if the string is a valid Python identifier.

Returns
`bool`	True if the string is a valid identifier, otherwise False.

def isJson(self) -> bool: (source) ¶

Check if the string is valid JSON.

Returns
`bool`	True if the string is valid JSON, otherwise False.

def isLower(self) -> bool: (source) ¶

Check if all cased characters in the string are lowercase.

Returns
`bool`	True if all cased characters are lowercase, otherwise False.

def isMatch(self, pattern: str | list[str]) -> bool: (source) ¶

Determine if the string matches any regular expression pattern.

Parameters
pattern:`str \| list[str]`	Regular expression pattern(s) to match.

Returns
`bool`	True if the string matches any pattern, otherwise False.

def isNotEmpty(self) -> bool: (source) ¶

Return True if the string is not empty.

Returns
`bool`	True if the string contains one or more characters, otherwise False.

def isNumeric(self) -> bool: (source) ¶

Check if all characters in the string are numeric.

Returns
`bool`	True if all characters are numeric, otherwise False.

def isPattern(self, pattern: str | list[str], *, ignore_case: bool = False) -> bool: (source) ¶

Check if the string matches any of the given patterns.

Parameters
pattern:`str \| list[str]`	Pattern(s) to match, supports wildcards '*' and '?'.
ignore_case:`bool, optional`	If True, perform case-insensitive matching. Default is False.

Returns
`bool`	True if the string matches any pattern, otherwise False.

Raises
`TypeError`	If pattern is not a string or list of strings.
`TypeError`	If ignore_case is not a boolean.
`ValueError`	If the pattern list is empty.

def isPrintable(self) -> bool: (source) ¶

Return True if all characters in the string are printable.

Returns
`bool`	True if all characters are printable, otherwise False.

def isSpace(self) -> bool: (source) ¶

Determine if the string contains only whitespace characters.

Returns
`bool`	True if the string contains only whitespace characters, otherwise False.

def isTitle(self) -> bool: (source) ¶

Check if the string is titlecased.

Returns
`bool`	True if the string is titlecased, otherwise False.

def isUlid(self) -> bool: (source) ¶

Check if the string is a valid ULID.

Returns
`bool`	True if the string is a valid ULID, otherwise False.

def isUpper(self) -> bool: (source) ¶

Check if all cased characters in the string are uppercase.

Returns
`bool`	True if all cased characters are uppercase, otherwise False.

def isUrl(self, protocols: list[str] | None = None) -> bool: (source) ¶

Determine if the string is a valid URL.

Parameters
protocols:`list[str] \| None, optional`	List of allowed protocols. Defaults to ["http", "https"].

Returns
`bool`	True if the string is a valid URL with an allowed protocol, otherwise False.

def isUuid(self, version: int | str | None = None) -> bool: (source) ¶

Determine if the string is a valid UUID.

Parameters
version:`int \| str \| None, optional`	UUID version to validate (1-8), or "max" for any version up to 8. If None, any valid UUID version is accepted.

Returns
`bool`	True if the string is a valid UUID (and version, if specified), otherwise False.

def jsonSerialize(self) -> str: (source) ¶

Convert the object to a string when JSON encoded.

This method is called when the Stringable object is being JSON serialized. It returns the string representation of the object for proper JSON encoding.

Returns
`str`	The string representation for JSON serialization.

def kebab(self) -> Stringable: (source) ¶

Convert the string to kebab case.

Returns
`Stringable`	A new Stringable instance in kebab-case.

def lcfirst(self) -> Stringable: (source) ¶

Convert the first character of the string to lowercase.

Returns
`Stringable`	A new Stringable instance with the first character in lowercase.

def length(self) -> int: (source) ¶

Return the number of characters in the string.

Returns
`int`	Number of characters in the string.

def limit(self, limit: int = 100, end: str = '...', *, preserve_words: bool = False) -> Stringable: (source) ¶

Limit the string to a maximum number of characters.

Parameters
limit:`int, default 100`	Maximum number of characters allowed.
end:`str, default "..."`	String to append if truncation occurs.
preserve_words:`bool, default False`	If True, do not cut off words in the middle.

Returns
`Stringable`	New Stringable instance limited to the specified number of characters. If truncation occurs, the `end` string is appended.

def lower(self) -> Stringable: (source) ¶

Convert to lowercase.

Returns
`Stringable`	A new Stringable instance with all characters in lowercase.

def lStrip(self, chars: str | None = None) -> Stringable: (source) ¶

Remove leading characters from the string.

Parameters
chars:`str \| None, optional`	Characters to remove from the beginning. If None, whitespace is removed.

Returns
`Stringable`	A new Stringable instance with leading characters removed.

def ltrim(self, characters: str | None = None) -> Stringable: (source) ¶

Remove leading characters from the string.

Parameters
characters:`str \| None, optional`	Characters to remove from the start. If None, whitespace is removed.

Returns
`Stringable`	A new Stringable instance with leading characters removed.

def mask(self, character: str, index: int, length: int | None = None) -> Stringable: (source) ¶

Mask a portion of the string with a repeated character.

Parameters
character:`str`	Character to use for masking.
index:`int`	Starting index for masking.
length:`int \| None, optional`	Number of characters to mask. If None, mask to end of string.

Returns
`Stringable`	A new Stringable with the specified portion masked.

def match(self, pattern: str) -> Stringable: (source) ¶

Return the first substring matching the given regular expression pattern.

Parameters
pattern:`str`	Regular expression pattern to search for.

Returns
`Stringable`	A new Stringable containing the first match, or an empty Stringable if no match is found.

def matchAll(self, pattern: str) -> list[str]: (source) ¶

Find all substrings matching the given regular expression pattern.

Parameters
pattern:`str`	Regular expression pattern to search for.

Returns
`list[str]`	List of all matching substrings found in the string.

def md5(self) -> str: (source) ¶

Compute the MD5 hash of the string.

Returns
`str`	Hexadecimal string representing the MD5 hash of the input string.

def newLine(self, count: int = 1) -> Stringable: (source) ¶

Append newline characters to the end of the string.

Parameters
count:`int, optional`	Number of newline characters to append. Default is 1.

Returns
`Stringable`	A new Stringable instance with the specified number of newline characters appended.

def numbers(self) -> Stringable: (source) ¶

Remove all non-numeric characters from the string.

Parameters
self:`Stringable`	The current string instance.

Returns
`Stringable`	A new Stringable containing only numeric characters.

def offsetExists(self, offset: int) -> bool: (source) ¶

Determine if the given offset exists in the string.

Parameters
offset:`int`	Offset to check for existence.

Returns
`bool`	True if the offset exists, False otherwise.

def offsetGet(self, offset: int) -> str: (source) ¶

Get the character at the specified offset.

Parameters
offset:`int`	Index of the character to retrieve.

Returns
`str`	Character at the given offset.

Raises
`TypeError`	If offset is not an integer.
`IndexError`	If offset is out of bounds.

def padBoth(self, length: int, pad: str = ' ') -> Stringable: (source) ¶

Pad both sides of the string to a specified total length.

Parameters
length:`int`	Total desired length of the resulting string.
pad:`str, optional`	String to use for padding. Default is a single space.

Returns
`Stringable`	New Stringable instance with padding added to both sides.

def padLeft(self, length: int, pad: str = ' ') -> Stringable: (source) ¶

Pad the left side of the string to a specified total length.

Parameters
length:`int`	Total desired length of the resulting string.
pad:`str, optional`	String to use for padding, by default a single space.

Returns
`Stringable`	New Stringable instance with left padding added.

def padRight(self, length: int, pad: str = ' ') -> Stringable: (source) ¶

Pad the right side of the string to a specified total length.

Parameters
length:`int`	The total desired length of the resulting string.
pad:`str, optional`	The string to use for padding, by default a single space.

Returns
`Stringable`	A new Stringable instance with right padding added.

def parseCallback(self, default: str | None = None) -> list[str | None]: (source) ¶

Parse a Class@method style callback into class and method.

Parameters
default:`str \| None, optional`	Default method name if not specified. Default is None.

Returns
`list[str \| None]`	List containing [class_name, method_name].

def pascal(self) -> Stringable: (source) ¶

Convert the string to PascalCase.

Returns
`Stringable`	A new Stringable instance in PascalCase.

def pipe(self, callback: Callable) -> Stringable: (source) ¶

Pass the string through the given callback and return the result.

Parameters
callback:`Callable`	The callback function to apply to the string.

Returns
`Stringable`	A new Stringable instance containing the result of the callback.

Raises
`TypeError`	If the callback is not callable.

def plural(self, count: int | list | Any = 2, *, prepend_count: bool = False) -> Stringable: (source) ¶

Get the plural form of an English word.

Parameters
count:`int \| list \| Any, optional`	Count to determine if plural is needed, by default 2
prepend_count:`bool, optional`	Whether to prepend the count, by default False

Returns
`Stringable`	A new Stringable with plural form

def pluralPascal(self, count: int | list | Any = 2) -> Stringable: (source) ¶

Pluralize the last word of an English Pascal case string.

Parameters
count:`int \| list \| Any, optional`	Count to determine if plural is needed. Default is 2.

Returns
`Stringable`	New Stringable with pluralized last word in PascalCase.

def pluralStudly(self, count: int | list | Any = 2) -> Stringable: (source) ¶

Pluralize the last word of an English, studly caps case string.

Parameters
count:`int \| list \| Any, optional`	Count to determine if plural is needed, by default 2

Returns
`Stringable`	A new Stringable with pluralized last word in StudlyCase

def position(self, needle: str, offset: int = 0, encoding: str | None = None) -> int | bool: (source) ¶

Find the position of the first occurrence of a substring.

Parameters
needle:`str`	Substring to search for.
offset:`int, optional`	Starting index for the search. Default is 0.
encoding:`str \| None, optional`	String encoding for compatibility. Default is None.

Returns
`int or bool`	Index of the first occurrence of the substring, or False if not found.

def prepend(self, *values: str) -> Stringable: (source) ¶

Prepend values to the beginning of the string.

Parameters
*values:`str`	One or more string values to prepend to the current string.

Returns
`Stringable`	A new Stringable instance with all provided values prepended.

Raises
`TypeError`	If any value is not a string.

def remove(self, search: str | list[str], *, case_sensitive: bool = True) -> Stringable: (source) ¶

Remove all occurrences of specified substrings from the string.

Parameters
search:`str \| list[str]`	Substring(s) to remove from the string.
case_sensitive:`bool, default True`	If True, removal is case sensitive.

Returns
`Stringable`	New Stringable instance with specified substrings removed.

def repeat(self, times: int) -> Stringable: (source) ¶

Repeat the string a specified number of times.

Parameters
times:`int`	Number of times to repeat the string.

Returns
`Stringable`	New Stringable instance with the string repeated the specified number of times.

def replace(self, search: str | Iterable[str], replace: str | Iterable[str], *, case_sensitive: bool = True) -> Stringable: (source) ¶

Replace occurrences of substrings with replacements.

Parameters
search:`str \| Iterable[str]`	Substring(s) to search for in the string.
replace:`str \| Iterable[str]`	Replacement string(s) for each search substring.
case_sensitive:`bool, optional`	If True, perform case-sensitive replacement. Default is True.

Returns
`Stringable`	A new Stringable instance with the specified replacements applied.

def replaceArray(self, search: str, replace: list[str]) -> Stringable: (source) ¶

Replace a substring sequentially with elements from a list.

Parameters
search:`str`	Substring to search for and replace.
replace:`list[str]`	List of replacement strings to use sequentially.

Returns
`Stringable`	New Stringable instance with sequential replacements applied.

def replaceEnd(self, search: str, replace: str) -> Stringable: (source) ¶

Replace the last occurrence of a value at the end of the string.

Parameters
search:`str`	String to search for at the end.
replace:`str`	Replacement string.

Returns
`Stringable`	New Stringable instance with the end replaced if the search string is found, otherwise returns the original string.

def replaceFirst(self, search: str, replace: str) -> Stringable: (source) ¶

Replace the first occurrence of a substring with a replacement.

Parameters
search:`str`	Substring to search for in the string.
replace:`str`	Replacement string.

Returns
`Stringable`	New Stringable instance with the first occurrence replaced.

def replaceLast(self, search: str, replace: str) -> Stringable: (source) ¶

Replace the last occurrence of a substring with a replacement.

Parameters
search:`str`	Substring to search for in the string.
replace:`str`	Replacement string.

Returns
`Stringable`	New Stringable instance with the last occurrence replaced.

def replaceMatches(self, pattern: str | list[str], replace: str | Callable, limit: int = -1) -> Stringable: (source) ¶

Replace pattern matches in the string using regular expressions.

Parameters
pattern:`str \| list[str]`	Regular expression pattern(s) to search for.
replace:`str \| Callable`	Replacement string or callback function.
limit:`int, optional`	Maximum number of replacements. Default is -1 (no limit).

Returns
`Stringable`	New Stringable instance with pattern matches replaced.

def replaceStart(self, search: str, replace: str) -> Stringable: (source) ¶

Replace the first occurrence of a value at the start of the string.

Parameters
search:`str`	String to search for at the start.
replace:`str`	Replacement string.

Returns
`Stringable`	New Stringable with the start replaced if the search string is found.

def reverse(self) -> Stringable: (source) ¶

Reverse the string.

Returns
`Stringable`	A new Stringable instance with characters in reverse order.

def rStrip(self, chars: str | None = None) -> Stringable: (source) ¶

Remove trailing characters from the string.

Parameters
chars:`str \| None, optional`	Characters to remove from the end. If None, removes whitespace.

Returns
`Stringable`	A new Stringable instance with trailing characters removed.

def rtrim(self, characters: str | None = None) -> Stringable: (source) ¶

Remove trailing characters from the string.

Parameters
characters:`str \| None, optional`	Characters to trim from the end. If None, trims whitespace.

Returns
`Stringable`	New Stringable instance with trailing characters removed.

def scan(self, format_str: str) -> list[str]: (source) ¶

Parse input from a string according to a format pattern.

Extracts values from the string using a simplified sscanf-like format string with %s (strings), %d (digits), and %f (floats) placeholders.

Parameters
format_str:`str`	Format string with placeholders (%s, %d, %f).

Returns
`list[str]`	List of parsed string values, or empty list if no matches found.

Raises
`TypeError`	If format_str is not a string.

def sha1(self) -> str: (source) ¶

Compute the SHA1 hash of the string.

Returns
`str`	Hexadecimal string representing the SHA1 hash of the input string.

def sha256(self) -> str: (source) ¶

Generate a SHA256 hash of the string.

Returns
`str`	Hexadecimal string representing the SHA256 hash of the input string.

def singular(self) -> Stringable: (source) ¶

Get the singular form of an English word.

Returns
`Stringable`	A new Stringable with singular form of the word.

def slug(self, separator: str = '-', dictionary: dict[str, str] | None = None) -> Stringable: (source) ¶

Generate a URL-friendly slug from the string.

Parameters
separator:`str, optional`	Separator to use in the slug. Default is "-".
dictionary:`dict[str, str] \| None, optional`	Dictionary for character replacements. Default is {"@": "at"}.

Returns
`Stringable`	A new Stringable instance containing the URL-friendly slug.

def snake(self, delimiter: str = '_') -> Stringable: (source) ¶

Convert the string to snake_case using the specified delimiter.

Parameters
delimiter:`str, optional`	Delimiter to use for separation, by default "_".

Returns
`Stringable`	A new Stringable instance in snake_case.

def split(self, pattern: str | int, limit: int = -1, flags: int = 0) -> list[str]: (source) ¶

Split the string by a regular expression or by length.

Parameters
pattern:`str or int`	Regular expression pattern or chunk length.
limit:`int, optional`	Maximum number of splits. Default is -1 (no limit).
flags:`int, optional`	Regular expression flags. Default is 0.

Returns
`list of str`	List of string segments after splitting.

def squish(self) -> Stringable: (source) ¶

Normalize whitespace in the string.

Replace consecutive whitespace characters with a single space and trim leading and trailing whitespace.

Returns
`Stringable`	Stringable instance with normalized whitespace.

def start(self, prefix: str) -> Stringable: (source) ¶

Ensure the string starts with a single instance of the given prefix.

Parameters
prefix:`str`	The prefix to ensure at the start of the string.

Returns
`Stringable`	A new Stringable instance starting with the specified prefix.

def startsWith(self, needles: str | list[str]) -> bool: (source) ¶

Determine if the string starts with any of the given substrings.

Parameters
needles:`str \| list[str]`	The substring(s) to check at the start of the string.

Returns
`bool`	True if the string starts with any of the needle values, otherwise False.

def stripTags(self, allowed_tags: str | None = None) -> Stringable: (source) ¶

Remove HTML and PHP tags from the string.

Parameters
allowed_tags:`str \| None, optional`	Tags that should not be stripped. Default is None.

Returns
`Stringable`	A new Stringable instance with tags removed.

def studly(self) -> Stringable: (source) ¶

Convert to StudlyCase (PascalCase).

Replaces underscores, hyphens, and spaces with spaces, splits into words, capitalizes each word, and joins them without separators.

Returns
`Stringable`	A new Stringable instance in StudlyCase.

def substr(self, start: int, length: int | None = None) -> Stringable: (source) ¶

Return the portion of the string specified by start and length parameters.

Parameters
start:`int`	Starting position for substring extraction.
length:`int \| None, optional`	Length of substring to extract. If None, extracts to end of string. Default is None.

Returns
`Stringable`	A new Stringable instance containing the extracted substring.

Raises
`TypeError`	If start is not an integer or length is not an integer or None.

def substrCount(self, needle: str, offset: int = 0, length: int | None = None) -> int: (source) ¶

Count the number of substring occurrences in the string.

Parameters
needle:`str`	The substring to count occurrences of.
offset:`int, optional`	Starting position to begin the search. Default is 0.
length:`int \| None, optional`	Maximum length to search within. If None, searches to end. Default is None.

Returns
`int`	Number of non-overlapping occurrences of the needle substring.

Raises
`TypeError`	If needle is not a string, offset is not an integer, or length is not an integer or None.

def substrReplace(self, replace: str | list[str], offset: int | list[int] = 0, length: int | list[int] | None = None) -> Stringable: (source) ¶

Replace text within a portion of a string.

Parameters
replace:`str \| list[str]`	Replacement string(s)
offset:`int \| list[int], optional`	Starting position(s), by default 0
length:`int \| list[int] \| None, optional`	Length(s) to replace, by default None

Returns
`Stringable`	A new Stringable with replaced text

Raises
`TypeError`	If replace is not a string or list of strings.
`TypeError`	If offset is not an integer or list of integers.
`TypeError`	If length is not an integer, list of integers, or None.
`ValueError`	If any length value is negative.
`ValueError`	If lists have incompatible lengths.

def swap(self, map_dict: dict[str, str]) -> Stringable: (source) ¶

Swap multiple keywords in a string with other keywords.

Parameters
map_dict:`Dict[str, str]`	Dictionary mapping old values to new values.

Returns
`Stringable`	A new Stringable instance with swapped values.

Raises
`TypeError`	If map_dict is not a dictionary or contains non-string keys/values.

def swapCase(self) -> Stringable: (source) ¶

Swap the case of each character in the string.

Converts uppercase characters to lowercase and lowercase characters to uppercase, leaving other characters unchanged.

Parameters
None

Returns
`Stringable`	New Stringable instance with all character cases swapped.

def take(self, limit: int) -> Stringable: (source) ¶

Take a specified number of characters from the start or end.

Parameters
limit:`int`	Number of characters to take. Negative values take from the end.

Returns
`Stringable`	A new Stringable containing the taken characters.

def tap(self, callback: Callable[[Stringable], Any]) -> Stringable: (source) ¶

Call the callback with the string and return the string.

Parameters
callback:`Callable[[Stringable], Any]`	Function to execute with the string.

Returns
`Stringable`	The same Stringable instance.

def test(self, pattern: str) -> bool: (source) ¶

Test whether the string matches a regular expression pattern.

Parameters
pattern:`str`	Regular expression pattern to match.

Returns
`bool`	True if the string matches the pattern, otherwise False.

def title(self) -> Stringable: (source) ¶

Convert the string to title case.

Returns
`Stringable`	A new Stringable instance with each word capitalized.

def toBase64(self) -> Stringable: (source) ¶

Encode the string as Base64.

Returns
`Stringable`	A new Stringable instance containing the Base64-encoded string.

def toBoolean(self) -> bool: (source) ¶

Convert to a boolean value.

The string is considered True if it matches common truthy values such as "1", "true", "on", or "yes" (case-insensitive).

Returns
`bool`	True if the string represents a truthy value, otherwise False.

def toDate(self, format_str: str | None = '%Y-%m-%d') -> datetime | None: (source) ¶

Convert string to a datetime object.

Parameters
format_str:`str or None, optional`	Format string for parsing. Defaults to "%Y-%m-%d".

Returns
`datetime or None`	Parsed datetime object if successful, otherwise raises ValueError.

def toFloat(self) -> float: (source) ¶

Convert the string to a float.

Returns
`float`	Float representation of the string.

Raises
`ValueError`	If the string cannot be converted to a float.

def toHtmlString(self) -> Stringable: (source) ¶

Escape HTML entities in the string.

Escapes special HTML characters in the string to ensure safe HTML output.

Returns
`Stringable`	A new Stringable instance containing the HTML-escaped string.

def toInteger(self, base: int = 10) -> int: (source) ¶

Convert the string to an integer.

Parameters
base:`int, optional`	The base for conversion. Default is 10.

Returns
`int`	Integer representation of the string.

Raises
`ValueError`	If the string cannot be converted to an integer.

def transliterate(self, unknown: str = '?', *, strict: bool = False) -> Stringable: (source) ¶

Transliterate a string to its closest ASCII representation.

Parameters
unknown:`str, optional`	Character to use for unknown characters. Default is "?".
strict:`bool, optional`	Whether to be strict about transliteration. Default is False.

Returns
`Stringable`	A new Stringable with transliterated text.

def trim(self, characters: str | None = None) -> Stringable: (source) ¶

Trim characters from both ends of the string.

Parameters
characters:`str \| None, optional`	Characters to trim from both ends. If None, trims whitespace.

Returns
`Stringable`	New Stringable instance with specified characters trimmed.

def ucfirst(self) -> Stringable: (source) ¶

Capitalize the first character of the string.

Returns
`Stringable`	A new Stringable instance with the first character in uppercase.

def ucsplit(self) -> list[str]: (source) ¶

Split the string by uppercase characters.

Parameters
self:`Stringable`	The current string instance.

Returns
`list of str`	List of words split by uppercase characters, or the original string in a list if no split occurs.

def unwrap(self, before: str, after: str | None = None) -> Stringable: (source) ¶

Remove the specified prefix and suffix from the string.

Parameters
before:`str`	Prefix string to remove from the start.
after:`str \| None, optional`	Suffix string to remove from the end. If None, uses `before`.

Returns
`Stringable`	New Stringable instance with the specified prefix and suffix removed.

def upper(self) -> Stringable: (source) ¶

Convert all characters to uppercase.

Returns
`Stringable`	A new Stringable instance with all characters in uppercase.

def value(self) -> str: (source) ¶

Return the string value.

Returns
`str`	String representation of the current instance.

def when(self, condition: bool | Callable, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the given callback if condition is true.

Parameters
condition:`bool or callable`	The condition to evaluate.
callback:`callable`	The callback to execute if condition is true.
default:`callable or None, optional`	The callback to execute if condition is false. Default is None.

Returns
`Stringable`	Result of callback execution or self.

def whenContains(self, needles: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string contains a given substring.

Parameters
needles:`str \| list[str]`	Substring(s) to search for in the string.
callback:`Callable`	Function to execute if the condition is True.
default:`Callable \| None, optional`	Function to execute if the condition is False.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenContainsAll(self, needles: list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string contains all specified substrings.

Parameters
needles:`list[str]`	Substrings to search for in the string.
callback:`Callable`	Function to execute if all substrings are found.
default:`Callable \| None, optional`	Function to execute if not all substrings are found.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenDoesntEndWith(self, needles: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string does not end with the given substring(s).

Parameters
needles:`str \| list[str]`	Substring(s) to check at the end of the string.
callback:`Callable`	Function to execute if the condition is True.
default:`Callable \| None, optional`	Function to execute if the condition is False.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenDoesntStartWith(self, needles: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string does not start with the given substring(s).

Parameters
needles:`str or list[str]`	Substring(s) to check at the start of the string.
callback:`Callable`	Function to execute if the condition is True.
default:`Callable \| None, optional`	Function to execute if the condition is False.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenEmpty(self, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string is empty.

Parameters
callback:`Callable`	Function to execute if the string is empty.
default:`Callable \| None, optional`	Function to execute if the string is not empty.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenEndsWith(self, needles: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string ends with the given substring(s).

Parameters
needles:`str or list[str]`	Substring(s) to check at the end of the string.
callback:`Callable`	Function to execute if the condition is True.
default:`Callable \| None, optional`	Function to execute if the condition is False.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenExactly(self, value: str, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string exactly matches the given value.

Parameters
value:`str`	Value to compare for an exact match.
callback:`Callable`	Function to execute if the string matches exactly.
default:`Callable \| None, optional`	Function to execute if the string does not match exactly.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenIs(self, pattern: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string matches the given pattern.

Parameters
pattern:`str or list of str`	Pattern(s) to match against.
callback:`Callable`	Function to execute if the string matches the pattern.
default:`Callable or None, optional`	Function to execute if the string does not match the pattern.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenIsAscii(self, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string is 7-bit ASCII.

Parameters
callback:`Callable`	Function to execute if the string is ASCII.
default:`Callable \| None, optional`	Function to execute if the string is not ASCII.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenIsUlid(self, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string is a valid ULID.

Parameters
callback:`Callable`	Function to execute if the string is a valid ULID.
default:`Callable \| None, optional`	Function to execute if the string is not a valid ULID.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenIsUuid(self, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string is a valid UUID.

Parameters
callback:`Callable`	Function to execute if the string is a valid UUID.
default:`Callable \| None, optional`	Function to execute if the string is not a valid UUID.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenNotEmpty(self, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute the callback if the string is not empty.

Parameters
callback:`Callable`	Function to execute if the string is not empty.
default:`Callable \| None, optional`	Function to execute if the string is empty.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenNotExactly(self, value: str, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if string does not exactly match the given value.

Parameters
value:`str`	Value to compare for an exact match.
callback:`Callable`	Function to execute if the string does not match exactly.
default:`Callable \| None, optional`	Function to execute if the string matches exactly.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenStartsWith(self, needles: str | list[str], callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string starts with a given substring.

Parameters
needles:`str or list[str]`	Substring(s) to check at the start of the string.
callback:`Callable`	Function to execute if the condition is True.
default:`Callable \| None, optional`	Function to execute if the condition is False.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def whenTest(self, pattern: str, callback: Callable, default: Callable | None = None) -> Stringable: (source) ¶

Execute callback if the string matches the given regular expression.

Parameters
pattern:`str`	Regular expression pattern to match.
callback:`Callable`	Function to execute if the pattern matches.
default:`Callable \| None, optional`	Function to execute if the pattern does not match. Default is None.

Returns
`Stringable`	Result of callback execution or the original Stringable instance.

def wordCount(self, characters: str | None = None) -> int: (source) ¶

Count words in the string.

Parameters
characters:`str \| None, optional`	Additional characters to treat as word separators. Default is None.

Returns
`int`	Number of words in the string.

def words(self, words: int = 100, end: str = '...') -> Stringable: (source) ¶

Limit the string to a maximum number of words.

Parameters
words:`int, optional`	Maximum number of words to include. Default is 100.
end:`str, optional`	String to append if truncation occurs. Default is '...'.

Returns
`Stringable`	New Stringable instance containing at most the specified number of words, with the end string appended if truncation occurs.

def wordWrap(self, characters: int = 75, break_str: str = '\n', *, cut_long_words: bool = False) -> Stringable: (source) ¶

Wrap text to a specified line width.

Parameters
characters:`int, optional`	Maximum line width. Default is 75.
break_str:`str, optional`	String to insert at line breaks.
cut_long_words:`bool, optional`	If True, break long words. Default is False.

Returns
`Stringable`	New Stringable instance with wrapped text.

def wrap(self, before: str, after: str | None = None) -> Stringable: (source) ¶

Wrap the string with a prefix and suffix.

Parameters
before:`str`	Prefix to prepend to the string.
after:`str \| None, optional`	Suffix to append to the string. If None, uses `before`.

Returns
`Stringable`	New Stringable instance with the string wrapped by prefix and suffix.

def zFill(self, width: int) -> Stringable: (source) ¶

Pad the string with leading zeros to a given width.

Parameters
width:`int`	Total width of the resulting string.

Returns
`Stringable`	A new Stringable instance padded with leading zeros.

__slots__: tuple = (source) ¶

Undocumented