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.

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.

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.

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).

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.

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.