0
# Container Methods
1

2
Utility functions that operate on containers to provide common patterns for container manipulation, state checking, and conditional creation.
3

4
## Capabilities
5

6
### Conditional Container Creation
7

8
Create containers based on conditions without explicit branching logic.
9

10
```python { .api }
11
def cond(
12
    condition: bool,
13
    success_value: T,
14
    failure_value: E
15
) -> Result[T, E]:
16
    """Create Success or Failure based on condition"""
17
```
18

19
Usage examples:
20

21
```python
22
from returns.methods import cond
23

24
# Conditional Result creation
25
def validate_age(age: int) -> Result[int, str]:
26
    return cond(
27
        age >= 18,
28
        success_value=age,
29
        failure_value="Must be 18 or older"
30
    )
31

32
result = validate_age(20)  # Success(20)
33
result = validate_age(15)  # Failure("Must be 18 or older")
34
```
35

36
### Container Partitioning  
37

38
Split collections of containers into successful and failed groups.
39

40
```python { .api }
41
def partition(
42
    containers: Iterable[Result[T, E]]
43
) -> tuple[list[T], list[E]]:
44
    """Partition Results into successes and failures"""
45
```
46

47
Usage examples:
48

49
```python
50
from returns.methods import partition
51
from returns.result import Success, Failure
52

53
results = [
54
    Success(1),
55
    Failure("error1"),
56
    Success(2),
57
    Failure("error2"),
58
    Success(3)
59
]
60

61
successes, failures = partition(results)
62
# successes: [1, 2, 3]
63
# failures: ["error1", "error2"]
64
```
65

66
### Safe Container Unwrapping
67

68
Extract values from containers with safe fallback behavior.
69

70
```python { .api }
71
def unwrap_or_failure(
72
    container: Result[T, E],
73
    default_failure: F
74
) -> T | F:
75
    """Safely unwrap or return default failure"""
76
```
77

78
Usage examples:
79

80
```python
81
from returns.methods import unwrap_or_failure
82
from returns.result import Success, Failure
83

84
# Safe extraction with default
85
success_value = unwrap_or_failure(Success(42), "default")  # 42
86
failure_value = unwrap_or_failure(Failure("error"), "default")  # "default"
87

88
# Useful for chaining operations
89
def process_data(data: Result[str, str]) -> str:
90
    clean_data = unwrap_or_failure(data, "")
91
    return clean_data.upper()
92
```
93

94
## Integration with Containers
95

96
These methods work seamlessly with all container types and provide building blocks for more complex functional programming patterns:
97

98
```python
99
from returns.methods import cond, partition
100
from returns.result import Success, Failure
101
from returns.pipeline import flow
102

103
# Complex validation pipeline
104
def validate_user_data(users: list[dict]) -> tuple[list[dict], list[str]]:
105
    validated = [
106
        cond(
107
            user.get("age", 0) >= 18 and "@" in user.get("email", ""),
108
            success_value=user,
109
            failure_value=f"Invalid user: {user.get('name', 'unknown')}"
110
        )
111
        for user in users
112
    ]
113
    
114
    return partition(validated)
115

116
# Usage
117
users = [
118
    {"name": "John", "age": 25, "email": "john@example.com"},
119
    {"name": "Jane", "age": 16, "email": "jane@example.com"},
120
    {"name": "Bob", "age": 30, "email": "invalid-email"}
121
]
122

123
valid_users, errors = validate_user_data(users)
124
```
125

126
These utilities enable cleaner, more declarative code when working with container collections and conditional logic.