Skip to content

string_encoding

shortfx.fxString.string_encoding

String Encoding and Decoding Functions.

This module provides functions for encoding and decoding strings using common formats such as Base64, URL percent-encoding, HTML entities, and classical ciphers (Caesar, Vigenère).

Key Features: - Base64 encoding and decoding - URL percent-encoding and decoding - HTML entity escaping and unescaping - Caesar cipher (shift cipher) - Vigenère cipher (polyalphabetic substitution)

Functions

caesar_cipher(text: str, shift: int, decrypt: bool = False) -> str

Applies the Caesar (shift) cipher to a string.

Shifts each alphabetical character by shift positions in the alphabet. Non-alphabetic characters are left unchanged.

Parameters:

Name Type Description Default
text str

The input string to encrypt or decrypt.

 required
shift int

Number of positions to shift (1-25).

 required
decrypt bool

If True, reverse the shift to decrypt.

 False

Returns:

Type Description
str

The encrypted or decrypted string.

Raises:

Type Description
TypeError

If text is not a string or shift is not an integer.
Example

caesar_cipher("Hello World", 3) 'Khoor Zruog' caesar_cipher("Khoor Zruog", 3, decrypt=True) 'Hello World'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def caesar_cipher(text: str, shift: int, decrypt: bool = False) -> str:
    """Applies the Caesar (shift) cipher to a string.

    Shifts each alphabetical character by *shift* positions in the
    alphabet. Non-alphabetic characters are left unchanged.

    Args:
        text: The input string to encrypt or decrypt.
        shift: Number of positions to shift (1-25).
        decrypt: If True, reverse the shift to decrypt.

    Returns:
        The encrypted or decrypted string.

    Raises:
        TypeError: If text is not a string or shift is not an integer.

    Example:
        >>> caesar_cipher("Hello World", 3)
        'Khoor Zruog'
        >>> caesar_cipher("Khoor Zruog", 3, decrypt=True)
        'Hello World'

    Complexity: O(n)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    if not isinstance(shift, int):
        raise TypeError("shift must be an integer")

    if decrypt:
        shift = -shift

    shift = shift % 26
    result: list[str] = []

    for ch in text:

        if "A" <= ch <= "Z":
            result.append(chr((ord(ch) - 65 + shift) % 26 + 65))
        elif "a" <= ch <= "z":
            result.append(chr((ord(ch) - 97 + shift) % 26 + 97))
        else:
            result.append(ch)

    return "".join(result)

decode_base64(encoded_text: str, encoding: str = 'utf-8') -> str

Decodes a Base64-encoded string back to plain text.

Parameters:

Name Type Description Default
encoded_text str

The Base64-encoded string.

 required
encoding str

Character encoding to use after Base64 decoding.

 'utf-8'

Returns:

Type Description
str

The decoded plain text string.

Raises:

Type Description
TypeError

If encoded_text is not a string.
ValueError

If the input is not valid Base64.
Example

decode_base64("SGVsbG8gV29ybGQ=") 'Hello World'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def decode_base64(encoded_text: str, encoding: str = "utf-8") -> str:
    """Decodes a Base64-encoded string back to plain text.

    Args:
        encoded_text: The Base64-encoded string.
        encoding: Character encoding to use after Base64 decoding.

    Returns:
        The decoded plain text string.

    Raises:
        TypeError: If encoded_text is not a string.
        ValueError: If the input is not valid Base64.

    Example:
        >>> decode_base64("SGVsbG8gV29ybGQ=")
        'Hello World'

    Complexity: O(n)
    """
    if not isinstance(encoded_text, str):
        raise TypeError("encoded_text must be a string")

    try:
        return base64.b64decode(encoded_text).decode(encoding)
    except Exception as exc:
        raise ValueError(f"Invalid Base64 input: {exc}") from exc

decode_html_entities(encoded_text: str) -> str

Unescapes HTML entities back to their original characters.

Parameters:

Name Type Description Default
encoded_text str

The string with HTML entities.

 required

Returns:

Type Description
str

The string with entities replaced by actual characters.

Raises:

Type Description
TypeError

If encoded_text is not a string.
Example

decode_html_entities('<b>bold</b>') 'bold'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def decode_html_entities(encoded_text: str) -> str:
    """Unescapes HTML entities back to their original characters.

    Args:
        encoded_text: The string with HTML entities.

    Returns:
        The string with entities replaced by actual characters.

    Raises:
        TypeError: If encoded_text is not a string.

    Example:
        >>> decode_html_entities('&lt;b&gt;bold&lt;/b&gt;')
        '<b>bold</b>'

    Complexity: O(n)
    """
    if not isinstance(encoded_text, str):
        raise TypeError("encoded_text must be a string")

    return html.unescape(encoded_text)

decode_url(encoded_text: str) -> str

Decodes a URL percent-encoded string back to plain text.

Parameters:

Name Type Description Default
encoded_text str

The percent-encoded string.

 required

Returns:

Type Description
str

The decoded plain text string.

Raises:

Type Description
TypeError

If encoded_text is not a string.
Example

decode_url("hello%20world%26foo%3Dbar") 'hello world&foo=bar'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def decode_url(encoded_text: str) -> str:
    """Decodes a URL percent-encoded string back to plain text.

    Args:
        encoded_text: The percent-encoded string.

    Returns:
        The decoded plain text string.

    Raises:
        TypeError: If encoded_text is not a string.

    Example:
        >>> decode_url("hello%20world%26foo%3Dbar")
        'hello world&foo=bar'

    Complexity: O(n)
    """
    if not isinstance(encoded_text, str):
        raise TypeError("encoded_text must be a string")

    return unquote(encoded_text)

encode_base64(text: str, encoding: str = 'utf-8') -> str

Encodes a string to Base64 representation.

Parameters:

Name Type Description Default
text str

The input string to encode.

 required
encoding str

Character encoding to use before Base64 conversion.

 'utf-8'

Returns:

Type Description
str

The Base64-encoded string.

Raises:

Type Description
TypeError

If text is not a string.
Example

encode_base64("Hello World") 'SGVsbG8gV29ybGQ='

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def encode_base64(text: str, encoding: str = "utf-8") -> str:
    """Encodes a string to Base64 representation.

    Args:
        text: The input string to encode.
        encoding: Character encoding to use before Base64 conversion.

    Returns:
        The Base64-encoded string.

    Raises:
        TypeError: If text is not a string.

    Example:
        >>> encode_base64("Hello World")
        'SGVsbG8gV29ybGQ='

    Complexity: O(n)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    return base64.b64encode(text.encode(encoding)).decode("ascii")

