/ 
Locale-Unicode-RBNF-v0.1.0
/ Locale::Unicode::RBNF::Rule

NAME

Locale::Unicode::RBNF::Rule - A single rule of a rule-based number format

VERSION

v0.1.0

DESCRIPTION

Internal module. This is a port of ICU4C NFRule (nfrule.cpp, ICU 79.1).

CONVENTIONS

The methods follow the ICU code they are ported from, and share these arguments:

  • $st

    A scalar reference that receives an error status, the equivalent of ICU UErrorCode. It holds a message starting with the ICU error code name, such as U_PARSE_ERROR: .... Most methods do nothing if it is already set.

  • $out

    A scalar reference to the string being built by formatting.

  • $pos

    The position in $out where the text produced is inserted. Rules are formatted by inserting their text into the output, then the text of their substitutions at their own offsets.

  • $rc

    The recursion count, checked against $Locale::Unicode::RBNF::RuleSet::RECURSION_LIMIT (64), as ICU does, to stop runaway rule descriptions.

  • $pp

    A parse position, as an hash reference with the keys index and error, the equivalent of ICU ParsePosition.

  • $mask

    The bit mask of the non-numerical rules already executed during a parse, used by ICU to prevent infinite recursion through them.

CONSTANTS

The rule types, which are also the base values of the non-numerical rules, as in ICU NFRule:

  • NO_BASE (0)

  • NEGATIVE_NUMBER (-1), the -x rule

  • IMPROPER_FRACTION (-2), the x.x rule

  • PROPER_FRACTION (-3), the 0.x rule

  • DEFAULT_RULE (-4), the x.0 rule

  • INFINITY_RULE (-5), the Inf rule

  • NAN_RULE (-6), the NaN rule

  • OTHER_RULE (-7), returned by "get_type" for a normal rule

The variable @RULE_PREFIXES holds the tokens that start a substitution: <<, <%, <#, <0, >>, >%, >#, >0, =%, =# and =0.

CONSTRUCTOR

new

my $rule = Locale::Unicode::RBNF::Rule->new( $formatter, $description, \$st );

Takes the Locale::Unicode::RBNF object that owns the rule, the description of a single rule, and a scalar reference that receives an error status. The rule descriptor, the part before the colon, such as 100, 1000/1000, 100>>, -x, x.x or Inf, is parsed, and removed from the rule text.

The formatter is kept as a weak reference. Rules are normally created with "make_rules", which also extracts the substitutions.

METHODS

do_format_double

$rule->do_format_double( $number, $out, $pos, $rc, $st );

This is ICU NFRule::doFormat() for a double: it inserts the rule text, with any plural sub-message resolved for the number, into $out at $pos, then lets each substitution format its part of the number, the second substitution first, so that the offsets remain valid.

do_format_int

$rule->do_format_int( $number, $out, $pos, $rc, $st );

The same as "do_format_double", for an integer.

do_parse

my( $success, $value ) = $rule->do_parse( $text, $pp, $is_fraction_rule, $upper_bound, $mask, $rc );

This is ICU NFRule::doParse(): it matches the text against the rule text and its substitutions, and returns a list of 2 elements: whether something was matched, and the value parsed. $pp->{index} is set to the number of characters matched.

This method is provided by Locale::Unicode::RBNF::PP, and used by the pure Perl parsing engine.

get_base_value

Returns the base value of the rule, or, for a non-numerical rule, its type; see "CONSTANTS".

get_decimal_point

Returns the decimal point character of a fraction rule, such as . in x.x or , in x,x, or an empty string if there is none.

get_divisor

Returns the divisor of the rule, that is the radix raised to the power of the exponent, as an int64_t.

get_type

Returns the base value for a non-numerical rule, and OTHER_RULE for a normal rule.

has_modulus_substitution

Returns true if one of the substitutions of the rule is a modulus substitution (>>).

make_rules

Locale::Unicode::RBNF::Rule->make_rules( $description, $rule_set, $predecessor, $formatter, \@rules, \$st );

This is ICU NFRule::makeRules(): it creates the rule, or, if the description contains bracketed optional text, the two rules it stands for, extracts their substitutions, and adds them to the array reference \@rules, or, for a non-numerical rule, to the special rules of the rule set $rule_set with "set_non_numerical_rule" in Locale::Unicode::RBNF::RuleSet.

$predecessor is the previous rule of the rule set, used by >>> substitutions. It returns nothing; errors are reported in $st.

set_base_value

$rule->set_base_value( $value, \$st );

Sets the base value of the rule, resets the radix to 10, computes the exponent and the divisor, and updates the divisor of the substitutions. This is used by the rule set for rules that have no explicit base value.

set_decimal_format_symbols

$rule->set_decimal_format_symbols( $symbols, \$st );

Passes new decimal format symbols to the substitutions of the rule.

should_roll_back

my $bool = $rule->should_roll_back( $number );

Returns true if the preceding rule must be used instead of this one for the number. For a rule such as 100: << hundred[]; >>, the rule at 101 must not be used for 200, otherwise the result would be "two hundred zero".

to_string

Returns the description of the rule in the ICU syntax, terminated with a semicolon, as ICU NFRule::_appendRuleText() produces it. This is used by "rules" in Locale::Unicode::RBNF.

SEE ALSO

Locale::Unicode::RBNF, Locale::Unicode::RBNF::RuleSet, Locale::Unicode::RBNF::Substitution

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright(c) 2026 DEGUEST Pte. Ltd.

Portions are derived from ICU, Copyright (C) 2016 and later Unicode, Inc. and others, under the Unicode License (https://www.unicode.org/copyright.html). Its text is in the LICENSE-UNICODE file of this distribution.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.