Path Manipulation

/**
 * Get or set path segments
 * @param segment - Segment index (number) or new segments (string/array)
 * @param value - New value for specific segment (when segment is number)
 * @param build - Whether to rebuild URI immediately
 * @returns Segment string, segments array, or URI instance for chaining
 */
segment(segment?: number | string | string[], value?: string, build?: boolean): string | string[] | URI;

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

const uri = new URI('http://example.com/path/to/file.html');

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

// Get specific segment by index
console.log(uri.segment(0)); // 'path'
console.log(uri.segment(1)); // 'to'
console.log(uri.segment(2)); // 'file.html'
console.log(uri.segment(-1)); // 'file.html' (last segment)

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

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

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

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

// Set encoded segments
encodedUri.segmentCoded(0, 'encoded path segment');
console.log(encodedUri.segment(0)); // 'encoded%20path%20segment'

/**
 * Join multiple path segments into a single path
 * @param paths - Variable number of path strings to join
 * @returns Joined path string
 */
URI.joinPaths(...paths: string[]): string;

/**
 * Find common path between two paths
 * @param one - First path string
 * @param two - Second path string
 * @returns Common path prefix
 */
URI.commonPath(one: string, two: string): string;

// Join paths
const joined = URI.joinPaths('/api', 'v1', 'users', '123');
console.log(joined); // '/api/v1/users/123'

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

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

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

const common3 = URI.commonPath('/completely/different', '/another/path');
console.log(common3); // '/'

const uri = new URI('http://example.com/docs/api/reference.html');

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

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

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

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

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

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

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

/**
 * Encode single path segment
 * @param segment - Path segment to encode
 * @returns Encoded path segment
 */
URI.encodePathSegment(segment: string): string;

/**
 * Decode single path segment
 * @param segment - Encoded path segment to decode
 * @returns Decoded path segment
 */
URI.decodePathSegment(segment: string): string;

/**
 * Decode entire path
 * @param path - Encoded path to decode
 * @returns Decoded path
 */
URI.decodePath(path: string): string;

/**
 * Re-encode path with current encoding settings
 * @param path - Path to re-encode
 * @returns Re-encoded path
 */
URI.recodePath(path: string): string;

// Encode path segments
const encoded = URI.encodePathSegment('hello world/special&chars');
console.log(encoded); // 'hello%20world%2Fspecial%26chars'

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

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

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

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

// Access decoded versions
console.log(uri.segmentCoded()); // ['docs', 'hello world', 'café.html']
console.log(uri.segmentCoded(1)); // 'hello world'

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

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

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

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

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

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

const edgeCase2 = new URI('http://example.com/./');
edgeCase2.normalizePath();
console.log(edgeCase2.pathname()); // '/'