Repository: apple/swift-nio
File: Sources/NIOFileSystem/NIOFilePath.swift (Swift)

Code before:
///
/// var unnormalizedPath: NIOFilePath = "/home/user/../user/./documents"
/// // Normalize the path
/// unnormalizedPath.lexicallyNormalize()
/// print(unnormalizedPath) // "/home/user/documents"
/// ```
public struct NIOFilePath: Equatable, Hashable, Sendable, ExpressibleByStringLiteral, CustomStringConvertible,
    CustomDebugStringConvertible
{
    /// The underlying `SystemPackage.FilePath` instance that ``NIOFilePath`` uses.
    package var underlying: SystemPackage.FilePath

    /// Creates a ``NIOFilePath`` given an underlying `SystemPackage.FilePath` instance.
    ///
    /// - Parameter underlying: The `SystemPackage.FilePath` to use as the underlying backing for ``NIOFilePath``.
    public init(_ underlying: SystemPackage.FilePath) {
        self.underlying = underlying
    }

    #if canImport(System)
    /// Creates a ``NIOFilePath`` given an underlying `System.FilePath` instance.
    ///
    /// - Parameter underlying: The `System.FilePath` instance to use to create this ``NIOFilePath`` instance.
    @available(macOS 12.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)
    public init(_ underlying: System.FilePath) {
        self.underlying = .init(underlying.string)
    }
    #endif

    /// Represents a root of a file path.
    ///
    /// On Unix, a root is simply the directory separator `/`.
    ///
    /// On Windows, a root contains the entire path prefix up to and including the final separator.
    ///
    /// Examples:
    /// * Unix:
    ///   * `/`
    /// * Windows:
    ///   * `C:\`
    ///   * `C:`
    ///   * `\`
    ///   * `\\server\share\`
    ///   * `\\?\UNC\server\share\`
    ///   * `\\?\Volume{12345678-abcd-1111-2222-123445789abc}\`
    public struct Root: Equatable, Hashable, Sendable {
        package let underlying: SystemPackage.FilePath.Root

        /// Creates a ``NIOFilePath/Root`` given an underlying `SystemPackage.FilePath.Root` instance.
        ///
        /// - Parameter underlying: The `SystemPackage.FilePath.Root` to use as the underlying backing for ``NIOFilePath/Root``.

Review comment (suggestion):
The conversion to String can be lossy so you'll need to use `withPlatformString` here instead which gives you the underlying bytes. 

Code after:
    /// Creates an instance representing an empty and null-terminated filepath.
    public init() {
        self.underlying = .init()
    }

    /// Creates an instance corresponding to the file path represented by the provided string.
    ///
    /// - Parameter string: A string whose Unicode encoded contents to use as the contents of the path
    public init(_ string: String) {
        self.underlying = .init(string)
    }

    /// Creates an instance from a string literal.
    ///
    /// - Parameter stringLiteral: A string literal whose Unicode encoded contents to use as the contents of the path.
    public init(stringLiteral: String) {
        self.init(stringLiteral)
    }

    /// A textual representation of the file path.
    ///
    /// If the content of the path isn't a well-formed Unicode string, this replaces invalid bytes with U+FFFD. See `String.init(decoding:)`
    public var description: String {
        self.underlying.description
    }

    /// A textual representation of the file path, suitable for debugging.
    ///
    /// If the content of the path isn't a well-formed Unicode string, this replaces invalid bytes with U+FFFD. See `String.init(decoding:)`
    public var debugDescription: String {
        self.underlying.debugDescription
    }
}

extension SystemPackage.FilePath {
    /// Creates a `SystemPackage.FilePath` from a ``NIOFilePath`` instance.
    public init(_ filePath: NIOFilePath) {
        self = filePath.underlying
    }
}

#if canImport(System)
@available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)
extension System.FilePath {
    /// Creates a `System.FilePath` from a ``NIOFilePath`` instance.
    public init(_ filePath: NIOFilePath) {
        self = filePath.underlying.withPlatformString {
            System.FilePath(platformString: $0)
        }
    }
}