{-# LANGUAGE NoImplicitPrelude #-}

-- | SDL locale services.
--
--     This provides a way to get a list of preferred locales (language plus country) for the user. There is exactly one function: @'getPreferredLocales'@, which handles all the heavy lifting, and offers documentation on all the strange ways humans might have configured their language settings. A struct to provide locale data.
--
--     Locale data is split into a spoken language, like English, and an optional country, like Canada. The language will be in ISO-639 format (so English would be \"en\"), and the country, if not NULL, will be an ISO-3166 country code (so Canada would be \"CA\").
--
--     @since 3.2.0
--
--     [See also]: 'getPreferredLocales'
--
--     == FFI conventions
--
--     Unsuffixed aliases are __unsafe__ foreign imports; aliases suffixed @Safe@ are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under @SDL3.Sys.Bindgen.Locale.Unsafe@); functions curated unsafe-only export only the unsuffixed one. Each alias\'s documentation records its flavor and rationale.
--
--     Full conventions: "SDL3.Sys".
module SDL3.Sys.Locale (
  module SDL3.Sys.Bindgen.Locale,

  -- * Function aliases
  SDL3.Sys.Locale.getPreferredLocales,
  SDL3.Sys.Locale.getPreferredLocalesSafe,
)
where

import Prelude (IO)

import HsBindgen.Runtime.Support qualified as BG
import SDL3.Sys.Bindgen.Locale
import SDL3.Sys.Bindgen.Locale.Safe qualified as Safe
import SDL3.Sys.Bindgen.Locale.Unsafe qualified as Unsafe

-- | Report the user\'s preferred locale.
--
--     Returned language strings are in the format xx, where \'xx\' is an ISO-639 language specifier (such as \"en\" for English, \"de\" for German, etc). Country strings are in the format YY, where \"YY\" is an ISO-3166 country code (such as \"US\" for the United States, \"CA\" for Canada, etc). Country might be NULL if there\'s no specific guidance on them (so you might get { \"en\", \"US\" } for American English, but { \"en\", NULL } means \"English language, generically\"). Language strings are never NULL, except to terminate the array.
--
--     Please note that not all of these strings are 2 characters; some are three or more.
--
--     The returned list of locales are in the order of the user\'s preference. For example, a German citizen that is fluent in US English and knows enough Japanese to navigate around Tokyo might have a list like: { \"de\", \"en_US\", \"jp\", NULL }. Someone from England might prefer British English (where \"color\" is spelled \"colour\", etc), but will settle for anything like it: { \"en_GB\", \"en\", NULL }.
--
--     This function returns NULL on error, including when the platform does not supply this information at all.
--
--     This might be a \"slow\" call that has to query the operating system. It\'s best to ask for this once and save the results. However, this list can change, usually because the user has changed a system preference outside of your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if possible, and you can call this function again to get an updated copy of preferred locales.
--
--     [Returns]: a NULL terminated array of locale pointers, or NULL on failure; call 'SDL3.Sys.Error.getError' for more information. This is a single allocation that should be freed with 'SDL3.Sys.Stdinc.free' when it is no longer needed.
--
--     [Thread safety]: This function is not thread safe.
--
--     @since 3.2.0
--
--     === __@sdl3-bindgen-sys@ notes__
--
--     [FFI safety]: __Unsafe__ foreign import of @SDL_GetPreferredLocales@.
--                   The safe flavor is 'getPreferredLocalesSafe'
--                   .
--
--     [C declaration]: @SDL_GetPreferredLocales@, defined at @SDL3\/SDL_locale.h 109:43@
getPreferredLocales
  :: BG.Ptr BG.CInt
  -- ^
  --
  --           [@count@]: a pointer filled in with the number of locales returned, may be NULL.
  -> IO (BG.Ptr (BG.Ptr SDL_Locale))
getPreferredLocales :: Ptr CInt -> IO (Ptr (Ptr SDL_Locale))
getPreferredLocales = Ptr CInt -> IO (Ptr (Ptr SDL_Locale))
Unsafe.sDL_GetPreferredLocales

-- | Report the user\'s preferred locale.
--
--     Returned language strings are in the format xx, where \'xx\' is an ISO-639 language specifier (such as \"en\" for English, \"de\" for German, etc). Country strings are in the format YY, where \"YY\" is an ISO-3166 country code (such as \"US\" for the United States, \"CA\" for Canada, etc). Country might be NULL if there\'s no specific guidance on them (so you might get { \"en\", \"US\" } for American English, but { \"en\", NULL } means \"English language, generically\"). Language strings are never NULL, except to terminate the array.
--
--     Please note that not all of these strings are 2 characters; some are three or more.
--
--     The returned list of locales are in the order of the user\'s preference. For example, a German citizen that is fluent in US English and knows enough Japanese to navigate around Tokyo might have a list like: { \"de\", \"en_US\", \"jp\", NULL }. Someone from England might prefer British English (where \"color\" is spelled \"colour\", etc), but will settle for anything like it: { \"en_GB\", \"en\", NULL }.
--
--     This function returns NULL on error, including when the platform does not supply this information at all.
--
--     This might be a \"slow\" call that has to query the operating system. It\'s best to ask for this once and save the results. However, this list can change, usually because the user has changed a system preference outside of your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if possible, and you can call this function again to get an updated copy of preferred locales.
--
--     [Returns]: a NULL terminated array of locale pointers, or NULL on failure; call 'SDL3.Sys.Error.getError' for more information. This is a single allocation that should be freed with 'SDL3.Sys.Stdinc.free' when it is no longer needed.
--
--     [Thread safety]: This function is not thread safe.
--
--     @since 3.2.0
--
--     === __@sdl3-bindgen-sys@ notes__
--
--     [FFI safety]: __Safe__ foreign import of @SDL_GetPreferredLocales@.
--                   The unsafe flavor is 'getPreferredLocales'
--                   .
--
--     [C declaration]: @SDL_GetPreferredLocales@, defined at @SDL3\/SDL_locale.h 109:43@
getPreferredLocalesSafe
  :: BG.Ptr BG.CInt
  -- ^
  --
  --           [@count@]: a pointer filled in with the number of locales returned, may be NULL.
  -> IO (BG.Ptr (BG.Ptr SDL_Locale))
getPreferredLocalesSafe :: Ptr CInt -> IO (Ptr (Ptr SDL_Locale))
getPreferredLocalesSafe =
  Ptr CInt -> IO (Ptr (Ptr SDL_Locale))
Safe.sDL_GetPreferredLocales