Document caveats for encodeWith, fixes #15

Author: hasufell

System/OsString/Common.hs

@@ -218,15 +218,24 @@ unsafeEncodeUtf = either (error . displayException) id . encodeWith utf16le
 unsafeEncodeUtf = either (error . displayException) id . encodeWith utf8
 #endif
 
+#ifdef WINDOWS
 -- | Encode a 'String' with the specified encoding.
-encodeWith :: TextEncoding
+--
+-- Note: 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  -- ^ text encoding (wide char)
            -> String
            -> Either EncodingException PLATFORM_STRING
 encodeWith enc str = unsafePerformIO $ do
-#ifdef WINDOWS
   r <- try @SomeException $ GHC.withCStringLen enc str $ \cstr -> WindowsString <$> BS8.packCStringLen cstr
   evaluate $ force $ first (flip EncodingError Nothing . displayException) r
 #else
+-- | Encode a 'String' with the specified encoding.
+encodeWith :: TextEncoding
+           -> String
+           -> Either EncodingException PLATFORM_STRING
+encodeWith enc str = unsafePerformIO $ do
   r <- try @SomeException $ GHC.withCStringLen enc str $ \cstr -> PosixString <$> BSP.packCStringLen cstr
   evaluate $ force $ first (flip EncodingError Nothing . displayException) r
 #endif

System/OsString/Internal.hs

@@ -55,9 +55,13 @@ encodeUtf = fmap OsString . PF.encodeUtf
 unsafeEncodeUtf :: HasCallStack => String -> OsString
 unsafeEncodeUtf = OsString . PF.unsafeEncodeUtf
 
--- | Encode an 'OsString' given the platform specific encodings.
+-- | 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)
            -> String
            -> Either EncodingException OsString
 #if defined(mingw32_HOST_OS) || defined(__MINGW32__)