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

# 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 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