ext/Encode/Encode.pm

   1 #
   2 # $Id: Encode.pm,v 1.80 2002/10/21 20:38:45 dankogai Exp $
   3 #
   4 package Encode;
   5 use strict;
   6 our $VERSION = do { my @r = (q$Revision: 1.80 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
   7 our $DEBUG = 0;
   8 use XSLoader ();
   9 XSLoader::load(__PACKAGE__, $VERSION);
  10
  11 require Exporter;
  12 use base qw/Exporter/;
  13
  14 # Public, encouraged API is exported by default
  15
  16 our @EXPORT = qw(
  17   decode  decode_utf8  encode  encode_utf8
  18   encodings  find_encoding
  19 );
  20
  21 our @FB_FLAGS  = qw(DIE_ON_ERR WARN_ON_ERR RETURN_ON_ERR LEAVE_SRC
  22                     PERLQQ HTMLCREF XMLCREF);
  23 our @FB_CONSTS = qw(FB_DEFAULT FB_CROAK FB_QUIET FB_WARN
  24                     FB_PERLQQ FB_HTMLCREF FB_XMLCREF);
  25
  26 our @EXPORT_OK =
  27     (
  28      qw(
  29        _utf8_off _utf8_on define_encoding from_to is_16bit is_8bit
  30        is_utf8 perlio_ok resolve_alias utf8_downgrade utf8_upgrade
  31       ),
  32      @FB_FLAGS, @FB_CONSTS,
  33     );
  34
  35 our %EXPORT_TAGS =
  36     (
  37      all          =>  [ @EXPORT, @EXPORT_OK ],
  38      fallbacks    =>  [ @FB_CONSTS ],
  39      fallback_all =>  [ @FB_CONSTS, @FB_FLAGS ],
  40     );
  41
  42 # Documentation moved after __END__ for speed - NI-S
  43
  44 our $ON_EBCDIC = (ord("A") == 193);
  45
  46 use Encode::Alias;
  47
  48 # Make a %Encoding package variable to allow a certain amount of cheating
  49 our %Encoding;
  50 our %ExtModule;
  51 require Encode::Config;
  52 eval { require Encode::ConfigLocal };
  53
  54 sub encodings
  55 {
  56     my $class = shift;
  57     my %enc;
  58     if (@_ and $_[0] eq ":all"){
  59         %enc = ( %Encoding, %ExtModule );
  60     }else{
  61         %enc = %Encoding;
  62         for my $mod (map {m/::/o ? $_ : "Encode::$_" } @_){
  63             $DEBUG and warn $mod;
  64             for my $enc (keys %ExtModule){
  65                 $ExtModule{$enc} eq $mod and $enc{$enc} = $mod;
  66             }
  67         }
  68     }
  69     return
  70         sort { lc $a cmp lc $b }
  71              grep {!/^(?:Internal|Unicode|Guess)$/o} keys %enc;
  72 }
  73
  74 sub perlio_ok{
  75     my $obj = ref($_[0]) ? $_[0] : find_encoding($_[0]);
  76     $obj->can("perlio_ok") and return $obj->perlio_ok();
  77     return 0; # safety net
  78 }
  79
  80 sub define_encoding
  81 {
  82     my $obj  = shift;
  83     my $name = shift;
  84     $Encoding{$name} = $obj;
  85     my $lc = lc($name);
  86     define_alias($lc => $obj) unless $lc eq $name;
  87     while (@_){
  88         my $alias = shift;
  89         define_alias($alias, $obj);
  90     }
  91     return $obj;
  92 }
  93
  94 sub getEncoding
  95 {
  96     my ($class, $name, $skip_external) = @_;
  97
  98     ref($name) && $name->can('new_sequence') and return $name;
  99     exists $Encoding{$name} and return $Encoding{$name};
 100     my $lc = lc $name;
 101     exists $Encoding{$lc} and return $Encoding{$lc};
 102
 103     my $oc = $class->find_alias($name);
 104     defined($oc) and return $oc;
 105     $lc ne $name and $oc = $class->find_alias($lc);
 106     defined($oc) and return $oc;
 107
 108     unless ($skip_external)
 109     {
 110         if (my $mod = $ExtModule{$name} || $ExtModule{$lc}){
 111             $mod =~ s,::,/,g ; $mod .= '.pm';
 112             eval{ require $mod; };
 113             exists $Encoding{$name} and return $Encoding{$name};
 114         }
 115     }
 116     return;
 117 }
 118
 119 sub find_encoding
 120 {
 121     my ($name, $skip_external) = @_;
 122     return __PACKAGE__->getEncoding($name,$skip_external);
 123 }
 124
 125 sub resolve_alias {
 126     my $obj = find_encoding(shift);
 127     defined $obj and return $obj->name;
 128     return;
 129 }
 130
 131 sub encode($$;$)
 132 {
 133     my ($name, $string, $check) = @_;
 134     $check ||=0;
 135     my $enc = find_encoding($name);
 136     unless(defined $enc){
 137         require Carp;
 138         Carp::croak("Unknown encoding '$name'");
 139     }
 140     my $octets = $enc->encode($string,$check);
 141     return undef if ($check && length($string));
 142     return $octets;
 143 }
 144
 145 sub decode($$;$)
 146 {
 147     my ($name,$octets,$check) = @_;
 148     $check ||=0;
 149     my $enc = find_encoding($name);
 150     unless(defined $enc){
 151         require Carp;
 152         Carp::croak("Unknown encoding '$name'");
 153     }
 154     my $string = $enc->decode($octets,$check);
 155     $_[1] = $octets if $check;
 156     return $string;
 157 }
 158
 159 sub from_to($$$;$)
 160 {
 161     my ($string,$from,$to,$check) = @_;
 162     $check ||=0;
 163     my $f = find_encoding($from);
 164     unless (defined $f){
 165         require Carp;
 166         Carp::croak("Unknown encoding '$from'");
 167     }
 168     my $t = find_encoding($to);
 169     unless (defined $t){
 170         require Carp;
 171         Carp::croak("Unknown encoding '$to'");
 172     }
 173     my $uni = $f->decode($string,$check);
 174     return undef if ($check && length($string));
 175     $string =  $t->encode($uni,$check);
 176     return undef if ($check && length($uni));
 177     return defined($_[0] = $string) ? length($string) : undef ;
 178 }
 179
 180 sub encode_utf8($)
 181 {
 182     my ($str) = @_;
 183     utf8::encode($str);
 184     return $str;
 185 }
 186
 187 sub decode_utf8($)
 188 {
 189     my ($str) = @_;
 190     return undef unless utf8::decode($str);
 191     return $str;
 192 }
 193
 194 predefine_encodings();
 195
 196 #
 197 # This is to restore %Encoding if really needed;
 198 #
 199
 200 sub predefine_encodings{
 201     use Encode::Encoding;
 202     if ($ON_EBCDIC) {
 203         # was in Encode::UTF_EBCDIC
 204         package Encode::UTF_EBCDIC;
 205         push @Encode::UTF_EBCDIC::ISA, 'Encode::Encoding';
 206         *decode = sub{
 207             my ($obj,$str,$chk) = @_;
 208             my $res = '';
 209             for (my $i = 0; $i < length($str); $i++) {
 210                 $res .=
 211                     chr(utf8::unicode_to_native(ord(substr($str,$i,1))));
 212             }
 213             $_[1] = '' if $chk;
 214             return $res;
 215         };
 216         *encode = sub{
 217             my ($obj,$str,$chk) = @_;
 218             my $res = '';
 219             for (my $i = 0; $i < length($str); $i++) {
 220                 $res .=
 221                     chr(utf8::native_to_unicode(ord(substr($str,$i,1))));
 222             }
 223             $_[1] = '' if $chk;
 224             return $res;
 225         };
 226         $Encode::Encoding{Unicode} =
 227             bless {Name => "UTF_EBCDIC"} => "Encode::UTF_EBCDIC";
 228     } else {
 229         package Encode::Internal;
 230         push @Encode::Internal::ISA, 'Encode::Encoding';
 231         *decode = sub{
 232             my ($obj,$str,$chk) = @_;
 233             utf8::upgrade($str);
 234             $_[1] = '' if $chk;
 235             return $str;
 236         };
 237         *encode = \&decode;
 238         $Encode::Encoding{Unicode} =
 239             bless {Name => "Internal"} => "Encode::Internal";
 240     }
 241
 242     {
 243         # was in Encode::utf8
 244         package Encode::utf8;
 245         push @Encode::utf8::ISA, 'Encode::Encoding';
 246         # encode and decode methods now in Encode.xs
 247         $Encode::Encoding{utf8} =
 248             bless {Name => "utf8"} => "Encode::utf8";
 249     }
 250 }
 251
 252 1;
 253
 254 __END__
 255
 256 =head1 NAME
 257
 258 Encode - character encodings
 259
 260 =head1 SYNOPSIS
 261
 262     use Encode;
 263
 264 =head2 Table of Contents
 265
 266 Encode consists of a collection of modules whose details are too big
 267 to fit in one document.  This POD itself explains the top-level APIs
 268 and general topics at a glance.  For other topics and more details,
 269 see the PODs below:
 270
 271   Name                          Description
 272   --------------------------------------------------------
 273   Encode::Alias         Alias definitions to encodings
 274   Encode::Encoding      Encode Implementation Base Class
 275   Encode::Supported     List of Supported Encodings
 276   Encode::CN            Simplified Chinese Encodings
 277   Encode::JP            Japanese Encodings
 278   Encode::KR            Korean Encodings
 279   Encode::TW            Traditional Chinese Encodings
 280   --------------------------------------------------------
 281
 282 =head1 DESCRIPTION
 283
 284 The C<Encode> module provides the interfaces between Perl's strings
 285 and the rest of the system.  Perl strings are sequences of
 286 B<characters>.
 287
 288 The repertoire of characters that Perl can represent is at least that
 289 defined by the Unicode Consortium. On most platforms the ordinal
 290 values of the characters (as returned by C<ord(ch)>) is the "Unicode
 291 codepoint" for the character (the exceptions are those platforms where
 292 the legacy encoding is some variant of EBCDIC rather than a super-set
 293 of ASCII - see L<perlebcdic>).
 294
 295 Traditionally, computer data has been moved around in 8-bit chunks
 296 often called "bytes". These chunks are also known as "octets" in
 297 networking standards. Perl is widely used to manipulate data of many
 298 types - not only strings of characters representing human or computer
 299 languages but also "binary" data being the machine's representation of
 300 numbers, pixels in an image - or just about anything.
 301
 302 When Perl is processing "binary data", the programmer wants Perl to
 303 process "sequences of bytes". This is not a problem for Perl - as a
 304 byte has 256 possible values, it easily fits in Perl's much larger
 305 "logical character".
 306
 307 =head2 TERMINOLOGY
 308
 309 =over 2
 310
 311 =item *
 312
 313 I<character>: a character in the range 0..(2**32-1) (or more).
 314 (What Perl's strings are made of.)
 315
 316 =item *
 317
 318 I<byte>: a character in the range 0..255
 319 (A special case of a Perl character.)
 320
 321 =item *
 322
 323 I<octet>: 8 bits of data, with ordinal values 0..255
 324 (Term for bytes passed to or from a non-Perl context, e.g. a disk file.)
 325
 326 =back
 327
 328 =head1 PERL ENCODING API
 329
 330 =over 2
 331
 332 =item $octets  = encode(ENCODING, $string [, CHECK])
 333
 334 Encodes a string from Perl's internal form into I<ENCODING> and returns
 335 a sequence of octets.  ENCODING can be either a canonical name or
 336 an alias.  For encoding names and aliases, see L</"Defining Aliases">.
 337 For CHECK, see L</"Handling Malformed Data">.
 338
 339 For example, to convert a string from Perl's internal format to
 340 iso-8859-1 (also known as Latin1),
 341
 342   $octets = encode("iso-8859-1", $string);
 343
 344 B<CAVEAT>: When you run C<$octets = encode("utf8", $string)>, then $octets
 345 B<may not be equal to> $string.  Though they both contain the same data, the utf8 flag
 346 for $octets is B<always> off.  When you encode anything, utf8 flag of
 347 the result is always off, even when it contains completely valid utf8
 348 string. See L</"The UTF-8 flag"> below.
 349
 350 encode($valid_encoding, undef) is harmless but warns you for
 351 C<Use of uninitialized value in subroutine entry>.
 352 encode($valid_encoding, '') is harmless and warnless.
 353
 354 =item $string = decode(ENCODING, $octets [, CHECK])
 355
 356 Decodes a sequence of octets assumed to be in I<ENCODING> into Perl's
 357 internal form and returns the resulting string.  As in encode(),
 358 ENCODING can be either a canonical name or an alias. For encoding names
 359 and aliases, see L</"Defining Aliases">.  For CHECK, see
 360 L</"Handling Malformed Data">.
 361
 362 For example, to convert ISO-8859-1 data to a string in Perl's internal format:
 363
 364   $string = decode("iso-8859-1", $octets);
 365
 366 B<CAVEAT>: When you run C<$string = decode("utf8", $octets)>, then $string
 367 B<may not be equal to> $octets.  Though they both contain the same data,
 368 the utf8 flag for $string is on unless $octets entirely consists of
 369 ASCII data (or EBCDIC on EBCDIC machines).  See L</"The UTF-8 flag">
 370 below.
 371
 372 decode($valid_encoding, undef) is harmless but warns you for
 373 C<Use of uninitialized value in subroutine entry>.
 374 decode($valid_encoding, '') is harmless and warnless.
 375
 376 =item [$length =] from_to($octets, FROM_ENC, TO_ENC [, CHECK])
 377
 378 Converts B<in-place> data between two encodings. The data in $octets
 379 must be encoded as octets and not as characters in Perl's internal
 380 format. For example, to convert ISO-8859-1 data to Microsoft's CP1250 encoding:
 381
 382   from_to($octets, "iso-8859-1", "cp1250");
 383
 384 and to convert it back:
 385
 386   from_to($octets, "cp1250", "iso-8859-1");
 387
 388 Note that because the conversion happens in place, the data to be
 389 converted cannot be a string constant; it must be a scalar variable.
 390
 391 from_to() returns the length of the converted string in octets on success, undef
 392 otherwise.
 393
 394 B<CAVEAT>: The following operations look the same but are not quite so;
 395
 396   from_to($data, "iso-8859-1", "utf8"); #1
 397   $data = decode("iso-8859-1", $data);  #2
 398
 399 Both #1 and #2 make $data consist of a completely valid UTF-8 string
 400 but only #2 turns utf8 flag on.  #1 is equivalent to
 401
 402   $data = encode("utf8", decode("iso-8859-1", $data));
 403
 404 See L</"The UTF-8 flag"> below.
 405
 406 =item $octets = encode_utf8($string);
 407
 408 Equivalent to C<$octets = encode("utf8", $string);> The characters
 409 that comprise $string are encoded in Perl's internal format and the
 410 result is returned as a sequence of octets. All possible
 411 characters have a UTF-8 representation so this function cannot fail.
 412
 413
 414 =item $string = decode_utf8($octets [, CHECK]);
 415
 416 equivalent to C<$string = decode("utf8", $octets [, CHECK])>.
 417 The sequence of octets represented by
 418 $octets is decoded from UTF-8 into a sequence of logical
 419 characters. Not all sequences of octets form valid UTF-8 encodings, so
 420 it is possible for this call to fail.  For CHECK, see
 421 L</"Handling Malformed Data">.
 422
 423 =back
 424
 425 =head2 Listing available encodings
 426
 427   use Encode;
 428   @list = Encode->encodings();
 429
 430 Returns a list of the canonical names of the available encodings that
 431 are loaded.  To get a list of all available encodings including the
 432 ones that are not loaded yet, say
 433
 434   @all_encodings = Encode->encodings(":all");
 435
 436 Or you can give the name of a specific module.
 437
 438   @with_jp = Encode->encodings("Encode::JP");
 439
 440 When "::" is not in the name, "Encode::" is assumed.
 441
 442   @ebcdic = Encode->encodings("EBCDIC");
 443
 444 To find out in detail which encodings are supported by this package,
 445 see L<Encode::Supported>.
 446
 447 =head2 Defining Aliases
 448
 449 To add a new alias to a given encoding, use:
 450
 451   use Encode;
 452   use Encode::Alias;
 453   define_alias(newName => ENCODING);
 454
 455 After that, newName can be used as an alias for ENCODING.
 456 ENCODING may be either the name of an encoding or an
 457 I<encoding object>
 458
 459 But before you do so, make sure the alias is nonexistent with
 460 C<resolve_alias()>, which returns the canonical name thereof.
 461 i.e.
 462
 463   Encode::resolve_alias("latin1") eq "iso-8859-1" # true
 464   Encode::resolve_alias("iso-8859-12")   # false; nonexistent
 465   Encode::resolve_alias($name) eq $name  # true if $name is canonical
 466
 467 resolve_alias() does not need C<use Encode::Alias>; it can be
 468 exported via C<use Encode qw(resolve_alias)>.
 469
 470 See L<Encode::Alias> for details.
 471
 472 =head1 Encoding via PerlIO
 473
 474 If your perl supports I<PerlIO> (which is the default), you can use a PerlIO layer to decode
 475 and encode directly via a filehandle.  The following two examples
 476 are totally identical in their functionality.
 477
 478   # via PerlIO
 479   open my $in,  "<:encoding(shiftjis)", $infile  or die;
 480   open my $out, ">:encoding(euc-jp)",   $outfile or die;
 481   while(<$in>){ print $out $_; }
 482
 483   # via from_to
 484   open my $in,  "<", $infile  or die;
 485   open my $out, ">", $outfile or die;
 486   while(<$in>){
 487     from_to($_, "shiftjis", "euc-jp", 1);
 488     print $out $_;
 489   }
 490
 491 Unfortunately, it may be that encodings are PerlIO-savvy.  You can check
 492 if your encoding is supported by PerlIO by calling the C<perlio_ok>
 493 method.
 494
 495   Encode::perlio_ok("hz");             # False
 496   find_encoding("euc-cn")->perlio_ok;  # True where PerlIO is available
 497
 498   use Encode qw(perlio_ok);            # exported upon request
 499   perlio_ok("euc-jp")
 500
 501 Fortunately, all encodings that come with Encode core are PerlIO-savvy
 502 except for hz and ISO-2022-kr.  For gory details, see L<Encode::Encoding> and L<Encode::PerlIO>.
 503
 504 =head1 Handling Malformed Data
 505
 506 =over 2
 507
 508 The I<CHECK> argument is used as follows.  When you omit it,
 509 the behaviour is the same as if you had passed a value of 0 for
 510 I<CHECK>.
 511
 512 =item I<CHECK> = Encode::FB_DEFAULT ( == 0)
 513
 514 If I<CHECK> is 0, (en|de)code will put a I<substitution character>
 515 in place of a malformed character.  For UCM-based encodings,
 516 E<lt>subcharE<gt> will be used.  For Unicode, the code point C<0xFFFD> is used.
 517 If the data is supposed to be UTF-8, an optional lexical warning
 518 (category utf8) is given.
 519
 520 =item I<CHECK> = Encode::FB_CROAK ( == 1)
 521
 522 If I<CHECK> is 1, methods will die on error immediately with an error
 523 message.  Therefore, when I<CHECK> is set to 1,  you should trap the
 524 fatal error with eval{} unless you really want to let it die on error.
 525
 526 =item I<CHECK> = Encode::FB_QUIET
 527
 528 If I<CHECK> is set to Encode::FB_QUIET, (en|de)code will immediately
 529 return the portion of the data that has been processed so far when
 530 an error occurs. The data argument will be overwritten with
 531 everything after that point (that is, the unprocessed part of data).
 532 This is handy when you have to call decode repeatedly in the case
 533 where your source data may contain partial multi-byte character
 534 sequences, for example because you are reading with a fixed-width
 535 buffer. Here is some sample code that does exactly this:
 536
 537   my $data = ''; my $utf8 = '';
 538   while(defined(read $fh, $buffer, 256)){
 539     # buffer may end in a partial character so we append
 540     $data .= $buffer;
 541     $utf8 .= decode($encoding, $data, Encode::FB_QUIET);
 542     # $data now contains the unprocessed partial character
 543   }
 544
 545 =item I<CHECK> = Encode::FB_WARN
 546
 547 This is the same as above, except that it warns on error.  Handy when
 548 you are debugging the mode above.
 549
 550 =item perlqq mode (I<CHECK> = Encode::FB_PERLQQ)
 551
 552 =item HTML charref mode (I<CHECK> = Encode::FB_HTMLCREF)
 553
 554 =item XML charref mode (I<CHECK> = Encode::FB_XMLCREF)
 555
 556 For encodings that are implemented by Encode::XS, CHECK ==
 557 Encode::FB_PERLQQ turns (en|de)code into C<perlqq> fallback mode.
 558
 559 When you decode, C<\xI<HH>> will be inserted for a malformed character,
 560 where I<HH> is the hex representation of the octet  that could not be
 561 decoded to utf8.  And when you encode, C<\x{I<HHHH>}> will be inserted,
 562 where I<HHHH> is the Unicode ID of the character that cannot be found
 563 in the character repertoire of the encoding.
 564
 565 HTML/XML character reference modes are about the same, in place of
 566 C<\x{I<HHHH>}>, HTML uses C<&#I<NNNN>>; where I<NNNN> is a decimal digit and
 567 XML uses C<&#xI<HHHH>>; where I<HHHH> is the hexadecimal digit.
 568
 569 =item The bitmask
 570
 571 These modes are actually set via a bitmask.  Here is how the FB_XX
 572 constants are laid out.  You can import the FB_XX constants via
 573 C<use Encode qw(:fallbacks)>; you can import the generic bitmask
 574 constants via C<use Encode qw(:fallback_all)>.
 575
 576                      FB_DEFAULT FB_CROAK FB_QUIET FB_WARN  FB_PERLQQ
 577  DIE_ON_ERR    0x0001             X
 578  WARN_ON_ERR   0x0002                               X
 579  RETURN_ON_ERR 0x0004                      X        X
 580  LEAVE_SRC     0x0008
 581  PERLQQ        0x0100                                        X
 582  HTMLCREF      0x0200
 583  XMLCREF       0x0400
 584
 585 =head2 Unimplemented fallback schemes
 586
 587 In the future, you will be able to use a code reference to a callback
 588 function for the value of I<CHECK> but its API is still undecided.
 589
 590 The fallback scheme does not work on EBCDIC platforms.
 591
 592 =head1 Defining Encodings
 593
 594 To define a new encoding, use:
 595
 596     use Encode qw(define_encoding);
 597     define_encoding($object, 'canonicalName' [, alias...]);
 598
 599 I<canonicalName> will be associated with I<$object>.  The object
 600 should provide the interface described in L<Encode::Encoding>.
 601 If more than two arguments are provided then additional
 602 arguments are taken as aliases for I<$object>.
 603
 604 See L<Encode::Encoding> for more details.
 605
 606 =head1 The UTF-8 flag
 607
 608 Before the introduction of utf8 support in perl, The C<eq> operator
 609 just compared the strings represented by two scalars. Beginning with
 610 perl 5.8, C<eq> compares two strings with simultaneous consideration
 611 of I<the utf8 flag>. To explain why we made it so, I will quote page
 612 402 of C<Programming Perl, 3rd ed.>
 613
 614 =over 2
 615
 616 =item Goal #1:
 617
 618 Old byte-oriented programs should not spontaneously break on the old
 619 byte-oriented data they used to work on.
 620
 621 =item Goal #2:
 622
 623 Old byte-oriented programs should magically start working on the new
 624 character-oriented data when appropriate.
 625
 626 =item Goal #3:
 627
 628 Programs should run just as fast in the new character-oriented mode
 629 as in the old byte-oriented mode.
 630
 631 =item Goal #4:
 632
 633 Perl should remain one language, rather than forking into a
 634 byte-oriented Perl and a character-oriented Perl.
 635
 636 =back
 637
 638 Back when C<Programming Perl, 3rd ed.> was written, not even Perl 5.6.0
 639 was born and many features documented in the book remained
 640 unimplemented for a long time.  Perl 5.8 corrected this and the introduction
 641 of the UTF-8 flag is one of them.  You can think of this perl notion as of a
 642 byte-oriented mode (utf8 flag off) and a character-oriented mode (utf8
 643 flag on).
 644
 645 Here is how Encode takes care of the utf8 flag.
 646
 647 =over 2
 648
 649 =item *
 650
 651 When you encode, the resulting utf8 flag is always off.
 652
 653 =item
 654
 655 When you decode, the resulting utf8 flag is on unless you can
 656 unambiguously represent data.  Here is the definition of
 657 dis-ambiguity.
 658
 659 After C<$utf8 = decode('foo', $octet);>,
 660
 661   When $octet is...   The utf8 flag in $utf8 is
 662   ---------------------------------------------
 663   In ASCII only (or EBCDIC only)            OFF
 664   In ISO-8859-1                              ON
 665   In any other Encoding                      ON
 666   ---------------------------------------------
 667
 668 As you see, there is one exception, In ASCII.  That way you can assue
 669 Goal #1.  And with Encode Goal #2 is assumed but you still have to be
 670 careful in such cases mentioned in B<CAVEAT> paragraphs.
 671
 672 This utf8 flag is not visible in perl scripts, exactly for the same
 673 reason you cannot (or you I<don't have to>) see if a scalar contains a
 674 string, integer, or floating point number.   But you can still peek
 675 and poke these if you will.  See the section below.
 676
 677 =back
 678
 679 =head2 Messing with Perl's Internals
 680
 681 The following API uses parts of Perl's internals in the current
 682 implementation.  As such, they are efficient but may change.
 683
 684 =over 2
 685
 686 =item is_utf8(STRING [, CHECK])
 687
 688 [INTERNAL] Tests whether the UTF-8 flag is turned on in the STRING.
 689 If CHECK is true, also checks the data in STRING for being well-formed
 690 UTF-8.  Returns true if successful, false otherwise.
 691
 692 =item _utf8_on(STRING)
 693
 694 [INTERNAL] Turns on the UTF-8 flag in STRING.  The data in STRING is
 695 B<not> checked for being well-formed UTF-8.  Do not use unless you
 696 B<know> that the STRING is well-formed UTF-8.  Returns the previous
 697 state of the UTF-8 flag (so please don't treat the return value as
 698 indicating success or failure), or C<undef> if STRING is not a string.
 699
 700 =item _utf8_off(STRING)
 701
 702 [INTERNAL] Turns off the UTF-8 flag in STRING.  Do not use frivolously.
 703 Returns the previous state of the UTF-8 flag (so please don't treat the
 704 return value as indicating success or failure), or C<undef> if STRING is
 705 not a string.
 706
 707 =back
 708
 709 =head1 SEE ALSO
 710
 711 L<Encode::Encoding>,
 712 L<Encode::Supported>,
 713 L<Encode::PerlIO>,
 714 L<encoding>,
 715 L<perlebcdic>,
 716 L<perlfunc/open>,
 717 L<perlunicode>,
 718 L<utf8>,
 719 the Perl Unicode Mailing List E<lt>perl-unicode@perl.orgE<gt>
 720
 721 =head1 MAINTAINER
 722
 723 This project was originated by Nick Ing-Simmons and later maintained
 724 by Dan Kogai E<lt>dankogai@dan.co.jpE<gt>.  See AUTHORS for a full
 725 list of people involved.  For any questions, use
 726 E<lt>perl-unicode@perl.orgE<gt> so we can all share.
 727
 728 =cut