06 — Strings & Text

# Python str stores Unicode CODE POINTS (integers in 0..0x10FFFF).
# This is NEITHER bytes (the on-disk encoding) NOR graphemes (what users see).

# ── The three-level model ──
s = "café"
print(len(s))                     # 4 — four CODE POINTS: c, a, f, é
print(len(s.encode("utf-8")))     # 5 — five BYTES (é is 2 bytes in UTF-8: 0xC3 0xA9)
# User-perceived "characters" (grapheme clusters) can differ from both — see below

# ── Code point ↔ integer conversion ──
print(ord("A"))                   # 65 — the integer value of code point U+0041
print(chr(65))                    # 'A' — code point U+0041 → str
print(hex(ord("é")))             # '0xe9' — U+00E9 (precomposed form)

# ── Production: Unicode normalization before comparison/lookup ──
# "é" has TWO valid Unicode representations:
#   NFC (precomposed):  U+00E9      — one code point, "é"
#   NFD (decomposed):   U+0065 + U+0301 — "e" + combining acute accent — two code points
import unicodedata

nfc = "é"                          # precomposed — \u00e9
nfd = "e\u0301"                    # decomposed — "e" + combining accent

print(nfc == nfd)                  # False! — different code point sequences
print(len(nfc), len(nfd))          # 1 2 — different lengths!
print(unicodedata.normalize("NFC", nfd) == nfc)   # True — normalize before comparing

# ANTI-PATTERN: using user-supplied strings as dict keys without normalization
# A user who types "café" via a compose key vs. a dead-key accent produces
# different code point sequences — they'll be DIFFERENT keys in a dict.
user_input_a = "café"              # NFC from one input method
user_input_b = "cafe\u0301"        # NFD from another input method
cache = {user_input_a: "data"}
print(user_input_b in cache)       # False — miss! same visual string, different code points

# CORRECT: normalize all strings to NFC before use as keys/comparisons
def normalize_key(s: str) -> str:
    return unicodedata.normalize("NFC", s)

cache = {normalize_key(user_input_a): "data"}
print(normalize_key(user_input_b) in cache)   # True — normalized comparison works

# ── Grapheme clusters: what users perceive vs. what len() reports ──
# Emoji and flags are the most common source of "len() is wrong" bugs.

flag = "🇺🇸"                       # US flag — two REGIONAL INDICATOR code points
print(len(flag))                   # 2 — two code points, one visible glyph
print([hex(ord(c)) for c in flag]) # ['0x1f1fa', '0x1f1f8'] — U=U+1F1FA, S=U+1F1F8

family = "👨‍👩‍👧‍👦"                  # family emoji — joined by ZWJ (zero-width joiner)
print(len(family))                 # 7 — seven code points (4 people + 3 ZWJ), one glyph
# ZWJ = U+200D — invisible joiner that tells the renderer to combine adjacent emoji

# For correct user-perceived character counting, use the \X regex grapheme cluster
# (requires the `regex` module, not stdlib `re`, which lacks grapheme support)
# import regex
# print(len(regex.findall(r"\X", family)))   # 1 — one grapheme cluster

# ── Production: truncating user-display text at grapheme boundaries ──
# Naive truncation at code point N can split a combining character from its base
def truncate_naive(s: str, max_len: int) -> str:
    """WRONG — can split combining accents from their base characters."""
    return s[:max_len]              # cuts at code point boundary, not grapheme boundary

def truncate_safe(s: str, max_len: int) -> str:
    """CORRECT — counts grapheme clusters, not code points (requires `regex` module)."""
    import regex
    clusters = regex.findall(r"\X", s)
    return "".join(clusters[:max_len])

# "café" in NFD form: c, a, f, e, combining-acute — truncating at 4 drops the accent
nfd_cafe = "cafe\u0301"
print(truncate_naive(nfd_cafe, 4))   # "cafe" — accent lost! displays as "cafe" not "café"
# print(truncate_safe(nfd_cafe, 4))  # "café" — correct, keeps the combining cluster intact

s = "Hello, World!"
print(s[0])          # 'H'
print(s[-1])           # '!'          — negative indices count from the end
print(s[7:12])           # 'World'
print(s[:5])                # 'Hello'
print(s[7:])                  # 'World!'
print(s[::-1])                  # '!dlroW ,olleH'  — reverse via step -1
print(s[::2])                     # 'Hlo ol!'        — every other character
print(s[100:200])                   # ''  — out-of-range slices never raise, just return empty/partial

s = "  Hello, World!  "

print(s.strip())            # "Hello, World!"      — trims whitespace both sides
print(s.lower())               # "  hello, world!  "
print(s.upper())                  # "  HELLO, WORLD!  "
print(s.replace("World", "Python"))  # "  Hello, Python!  "
print(s.strip().split(", "))            # ['Hello', 'World!']
print("-".join(["a", "b", "c"]))          # "a-b-c"
print("Hello".startswith("He"))              # True
print("Hello".endswith("lo"))                  # True
print("Hello".find("l"))                         # 2  — index of first match, -1 if absent
print("Hello".index("z"))                          # ValueError: substring not found (raises!)
print("hello world".title())                          # "Hello World"
print("  ".isspace())                                    # True
print("42".isdigit())                                      # True
print("Hello123".isalnum())                                   # True

