Provided by: libconvert-scalar-perl_1.12-2build4_amd64 bug

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 whether 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 error, 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  occurred),  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/

perl v5.38.2                                       2024-03-31                                        Scalar(3pm)