0
# Multiple Duration Formatting
1

2
Multiple duration formatting enables coordinated formatting of arrays of duration objects, ensuring consistent output across all durations in the set.
3

4
## Capabilities
5

6
### Multiple Duration Format Method
7

8
Format arrays of duration objects with coordinated trimming and consistent token usage.
9

10
```javascript { .api }
11
/**
12
 * Format multiple durations with coordinated output
13
 * @param durationsArray - Array of moment duration objects
14
 * @param template - Format template string or function (optional)
15
 * @param precision - Number of decimal places or integer truncation (optional) 
16
 * @param settings - Configuration object (optional)
17
 * @returns Array of formatted duration strings
18
 */
19
moment.duration.format(durationsArray, [template] [, precision] [, settings]): string[];
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
var durations = [
26
    moment.duration(1, "minute"),
27
    moment.duration(1, "hour"),
28
    moment.duration(1, "day")
29
];
30

31
// Basic multiple formatting
32
moment.duration.format(durations, "h:mm:ss");
33
// ["0:01:00", "1:00:00", "24:00:00"]
34

35
// With settings
36
moment.duration.format(durations, "d [days], h [hours], m [minutes]", {
37
    trim: "both"
38
});
39
// ["1 minute", "1 hour", "1 day"]
40

41
// Coordinated trimming demonstration
42
moment.duration.format([
43
    moment.duration(30, "seconds"),
44
    moment.duration(2, "hours"),
45
    moment.duration(3, "days")
46
], "d [days], h [hours], m [minutes], s [seconds]");
47
// [
48
//   "0 days, 0 hours, 0 minutes, 30 seconds",
49
//   "0 days, 2 hours, 0 minutes, 0 seconds", 
50
//   "3 days, 0 hours, 0 minutes, 0 seconds"
51
// ]
52
```
53

54
## Coordinated Processing
55

56
### Unified Token Analysis
57

58
The multiple duration formatter analyzes all durations to determine which tokens should appear in the final output, ensuring consistency across the result set.
59

60
**Internal Process:**
61
1. Format each duration individually with `returnMomentTypes: true`
62
2. Merge token types from all durations
63
3. Apply `largest` setting if specified to limit output types
64
4. Re-format all durations using the unified token types
65

66
**Usage Examples:**
67

68
```javascript
69
// Different magnitude durations get consistent formatting
70
var mixedDurations = [
71
    moment.duration(30, "seconds"),      // Small magnitude
72
    moment.duration(2, "hours"),         // Medium magnitude  
73
    moment.duration(3, "days")           // Large magnitude
74
];
75

76
moment.duration.format(mixedDurations, "w [w] d [d] h [h] m [m] s [s]");
77
// All outputs include the same token types:
78
// [
79
//   "0w 0d 0h 0m 30s",
80
//   "0w 0d 2h 0m 0s",
81
//   "0w 3d 0h 0m 0s"  
82
// ]
83

84
// Compare with individual formatting (inconsistent)
85
mixedDurations.map(d => d.format("w [w] d [d] h [h] m [m] s [s]"));
86
// [
87
//   "30s",      // Only seconds shown
88
//   "2h",       // Only hours shown  
89
//   "3d"        // Only days shown
90
// ]
91
```
92

93
### Coordinated Trimming
94

95
Trimming behavior is coordinated across all durations to maintain consistent output structure.
96

97
```javascript
98
var durations = [
99
    moment.duration(1, "second"),
100
    moment.duration(1, "minute"), 
101
    moment.duration(1, "hour")
102
];
103

104
// Without coordination, individual formatting would vary
105
durations.map(d => d.format("h [hours], m [minutes], s [seconds]"));
106
// [
107
//   "1 second",           // Different structure
108
//   "1 minute",           // Different structure
109
//   "1 hour"              // Different structure
110
// ]
111

112
// With coordinated formatting
113
moment.duration.format(durations, "h [hours], m [minutes], s [seconds]");
114
// [
115
//   "0 hours, 0 minutes, 1 second",    // Consistent structure
116
//   "0 hours, 1 minute, 0 seconds",    // Consistent structure
117
//   "1 hour, 0 minutes, 0 seconds"     // Consistent structure
118
// ]
119
```
120

121
### Largest Setting Application
122

123
The `largest` setting is applied to the unified token set, not individual durations.
124

125
```javascript
126
var durations = [
127
    moment.duration(7322, "seconds"),      // 2 hours, 2 minutes, 2 seconds
128
    moment.duration(3661, "seconds"),      // 1 hour, 1 minute, 1 second
129
    moment.duration(61, "seconds")         // 1 minute, 1 second
130
];
131

132
moment.duration.format(durations, "h [hours], m [minutes], s [seconds]", {
133
    largest: 2
134
});
135
// All durations show the same 2 largest token types:
136
// [
137
//   "2 hours, 2 minutes",   // Hours and minutes (largest 2)
138
//   "1 hour, 1 minute",     // Hours and minutes (largest 2)  
139
//   "0 hours, 1 minute"     // Hours and minutes (largest 2)
140
// ]
141
```
142

143
## Settings Inheritance
144

145
All settings available for single duration formatting apply to multiple duration formatting, with the same settings object used to format each individual duration.
146

147
### Shared Configuration
148

149
```javascript
150
var durations = [
151
    moment.duration(3661.5, "seconds"),
152
    moment.duration(7200.7, "seconds")
153
];
154

155
var settings = {
156
    template: "h [hrs] m [min] s [sec]",
157
    precision: 1,
158
    trim: "small",
159
    usePlural: true
160
};
161

162
moment.duration.format(durations, settings);
163
// [
164
//   "1.0 hr 1.0 min 1.5 sec",
165
//   "2.0 hrs 0.0 min 0.7 sec"  
166
// ]
167
```
168

169
### Template Functions with Multiple Durations
170

171
Template functions receive the same context for each duration but can access individual duration values:
172

173
```javascript
174
function adaptiveTemplate() {
175
    var seconds = this.duration.asSeconds();
176
    
177
    if (seconds < 60) {
178
        return "s [seconds]";
179
    } else if (seconds < 3600) {
180
        return "m:ss";
181
    } else {
182
        return "h:mm:ss";
183
    }
184
}
185

186
var durations = [
187
    moment.duration(30, "seconds"),
188
    moment.duration(90, "seconds"),
189
    moment.duration(3661, "seconds")
190
];
191

192
// Note: Template functions work differently with multiple durations
193
// Each duration gets its own template evaluation
194
moment.duration.format(durations, adaptiveTemplate);
195
// Results depend on individual duration magnitudes
196
```
197

198
## Error Handling
199

200
Invalid durations in the array are treated consistently with single duration formatting:
201

202
```javascript
203
var durations = [
204
    moment.duration(60, "seconds"),
205
    moment.duration(NaN, "seconds"),  // Invalid
206
    moment.duration(120, "seconds")
207
];
208

209
moment.duration.format(durations, "m:ss");
210
// [
211
//   "1:00",
212
//   "0:00",    // Invalid duration treated as 0
213
//   "2:00"
214
// ]
215
```