[ViewVC] Contents of: cvs/Convert-Scalar/README

NAME
    Convert::Scalar - convert between different representations of perl
    scalars

SYNOPSIS
     use Convert::Scalar;

DESCRIPTION
    This module exports various internal perl methods that change the
    internal representation or state of a perl scalar. All of these work
    in-place, that is, they modify their scalar argument. No functions are
    exported by default.

    The following export tags exist:

     :utf8   all functions with utf8 in their name
     :taint  all functions with taint in their name
     :refcnt all functions with refcnt in their name
     :ok     all *ok-functions.

    utf8 scalar[, mode]
        Returns true when the given scalar is marked as utf8, false
        otherwise. If the optional mode argument is given, also forces the
        interpretation of the string to utf8 (mode true) or plain bytes
        (mode false). The actual (byte-) content is not changed. The return
        value always reflects the state before any modification is done.

        This function is useful when you "import" utf8-data into perl, or
        when some external function (e.g. storing/retrieving from a
        database) removes the utf8-flag.

    utf8_on scalar
        Similar to "utf8 scalar, 1", but additionally returns the scalar
        (the argument is still modified in-place).

    utf8_off scalar
        Similar to "utf8 scalar, 0", but additionally returns the scalar
        (the argument is still modified in-place).

    utf8_valid scalar [Perl 5.7]
        Returns true if the bytes inside the scalar form a valid utf8
        string, false otherwise (the check is independent of the actual
        encoding perl thinks the string is in).

    utf8_upgrade scalar
        Convert the string content of the scalar in-place to its
        UTF8-encoded form (and also returns it).

    utf8_downgrade scalar[, fail_ok=0]
        Attempt to convert the string content of the scalar from
        UTF8-encoded to ISO-8859-1. This may not be possible if the string
        contains characters that cannot be represented in a single byte; if
        this is the case, it leaves the scalar unchanged and either returns
        false or, if "fail_ok" is not true (the default), croaks.

    utf8_encode scalar
        Convert the string value of the scalar to UTF8-encoded, but then
        turn off the "SvUTF8" flag so that it looks like bytes to perl
        again. (Might be removed in future versions).

    utf8_length scalar
        Returns the number of characters in the string, counting wide UTF8
        characters as a single character, independent of wether the scalar
        is marked as containing bytes or mulitbyte characters.

    $old = readonly scalar[, $new]
        Returns whether the scalar is currently readonly, and sets or clears
        the readonly status if a new status is given.

    readonly_on scalar
        Sets the readonly flag on the scalar.

    readonly_off scalar
        Clears the readonly flag on the scalar.

    unmagic scalar, type
        Remove the specified magic from the scalar (DANGEROUS!).

    weaken scalar
        Weaken a reference. (See also WeakRef).

    taint scalar
        Taint the scalar.

    tainted scalar
        returns true when the scalar is tainted, false otherwise.

    untaint scalar
        Remove the tainted flag from the specified scalar.

    length = len scalar
        Returns SvLEN (scalar), that is, the actual number of bytes
        allocated to the string value, or "undef", is the scalar has no
        string value.

    scalar = grow scalar, newlen
        Sets the memory area used for the scalar to the given length, if the
        current length is less than the new value. This does not affect the
        contents of the scalar, but is only useful to "pre-allocate" memory
        space if you know the scalar will grow. The return value is the
        modified scalar (the scalar is modified in-place).

    scalar = extend scalar, addlen=64
        Reserves enough space in the scalar so that addlen bytes can be
        appended without reallocating it. The actual contents of the scalar
        will not be affected. The modified scalar will also be returned.

        This function is meant to make append workloads efficient - if you
        append a short string to a scalar many times (millions of times),
        then perl will have to reallocate and copy the scalar basically
        every time.

        If you instead use "extend $scalar, length $shortstring", then
        Convert::Scalar will use a "size to next power of two, roughly"
        algorithm, so as the scalar grows, perl will have to resize and copy
        it less and less often.

    nread = extend_read fh, scalar, addlen=64
        Calls "extend scalar, addlen" to ensure some space is available,
        then do the equivalent of "sysread" to the end, to try to fill the
        extra space. Returns how many bytes have been read, 0 on EOF or
        undef> on eror, just like "sysread".

        This function is useful to implement many protocols where you read
        some data, see if it is enough to decode, and if not, read some
        more, where the naive or easy way of doing this would result in bad
        performance.

    nread = read_all fh, scalar, length
        Tries to read "length" bytes into "scalar". Unlike "read" or
        "sysread", it will try to read more bytes if not all bytes could be
        read in one go (this is often called "xread" in C).

        Returns the total nunmber of bytes read (normally "length", unless
        an error or EOF occured), 0 on EOF and "undef" on errors.

    nwritten = write_all fh, scalar
        Like "readall", but for writes - the equivalent of the "xwrite"
        function often seen in C.

    refcnt scalar[, newrefcnt]
        Returns the current reference count of the given scalar and
        optionally sets it to the given reference count.

    refcnt_inc scalar
        Increments the reference count of the given scalar inplace.

    refcnt_dec scalar
        Decrements the reference count of the given scalar inplace. Use
        "weaken" instead if you understand what this function is fore.
        Better yet: don't use this module in this case.

    refcnt_rv scalar[, newrefcnt]
        Works like "refcnt", but dereferences the given reference first.
        This is useful to find the reference count of arrays or hashes,
        which cannot be passed directly. Remember that taking a reference of
        some object increases it's reference count, so the reference count
        used by the *_rv-functions tend to be one higher.

    refcnt_inc_rv scalar
        Works like "refcnt_inc", but dereferences the given reference first.

    refcnt_dec_rv scalar
        Works like "refcnt_dec", but dereferences the given reference first.

    ok scalar
    uok scalar
    rok scalar
    pok scalar
    nok scalar
    niok scalar
        Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
        scalar, respectively.

  CANDIDATES FOR FUTURE RELEASES
    The following API functions (perlapi) are considered for future
    inclusion in this module If you want them, write me.

     sv_upgrade
     sv_pvn_force
     sv_pvutf8n_force
     the sv2xx family

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.4
Committed:	Tue Aug 15 07:29:06 2017 UTC (6 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_12, HEAD
Changes since 1.3:	+24 -1 lines
Log Message:	1.12
#	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