Perl Diver 2.31
Main Environment Variables Perl Default Values Perl Config - Summary Perl Config - Full Installed Modules List Directory uptime Docs

Module Documentation
Details and documentation about a specific module, including version and documentation (if available). Note that while links to perldoc.com and search.cpan.org are provided, the module may be part of a larger distribution. If you reach a File Not Found page on either site, please try the parent module.

utf8

Name utf8
Version 1.19
Located at /usr/share/perl5
File /usr/share/perl5/utf8.pm
Is Core Yes
Search CPAN for this module utf8
Documentation utf8
Module Details utf8

NAME

utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code


SYNOPSIS

 use utf8;
 no utf8;
 # Convert the internal representation of a Perl scalar to/from UTF-8.
 $num_octets = utf8::upgrade($string);
 $success    = utf8::downgrade($string[, $fail_ok]);
 # Change each character of a Perl scalar to/from a series of
 # characters that represent the UTF-8 bytes of each original character.
 utf8::encode($string);  # "\x{100}"  becomes "\xc4\x80"
 utf8::decode($string);  # "\xc4\x80" becomes "\x{100}"
 # Convert a code point from the platform native character set to
 # Unicode, and vice-versa.
 $unicode = utf8::native_to_unicode(ord('A')); # returns 65 on both
                                               # ASCII and EBCDIC
                                               # platforms
 $native = utf8::unicode_to_native(65);        # returns 65 on ASCII
                                               # platforms; 193 on
                                               # EBCDIC
 $flag = utf8::is_utf8($string); # since Perl 5.8.1
 $flag = utf8::valid($string);


DESCRIPTION

The use utf8 pragma tells the Perl parser to allow UTF-8 in the program text in the current lexical scope. The no utf8 pragma tells Perl to switch back to treating the source text as literal bytes in the current lexical scope. (On EBCDIC platforms, technically it is allowing UTF-EBCDIC, and not UTF-8, but this distinction is academic, so in this document the term UTF-8 is used to mean both).

Do not use this pragma for anything else than telling Perl that your script is written in UTF-8. The utility functions described below are directly usable without use utf8;.

Because it is not possible to reliably tell UTF-8 from native 8 bit encodings, you need either a Byte Order Mark at the beginning of your source code, or use utf8;, to instruct perl.

When UTF-8 becomes the standard source format, this pragma will effectively become a no-op.

See also the effects of the -C switch and its cousin, the PERL_UNICODE environment variable, in perlrun.

Enabling the utf8 pragma has the following effect:

  • Bytes in the source text that are not in the ASCII character set will be treated as being part of a literal UTF-8 sequence. This includes most literals such as identifier names, string constants, and constant regular expression patterns.

Note that if you have non-ASCII, non-UTF-8 bytes in your script (for example embedded Latin-1 in your string literals), use utf8 will be unhappy. If you want to have such bytes under use utf8, you can disable this pragma until the end the block (or file, if at top level) by no utf8;.

Utility functions

The following functions are defined in the utf8:: package by the Perl core. You do not need to say use utf8 to use these and in fact you should not say that unless you really want to have UTF-8 source code.

utf8::encode is like utf8::upgrade, but the UTF8 flag is cleared. See perlunicode, and the C API functions sv_utf8_upgrade|perlapi/sv_utf8_upgrade, perlapi/sv_utf8_downgrade, perlapi/sv_utf8_encode, and perlapi/sv_utf8_decode, which are wrapped by the Perl functions utf8::upgrade, utf8::downgrade, utf8::encode and utf8::decode. Also, the functions utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade, and utf8::downgrade are actually internal, and thus always available, without a require utf8 statement.


BUGS

Some filesystems may not support UTF-8 file names, or they may be supported incompatibly with Perl. Therefore UTF-8 names that are visible to the filesystem, such as module names may not work.


SEE ALSO

perlunitut, perluniintro, perlrun, bytes, perlunicode

Perl Diver brought to you by ScriptSolutions.com © 1997- 2024