develooper Front page | perl.perl5.porters | Postings from February 2017

Re: Proposal: Rename utf8::is_utf8() to utf8::is_upgraded()

Thread Previous
From:
Sawyer X
Date:
February 20, 2017 10:36
Subject:
Re: Proposal: Rename utf8::is_utf8() to utf8::is_upgraded()
Message ID:
e6d85767-131f-11f3-4603-ebfdc3d31a5a@gmail.com
[Top-posted]

I basically agree with Karl and Kent on this. Having a synonym allows
people to use it knowingly, even in only that narrow use-case.

Following Kent's reasoning, we should make it absolutely clear through
the documentation which function you should use when. is_utf8() can be
documented succinctly as "Synonym to is_upgraded()" (or whatever we call
it). I explicitly meant "synonym to <new name>" to make sure the new
name stands out and not the old name. That way you have a clear function
(is_upgraded() or whatever) that clearly states when you want to use it,
but you could also find is_utf8() if you look for it.


On 02/19/2017 07:51 PM, Kent Fredric wrote:
> On 20 February 2017 at 07:41, Father Chrysostomos <sprout@cpan.org> wrote:
>> I do not.  The main reasons for using the function are to work around
>> problems with buggy XS modules.  Adding a synonym for a function that
>> most correct code should not be using seems like the wrong direction
>> to be going in.
> A better direction IMHO would be:
>
> 1. Remove is_utf8 from utf8.pm's synopsis
> 2. Make it *much* clearer in utf8.pm that is_utf8 is not something
> people should use, because the current description doesn't give any
> direction in this regard:
>
>     *   "$flag = utf8::is_utf8($string)"
>
>         (Since Perl 5.8.1) Test whether $string is marked internally as
>         encoded in UTF-8. Functionally the same as "Encode::is_utf8()".
>
> And the followed ref says:
>
>    is_utf8
>       is_utf8(STRING [, CHECK])
>
>     [INTERNAL] Tests whether the UTF8 flag is turned on in the STRING. If
>     CHECK is true, also checks whether STRING contains well-formed UTF-8.
>     Returns true if successful, false otherwise.
>
>     As of Perl 5.8.1, utf8 also has the "utf8::is_utf8" function.
>
> Doesn't really convey any sort of clarity here as to where and when it
> makes sense to use, or stipulate clearly that typical expectations of
> what this does is wrong.
>
> Can't expect people to do the right thing if even the documentation
> doesn't help.
>
>

Thread Previous


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About