0
# Path Manipulation
1

2
Path segment manipulation, directory/filename extraction, and path normalization with support for both string and array-based operations.
3

4
## Capabilities
5

6
### Path Segment Access
7

8
Methods for working with individual path segments as arrays or by index.
9

10
```javascript { .api }
11
/**
12
 * Get or set path segments
13
 * @param segment - Segment index (number) or new segments (string/array)
14
 * @param value - New value for specific segment (when segment is number)
15
 * @param build - Whether to rebuild URI immediately
16
 * @returns Segment string, segments array, or URI instance for chaining
17
 */
18
segment(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI;
19

20
/**
21
 * Get or set decoded path segments
22
 * @param segment - Segment index (number) or new segments (string/array)
23
 * @param value - New value for specific segment (when segment is number)
24
 * @param build - Whether to rebuild URI immediately
25
 * @returns Decoded segment string, segments array, or URI instance for chaining
26
 */
27
segmentCoded(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI;
28
```
29

30
**Usage Examples:**
31

32
```javascript
33
const uri = new URI('http://example.com/path/to/file.html');
34

35
// Get all segments as array
36
console.log(uri.segment()); // ['path', 'to', 'file.html']
37

38
// Get specific segment by index
39
console.log(uri.segment(0)); // 'path'
40
console.log(uri.segment(1)); // 'to'
41
console.log(uri.segment(2)); // 'file.html'
42
console.log(uri.segment(-1)); // 'file.html' (last segment)
43

44
// Set specific segment
45
uri.segment(1, 'from');
46
console.log(uri.pathname()); // '/path/from/file.html'
47

48
// Set all segments
49
uri.segment(['api', 'v1', 'users', '123']);
50
console.log(uri.pathname()); // '/api/v1/users/123'
51

52
// Set from string
53
uri.segment('/new/path/segments');
54
console.log(uri.segment()); // ['new', 'path', 'segments']
55

56
// Handle encoded segments
57
const encodedUri = new URI('http://example.com/hello%20world/caf%C3%A9');
58
console.log(encodedUri.segment()); // ['hello%20world', 'caf%C3%A9']
59
console.log(encodedUri.segmentCoded()); // ['hello world', 'café']
60

61
// Set encoded segments
62
encodedUri.segmentCoded(0, 'encoded path segment');
63
console.log(encodedUri.segment(0)); // 'encoded%20path%20segment'
64
```
65

66
### Static Path Utilities
67

68
Static methods for working with paths independently of URI instances.
69

70
```javascript { .api }
71
/**
72
 * Join multiple path segments into a single path
73
 * @param paths - Variable number of path strings to join
74
 * @returns Joined path string
75
 */
76
URI.joinPaths(...paths: string[]): string;
77

78
/**
79
 * Find common path between two paths
80
 * @param one - First path string
81
 * @param two - Second path string
82
 * @returns Common path prefix
83
 */
84
URI.commonPath(one: string, two: string): string;
85
```
86

87
**Usage Examples:**
88

89
```javascript
90
// Join paths
91
const joined = URI.joinPaths('/api', 'v1', 'users', '123');
92
console.log(joined); // '/api/v1/users/123'
93

94
const joinedRelative = URI.joinPaths('docs', '../assets', 'images', 'logo.png');
95
console.log(joinedRelative); // 'docs/../assets/images/logo.png'
96

97
// Find common path
98
const common1 = URI.commonPath('/api/v1/users/123', '/api/v1/users/456');
99
console.log(common1); // '/api/v1/users'
100

101
const common2 = URI.commonPath('/docs/guide/intro.html', '/docs/api/reference.html');
102
console.log(common2); // '/docs'
103

104
const common3 = URI.commonPath('/completely/different', '/another/path');
105
console.log(common3); // '/'
106
```
107

108
### Advanced Path Operations
109

110
More complex path manipulation operations for real-world scenarios.
111

112
**Usage Examples:**
113

