| Copyright | © 2021 Julian Ospald |
|---|---|
| License | MIT |
| Maintainer | Julian Ospald <hasufell@posteo.de> |
| Stability | experimental |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
System.OsString
Description
An implementation of platform specific short OsString, which is:
- on windows UTF16 data
- on unix UTF8 data
It captures the notion of syscall specific encoding to avoid roundtrip issues and memory fragmentation by using unpinned byte arrays.
Synopsis
- data OsString
- toOsStringUtf :: MonadThrow m => String -> m OsString
- toOsStringEnc :: String -> TextEncoding -> TextEncoding -> Either EncodingException OsString
- toOsStringFS :: String -> IO OsString
- osstr :: QuasiQuoter
- packOsString :: [OsChar] -> OsString
- fromOsStringUtf :: MonadThrow m => OsString -> m String
- fromOsStringEnc :: OsString -> TextEncoding -> TextEncoding -> Either EncodingException String
- fromOsStringFS :: OsString -> IO String
- unpackOsString :: OsString -> [OsChar]
- data OsChar
- unsafeFromChar :: Char -> OsChar
- toChar :: OsChar -> Char
String types
Newtype representing short operating system specific strings.
Internally this is either WindowsString or PosixString,
depending on the platform. Both use unpinned
ShortByteString for efficiency.
The constructor is only exported via System.OsString.Internal.Types, since dealing with the internals isn't generally recommended, but supported in case you need to write platform specific code.
Instances
| Eq OsString Source # | Byte equality of the internal representation. |
| Ord OsString Source # | Byte ordering of the internal representation. |
Defined in System.OsString.Internal.Types | |
| Read OsString Source # | Encodes as UTF-8 on unix and UTF-16LE on windows. |
Defined in System.OsString.Internal.Types | |
| Show OsString Source # | Decodes as UTF-16 on windows. Decodes as UTF-8 on unix and replaces invalid chars with unicode replacement char U+FFFD. |
| IsString OsString Source # | Encodes as UTF16 on windows and UTF8 on unix. |
Defined in System.OsString.Internal.Types Methods fromString :: String -> OsString | |
| Generic OsString Source # | |
| Semigroup OsString Source # | |
| Monoid OsString Source # | "String-Concatenation" for 'OsString. This is not the same
as |
| NFData OsString Source # | |
Defined in System.OsString.Internal.Types | |
| Lift OsString Source # | |
| type Rep OsString Source # | |
Defined in System.OsString.Internal.Types type Rep OsString = D1 ('MetaData "OsString" "System.OsString.Internal.Types" "filepath-2.0.0.1-inplace" 'True) (C1 ('MetaCons "OsString" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PlatformString))) | |
String construction
toOsStringUtf :: MonadThrow m => String -> m OsString Source #
Convert a String.
On windows this encodes as UTF16-LE, which is a pretty good guess. On unix this encodes as UTF8, which is a good guess.
Throws a EncodingException if encoding fails.
Arguments
| :: String | |
| -> TextEncoding | unix text encoding |
| -> TextEncoding | windows text encoding |
| -> Either EncodingException OsString |
Like toOsStringUtf, except allows to provide encodings.
toOsStringFS :: String -> IO OsString Source #
Like toOsStringUtf, except on unix this uses the current
filesystem locale for encoding instead of always UTF8.
Looking up the locale requires IO. If you're not worried about calls
to setFileSystemEncoding, then unsafePerformIO may be feasible (make sure
to deeply evaluate the result to catch exceptions).
Throws a EncodingException if decoding fails.
QuasiQuote an OsString. This accepts Unicode characters
and encodes as UTF-8 on unix and UTF-16 on windows.
packOsString :: [OsChar] -> OsString Source #
Pack a list of OsChar to an OsString
Note that using this in conjunction with unsafeFromChar to
convert from [Char] to OsString is probably not what
you want, because it will truncate unicode code points.
String deconstruction
fromOsStringUtf :: MonadThrow m => OsString -> m String Source #
Partial unicode friendly decoding.
On windows this decodes as UTF16-LE (which is the expected filename encoding). On unix this decodes as UTF8 (which is a good guess). Note that filenames on unix are encoding agnostic char arrays.
Throws a EncodingException if decoding fails.
Arguments
| :: OsString | |
| -> TextEncoding | unix text encoding |
| -> TextEncoding | windows text encoding |
| -> Either EncodingException String |
Like fromOsStringUtf, except allows to provide encodings.
The String is forced into memory to catch all exceptions.
fromOsStringFS :: OsString -> IO String Source #
Like fromOsStringUtf, except on unix this uses the current
filesystem locale for decoding instead of always UTF8. On windows, uses UTF-16LE.
Looking up the locale requires IO. If you're not worried about calls
to setFileSystemEncoding, then unsafePerformIO may be feasible (make sure
to deeply evaluate the result to catch exceptions).
Throws EncodingException if decoding fails.
Word types
Newtype representing a code unit.
On Windows, this is restricted to two-octet codepoints Word16,
on POSIX one-octet (Word8).
Instances
| Eq OsChar Source # | Byte equality of the internal representation. |
| Ord OsChar Source # | Byte ordering of the internal representation. |
| Show OsChar Source # | |
| Generic OsChar Source # | |
| NFData OsChar Source # | |
Defined in System.OsString.Internal.Types | |
| type Rep OsChar Source # | |
Defined in System.OsString.Internal.Types type Rep OsChar = D1 ('MetaData "OsChar" "System.OsString.Internal.Types" "filepath-2.0.0.1-inplace" 'True) (C1 ('MetaCons "OsChar" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 PlatformChar))) | |
Word construction
unsafeFromChar :: Char -> OsChar Source #
Truncates on unix to 1 and on Windows to 2 octets.