ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-Scalar/README
Revision: 1.1
Committed: Tue Mar 8 20:17:17 2005 UTC (19 years, 8 months ago) by root
Branch: MAIN
CVS Tags: rel-1_04
Log Message:
*** empty log message ***

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     unmagic scalar, type
67     Remove the specified magic from the scalar (DANGEROUS!).
68    
69     weaken scalar
70     Weaken a reference. (See also WeakRef).
71    
72     taint scalar
73     Taint the scalar.
74    
75     tainted scalar
76     returns true when the scalar is tainted, false otherwise.
77    
78     untaint scalar
79     Remove the tainted flag from the specified scalar.
80    
81     grow scalar, newlen
82     Sets the memory area used for the scalar to the given length, if the
83     current length is less than the new value. This does not affect the
84     contents of the scalar, but is only useful to "pre-allocate" memory
85     space if you know the scalar will grow. The return value is the
86     modified scalar (the scalar is modified in-place).
87    
88     refcnt scalar[, newrefcnt]
89     Returns the current reference count of the given scalar and
90     optionally sets it to the given reference count.
91    
92     refcnt_inc scalar
93     Increments the reference count of the given scalar inplace.
94    
95     refcnt_dec scalar
96     Decrements the reference count of the given scalar inplace. Use
97     "weaken" instead if you understand what this function is fore.
98     Better yet: don't use this module in this case.
99    
100     refcnt_rv scalar[, newrefcnt]
101     Works like "refcnt", but dereferences the given reference first.
102     This is useful to find the reference count of arrays or hashes,
103     which cnanot be passed directly. Remember that taking a reference of
104     some object increases it's reference count, so the reference count
105     used by the *_rv-functions tend to be one higher.
106    
107     refcnt_inc_rv scalar
108     Works like "refcnt_inc", but dereferences the given reference first.
109    
110     refcnt_dec_rv scalar
111     Works like "refcnt_dec", but dereferences the given reference first.
112    
113     ok scalar
114     uok scalar
115     rok scalar
116     pok scalar
117     nok scalar
118     niok scalar
119     Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
120     scalar, respectively.
121    
122     CANDIDATES FOR FUTURE RELEASES
123     The following API functions (perlapi) are considered for future
124     inclusion in this module If you want them, write me.
125    
126     sv_upgrade
127     sv_pvn_force
128     sv_pvutf8n_force
129     the sv2xx family
130    
131     AUTHOR
132     Marc Lehmann <schmorp@schmorp.de>
133     http://home.schmorp.de/
134