include/unicode/messageformat2_function_registry.h

0001 // © 2024 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003
0004 #include "unicode/utypes.h"
0005
0006 #ifndef MESSAGEFORMAT2_FUNCTION_REGISTRY_H
0007 #define MESSAGEFORMAT2_FUNCTION_REGISTRY_H
0008
0009 #if U_SHOW_CPLUSPLUS_API
0010
0011 #if !UCONFIG_NO_FORMATTING
0012
0013 #if !UCONFIG_NO_MF2
0014
0015 #include "unicode/messageformat2_data_model_names.h"
0016 #include "unicode/messageformat2_formattable.h"
0017
0018 #ifndef U_HIDE_DEPRECATED_API
0019
0020 #include <map>
0021
0022 U_NAMESPACE_BEGIN
0023
0024 class Hashtable;
0025 class UVector;
0026
0027 namespace message2 {
0028
0029     using namespace data_model;
0030
0031     /**
0032      * Interface that factory classes for creating formatters must implement.
0033      *
0034      * @internal ICU 75 technology preview
0035      * @deprecated This API is for technology preview only.
0036      */
0037     class U_I18N_API FormatterFactory : public UObject {
0038         // TODO: the coding guidelines say that interface classes
0039         // shouldn't inherit from UObject, but if I change it so these
0040         // classes don't, and the individual formatter factory classes
0041         // inherit from public FormatterFactory, public UObject, then
0042         // memory leaks ensue
0043     public:
0044         /**
0045          * Constructs a new formatter object. This method is not const;
0046          * formatter factories with local state may be defined.
0047          *
0048          * @param locale Locale to be used by the formatter.
0049          * @param status    Input/output error code.
0050          * @return The new Formatter, which is non-null if U_SUCCESS(status).
0051          *
0052          * @internal ICU 75 technology preview
0053          * @deprecated This API is for technology preview only.
0054          */
0055         virtual Formatter* createFormatter(const Locale& locale, UErrorCode& status) = 0;
0056         /**
0057          * Destructor.
0058          *
0059          * @internal ICU 75 technology preview
0060          * @deprecated This API is for technology preview only.
0061          */
0062         virtual ~FormatterFactory();
0063         /**
0064          * Copy constructor.
0065          *
0066          * @internal ICU 75 technology preview
0067          * @deprecated This API is for technology preview only.
0068          */
0069         FormatterFactory& operator=(const FormatterFactory&) = delete;
0070     }; // class FormatterFactory
0071
0072     /**
0073      * Interface that factory classes for creating selectors must implement.
0074      *
0075      * @internal ICU 75 technology preview
0076      * @deprecated This API is for technology preview only.
0077      */
0078     class U_I18N_API SelectorFactory : public UObject {
0079     public:
0080         /**
0081          * Constructs a new selector object.
0082          *
0083          * @param locale    Locale to be used by the selector.
0084          * @param status    Input/output error code.
0085          * @return          The new selector, which is non-null if U_SUCCESS(status).
0086          *
0087          * @internal ICU 75 technology preview
0088          * @deprecated This API is for technology preview only.
0089          */
0090         virtual Selector* createSelector(const Locale& locale, UErrorCode& status) const = 0;
0091         /**
0092          * Destructor.
0093          *
0094          * @internal ICU 75 technology preview
0095          * @deprecated This API is for technology preview only.
0096          */
0097         virtual ~SelectorFactory();
0098         /**
0099          * Copy constructor.
0100          *
0101          * @internal ICU 75 technology preview
0102          * @deprecated This API is for technology preview only.
0103          */
0104         SelectorFactory& operator=(const SelectorFactory&) = delete;
0105     }; // class SelectorFactory
0106
0107     /**
0108      * Defines mappings from names of formatters and selectors to functions implementing them.
0109      * The required set of formatter and selector functions is defined in the spec. Users can
0110      * also define custom formatter and selector functions.
0111      *
0112      * `MFFunctionRegistry` is immutable and movable. It is not copyable.
0113      *
0114      * @internal ICU 75 technology preview
0115      * @deprecated This API is for technology preview only.
0116      */
0117     class U_I18N_API MFFunctionRegistry : public UObject {
0118     private:
0119
0120         using FormatterMap = Hashtable; // Map from stringified function names to FormatterFactory*
0121         using SelectorMap  = Hashtable; // Map from stringified function names to SelectorFactory*
0122
0123     public:
0124         /**
0125          * Looks up a formatter factory by the name of the formatter. The result is non-const,
0126          * since formatter factories may have local state. Returns the result by pointer
0127          * rather than by reference since it can fail.
0128          *
0129          * @param formatterName Name of the desired formatter.
0130          * @return A pointer to the `FormatterFactory` registered under `formatterName`, or null
0131          *         if no formatter was registered under that name. The pointer is not owned
0132          *         by the caller.
0133          *
0134          * @internal ICU 75 technology preview
0135          * @deprecated This API is for technology preview only.
0136          */
0137         FormatterFactory* getFormatter(const FunctionName& formatterName) const;
0138         /**
0139          * Looks up a selector factory by the name of the selector. (This returns the result by pointer
0140          * rather than by reference since `FormatterFactory` is an abstract class.)
0141          *
0142          * @param selectorName Name of the desired selector.
0143          * @return A pointer to the `SelectorFactory` registered under `selectorName`, or null
0144          *         if no formatter was registered under that name.
0145          *
0146          * @internal ICU 75 technology preview
0147          * @deprecated This API is for technology preview only.
0148          */
0149         const SelectorFactory* getSelector(const FunctionName& selectorName) const;
0150         /**
0151          * Looks up a formatter factory by a type tag. This method gets the name of the default formatter registered
0152          * for that type. If no formatter was explicitly registered for this type, it returns false.
0153          *
0154          * @param formatterType Type tag for the desired `FormattableObject` type to be formatted.
0155          * @param name Output parameter; initialized to the name of the default formatter for `formatterType`
0156          *        if one has been registered. Its value is undefined otherwise.
0157          * @return True if and only if the function registry contains a default formatter for `formatterType`.
0158          *         If the return value is false, then the value of `name` is undefined.
0159          *
0160          * @internal ICU 75 technology preview
0161          * @deprecated This API is for technology preview only.
0162          */
0163         UBool getDefaultFormatterNameByType(const UnicodeString& formatterType, FunctionName& name) const;
0164         /**
0165          * The mutable Builder class allows each formatter and selector factory
0166          * to be initialized separately; calling its `build()` method yields an
0167          * immutable MFFunctionRegistry object.
0168          *
0169          * Builder is not copyable or movable.
0170          *
0171          * @internal ICU 75 technology preview
0172          * @deprecated This API is for technology preview only.
0173          */
0174         class U_I18N_API Builder : public UObject {
0175         private:
0176             // Must use raw pointers to avoid instantiating `LocalPointer` on an internal type
0177             FormatterMap* formatters;
0178             SelectorMap* selectors;
0179             Hashtable* formattersByType;
0180
0181             // Do not define copy constructor/assignment operator
0182             Builder& operator=(const Builder&) = delete;
0183             Builder(const Builder&) = delete;
0184
0185         public:
0186             /*
0187               Notes about `adoptFormatter()`'s type signature:
0188
0189               Alternative considered: take a non-owned FormatterFactory*
0190               This is unsafe.
0191
0192               Alternative considered: take a FormatterFactory&
0193                  This requires getFormatter() to cast the reference to a pointer,
0194                  as it must return an unowned FormatterFactory* since it can fail.
0195                  That is also unsafe, since the caller could delete the pointer.
0196
0197               The "TemperatureFormatter" test from the previous ICU4J version doesn't work now,
0198               as it only works if the `formatterFactory` argument is non-owned.
0199               If registering a non-owned FormatterFactory is desirable, this could
0200               be re-thought.
0201               */
0202             /**
0203              * Registers a formatter factory to a given formatter name.
0204              *
0205              * @param formatterName Name of the formatter being registered.
0206              * @param formatterFactory A pointer to a FormatterFactory object to use
0207              *        for creating `formatterName` formatters. This argument is adopted.
0208              * @param errorCode Input/output error code
0209              * @return A reference to the builder.
0210              *
0211              * @internal ICU 75 technology preview
0212              * @deprecated This API is for technology preview only.
0213              */
0214             Builder& adoptFormatter(const data_model::FunctionName& formatterName, FormatterFactory* formatterFactory, UErrorCode& errorCode);
0215             /**
0216              * Registers a formatter factory to a given type tag.
0217              * (See `FormattableObject` for details on type tags.)
0218              *
0219              * @param type Tag for objects to be formatted with this formatter.
0220              * @param functionName A reference to the name of the function to use for
0221              *        creating formatters for `formatterType` objects.
0222              * @param errorCode Input/output error code
0223              * @return A reference to the builder.
0224              *
0225              * @internal ICU 75 technology preview
0226              * @deprecated This API is for technology preview only.
0227              */
0228             Builder& setDefaultFormatterNameByType(const UnicodeString& type, const data_model::FunctionName& functionName, UErrorCode& errorCode);
0229
0230             /**
0231              * Registers a selector factory to a given selector name. Adopts `selectorFactory`.
0232              *
0233              * @param selectorName Name of the selector being registered.
0234              * @param selectorFactory A SelectorFactory object to use for creating `selectorName`
0235              *        selectors.
0236              * @param errorCode Input/output error code
0237              * @return A reference to the builder.
0238              *
0239              * @internal ICU 75 technology preview
0240              * @deprecated This API is for technology preview only.
0241              */
0242             Builder& adoptSelector(const data_model::FunctionName& selectorName, SelectorFactory* selectorFactory, UErrorCode& errorCode);
0243             /**
0244              * Creates an immutable `MFFunctionRegistry` object with the selectors and formatters
0245              * that were previously registered. The builder cannot be used after this call.
0246              * The `build()` method is destructive to avoid the need for a deep copy of the
0247              * `FormatterFactory` and `SelectorFactory` objects (this would be necessary because
0248              * `FormatterFactory` can have mutable state), which in turn would require implementors
0249              * of those interfaces to implement a `clone()` method.
0250              *
0251              * @return The new MFFunctionRegistry
0252              *
0253              * @internal ICU 75 technology preview
0254              * @deprecated This API is for technology preview only.
0255              */
0256             MFFunctionRegistry build();
0257             /**
0258              * Default constructor.
0259              * Returns a Builder with no functions registered.
0260              *
0261              * @param errorCode Input/output error code
0262              *
0263              * @internal ICU 75 technology preview
0264              * @deprecated This API is for technology preview only.
0265              */
0266             Builder(UErrorCode& errorCode);
0267             /**
0268              * Destructor.
0269              *
0270              * @internal ICU 75 technology preview
0271              * @deprecated This API is for technology preview only.
0272              */
0273             virtual ~Builder();
0274         }; // class MFFunctionRegistry::Builder
0275
0276         /**
0277          * Move assignment operator:
0278          * The source MFFunctionRegistry will be left in a valid but undefined state.
0279          *
0280          * @internal ICU 75 technology preview
0281          * @deprecated This API is for technology preview only.
0282          */
0283         MFFunctionRegistry& operator=(MFFunctionRegistry&&) noexcept;
0284         /**
0285          * Move constructor:
0286          * The source MFFunctionRegistry will be left in a valid but undefined state.
0287          *
0288          * @internal ICU 75 technology preview
0289          * @deprecated This API is for technology preview only.
0290          */
0291         MFFunctionRegistry(MFFunctionRegistry&& other) { *this = std::move(other); }
0292         /**
0293          * Destructor.
0294          *
0295          * @internal ICU 75 technology preview
0296          * @deprecated This API is for technology preview only.
0297          */
0298         virtual ~MFFunctionRegistry();
0299
0300     private:
0301         friend class MessageContext;
0302         friend class MessageFormatter;
0303
0304         // Do not define copy constructor or copy assignment operator
0305         MFFunctionRegistry& operator=(const MFFunctionRegistry&) = delete;
0306         MFFunctionRegistry(const MFFunctionRegistry&) = delete;
0307
0308         MFFunctionRegistry(FormatterMap* f, SelectorMap* s, Hashtable* byType);
0309
0310         MFFunctionRegistry() {}
0311
0312         // Debugging; should only be called on a function registry with
0313         // all the standard functions registered
0314         void checkFormatter(const char*) const;
0315         void checkSelector(const char*) const;
0316         void checkStandard() const;
0317
0318         bool hasFormatter(const data_model::FunctionName& f) const;
0319         bool hasSelector(const data_model::FunctionName& s) const;
0320         void cleanup() noexcept;
0321
0322         // Must use raw pointers to avoid instantiating `LocalPointer` on an internal type
0323         FormatterMap* formatters = nullptr;
0324         SelectorMap* selectors = nullptr;
0325         // Mapping from strings (type tags) to FunctionNames
0326         Hashtable* formattersByType = nullptr;
0327     }; // class MFFunctionRegistry
0328
0329     /**
0330      * Interface that formatter classes must implement.
0331      *
0332      * @internal ICU 75 technology preview
0333      * @deprecated This API is for technology preview only.
0334      */
0335     class U_I18N_API Formatter : public UObject {
0336     public:
0337         /**
0338          * Formats the input passed in `context` by setting an output using one of the
0339          * `FormattingContext` methods or indicating an error.
0340          *
0341          * @param toFormat Placeholder, including a source formattable value and possibly
0342          *        the output of a previous formatter applied to it; see
0343          *        `message2::FormattedPlaceholder` for details. Passed by move.
0344          * @param options The named function options. Passed by move
0345          * @param status    Input/output error code. Should not be set directly by the
0346          *        custom formatter, which should use `FormattingContext::setFormattingWarning()`
0347          *        to signal errors. The custom formatter may pass `status` to other ICU functions
0348          *        that can signal errors using this mechanism.
0349          *
0350          * @return The formatted value.
0351          *
0352          * @internal ICU 75 technology preview
0353          * @deprecated This API is for technology preview only.
0354          */
0355         virtual FormattedPlaceholder format(FormattedPlaceholder&& toFormat,
0356                                       FunctionOptions&& options,
0357                                       UErrorCode& status) const = 0;
0358         /**
0359          * Destructor.
0360          *
0361          * @internal ICU 75 technology preview
0362          * @deprecated This API is for technology preview only.
0363          */
0364         virtual ~Formatter();
0365     }; // class Formatter
0366
0367     /**
0368      * Interface that selector classes must implement.
0369      *
0370      * @internal ICU 75 technology preview
0371      * @deprecated This API is for technology preview only.
0372      */
0373     class U_I18N_API Selector : public UObject {
0374     public:
0375         /**
0376          * Compares the input to an array of keys, and returns an array of matching
0377          * keys sorted by preference.
0378          *
0379          * @param toFormat The unnamed function argument; passed by move.
0380          * @param options A reference to the named function options.
0381          * @param keys An array of strings that are compared to the input
0382          *        (`context.getFormattableInput()`) in an implementation-specific way.
0383          * @param keysLen The length of `keys`.
0384          * @param prefs An array of strings with length `keysLen`. The contents of
0385          *        the array is undefined. `selectKey()` should set the contents
0386          *        of `prefs` to a subset of `keys`, with the best match placed at the lowest index.
0387          * @param prefsLen A reference that `selectKey()` should set to the length of `prefs`,
0388          *        which must be less than or equal to `keysLen`.
0389          * @param status    Input/output error code. Should not be set directly by the
0390          *        custom selector, which should use `FormattingContext::setSelectorError()`
0391          *        to signal errors. The custom selector may pass `status` to other ICU functions
0392          *        that can signal errors using this mechanism.
0393          *
0394          * @internal ICU 75 technology preview
0395          * @deprecated This API is for technology preview only.
0396          */
0397         virtual void selectKey(FormattedPlaceholder&& toFormat,
0398                                FunctionOptions&& options,
0399                                const UnicodeString* keys,
0400                                int32_t keysLen,
0401                                UnicodeString* prefs,
0402                                int32_t& prefsLen,
0403                                UErrorCode& status) const = 0;
0404         // Note: This takes array arguments because the internal MessageFormat code has to
0405         // call this method, and can't include any code that constructs std::vectors.
0406         /**
0407          * Destructor.
0408          *
0409          * @internal ICU 75 technology preview
0410          * @deprecated This API is for technology preview only.
0411          */
0412         virtual ~Selector();
0413     }; // class Selector
0414
0415 } // namespace message2
0416
0417 U_NAMESPACE_END
0418
0419 #endif // U_HIDE_DEPRECATED_API
0420
0421 #endif /* #if !UCONFIG_NO_MF2 */
0422
0423 #endif /* #if !UCONFIG_NO_FORMATTING */
0424
0425 #endif /* U_SHOW_CPLUSPLUS_API */
0426
0427 #endif // MESSAGEFORMAT2_FUNCTION_REGISTRY_H
0428
0429 // eof