ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-Scalar/README
Revision: 1.2
Committed: Thu Aug 18 19:36:32 2011 UTC (13 years, 3 months ago) by root
Branch: MAIN
CVS Tags: rel-1_1
Changes since 1.1: +31 -1 lines
Log Message:
1.1

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
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 refcnt scalar[, newrefcnt]
119 Returns the current reference count of the given scalar and
120 optionally sets it to the given reference count.
121
122 refcnt_inc scalar
123 Increments the reference count of the given scalar inplace.
124
125 refcnt_dec scalar
126 Decrements the reference count of the given scalar inplace. Use
127 "weaken" instead if you understand what this function is fore.
128 Better yet: don't use this module in this case.
129
130 refcnt_rv scalar[, newrefcnt]
131 Works like "refcnt", but dereferences the given reference first.
132 This is useful to find the reference count of arrays or hashes,
133 which cnanot be passed directly. Remember that taking a reference of
134 some object increases it's reference count, so the reference count
135 used by the *_rv-functions tend to be one higher.
136
137 refcnt_inc_rv scalar
138 Works like "refcnt_inc", but dereferences the given reference first.
139
140 refcnt_dec_rv scalar
141 Works like "refcnt_dec", but dereferences the given reference first.
142
143 ok scalar
144 uok scalar
145 rok scalar
146 pok scalar
147 nok scalar
148 niok scalar
149 Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
150 scalar, respectively.
151
152 CANDIDATES FOR FUTURE RELEASES
153 The following API functions (perlapi) are considered for future
154 inclusion in this module If you want them, write me.
155
156 sv_upgrade
157 sv_pvn_force
158 sv_pvutf8n_force
159 the sv2xx family
160
161 AUTHOR
162 Marc Lehmann <schmorp@schmorp.de>
163 http://home.schmorp.de/
164