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
Log Message:
1.12

File Contents

# User Rev Content
1 root 1.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 root 1.2 $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 root 1.1 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 root 1.2 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 root 1.1 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 root 1.4 scalar = extend scalar, addlen=64
104 root 1.2 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 root 1.4 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 root 1.1 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 root 1.3 which cannot be passed directly. Remember that taking a reference of
157 root 1.1 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