encode_html_entities(text: str) -> str

Escapes HTML special characters into their entity equivalents.

Converts characters like <, >, &, " and ' into safe HTML entities (e.g. &lt;, &gt;, &amp;).

Parameters:

Name Type Description Default
text str

The input string containing HTML characters.

 required

Returns:

Type Description
str

The string with HTML characters escaped.

Raises:

Type Description
TypeError

If text is not a string.
Example

encode_html_entities('') '<script>alert("xss")</script>'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def encode_html_entities(text: str) -> str:
    """Escapes HTML special characters into their entity equivalents.

    Converts characters like ``<``, ``>``, ``&``, ``"`` and ``'`` into
    safe HTML entities (e.g. ``&lt;``, ``&gt;``, ``&amp;``).

    Args:
        text: The input string containing HTML characters.

    Returns:
        The string with HTML characters escaped.

    Raises:
        TypeError: If text is not a string.

    Example:
        >>> encode_html_entities('<script>alert("xss")</script>')
        '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'

    Complexity: O(n)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    return html.escape(text, quote=True)

encode_url(text: str, safe: str = '') -> str

Encodes a string using URL percent-encoding (RFC 3986).

Parameters:

Name Type Description Default
text str

The input string to encode.

 required
safe str

Characters that should not be encoded.

 ''

Returns:

Type Description
str

The percent-encoded string.

Raises:

Type Description
TypeError

If text is not a string.
Example

encode_url("hello world&foo=bar") 'hello%20world%26foo%3Dbar'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def encode_url(text: str, safe: str = "") -> str:
    """Encodes a string using URL percent-encoding (RFC 3986).

    Args:
        text: The input string to encode.
        safe: Characters that should not be encoded.

    Returns:
        The percent-encoded string.

    Raises:
        TypeError: If text is not a string.

    Example:
        >>> encode_url("hello world&foo=bar")
        'hello%20world%26foo%3Dbar'

    Complexity: O(n)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    return quote(text, safe=safe)

vigenere_cipher(text: str, key: str, decrypt: bool = False) -> str

Applies the Vigenère polyalphabetic cipher to a string.

Each alphabetical character is shifted by the corresponding character in key. Non-alphabetic characters pass through unchanged and do not consume a key character.

Parameters:

Name Type Description Default
text str

The input string to encrypt or decrypt.

 required
key str

Alphabetic key string (e.g. "SECRET").

 required
decrypt bool

If True, reverse the operation to decrypt.

 False

Returns:

Type Description
str

The encrypted or decrypted string.

Raises:

Type Description
TypeError

If text or key is not a string.
ValueError

If key is empty or contains non-alphabetic characters.
Example

vigenere_cipher("Hello World", "KEY") 'Rijvs Uyvjn' vigenere_cipher("Rijvs Uyvjn", "KEY", decrypt=True) 'Hello World'

Complexity: O(n)

Source code in shortfx/fxString/string_encoding.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def vigenere_cipher(
    text: str, key: str, decrypt: bool = False
) -> str:
    """Applies the Vigenère polyalphabetic cipher to a string.

    Each alphabetical character is shifted by the corresponding
    character in *key*. Non-alphabetic characters pass through
    unchanged and do not consume a key character.

    Args:
        text: The input string to encrypt or decrypt.
        key: Alphabetic key string (e.g. ``"SECRET"``).
        decrypt: If True, reverse the operation to decrypt.

    Returns:
        The encrypted or decrypted string.

    Raises:
        TypeError: If text or key is not a string.
        ValueError: If key is empty or contains non-alphabetic characters.

    Example:
        >>> vigenere_cipher("Hello World", "KEY")
        'Rijvs Uyvjn'
        >>> vigenere_cipher("Rijvs Uyvjn", "KEY", decrypt=True)
        'Hello World'

    Complexity: O(n)
    """
    if not isinstance(text, str):
        raise TypeError("text must be a string")

    if not isinstance(key, str):
        raise TypeError("key must be a string")

    if not key or not key.isalpha():
        raise ValueError("key must be a non-empty alphabetic string")

    key_upper = key.upper()
    key_len = len(key_upper)
    result: list[str] = []
    ki = 0

    for ch in text:

        if ch.isalpha():
            shift = ord(key_upper[ki % key_len]) - 65

            if decrypt:
                shift = -shift

            base = 65 if ch.isupper() else 97
            result.append(chr((ord(ch) - base + shift) % 26 + base))
            ki += 1
        else:
            result.append(ch)

    return "".join(result)