Debian Codegraph @

upstream/mageia-cauldron/man3pm/bytes.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "bytes 3pm"
61 .TH bytes 3pm 2024-05-07 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 bytes \- Perl pragma to expose the individual bytes of characters
68 .SH NOTICE
69 .IX Header "NOTICE"
70 Because the bytes pragma breaks encapsulation (i.e. it exposes the innards of
71 how the perl executable currently happens to store a string), the byte values
72 that result are in an unspecified encoding.
73 .PP
74 \&\fBUse of this module for anything other than debugging purposes is
75 strongly discouraged.\fR If you feel that the functions here within
76 might be useful for your application, this possibly indicates a
77 mismatch between your mental model of Perl Unicode and the current
78 reality. In that case, you may wish to read some of the perl Unicode
79 documentation: perluniintro, perlunitut, perlunifaq and
80 perlunicode.
81 .SH SYNOPSIS
82 .IX Header "SYNOPSIS"
83 .Vb 8
84 \& use bytes;
85 \& ... chr(...); # or bytes::chr
86 \& ... index(...); # or bytes::index
87 \& ... length(...); # or bytes::length
88 \& ... ord(...); # or bytes::ord
89 \& ... rindex(...); # or bytes::rindex
90 \& ... substr(...); # or bytes::substr
91 \& no bytes;
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 Perl\*(Aqs characters are stored internally as sequences of one or more bytes.
96 This pragma allows for the examination of the individual bytes that together
97 comprise a character.
98 .PP
99 Originally the pragma was designed for the loftier goal of helping incorporate
100 Unicode into Perl, but the approach that used it was found to be defective,
101 and the one remaining legitimate use is for debugging when you need to
102 non\-destructively examine characters\*(Aq individual bytes. Just insert this
103 pragma temporarily, and remove it after the debugging is finished.
104 .PP
105 The original usage can be accomplished by explicit (rather than this pragma\*(Aqs
106 implicit) encoding using the Encode module:
107 .PP
108 .Vb 1
109 \& use Encode qw/encode/;
110 \&
111 \& my $utf8_byte_string = encode "UTF8", $string;
112 \& my $latin1_byte_string = encode "Latin1", $string;
113 .Ve
114 .PP
115 Or, if performance is needed and you are only interested in the UTF\-8
116 representation:
117 .PP
118 .Vb 1
119 \& utf8::encode(my $utf8_byte_string = $string);
120 .Ve
121 .PP
122 \&\f(CW\*(C`no bytes\*(C'\fR can be used to reverse the effect of \f(CW\*(C`use bytes\*(C'\fR within the
123 current lexical scope.
124 .PP
125 As an example, when Perl sees \f(CW\*(C`$x = chr(400)\*(C'\fR, it encodes the character
126 in UTF\-8 and stores it in \f(CW$x\fR. Then it is marked as character data, so,
127 for instance, \f(CW\*(C`length $x\*(C'\fR returns \f(CW1\fR. However, in the scope of the
128 \&\f(CW\*(C`bytes\*(C'\fR pragma, \f(CW$x\fR is treated as a series of bytes \- the bytes that make
129 up the UTF8 encoding \- and \f(CW\*(C`length $x\*(C'\fR returns \f(CW2\fR:
130 .PP
131 .Vb 9
132 \& $x = chr(400);
133 \& print "Length is ", length $x, "\en"; # "Length is 1"
134 \& printf "Contents are %vd\en", $x; # "Contents are 400"
135 \& {
136 \& use bytes; # or "require bytes; bytes::length()"
137 \& print "Length is ", length $x, "\en"; # "Length is 2"
138 \& printf "Contents are %vd\en", $x; # "Contents are 198.144 (on
139 \& # ASCII platforms)"
140 \& }
141 .Ve
142 .PP
143 \&\f(CWchr()\fR, \f(CWord()\fR, \f(CWsubstr()\fR, \f(CWindex()\fR and \f(CWrindex()\fR behave similarly.
144 .PP
145 For more on the implications, see perluniintro and perlunicode.
146 .PP
147 \&\f(CWbytes::length()\fR is admittedly handy if you need to know the
148 \&\fBbyte length\fR of a Perl scalar. But a more modern way is:
149 .PP
150 .Vb 2
151 \& use Encode \*(Aqencode\*(Aq;
152 \& length(encode(\*(AqUTF\-8\*(Aq, $scalar))
153 .Ve
154 .SH LIMITATIONS
155 .IX Header "LIMITATIONS"
156 \&\f(CWbytes::substr()\fR does not work as an \fR\f(BIlvalue()\fR\fI\fR.
157 .SH "SEE ALSO"
158 .IX Header "SEE ALSO"
159 perluniintro, perlunicode, utf8, Encode