From 570444d3137acb9d3f38839e6563a48dbb9125b8 Mon Sep 17 00:00:00 2001
From: Julian Ospald <hasufell@posteo.de>
Date: Sun, 12 May 2024 23:41:21 +0800
Subject: [PATCH] Document caveats for encodeWith, fixes #15

---
 System/OsString/Common.hs   | 13 +++++++++++--
 System/OsString/Internal.hs |  8 ++++++--
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/System/OsString/Common.hs b/System/OsString/Common.hs
index ba9ab19..f8d0387 100644
--- a/System/OsString/Common.hs
+++ b/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
diff --git a/System/OsString/Internal.hs b/System/OsString/Internal.hs
index 140be0c..1753d58 100644
--- a/System/OsString/Internal.hs
+++ b/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__)