Document caveats for encodeWith

See haskell/os-string#15
haskell · May 12, 2024 · e7cb9fd · e7cb9fd
1 parent 9e4fd51
commit e7cb9fd
Showing 1 changed file with 5 additions and 1 deletion.
diff --git a/System/OsPath/Internal.hs b/System/OsPath/Internal.hs
@@ -56,8 +56,12 @@ unsafeEncodeUtf :: HasCallStack => String -> OsString
 unsafeEncodeUtf = OS.unsafeEncodeUtf
 
 -- | Encode a 'FilePath' with the specified encoding.
+--
+-- Note: on windows, we expect a "wide char" encoding (e.g. UCS-2 or UTF-16). Anything
+-- that works with @Word16@ boundaries. Picking an incompatible encoding may crash
+-- filepath operations.
 encodeWith :: TextEncoding  -- ^ unix text encoding
-           -> TextEncoding  -- ^ windows text encoding
+           -> TextEncoding  -- ^ windows text encoding (wide char)
            -> FilePath
            -> Either EncodingException OsPath
 encodeWith = OS.encodeWith