Manual review of builtin functions: set-frozenset

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: heikkitoivonen

docs/builtins/frozenset_func.md

@@ -14,6 +14,9 @@ The `frozenset()` function creates immutable sets from iterables.
 
 ## Basic Usage
 
+!!! note "Element order in examples"
+    Frozensets are unordered. The element order shown in comments below is illustrative; actual `repr()` output is not guaranteed and may differ between runs, Python versions, or hash-randomization settings.
+
 ### Create Empty Frozenset
 
 ```python
@@ -25,25 +28,25 @@ fs = frozenset()  # frozenset()
 
 ```python
 # O(n) - where n = list length
-fs = frozenset([1, 2, 3])           # frozenset({1, 2, 3})
-fs = frozenset([1, 2, 2, 3, 3, 3])  # frozenset({1, 2, 3})
+fs = frozenset([1, 2, 3])           # frozenset({2, 1, 3})
+fs = frozenset([1, 2, 2, 3, 3, 3])  # frozenset({1, 3, 2})
 ```
 
 ### From String
 
 ```python
 # O(n) - where n = string length
-fs = frozenset("hello")    # frozenset({'h', 'e', 'l', 'o'})
-fs = frozenset("aabbcc")   # frozenset({'a', 'b', 'c'})
+fs = frozenset("hello")    # frozenset({'h', 'l', 'e', 'o'})
+fs = frozenset("aabbcc")   # frozenset({'c', 'b', 'a'})
 ```
 
 ### From Other Iterables
 
 ```python
 # O(n) - where n = iterable length
-fs = frozenset((1, 2, 3))         # frozenset({1, 2, 3})
+fs = frozenset((1, 2, 3))         # frozenset({2, 1, 3})
 fs = frozenset({1, 2, 3})         # frozenset({1, 2, 3})
-fs = frozenset(range(5))          # frozenset({0, 1, 2, 3, 4})
+fs = frozenset(range(5))          # frozenset({0, 2, 1, 3, 4})
 fs = frozenset(map(str, [1, 2]))  # frozenset({'1', '2'})
 ```
 
@@ -165,93 +168,6 @@ fs1 & fs2      # frozenset({2, 3})
 s1 & fs2       # {2, 3} - mixed works
 ```
 
-## Practical Examples
-
-### Config Validation
-
-```python
-# O(n) - validate against allowed values
-ALLOWED_ROLES = frozenset(["admin", "user", "guest"])
-
-def validate_roles(roles):
-    role_set = frozenset(roles)  # O(n)
-    if not role_set.issubset(ALLOWED_ROLES):  # O(n)
-        raise ValueError("Invalid roles")
-    return role_set
-
-valid = validate_roles(["admin", "user"])
-```
-
-### Cache Configuration
-
-```python
-# O(n) - use frozenset as cache key
-from functools import lru_cache
-
-@lru_cache(maxsize=256)
-def analyze_features(features):
-    # features is frozenset - hashable
-    return len(features)
-
-result = analyze_features(frozenset(["a", "b", "c"]))  # O(3)
-```
-
-### Immutable Data Structure
-
-```python
-# O(n) - create immutable set for safety
-class DataSet:
-    def __init__(self, items):
-        self._items = frozenset(items)  # O(n)
-    
-    def get_items(self):
-        return self._items  # O(1) - safe to return
-    
-    def has_item(self, item):
-        return item in self._items  # O(1)
-
-dataset = DataSet([1, 2, 3])
-items = dataset.get_items()  # frozenset({1, 2, 3})
-# Can't modify items
-```
-
-### Database Index Key
-
-```python
-# O(n) - frozenset for database queries
-def query_by_tags(tags):
-    tag_set = frozenset(tags)  # O(n)
-    
-    # Use as cache key
-    cache_key = ("tags", tag_set)  # O(1)
-    
-    # Query database
-    return db_lookup[cache_key]  # O(1)
-
-results = query_by_tags(["python", "database"])
-```
-
-### Unique Constraint
-
-```python
-# O(n) - enforce uniqueness immutably
-class User:
-    def __init__(self, permissions):
-        self.permissions = frozenset(permissions)  # O(n)
-    
-    def __hash__(self):
-        return hash(self.permissions)  # O(1) - hashable
-    
-    def __eq__(self, other):
-        return self.permissions == other.permissions
-
-user1 = User(["read", "write"])
-user2 = User(["read", "write"])
-
-# Can use in set
-unique_users = {user1, user2}  # Only one (equal)
-```
-
 ## Edge Cases
 
 ### Empty Frozenset

docs/builtins/set_func.md

@@ -14,6 +14,9 @@ The `set()` function creates sets from iterables or creates empty sets.
 
 ## Basic Usage
 
