.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Scalar 3pm" .TH Scalar 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Convert::Scalar \- convert between different representations of perl scalars .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Convert::Scalar; .Ve .SH "DESCRIPTION" .IX Header "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. .PP The following export tags exist: .PP .Vb 4 \& :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. .Ve .IP "utf8 scalar[, mode]" 4 .IX Item "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. .Sp This function is useful when you \*(L"import\*(R" utf8\-data into perl, or when some external function (e.g. storing/retrieving from a database) removes the utf8\-flag. .IP "utf8_on scalar" 4 .IX Item "utf8_on scalar" Similar to \f(CW\*(C`utf8 scalar, 1\*(C'\fR, but additionally returns the scalar (the argument is still modified in-place). .IP "utf8_off scalar" 4 .IX Item "utf8_off scalar" Similar to \f(CW\*(C`utf8 scalar, 0\*(C'\fR, but additionally returns the scalar (the argument is still modified in-place). .IP "utf8_valid scalar [Perl 5.7]" 4 .IX Item "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). .IP "utf8_upgrade scalar" 4 .IX Item "utf8_upgrade scalar" Convert the string content of the scalar in-place to its UTF8\-encoded form (and also returns it). .IP "utf8_downgrade scalar[, fail_ok=0]" 4 .IX Item "utf8_downgrade scalar[, fail_ok=0]" Attempt to convert the string content of the scalar from UTF8\-encoded to \&\s-1ISO\-8859\-1.\s0 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 \f(CW\*(C`fail_ok\*(C'\fR is not true (the default), croaks. .IP "utf8_encode scalar" 4 .IX Item "utf8_encode scalar" Convert the string value of the scalar to UTF8\-encoded, but then turn off the \f(CW\*(C`SvUTF8\*(C'\fR flag so that it looks like bytes to perl again. (Might be removed in future versions). .IP "utf8_length scalar" 4 .IX Item "utf8_length scalar" Returns the number of characters in the string, counting wide \s-1UTF8\s0 characters as a single character, independent of whether the scalar is marked as containing bytes or mulitbyte characters. .ie n .IP "$old = readonly scalar[, $new]" 4 .el .IP "\f(CW$old\fR = readonly scalar[, \f(CW$new\fR]" 4 .IX Item "$old = readonly scalar[, $new]" Returns whether the scalar is currently readonly, and sets or clears the readonly status if a new status is given. .IP "readonly_on scalar" 4 .IX Item "readonly_on scalar" Sets the readonly flag on the scalar. .IP "readonly_off scalar" 4 .IX Item "readonly_off scalar" Clears the readonly flag on the scalar. .IP "unmagic scalar, type" 4 .IX Item "unmagic scalar, type" Remove the specified magic from the scalar (\s-1DANGEROUS\s0!). .IP "weaken scalar" 4 .IX Item "weaken scalar" Weaken a reference. (See also WeakRef). .IP "taint scalar" 4 .IX Item "taint scalar" Taint the scalar. .IP "tainted scalar" 4 .IX Item "tainted scalar" returns true when the scalar is tainted, false otherwise. .IP "untaint scalar" 4 .IX Item "untaint scalar" Remove the tainted flag from the specified scalar. .IP "length = len scalar" 4 .IX Item "length = len scalar" Returns SvLEN (scalar), that is, the actual number of bytes allocated to the string value, or \f(CW\*(C`undef\*(C'\fR, is the scalar has no string value. .IP "scalar = grow scalar, newlen" 4 .IX Item "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 \*(L"pre-allocate\*(R" memory space if you know the scalar will grow. The return value is the modified scalar (the scalar is modified in-place). .IP "scalar = extend scalar, addlen=64" 4 .IX Item "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. .Sp 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. .Sp If you instead use \f(CW\*(C`extend $scalar, length $shortstring\*(C'\fR, then Convert::Scalar will use a \*(L"size to next power of two, roughly\*(R" algorithm, so as the scalar grows, perl will have to resize and copy it less and less often. .IP "nread = extend_read fh, scalar, addlen=64" 4 .IX Item "nread = extend_read fh, scalar, addlen=64" Calls \f(CW\*(C`extend scalar, addlen\*(C'\fR to ensure some space is available, then do the equivalent of \f(CW\*(C`sysread\*(C'\fR to the end, to try to fill the extra space. Returns how many bytes have been read, \f(CW0\fR on \s-1EOF\s0 or undef> on error, just like \f(CW\*(C`sysread\*(C'\fR. .Sp 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. .IP "nread = read_all fh, scalar, length" 4 .IX Item "nread = read_all fh, scalar, length" Tries to read \f(CW\*(C`length\*(C'\fR bytes into \f(CW\*(C`scalar\*(C'\fR. Unlike \f(CW\*(C`read\*(C'\fR or \&\f(CW\*(C`sysread\*(C'\fR, it will try to read more bytes if not all bytes could be read in one go (this is often called \f(CW\*(C`xread\*(C'\fR in C). .Sp Returns the total nunmber of bytes read (normally \f(CW\*(C`length\*(C'\fR, unless an error or \s-1EOF\s0 occurred), \f(CW0\fR on \s-1EOF\s0 and \f(CW\*(C`undef\*(C'\fR on errors. .IP "nwritten = write_all fh, scalar" 4 .IX Item "nwritten = write_all fh, scalar" Like \f(CW\*(C`readall\*(C'\fR, but for writes \- the equivalent of the \f(CW\*(C`xwrite\*(C'\fR function often seen in C. .IP "refcnt scalar[, newrefcnt]" 4 .IX Item "refcnt scalar[, newrefcnt]" Returns the current reference count of the given scalar and optionally sets it to the given reference count. .IP "refcnt_inc scalar" 4 .IX Item "refcnt_inc scalar" Increments the reference count of the given scalar inplace. .IP "refcnt_dec scalar" 4 .IX Item "refcnt_dec scalar" Decrements the reference count of the given scalar inplace. Use \f(CW\*(C`weaken\*(C'\fR instead if you understand what this function is fore. Better yet: don't use this module in this case. .IP "refcnt_rv scalar[, newrefcnt]" 4 .IX Item "refcnt_rv scalar[, newrefcnt]" Works like \f(CW\*(C`refcnt\*(C'\fR, 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 \f(CW*_rv\fR\-functions tend to be one higher. .IP "refcnt_inc_rv scalar" 4 .IX Item "refcnt_inc_rv scalar" Works like \f(CW\*(C`refcnt_inc\*(C'\fR, but dereferences the given reference first. .IP "refcnt_dec_rv scalar" 4 .IX Item "refcnt_dec_rv scalar" Works like \f(CW\*(C`refcnt_dec\*(C'\fR, but dereferences the given reference first. .IP "ok scalar" 4 .IX Item "ok scalar" .PD 0 .IP "uok scalar" 4 .IX Item "uok scalar" .IP "rok scalar" 4 .IX Item "rok scalar" .IP "pok scalar" 4 .IX Item "pok scalar" .IP "nok scalar" 4 .IX Item "nok scalar" .IP "niok scalar" 4 .IX Item "niok scalar" .PD Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar, respectively. .SS "\s-1CANDIDATES FOR FUTURE RELEASES\s0" .IX Subsection "CANDIDATES FOR FUTURE RELEASES" The following \s-1API\s0 functions (perlapi) are considered for future inclusion in this module If you want them, write me. .PP .Vb 4 \& sv_upgrade \& sv_pvn_force \& sv_pvutf8n_force \& the sv2xx family .Ve .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://home.schmorp.de/ .Ve