Reference¶
- class coolstring.CoolString(val, creator=None)
This class implements a CoolString object that is a string with additional features. It tries to implement as many magic methods as possible.
- Parameters:
val (str or any object that can be converted to a string.) – The value of the CoolString object.
creator (
CoolString
, optional) – An optional CoolString object that is used to copy the attributes of the creator object. It is used to create new CoolString objects with the same attributes as the creator object so settings get derived from the creator.
Public Methods¶
- CoolString.__init__(val, creator=None)¶
Initializes a CoolString object with the given value and an optional creator object.
- Parameters:
val (str or any object that can be converted to a string.) – The value of the CoolString object.
creator (
CoolString
, optional) – An optional CoolString object that is used to copy the attributes of the creator object.
- CoolString.__str__()¶
Returns the string representation of the CoolString object.
- Returns:
The string representation of the CoolString object.
- Return type:
str
- CoolString.__repr__()¶
Returns a string representation of the CoolString object for debugging purposes.
- Returns:
A meta styled string representation of the CoolString object.
- Return type:
str
- CoolString.__int__()¶
Converts the CoolString value to an integer.
- Returns:
The integer representation of the CoolString value.
- Return type:
int
- Raises:
ValueError – If the value cannot be converted to an integer.
- CoolString.__add__(other)¶
Adds the given value to the CoolString value.
- Parameters:
other (str or any object that can be converted to a string.) – The value to add to the CoolString value.
- Returns:
A new CoolString object with the concatenated value.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a string.
- CoolString.__sub__(other)¶
Removes the given value from the CoolString value.
- Parameters:
other (str or any object that can be converted to a string.) – The value to remove from the CoolString value.
- Returns:
A new CoolString object with the value after removal.
- Return type:
CoolString
- Raises:
ValueError – If the given value is not a substring of the CoolString value.
ValueError – If the given value cannot be converted to a string.
- CoolString.__mul__(other)¶
Multiplies the CoolString value by the given value.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to multiply the CoolString value by.
- Returns:
A new CoolString object with the multiplied value.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__truediv__(other)¶
Divides the CoolString value by the given value.
This method splits the CoolString value into parts of equal length based on length divided by the given value. If the other value is negative, the CoolString value is reversed before truncation and then reversed back. The remaining part is added as the last element in the list.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
A list of new CoolString objects with the truncated values.
- Return type:
list(
CoolString
)- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__floordiv__(other)¶
The same as __truediv__ for the floor division operator.
Only difference is that it does not return the remaining part as a new CoolString object.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
A new CoolString object with the truncated value.
- Return type:
list(
CoolString
)- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__mod__(other)¶
Modulo operator for CoolString.
This method splits the CoolString value into parts of equal length based on length modulo the given value and returns the remaining part as a new CoolString object.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
A new CoolString object with the remaining value after division.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__pow__(other)¶
Power operator for CoolString.
This method repeats the CoolString value length power given value times. If the other value is negative, it truncates the CoolString value to a fraction of its length. The behavior is the same as the default power operator, but applied on string and its length.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to raise the CoolString value to the power of.
- Returns:
A new CoolString object with the value raised to the power of the given value.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__len__()¶
Returns the length of the CoolString value.
- Returns:
The length of the CoolString value.
- Return type:
int
- CoolString.__rshift__(other)¶
Right shift operator for CoolString.
Depending on the shift mode, it either removes characters from the end of the string or performs a bitwise right shift on the string’s byte representation.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to shift the CoolString value by.
- Returns:
A new CoolString object with the shifted value.
- Return type:
CoolString
- Raises:
ValueError – If the given value is greater than the length of the CoolString value in string shift mode.
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__lshift__(other)¶
Left shift operator for CoolString.
Depending on the shift mode, it either adds spaces to the end of the string or performs a bitwise left shift on the string’s byte representation.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to shift the CoolString value by.
- Returns:
A new CoolString object with the shifted value.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__and__(other)¶
Bitwise AND operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise AND operation with.
- Returns:
A new CoolString object with the result of the bitwise AND operation.
- Return type:
CoolString
- CoolString.__or__(other)¶
Bitwise OR operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise OR operation with.
- Returns:
A new CoolString object with the result of the bitwise OR operation.
- Return type:
CoolString
- CoolString.__xor__(other)¶
Bitwise XOR operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise XOR operation with.
- Returns:
A new CoolString object with the result of the bitwise XOR operation.
- Return type:
CoolString
- CoolString.__lt__(other)¶
Less than operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is less than the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__gt__(other)¶
Greater than operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is greater than the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__le__(other)¶
Less than or equal to operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is less than or equal to the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__ge__(other)¶
Greater than or equal to operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is greater than or equal to the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__eq__(other)¶
Equality operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is equal to the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__ne__(other)¶
Not equal operator for CoolString. Functionality depends on the comparison mode.
- Parameters:
other (str or any object that can be converted to a string.) – The value to compare the CoolString value with.
- Returns:
True if the CoolString value is not equal to the other value, False otherwise.
- Return type:
bool
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString.__iadd__(other)¶
In-place addition operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to add to the CoolString value.
- Returns:
The CoolString object itself after addition.
- Return type:
CoolString
- CoolString.__isub__(other)¶
In-place subtraction operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to remove from the CoolString value.
- Returns:
The CoolString object itself after removal.
- Return type:
CoolString
- Raises:
ValueError – If the given value is not a substring of the CoolString value.
- CoolString.__imul__(other)¶
In-place multiplication operator for CoolString.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to multiply the CoolString value by.
- Returns:
The CoolString object itself after multiplication.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__idiv__(other)¶
In-place division operator for CoolString.
This method truncates the CoolString value to a fraction of its length based on the given value. This length is determined by the length of the CoolString divided by the given value. If the other value is negative, the CoolString value is reversed before truncation and then reversed back.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
The CoolString object itself after division.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__ifloordiv__(other)¶
In-place floor division operator for CoolString.
This method is similar to __idiv__.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
The CoolString object itself after floor division.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__imod__(other)¶
In-place modulo operator for CoolString.
This method truncates the CoolString value to a fraction of its length based on the given value. The length is determined by the length of the CoolString modulo the given value. If the other value is negative, the CoolString value is reversed before truncation and then reversed back.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
The CoolString object itself after modulo operation.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__ipow__(other)¶
In-place power operator for CoolString.
This method repeats the CoolString value length power given value times. If the other value is negative, it truncates the CoolString value to a fraction of its length. The behavior is the same as the default power operator, but applied on string and its length.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to raise the CoolString value to the power of.
- Returns:
The CoolString object itself after raising to the power.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__irshift__(other)¶
In-place right shift operator for CoolString.
Depending on the shift mode, it either removes characters from the end of the string or performs a bitwise right shift on the string’s byte representation.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to shift the CoolString value by.
- Returns:
The CoolString object itself after right shifting.
- Return type:
CoolString
- Raises:
ValueError – If the given value is greater than the length of the CoolString value in string shift mode.
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__ilshift__(other)¶
In-place left shift operator for CoolString.
Depending on the shift mode, it either adds spaces to the end of the string or performs a bitwise left shift on the string’s byte representation.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to shift the CoolString value by.
- Returns:
The CoolString object itself after left shifting.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__iand__(other)¶
In-place bitwise AND operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise AND operation with.
- Returns:
The CoolString object itself after the bitwise AND operation.
- Return type:
CoolString
- CoolString.__ior__(other)¶
In-place bitwise OR operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise OR operation with.
- Returns:
The CoolString object itself after the bitwise OR operation.
- Return type:
CoolString
- CoolString.__ixor__(other)¶
In-place bitwise XOR operator for CoolString.
- Parameters:
other (str or any object that can be converted to a string.) – The value to perform the bitwise XOR operation with.
- Returns:
The CoolString object itself after the bitwise XOR operation.
- Return type:
CoolString
- CoolString.__neg__()¶
Negation operator for CoolString.
This method converts the CoolString value to lowercase.
- Returns:
A new CoolString object with the value in lowercase.
- Return type:
CoolString
- CoolString.__pos__()¶
Positive operator for CoolString.
This method converts the CoolString value to uppercase.
- Returns:
A new CoolString object with the value in uppercase.
- Return type:
CoolString
- CoolString.__invert__()¶
Inversion operator for CoolString.
This method swaps the case of all characters in the CoolString value.
- Returns:
A new CoolString object with the value with swapped case.
- Return type:
CoolString
- CoolString.__trunc__()¶
Truncates the CoolString value to an integer.
- Returns:
The integer representation of the CoolString value.
- Return type:
int
- CoolString.__ceil__()¶
Ceil operator for CoolString.
This method rounds the CoolString value up to the nearest integer.
- Returns:
The integer representation of the CoolString value rounded up.
- Return type:
int
- CoolString.__floor__()¶
Floor operator for CoolString.
This method rounds the CoolString value down to the nearest integer.
- Returns:
The integer representation of the CoolString value rounded down.
- Return type:
int
- CoolString.__round__(ndigits=2)¶
Rounds the CoolString value to a specified number of digits.
This method prefers mathematical rounding to string length rounding if possible. If the value cannot be converted to a float, it rounds based on the length of the string. if string length round(length/base) * base is less than or equal to the length of the string, it truncates the string to that length, otherwise it pads the string with spaces.
- Parameters:
ndigits (int or str or any object that can be converted to an integer.) – The number of digits to round to. If negative, it rounds to the nearest base of 10.
- Returns:
A new CoolString object with the rounded value.
- Return type:
CoolString
- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__abs__()¶
Absolute value operator for CoolString.
This method returns a new CoolString object with all words starting with ‘-’ having their case swapped.
- Returns:
A new CoolString object with swapped case for words starting with ‘-‘.
- Return type:
CoolString
- CoolString.__divmod__(other)¶
Divmod operator for CoolString.
This method returns a tuple containing the result of true division and modulo operation on the CoolString value.
- Parameters:
other (int or str or any object that can be converted to an integer.) – The value to divide the CoolString value by.
- Returns:
A tuple containing the result of true division and modulo operation.
- Return type:
tuple(list(
CoolString
),CoolString
)- Raises:
ValueError – If the given value cannot be converted to a numeric.
- CoolString.__unicode__()¶
Returns the CoolString value as a Unicode string.
- Returns:
A Unicode string representation of the CoolString value.
- Return type:
str
- CoolString.__format__(format_spec)¶
Formats the CoolString value according to the given format specification. This method supports various format specifications such as:
“d”: Decimal representation of character codes
“b”: Binary representation of character codes
“o”: Octal representation of character codes
“x”: Hexadecimal representation of character codes
“X”: Uppercase hexadecimal representation of character codes
“,”: Comma-separated format every 3 characters
“_”: Underscore-separated format every 3 characters
“%”: Appends a percentage sign to the end of the string
“g”: General format, removing non-alphanumeric characters and replacing multiple whitespaces with a single space
“G”: General format, removing non-alphanumeric characters and multiple whitespaces with a single space, then converting to uppercase
“u”: Converts the CoolString value to uppercase
“l”: Converts the CoolString value to lowercase
“s”: Swaps the case of the CoolString value
“i”: Reverses the CoolString value
Any other format specifier is passed to the default format function.
- Parameters:
format_spec (str) – The format specification string.
- Returns:
A formatted string representation of the CoolString value.
- Return type:
str
- Raises:
ValueError – If the format specification is invalid.
- CoolString.__hash__()¶
Returns a hash of the CoolString object. This method hashes the CoolString value and its attributes by xoring the hash of the value and the hash of the attributes.
- Returns:
A hash value of the CoolString object.
- Return type:
int
- CoolString.__bool__()¶
Returns True if the CoolString value is not empty, False otherwise.
- Returns:
True if the CoolString value is not empty, False otherwise.
- Return type:
bool
- CoolString.__contains__(item)¶
Checks if the given item is in the CoolString value.
- Parameters:
item (str or any object that can be converted to a string.) – The item to check for in the CoolString value.
- Returns:
True if the item is in the CoolString value, False otherwise.
- Return type:
bool
- CoolString.__delattr__(name)¶
Deletes an attribute from the CoolString object.
This method prevents deletion of critical attributes such as ‘shiftmode’, ‘compmode’, ‘verbose’, and ‘val’.
- Parameters:
name (str) – The name of the attribute to delete.
- Raises:
AttributeError – If the attribute is critical and cannot be deleted.
- CoolString.__iter__()¶
Creates an iterator for the CoolString value.
- Returns:
An iterator for the CoolString value.
- Return type:
iterator
- CoolString.__call__(*args, **kwargs)¶
Calls the CoolString object as a function.
This method returns some cool string.
- Parameters:
args (tuple) – args
kwargs (dict) – kwargs
- Returns:
A random cool string.
- Return type:
str
- CoolString.__getitem__(idx)¶
Gets a portion of the CoolString value based on the given index or slice.
- Parameters:
idx (int or slice) – The index or slice to get from the CoolString value.
- Returns:
A new CoolString object with the value at the given index or slice.
- Return type:
CoolString
- Raises:
IndexError – If the index is out of range.
TypeError – If the index is not an integer or a slice.
- CoolString.__reversed__()¶
Reverses the CoolString value.
This method works similar to the ~-operator.
- Returns:
A new CoolString object with the value reversed.
- Return type:
CoolString
- CoolString.configure(**kwargs)¶
Configures the CoolString object with the given keyword arguments.
Valid keyword arguments include:
shiftmode: The shift mode, either “stringshift” or “bitshift”.
compmode: The comparison mode, can be “length”, “content”, “unicodesum”, or “unicodemax”.
verbose: A boolean indicating whether to enable verbose mode.
- Parameters:
kwargs (dict) – Keyword arguments to configure the CoolString object.
- Raises:
ValueError – If a given keyword argument is invalid.
Private Methods¶
- static CoolString.convertval(val)¶
Converts the given value to a string representation.
Throws a warning if the string representation is the identity representation of an object or class.
- Parameters:
val (any object that can be converted to a string.) – The value to convert.
- Returns:
The string representation of the value.
- Return type:
str
- static CoolString.classifyfloat(val)¶
Classifies the given value as a float and determines if it is positive or negative.
- Parameters:
val (any object that can be converted to a float.) – The value to classify.
- Returns:
A tuple containing the float value and a boolean indicating if it is positive.
- Return type:
tuple(float, bool)
- Raises:
ValueError – If the value cannot be converted to a float.
- static CoolString.classifyint(val)¶
Classifies the given value as an integer and determines if it is positive or negative.
- Parameters:
val (any object that can be converted to an integer.) – The value to classify.
- Returns:
A tuple containing the integer value and a boolean indicating if it is positive.
- Return type:
tuple(int, bool)
- Raises:
ValueError – If the value cannot be converted to an integer.
- static CoolString.matchlengths(val1, val2)¶
Matches the lengths of two strings by padding the shorter one with spaces.
- Parameters:
val1 (str) – String to match with val2.
val2 (str) – String to match with val1.
- Returns:
A tuple containing the two strings with matched lengths.
- Return type:
tuple(str, str)
- static CoolString.bitshift(val, shift, direction)¶
Performs a bitwise shift on the given string value.
This method encodes the string to bytes, converts it to an integer, shifts the bits, and then decodes it back to a string.
- Parameters:
val (str) – The string value to shift.
shift (int) – The number of bits to shift.
direction (str) – The direction of the shift, either “l” for left or “r” for right.
- Returns:
The new string value after the bitwise shift.
- Return type:
str
- Raises:
ValueError – If the direction is neither “l” nor “r”.
- CoolString._decode(val)¶
Decodes the given value.
- Parameters:
val (str) – The value to decode.
- Returns:
The decoded value.
- Return type:
str
- CoolString.getcompval(val)¶
Gets the comparison value of the given value based on the configured comparison mode.
- Parameters:
val (str) – The value to get the comparison value for.
- Returns:
The comparison value.
- Return type:
int or str
- Raises:
ValueError – If the comparison mode is invalid.
- CoolString._createnew(val)¶
Creates a new CoolString object with the given value and the same attributes as the creator.
- Parameters:
val (str or any object that can be converted to a string.) – The value for the new CoolString object.
- Returns:
A new CoolString object with the given value and the same attributes as the creator.
- Return type:
CoolString
- CoolString._verbose(*args, **kwargs)¶
Passes the given arguments to the print function if verbose mode is enabled.
- Parameters:
args (tuple) – args
kwargs (dict) – kwargs