+!!! note "Element order in examples"
+    Sets are unordered. The element order shown in comments below is illustrative; actual `repr()` output is not guaranteed and may differ between runs, Python versions, or hash-randomization settings.
+
 ### Create Empty Set
 
 ```python
@@ -25,25 +28,25 @@ s = set()  # set()
 
 ```python
 # O(n) - where n = list length
-s = set([1, 2, 3])           # {1, 2, 3}
-s = set([1, 2, 2, 3, 3, 3])  # {1, 2, 3} - duplicates removed
+s = set([1, 2, 3])           # {3, 2, 1}
+s = set([1, 2, 2, 3, 3, 3])  # {2, 1, 3} - duplicates removed
 ```
 
 ### From String
 
 ```python
 # O(n) - where n = string length
-s = set("hello")      # {'h', 'e', 'l', 'o'}
-s = set("aabbcc")     # {'a', 'b', 'c'} - each char once
+s = set("hello")      # {'e', 'h', 'l', 'o'}
+s = set("aabbcc")     # {'c', 'b', 'a'} - each char once
 ```
 
 ### From Other Iterables
 
 ```python
 # O(n) - where n = iterable length
-s = set((1, 2, 3))          # {1, 2, 3} (from tuple)
-s = set({1, 2, 3})          # {1, 2, 3} (from set - copy)
-s = set(range(5))           # {0, 1, 2, 3, 4}
+s = set((1, 2, 3))          # {2, 1, 3} (from tuple)
+s = set({1, 2, 3})          # {1, 3, 2} (from set - copy)
+s = set(range(5))           # {0, 2, 1, 3, 4}
 s = set(map(str, [1, 2]))   # {'1', '2'} (from generator)
 ```
 
@@ -52,7 +55,7 @@ s = set(map(str, [1, 2]))   # {'1', '2'} (from generator)
 ```python
 # O(n) - uses dict keys
 d = {"a": 1, "b": 2, "c": 3}
-s = set(d)  # {'a', 'b', 'c'} - only keys, not values
+s = set(d)  # {'b', 'a', 'c'} - only keys, not values
 ```
 
 ## Complexity Details
@@ -76,10 +79,10 @@ s = set(items)  # O(10)
 ```python
 # O(n) - automatic deduplication
 items = [1, 1, 2, 2, 3, 3]
-s = set(items)  # O(6) - creates {1, 2, 3}
+s = set(items)  # O(6) - creates {2, 1, 3}
 
-# Useful for removing duplicates while preserving unordered
-unique = set("mississippi")  # {'m', 'i', 's', 'p'}
+# Useful for removing duplicates
+unique = set("mississippi")  # {'i', 'm', 's', 'p'}
 ```
 
 ### From String
@@ -98,7 +101,7 @@ long = set("a" * 1000)  # O(1000) - {'a'} (one item!)
 # O(n) - fastest way to remove duplicates
 items = [1, 2, 2, 3, 3, 3, 4]
 unique = set(items)  # O(7)
-# {1, 2, 3, 4}
+# {2, 1, 3, 4}
 
 # Back to list if needed
 unique_list = list(set(items))  # O(n)
@@ -120,7 +123,7 @@ s1 = set([1, 2, 3])
 s2 = set([2, 3, 4])
 
 intersection = s1 & s2      # {2, 3} - O(n)
-union = s1 | s2            # {1, 2, 3, 4} - O(n)
+union = s1 | s2            # {2, 1, 3, 4} - O(n)
 difference = s1 - s2       # {1} - O(n)
 symmetric_diff = s1 ^ s2   # {1, 4} - O(n)
 ```
@@ -166,54 +169,6 @@ if 500 in s:    # O(1)
     pass
 ```
 
-## Practical Examples
-
-### Find Unique Words
-
-```python
-# O(n) - get unique words from text
-text = "the quick brown fox jumps over the lazy dog"
-words = text.split()
-unique_words = set(words)  # O(n)
-# {'the', 'quick', 'brown', 'fox', ...}
-```
-
-### Common Elements
-
-```python
-# O(n) - find common items
-list1 = [1, 2, 3, 4, 5]
-list2 = [4, 5, 6, 7, 8]
-
-set1 = set(list1)  # O(n)
-set2 = set(list2)  # O(m)
-
-common = set1 & set2  # {4, 5} - O(min(n,m))
-```
-
-### Unique Count
-
-```python
-# O(n) - count unique items
-data = [1, 1, 2, 2, 2, 3, 3, 3, 3, 4]
-unique_count = len(set(data))  # O(n) - 4 unique
-
-# Useful for analytics
-log_entries = ["error", "error", "warning", "error"]
-unique_types = set(log_entries)  # O(n)
-```
-
-### Validate Uniqueness
-
-```python
-# O(n) - check if all unique
-def has_duplicates(items):
-    return len(items) != len(set(items))  # O(n)
-
-assert not has_duplicates([1, 2, 3])     # True - unique
-assert has_duplicates([1, 2, 2])         # False - duplicates
-```
-
 ## Edge Cases
 
 ### Empty Set