name = "Ada"
age = 36
pi = 3.14159265

print(f"{name} is {age} years old")             # Ada is 36 years old
print(f"{name!r}")                                 # 'Ada'  — !r calls repr()
print(f"{pi:.2f}")                                    # 3.14  — format spec: 2 decimal places
print(f"{1234567:,}")                                    # 1,234,567 — thousands separator
print(f"{age:>5}")                                          # "   36" — right-aligned, width 5
print(f"{age:<5}|")                                            # "36   |" — left-aligned
print(f"{age:^5}|")                                                # " 36  |" — centered

# Self-documenting expressions (3.8+) — the = specifier
print(f"{name=}")                                                     # name='Ada'
print(f"{age * 2=}")                                                    # age * 2=72

# Nested expressions and method calls work directly inside braces
items = ["apple", "banana"]
print(f"Items: {', '.join(items).upper()}")                              # Items: APPLE, BANANA

name, score = "Ada", 98

# %-formatting — legacy, still seen in logging calls and old codebases
print("%s scored %d" % (name, score))

# .format() — flexible, verbose, used when the template is data (not a literal)
print("{} scored {}".format(name, score))
template = "{n} scored {s}"      # e.g. loaded from a config file or translation string
print(template.format(n=name, s=score))

# f-strings — fastest, clearest, the default choice for literal templates (3.6+)
print(f"{name} scored {score}")

text = "café"                    # str — a sequence of Unicode code points
encoded = text.encode("utf-8")     # bytes — b'caf\xc3\xa9', é takes 2 bytes in UTF-8
print(encoded)                       # b'caf\xc3\xa9'
print(len(text))                       # 4 — 4 code points
print(len(encoded))                      # 5 — 5 bytes (é is 2 bytes in UTF-8)

decoded = encoded.decode("utf-8")           # back to str
print(decoded == text)                        # True

# Wrong encoding raises or corrupts silently depending on the codec
try:
    encoded.decode("ascii")
except UnicodeDecodeError as e:
    print(f"Failed: {e}")

# Mixing str and bytes is a TypeError — Python 3 refuses to silently coerce
try:
    "hello" + b"world"
except TypeError as e:
    print(e)   # can only concatenate str (not "bytes") to str

# BAD — relies on the platform's default encoding, which varies!
# (open() without encoding= uses locale.getpreferredencoding(), which is
#  UTF-8 on most modern Linux/macOS but can be cp1252 on some Windows setups)
with open("data.txt") as f:      # DANGEROUS: implicit encoding
    content = f.read()

# GOOD — always specify encoding explicitly for portable, reproducible I/O
with open("data.txt", encoding="utf-8") as f:
    content = f.read()

import re

text = "Contact: alice@example.com or bob@work.org"

# search — first match anywhere
match = re.search(r"[\w.+-]+@[\w-]+\.[\w.-]+", text)
print(match.group())          # alice@example.com

# findall — all non-overlapping matches
emails = re.findall(r"[\w.+-]+@[\w-]+\.[\w.-]+", text)
print(emails)                   # ['alice@example.com', 'bob@work.org']

# sub — replace matches
redacted = re.sub(r"[\w.+-]+@[\w-]+\.[\w.-]+", "[REDACTED]", text)
print(redacted)                    # Contact: [REDACTED] or [REDACTED]

# Named groups for structured extraction
pattern = re.compile(r"(?P<user>[\w.+-]+)@(?P<domain>[\w.-]+)")
m = pattern.search("alice@example.com")
print(m.group("user"), m.group("domain"))   # alice example.com
print(m.groupdict())                            # {'user': 'alice', 'domain': 'example.com'}

# Compile once, reuse many times, in hot paths (loops, per-request validation)
EMAIL_RE = re.compile(r"^[\w.+-]+@[\w-]+\.[\w.-]+$")

def is_valid_email(s: str) -> bool:
    return bool(EMAIL_RE.match(s))    # match() anchors at the START only, not the end!

print(is_valid_email("alice@example.com"))     # True
print(is_valid_email("alice@example.com\nmalicious"))   # True in re.match with $!

STRICT_EMAIL_RE = re.compile(r"^[\w.+-]+@[\w-]+\.[\w.-]+\Z")

def is_valid_email_strict(s: str) -> bool:
    return bool(STRICT_EMAIL_RE.match(s))

print(is_valid_email_strict("alice@example.com\nmalicious"))   # False — correctly rejected

# Or, more idiomatically:
def is_valid_email_fullmatch(s: str) -> bool:
    return bool(re.fullmatch(r"[\w.+-]+@[\w-]+\.[\w.-]+", s))

print(is_valid_email_fullmatch("alice@example.com\nmalicious"))   # False

# BAD in a loop — each += creates a brand-new string (strings are immutable),
# making naive concatenation O(n^2) for n appends in the worst case
result = ""
for i in range(10000):
    result += str(i)   # allocates a new string of growing size EVERY iteration

# GOOD — collect pieces, join once (join is O(n))
parts = [str(i) for i in range(10000)]
result = "".join(parts)

flag = "🇺🇸"
name = "café"

print(len(flag))
print(len(name))
print(name[3])
print(name.encode("utf-8")[3])