Skip to content

Commit

Permalink
Add doc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@catamorphism
catamorphism committed Oct 7, 2024
1 parent 10dfe45 commit a2f4a59
Show file tree
Hide file tree
Showing 3 changed files with 149 additions and 15 deletions.
6 changes: 6 additions & 0 deletions icu4c/source/i18n/messageformat2_evaluation.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,12 @@ namespace message2 {
BaseValue(const Locale&, const Formattable&);
}; // class BaseValue

// A NullValue represents the absence of an argument.
class NullValue : public FunctionValue {
public:
virtual UBool isNullOperand() const { return true; }
}; // class NullValue

// PrioritizedVariant

// For how this class is used, see the references to (integer, variant) tuples
Expand Down
15 changes: 13 additions & 2 deletions icu4c/source/i18n/unicode/messageformat2_formattable.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,18 @@ class U_I18N_API FunctionOptions : public UObject {
}
return result;
}
/**
* Returns a new FunctionOptions object containing all the key-value
* pairs from `this` and `other`. When `this` and `other` define options with
* the same name, `this` takes preference.
* `this` cannot be used after calling this method.
*
* @return The result of merging `this` and `other`.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
FunctionOptions mergeOptions(FunctionOptions&& other, UErrorCode&);
/**
* Default constructor.
* Returns an empty mapping.
Expand Down Expand Up @@ -549,8 +561,7 @@ class U_I18N_API FunctionOptions : public UObject {
* @deprecated This API is for technology preview only.
*/
FunctionOptions& operator=(const FunctionOptions&) = delete;
// TODO
FunctionOptions mergeOptions(FunctionOptions&&, UErrorCode&);

private:
friend class MessageFormatter;
friend class StandardFunctions;
Expand Down
143 changes: 130 additions & 13 deletions icu4c/source/i18n/unicode/messageformat2_function_registry.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -269,32 +269,136 @@ namespace message2 {
/**
* Interface that function handler classes must implement.
*
* @internal ICU 75 technology preview
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
class U_I18N_API Function : public UObject {
public:
virtual FunctionValue* call(FunctionValue&, FunctionOptions&&, UErrorCode&) = 0;
virtual ~Function();
public:
/**
* Calls this Function on a FunctionValue operand and its FunctionOptions options,
* returning a new pointer to a FunctionValue (which is adopted by the caller).
*
* @param operand The unnamed argument to the function.
* @param options Resolved options for this function.
* @param status Input/output error code
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual FunctionValue* call(FunctionValue& operand,
FunctionOptions&& options,
UErrorCode& status) = 0;
/**
* Destructor.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual ~Function();
}; // class Function

/**
* Type representing argument and return values for custom functions.
* It encapsulates an operand and resolved options, and can be extended with
* additional state.
* Adding a new custom function requires adding a new class that
* implements this interface.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
class U_I18N_API FunctionValue : public UObject {
public:
/**
* Returns the string representation of this value. The default
* method signals an error. Must be overridden by classes
* implementing values that support formatting.
*
* @param status Input/output error code
* @return A string.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual UnicodeString formatToString(UErrorCode& status) const {
if (U_SUCCESS(status)) {
status = U_MF_FORMATTING_ERROR;
}
return {};
}
/**
* Returns the Formattable operand that was used to construct
* this value. The operand may be obtained from calling getOperand()
* on the input FunctionValue, or it may be constructed separately.
*
* @return A reference to a message2::Formattable object.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual const Formattable& getOperand() const { return operand; }
// `this` can't be used after calling this method
/**
* Returns the resolved options that were used to construct this value.
* `this` may not be used after calling this method. This overload
* is provided so that mergeOptions(), which passes its `this` argument
* by move, can be called.
*
* @return The resolved options for this value.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual FunctionOptions getResolvedOptions() { return std::move(opts); }
// const method is for reading the options attached to another option
// (i.e. options don't escape) --
// non-const method is for calling mergeOptions() -- i.e. options escape
/**
* Returns a reference to the resolved options for this value.
*
* @return A reference to the resolved options for this value.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual const FunctionOptions& getResolvedOptions() const { return opts; }
/**
* Returns true if this value supports selection. The default method
* returns false. The method must be overridden for values that support
* selection.
*
* @return True iff this value supports selection.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual UBool isSelectable() const { return false; }
/**
* Returns true if this value represents a null operand, that is,
* the absence of an argument. This method should not be overridden.
* It can be called in order to check whether the argument is present.
* Some functions may be nullary (they may work with no arguments).
*
* @return True iff this value represents an absent operand.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual UBool isNullOperand() const { return false; }
/**
* Compares this value to an array of keys, and returns an array of matching
* keys sorted by preference. The default implementation of this method
* signals an error. It should be overridden for value classes that support
* selection.
*
* @param keys An array of strings to compare to the input.
* @param keysLen The length of `keys`.
* @param prefs An array of strings with length `keysLen`. The contents of
* the array is undefined. `selectKey()` should set the contents
* of `prefs` to a subset of `keys`, with the best match placed at the lowest index.
* @param prefsLen A reference that `selectKey()` should set to the length of `prefs`,
* which must be less than or equal to `keysLen`.
* @param status Input/output error code.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual void selectKeys(const UnicodeString* keys,
int32_t keysLen,
UnicodeString* prefs,
Expand All @@ -308,17 +412,30 @@ namespace message2 {
status = U_MF_SELECTOR_ERROR;
}
}
/**
* Destructor.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
virtual ~FunctionValue();
protected:
/**
* Operand used to construct this value.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
Formattable operand;
/**
* Resolved options attached to this value.
*
* @internal ICU 77 technology preview
* @deprecated This API is for technology preview only.
*/
FunctionOptions opts;
}; // class FunctionValue

class NullValue : public FunctionValue {
public:
virtual UBool isNullOperand() const { return true; }
}; // class NullValue

} // namespace message2

U_NAMESPACE_END
Expand Down

0 comments on commit a2f4a59

Please sign in to comment.