ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-Scalar/README
Revision: 1.4
Committed: Tue Aug 15 07:29:06 2017 UTC (7 years, 3 months ago) by root
Branch: MAIN
CVS Tags: rel-1_12, HEAD
Changes since 1.3: +24 -1 lines
Error occurred while calculating annotation data.
Log Message:
1.12

File Contents

# Content
1 NAME
2 Convert::Scalar - convert between different representations of perl
3 scalars
4
5 SYNOPSIS
6 use Convert::Scalar;
7
8 DESCRIPTION
9 This module exports various internal perl methods that change the
10 internal representation or state of a perl scalar. All of these work
11 in-place, that is, they modify their scalar argument. No functions are
12 exported by default.
13
14 The following export tags exist:
15
16 :utf8 all functions with utf8 in their name
17 :taint all functions with taint in their name
18 :refcnt all functions with refcnt in their name
19 :ok all *ok-functions.
20
21 utf8 scalar[, mode]
22 Returns true when the given scalar is marked as utf8, false
23 otherwise. If the optional mode argument is given, also forces the
24 interpretation of the string to utf8 (mode true) or plain bytes
25 (mode false). The actual (byte-) content is not changed. The return
26 value always reflects the state before any modification is done.
27
28 This function is useful when you "import" utf8-data into perl, or
29 when some external function (e.g. storing/retrieving from a
30 database) removes the utf8-flag.
31
32 utf8_on scalar
33 Similar to "utf8 scalar, 1", but additionally returns the scalar
34 (the argument is still modified in-place).
35
36 utf8_off scalar
37 Similar to "utf8 scalar, 0", but additionally returns the scalar
38 (the argument is still modified in-place).
39
40 utf8_valid scalar [Perl 5.7]
41 Returns true if the bytes inside the scalar form a valid utf8
42 string, false otherwise (the check is independent of the actual
43 encoding perl thinks the string is in).
44
45 utf8_upgrade scalar
46 Convert the string content of the scalar in-place to its
47 UTF8-encoded form (and also returns it).
48
49 utf8_downgrade scalar[, fail_ok=0]
50 Attempt to convert the string content of the scalar from
51 UTF8-encoded to ISO-8859-1. This may not be possible if the string
52 contains characters that cannot be represented in a single byte; if
53 this is the case, it leaves the scalar unchanged and either returns
54 false or, if "fail_ok" is not true (the default), croaks.
55
56 utf8_encode scalar
57 Convert the string value of the scalar to UTF8-encoded, but then
58 turn off the "SvUTF8" flag so that it looks like bytes to perl
59 again. (Might be removed in future versions).
60
61 utf8_length scalar
62 Returns the number of characters in the string, counting wide UTF8
63 characters as a single character, independent of wether the scalar
64 is marked as containing bytes or mulitbyte characters.
65
66 $old = readonly scalar[, $new]
67 Returns whether the scalar is currently readonly, and sets or clears
68 the readonly status if a new status is given.
69
70 readonly_on scalar
71 Sets the readonly flag on the scalar.
72
73 readonly_off scalar
74 Clears the readonly flag on the scalar.
75
76 unmagic scalar, type
77 Remove the specified magic from the scalar (DANGEROUS!).
78
79 weaken scalar
80 Weaken a reference. (See also WeakRef).
81
82 taint scalar
83 Taint the scalar.
84
85 tainted scalar
86 returns true when the scalar is tainted, false otherwise.
87
88 untaint scalar
89 Remove the tainted flag from the specified scalar.
90
91 length = len scalar
92 Returns SvLEN (scalar), that is, the actual number of bytes
93 allocated to the string value, or "undef", is the scalar has no
94 string value.
95
96 scalar = grow scalar, newlen
97 Sets the memory area used for the scalar to the given length, if the
98 current length is less than the new value. This does not affect the
99 contents of the scalar, but is only useful to "pre-allocate" memory
100 space if you know the scalar will grow. The return value is the
101 modified scalar (the scalar is modified in-place).
102
103 scalar = extend scalar, addlen=64
104 Reserves enough space in the scalar so that addlen bytes can be
105 appended without reallocating it. The actual contents of the scalar
106 will not be affected. The modified scalar will also be returned.
107
108 This function is meant to make append workloads efficient - if you
109 append a short string to a scalar many times (millions of times),
110 then perl will have to reallocate and copy the scalar basically
111 every time.
112
113 If you instead use "extend $scalar, length $shortstring", then
114 Convert::Scalar will use a "size to next power of two, roughly"
115 algorithm, so as the scalar grows, perl will have to resize and copy
116 it less and less often.
117
118 nread = extend_read fh, scalar, addlen=64
119 Calls "extend scalar, addlen" to ensure some space is available,
120 then do the equivalent of "sysread" to the end, to try to fill the
121 extra space. Returns how many bytes have been read, 0 on EOF or
122 undef> on eror, just like "sysread".
123
124 This function is useful to implement many protocols where you read
125 some data, see if it is enough to decode, and if not, read some
126 more, where the naive or easy way of doing this would result in bad
127 performance.
128
129 nread = read_all fh, scalar, length
130 Tries to read "length" bytes into "scalar". Unlike "read" or
131 "sysread", it will try to read more bytes if not all bytes could be
132 read in one go (this is often called "xread" in C).
133
134 Returns the total nunmber of bytes read (normally "length", unless
135 an error or EOF occured), 0 on EOF and "undef" on errors.
136
137 nwritten = write_all fh, scalar
138 Like "readall", but for writes - the equivalent of the "xwrite"
139 function often seen in C.
140
141 refcnt scalar[, newrefcnt]
142 Returns the current reference count of the given scalar and
143 optionally sets it to the given reference count.
144
145 refcnt_inc scalar
146 Increments the reference count of the given scalar inplace.
147
148 refcnt_dec scalar
149 Decrements the reference count of the given scalar inplace. Use
150 "weaken" instead if you understand what this function is fore.
151 Better yet: don't use this module in this case.
152
153 refcnt_rv scalar[, newrefcnt]
154 Works like "refcnt", but dereferences the given reference first.
155 This is useful to find the reference count of arrays or hashes,
156 which cannot be passed directly. Remember that taking a reference of
157 some object increases it's reference count, so the reference count
158 used by the *_rv-functions tend to be one higher.
159
160 refcnt_inc_rv scalar
161 Works like "refcnt_inc", but dereferences the given reference first.
162
163 refcnt_dec_rv scalar
164 Works like "refcnt_dec", but dereferences the given reference first.
165
166 ok scalar
167 uok scalar
168 rok scalar
169 pok scalar
170 nok scalar
171 niok scalar
172 Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
173 scalar, respectively.
174
175 CANDIDATES FOR FUTURE RELEASES
176 The following API functions (perlapi) are considered for future
177 inclusion in this module If you want them, write me.
178
179 sv_upgrade
180 sv_pvn_force
181 sv_pvutf8n_force
182 the sv2xx family
183
184 AUTHOR
185 Marc Lehmann <schmorp@schmorp.de>
186 http://home.schmorp.de/
187