Fix langinfo(ALT_DIGITS)

This has never worked properly before in Perl.  The code is returning
the result of the libc function nl_langinfo().  The documentation for it
that I have found (and presumably my predecessors) is very unclear.  But
what actually happens (from using gdb) is that the return is very C
unfriendly.

Instead of returning a NUL-terminated string, it returns 100 (perhaps
fewer) NUL-terminated strings in a row.  When it is fewer (given the
few examples I've seen), the final one ends with two NULs in a row.  (I
can't think of a way for it to work and be otherwise).  The 100th one
doesn't necessarily have two terminating NULs.

Prior to this commit, only the string for the zeroth digit was returned;
now the entire ALT_DIGIT string sequence is returned, forcing a double
NUL at the end of the final one.

This information is accessible in several ways.  Via XS, one can use any
of several functions, including the newly introduced sv_langinfo(),
returning an SV, which allows for easier handling of embedded NULs.
(Otherwise in XS, using the functions that return a char*, one has to
look for the double-NUL.)

From Perl-space, the access is via I18N::Langinfo, which behind the
scenes also uses an SV.  The documentation added in this commit gives
advice for how to turn the return into an @array for more convenient
access.

Author: khwilliamson

ext/I18N-Langinfo/Langinfo.pm

@@ -77,6 +77,8 @@ XSLoader::load();
 1;
 __END__
 
+=encoding utf8
+
 =head1 NAME
 
 I18N::Langinfo - query locale information
@@ -155,13 +157,52 @@ For the character code set being used (such as "ISO8859-1", "cp850",
 
 =item *
 
-For an alternate representation of digits, for the
-radix character used between the integer and the fractional part
-of decimal numbers, the group separator string for large-ish floating point
-numbers (yes, the final two are redundant with
+For the radix character used between the integer and the fractional part of
+decimal numbers, and the group separator string for large-ish floating point
+numbers (yes, these are redundant with
 L<POSIX::localeconv()|POSIX/localeconv>):
 
-    ALT_DIGITS RADIXCHAR THOUSEP
+    RADIXCHAR THOUSEP
+
+=item *
+
+For any alternate digits used in this locale besides the standard C<0..9>:
+
+    ALT_DIGITS
+
+This returns a sequence of alternate numeric reprsesentations for the numbers
+C<0> ... up to C<99>.  The representations are returned in a single string,
+with a semi-colon C<;> used to separated the individual ones.
+
+Most locales don't have alternate digits, so the string will be empty.
+
+To access this data conveniently, you could do something like
+
+ use I18N::Langinfo qw(langinfo ALT_DIGITS);
+ my @alt_digits = split ';', langinfo(ALT_DIGITS);
+
+The array C<@alt_digits> will contain 0 elements if the current locale doesn't
+have alternate digits specified for it.  Otherwise, it will have as many
+elements as the locale defines, with C<[0]> containing the alternate digit for
+zero; C<[1]> for one; and so forth, up to potentially C<[99]> for the
+alternate representation of ninety-nine.
+
+Be aware that the alternate representation in some locales for the numbers
+0..9 will have a leading alternate-zero, so would look like the equivalent of
+00..09.
+
+Running this program
+
+ use I18N::Langinfo qw(langinfo ALT_DIGITS);
+ my @alt_digits = split ';', langinfo(ALT_DIGITS);
+ splice @alt_digits, 15;
+ print join " ", @alt_digits, "\n";
+
+on a Japanese locale yields
+
+S<C<〇 一 二 三 四 五 六 七 八 九 十 十一 十二 十三 十四>>
+
+on some platforms.
 
 =item *
 
@@ -214,6 +255,16 @@ Only the values for English are returned.  C<YESSTR> and C<NOSTR> have been
 removed from POSIX 2008, and are retained here for backwards compatibility.
 Your platform's C<nl_langinfo> may not support them.
 
+=item C<ALT_DIGITS>
+
+On systems with a C<L<strftime(3)>> that recognizes the POSIX-defined C<%O>
+format modifier (not Windows), perl tries hard to return these.  The result
+likely will go as high as what C<nl_langinfo()> would return, but not
+necessarily; and the numbers from C<0..9> will always be stripped of leading
+zeros.
+
+Without C<%O>, an empty string is always returned.
+
 =item C<D_FMT>
 
 Always evaluates to C<%x>, the locale's appropriate date representation.
@@ -232,13 +283,6 @@ representation.
 The return may be incorrect for those rare locales where the currency symbol
 replaces the radix character.  If you have examples of it needing to work
 differently, please file a report at L<https://github.com/Perl/perl5/issues>.
-
-=item C<ALT_DIGITS>
-
-Currently this gives the same results as Linux does.  If you have examples of
-it needing to work differently, please file a report at
-L<https://github.com/Perl/perl5/issues>.
-
 =item C<ERA_D_FMT>
 
 =item C<ERA_T_FMT>

lib/locale.t

@@ -2495,6 +2495,51 @@ foreach my $Locale (@Locale) {
             print "# failed $locales_test_number locale '$Locale' numbers @f\n"
 	}
     }
+
+    {
+        my @f = ();
+        ++$locales_test_number;
+        $test_names{$locales_test_number} =
+                 'Verify ALT_DIGITS returns nothing, or else non-ASCII and'
+               . ' the single char digits evaluate to consecutive integers'
+               . ' starting at 0';
+
+        my $alts = langinfo(ALT_DIGITS);
+        if ($alts) {
+            my @alts = split ';', $alts;
+            my $prev = -1;
+            foreach my $num (@alts) {
+                if ($num =~ /[[:ascii:]]/) {
+                    push @f, disp_str($num);
+                    last;
+                }
+
+                # We only look at single character strings; likely locales
+                # that have alternate digits have a different mechanism for
+                # representing larger numbers.  Japanese for example, has a
+                # single character for the number 10, which is prefixed to the
+                # '1' symbol for '11', etc.  And 21 is represented by 3
+                # characters, the '2' symbol, followed by the '10' symbol,
+                # then the '1' symbol.  (There is nothing to say that a locale
+                # even has to use base 10.)
+                last if length $num > 1;
+
+                use Unicode::UCD 'num';
+                my $value = num($num);
+                if ($value != $prev + 1) {
+                    push @f, disp_str($num);
+                    last;
+                }
+
+                $prev = $value;
+            }
+        }
+
+        report_result($Locale, $locales_test_number, @f == 0);
+        if (@f) {
+            print "# failed $locales_test_number locale '$Locale' numbers @f\n"
+	}
+    }
 }
 
 my $final_locales_test_number = $locales_test_number;