114
```javascript
115
const uri = new URI('http://example.com/docs/api/reference.html');
116

117
// Insert segments
118
const segments = uri.segment();
119
segments.splice(1, 0, 'v2'); // Insert 'v2' after 'docs'
120
uri.segment(segments);
121
console.log(uri.pathname()); // '/docs/v2/api/reference.html'
122

123
// Remove segments
124
const currentSegments = uri.segment();
125
currentSegments.splice(-1, 1); // Remove last segment
126
uri.segment(currentSegments);
127
console.log(uri.pathname()); // '/docs/v2/api'
128

129
// Append segments
130
uri.segment(uri.segment().concat(['endpoint', 'details']));
131
console.log(uri.pathname()); // '/docs/v2/api/endpoint/details'
132

133
// Replace multiple segments
134
const pathSegments = uri.segment();
135
pathSegments.splice(1, 2, 'latest', 'documentation'); // Replace v2/api with latest/documentation
136
uri.segment(pathSegments);
137
console.log(uri.pathname()); // '/docs/latest/documentation/endpoint/details'
138

139
// Handle edge cases
140
const rootUri = new URI('http://example.com/');
141
console.log(rootUri.segment()); // ['']
142

143
const emptyUri = new URI('http://example.com');
144
console.log(emptyUri.segment()); // []
145

146
// Work with trailing slashes
147
const trailingUri = new URI('http://example.com/path/to/dir/');
148
console.log(trailingUri.segment()); // ['path', 'to', 'dir', '']
149
console.log(trailingUri.segment(-1)); // '' (empty string for trailing slash)
150
```
151

152
### Path Encoding Operations
153

154
Methods for handling encoded path segments and special characters.
155

156
```javascript { .api }
157
/**
158
 * Encode single path segment
159
 * @param segment - Path segment to encode
160
 * @returns Encoded path segment
161
 */
162
URI.encodePathSegment(segment: string): string;
163

164
/**
165
 * Decode single path segment
166
 * @param segment - Encoded path segment to decode
167
 * @returns Decoded path segment
168
 */
169
URI.decodePathSegment(segment: string): string;
170

171
/**
172
 * Decode entire path
173
 * @param path - Encoded path to decode
174
 * @returns Decoded path
175
 */
176
URI.decodePath(path: string): string;
177

178
/**
179
 * Re-encode path with current encoding settings
180
 * @param path - Path to re-encode
181
 * @returns Re-encoded path
182
 */
183
URI.recodePath(path: string): string;
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
// Encode path segments
190
const encoded = URI.encodePathSegment('hello world/special&chars');
191
console.log(encoded); // 'hello%20world%2Fspecial%26chars'
192

193
// Decode path segments
194
const decoded = URI.decodePathSegment('hello%20world%2Fspecial%26chars');
195
console.log(decoded); // 'hello world/special&chars'
196

197
// Work with full paths
198
const fullPath = URI.decodePath('/docs/hello%20world/caf%C3%A9.html');
199
console.log(fullPath); // '/docs/hello world/café.html'
200

201
// Re-encode paths
202
const reencoded = URI.recodePath('/docs/hello world/café.html');
203
console.log(reencoded); // '/docs/hello%20world/caf%C3%A9.html'
204

205
// Use in URI construction
206
const uri = new URI('http://example.com/');
207
uri.segment(['docs', 'hello world', 'café.html']);
208
console.log(uri.pathname()); // '/docs/hello%20world/caf%C3%A9.html'
209

210
// Access decoded versions
211
console.log(uri.segmentCoded()); // ['docs', 'hello world', 'café.html']
212
console.log(uri.segmentCoded(1)); // 'hello world'
213
```
214

215
### Path Normalization
216

217
Path normalization operations to clean up and standardize paths.
218

219
**Usage Examples:**
220

221
```javascript
222
const uri = new URI('http://example.com/docs/../api/./users/../groups/./list');
223

224
// Before normalization
225
console.log(uri.pathname()); // '/docs/../api/./users/../groups/./list'
226

227
// Normalize path
228
uri.normalizePath();
229
console.log(uri.pathname()); // '/api/groups/list'
230

231
// Complex normalization examples
232
const complex = new URI('http://example.com/a/b/c/../../d/./e/../f');
233
complex.normalizePath();
234
console.log(complex.pathname()); // '/a/d/f'
235

236
// Absolute vs relative path normalization
237
const relative = new URI('../docs/./guide/../api/users');
238
relative.normalizePath();
239
console.log(relative.pathname()); // '../docs/api/users'
240

241
// Edge cases
242
const edgeCase1 = new URI('http://example.com/../../outside');
243
edgeCase1.normalizePath();
244
console.log(edgeCase1.pathname()); // '/outside' (can't go above root)
245

246
const edgeCase2 = new URI('http://example.com/./');
247
edgeCase2.normalizePath();
248
console.log(edgeCase2.pathname()); // '/'
249
```