js/public/LocaleSensitive.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /*
   7  * Functions and structures related to locale-sensitive behavior, including
   8  * exposure of the default locale (used by operations like toLocaleString).
   9  */
  10
  11 #ifndef js_LocaleSensitive_h
  12 #define js_LocaleSensitive_h
  13
  14 #include "jstypes.h"  // JS_PUBLIC_API
  15
  16 #include "js/RootingAPI.h"  // JS::Handle, JS::MutableHandle
  17 #include "js/Utility.h"     // JS::UniqueChars
  18 #include "js/Value.h"       // JS::Value
  19
  20 struct JS_PUBLIC_API JSContext;
  21 struct JS_PUBLIC_API JSRuntime;
  22 class JS_PUBLIC_API JSString;
  23
  24 /**
  25  * Set the default locale for the ECMAScript Internationalization API
  26  * (Intl.Collator, Intl.NumberFormat, Intl.DateTimeFormat, and others that will
  27  * arise as time passes).  (Note that the Internationalization API encourages
  28  * clients to specify their own locales; this default locale is only used when
  29  * no locale is specified, e.g. calling a toLocaleString function without
  30  * passing a locale argument to it.)
  31  *
  32  * The locale string remains owned by the caller.
  33  */
  34 extern JS_PUBLIC_API bool JS_SetDefaultLocale(JSRuntime* rt,
  35                                               const char* locale);
  36
  37 /**
  38  * Return a copy of the default locale for the ECMAScript Internationalization
  39  * API (and for various ECMAScript functions that will invoke it).  The locale
  40  * is retrieved from the |JSRuntime| that corresponds to |cx|.
  41  *
  42  * XXX Bug 1483961 means it's difficult to interpret the meaning of a null
  43  *     return value for the time being, and we should fix this!
  44  */
  45 extern JS_PUBLIC_API JS::UniqueChars JS_GetDefaultLocale(JSContext* cx);
  46
  47 /** Reset the default locale to OS defaults. */
  48 extern JS_PUBLIC_API void JS_ResetDefaultLocale(JSRuntime* rt);
  49
  50 using JSLocaleToUpperCase = bool (*)(JSContext* cx, JS::Handle<JSString*> src,
  51                                      JS::MutableHandle<JS::Value> rval);
  52
  53 using JSLocaleToLowerCase = bool (*)(JSContext* cx, JS::Handle<JSString*> src,
  54                                      JS::MutableHandle<JS::Value> rval);
  55
  56 using JSLocaleCompare = bool (*)(JSContext* cx, JS::Handle<JSString*> src1,
  57                                  JS::Handle<JSString*> src2,
  58                                  JS::MutableHandle<JS::Value> rval);
  59
  60 using JSLocaleToUnicode = bool (*)(JSContext* cx, const char* src,
  61                                    JS::MutableHandle<JS::Value> rval);
  62
  63 /**
  64  * A suite of locale-specific string conversion and error message callbacks
  65  * used to implement locale-sensitive behaviors (such as those performed by
  66  * the various toLocaleString and toLocale{Date,Time}String functions).
  67  *
  68  * If SpiderMonkey is compiled --with-intl-api, then #if JS_HAS_INTL_API.  In
  69  * this case, SpiderMonkey itself will implement ECMA-402-compliant behavior by
  70  * calling on ICU, and none of the fields in this struct will ever be used.
  71  * (You'll still be able to call the get/set-callbacks functions; they just
  72  * won't affect JavaScript semantics.)
  73  */
  74 struct JSLocaleCallbacks {
  75   JSLocaleToUpperCase localeToUpperCase;
  76   JSLocaleToLowerCase localeToLowerCase;
  77   JSLocaleCompare localeCompare;
  78   JSLocaleToUnicode localeToUnicode;
  79 };
  80
  81 /**
  82  * Set locale callbacks to be used in builds not compiled --with-intl-api.
  83  * |callbacks| must persist as long as the |JSRuntime|.  Pass |nullptr| to
  84  * restore default behavior.
  85  */
  86 extern JS_PUBLIC_API void JS_SetLocaleCallbacks(
  87     JSRuntime* rt, const JSLocaleCallbacks* callbacks);
  88
  89 /**
  90  * Return the current locale callbacks, which may be nullptr.
  91  */
  92 extern JS_PUBLIC_API const JSLocaleCallbacks* JS_GetLocaleCallbacks(
  93     JSRuntime* rt);
  94
  95 #endif /* js_LocaleSensitive_h */