0
# Combining and Augmenting
1

2
Functions for merging, combining, and augmenting iterables.
3

4
## Capabilities
5

6
### Interleaving Operations
7

8
Combine multiple iterables in various patterns.
9

10
```python { .api }
11
def interleave(*iterables):
12
    """
13
    Round-robin interleaving of multiple iterables.
14
    
15
    Args:
16
        *iterables: Variable number of iterables to interleave
17
        
18
    Returns:
19
        Iterator yielding items in round-robin fashion
20
    """
21

22
def interleave_longest(*iterables):
23
    """
24
    Interleave until the longest iterable is exhausted.
25
    
26
    Args:
27
        *iterables: Variable number of iterables to interleave
28
        
29
    Returns:
30
        Iterator yielding items until longest is exhausted
31
    """
32

33
def interleave_evenly(iterables, lengths=None):
34
    """
35
    Interleave with even distribution based on lengths.
36
    
37
    Args:
38
        iterables: Sequence of iterables to interleave
39
        lengths: Optional sequence of lengths for distribution
40
        
41
    Returns:
42
        Iterator with evenly distributed items
43
    """
44

45
def roundrobin(*iterables):
46
    """
47
    Round-robin tournament scheduling of iterables.
48
    
49
    Args:
50
        *iterables: Variable number of iterables
51
        
52
    Returns:
53
        Iterator yielding items in round-robin order
54
    """
55
```
56

57
**Usage Examples:**
58

59
```python
60
from more_itertools import interleave, roundrobin
61

62
# Basic interleaving
63
result = list(interleave([1, 2, 3], ['a', 'b', 'c']))
64
# Result: [1, 'a', 2, 'b', 3, 'c']
65

66
# Multiple iterables
67
result = list(interleave([1, 2], ['a', 'b'], ['x', 'y']))
68
# Result: [1, 'a', 'x', 2, 'b', 'y']
69

70
# Round-robin (alias for interleave)
71
result = list(roundrobin('ABC', '12'))
72
# Result: ['A', '1', 'B', '2', 'C']
73
```
74

75
### Zip Operations
76

77
Enhanced zip operations with special behaviors.
78

79
```python { .api }
80
def zip_equal(*iterables):
81
    """
82
    Zip iterables ensuring they have equal lengths.
83
    
84
    Args:
85
        *iterables: Iterables to zip together
86
        
87
    Returns:
88
        Iterator of tuples
89
        
90
    Raises:
91
        UnequalIterablesError: If iterables have different lengths
92
    """
93

94
def zip_offset(*iterables, offsets=None, longest=False, fillvalue=None):
95
    """
96
    Zip iterables with specified offsets.
97
    
98
    Args:
99
        *iterables: Iterables to zip
100
        offsets: Sequence of offset values for each iterable
101
        longest: If True, continue until longest is exhausted
102
        fillvalue: Value for padding when longest=True
103
        
104
    Returns:
105
        Iterator of offset-aligned tuples
106
    """
107

108
def zip_broadcast(*objects, scalar_types=(str, bytes), strict=False):
109
    """
110
    Zip with broadcasting of scalar values.
111
    
112
    Args:
113
        *objects: Objects to zip (iterables and scalars)
114
        scalar_types: Types considered as scalars
115
        strict: If True, require equal lengths for iterables
116
        
117
    Returns:
118
        Iterator with broadcasted values
119
    """
120
```
121

122
### Augmenting Operations
123

124
Add elements or modify iterables without removing items.
125

126
```python { .api }
127
def intersperse(element, iterable, n=1):
128
    """
129
    Insert element between items in iterable.
130
    
131
    Args:
132
        element: Element to insert
133
        iterable: Input iterable
134
        n: Insert after every n items
135
        
136
    Returns:
137
        Iterator with element interspersed
138
    """
139

140
def padded(iterable, fillvalue=None, n=None, next_multiple=False):
141
    """
142
    Pad iterable to specified length.
143
    
144
    Args:
145
        iterable: Input iterable
146
        fillvalue: Value to use for padding
147
        n: Target length (optional)
148
        next_multiple: If True, pad to next multiple of len
149
        
150
    Returns:
151
        Iterator padded to specified length
152
    """
153

154
def repeat_each(iterable, n=2):
155
    """
156
    Repeat each item n times.
157
    
158
    Args:
159
        iterable: Input iterable
160
        n: Number of times to repeat each item
161
        
162
    Returns:
163
        Iterator with each item repeated n times
164
    """
165

166
def repeat_last(iterable, default=None):
167
    """
168
    Repeat the last item indefinitely.
169
    
170
    Args:
171
        iterable: Input iterable
172
        default: Value to repeat if iterable is empty
173
        
174
    Returns:
175
        Iterator that repeats last item forever
176
    """
177

178
def prepend(value, iterator):
179
    """
180
    Prepend a value to an iterator.
181
    
182
    Args:
183
        value: Value to prepend
184
        iterator: Iterator to prepend to
185
        
186
    Returns:
187
        Iterator with value prepended
188
    """
189
```
190

191
**Usage Examples:**
192

193
```python
194
from more_itertools import intersperse, repeat_each, prepend
195

196
# Intersperse separator
197
result = list(intersperse(',', ['a', 'b', 'c']))
198
# Result: ['a', ',', 'b', ',', 'c']
199

200
# Repeat each item
201
result = list(repeat_each([1, 2, 3], 2))
202
# Result: [1, 1, 2, 2, 3, 3]
203

204
# Prepend value
205
result = list(prepend('start', [1, 2, 3]))
206
# Result: ['start', 1, 2, 3]
207
```
208

209
### Chaining and Value Operations
210

211
Combine values and iterables in flexible ways.
212

213
```python { .api }
214
def value_chain(*args):
215
    """
216
    Chain values and iterables together.
217
    
218
    Args:
219
        *args: Mix of values and iterables to chain
220
        
221
    Returns:
222
        Iterator chaining all values and iterable contents
223
    """
224
```
225

226
**Usage Examples:**
227

228
```python
229
from more_itertools import value_chain
230

231
# Chain values and iterables
232
result = list(value_chain(1, [2, 3], 4, [5, 6]))
233
# Result: [1, 2, 3, 4, 5, 6]
234
```
235

236
### Count and Cycle Operations
237

238
Counting and cycling augmentation.
239

240
```python { .api }
241
def count_cycle(iterable, n=None):
242
    """
243
    Cycle through iterable while counting occurrences.
244
    
245
    Args:
246
        iterable: Input iterable to cycle
247
        n: Maximum number of cycles (None for infinite)
248
        
249
    Returns:
250
        Iterator of (count, item) tuples
251
    """
252

253
def ncycles(iterable, n):
254
    """
255
    Repeat iterable n times.
256
    
257
    Args:
258
        iterable: Input iterable to repeat
259
        n: Number of repetitions
260
        
261
    Returns:
262
        Iterator repeating iterable n times
263
    """
264
```
265

266
### Side Effects
267

268
Apply side effects while iterating.
269

270
```python { .api }
271
def side_effect(func, iterable, chunk_size=None, before=None, after=None):
272
    """
273
    Apply side effect function while iterating.
274
    
275
    Args:
276
        func: Side effect function to apply
277
        iterable: Input iterable
278
        chunk_size: Process in chunks of this size
279
        before: Function to call before processing
280
        after: Function to call after processing
281
        
282
    Returns:
283
        Iterator yielding original items while applying side effects
284
    """
285
```