Scalar(3pm)

🌸 NAME 🌸

bestie. okay so Convert::Scalar is the module (yes, that's the Scalar(3pm) page you're looking at, hi, welcome 💖) and it converts between different representations of perl scalars ✨

---

🎀 SYNOPSIS 🎀

use Convert::Scalar;

---

💅 DESCRIPTION 💅

okay so real talk: this module exports a whole bunch of internal perl methods that change the internal representation or state of a perl scalar. every single one of them works in-place, meaning they modify the scalar you hand them. no cap. they don't return a fresh copy for you, they mess with the one you gave them.

and no functions are exported by default 🫶 so you have to ask for what you want.

the following export tags exist:

• :utf8 — every function with utf8 in its name
• :taint — every function with taint in its name
• :refcnt — every function with refcnt in its name
• :ok — all the *ok-functions 🌈

---

🦋 the functions, one by one 🦋

• utf8 scalar[, mode] — returns true when the scalar you passed is marked as utf8, false otherwise. if you give it that optional mode argument, it also forces the interpretation of the string to utf8 (mode true) or plain bytes (mode false). heads up: the actual (byte-)content does not change. and the return value always reflects the state before any modification happens 👑

this is the one you want when you're "importing" utf8-data into perl, or when some external function (storing to / retrieving from a database, we're looking at you 😭) removes the utf8-flag.

• utf8_on scalar — basically the same as "utf8 scalar, 1", but it also returns the scalar (and yeah, the argument still gets modified in-place).
• utf8_off scalar — basically the same as "utf8 scalar, 0", but it also returns the scalar (still modified in-place, always in-place 💅).
• utf8_valid scalar [Perl 5.7] — returns true if the bytes inside the scalar form a valid utf8 string, false otherwise. and listen, the check is independent of the actual encoding perl thinks the string is in. the bytes are the vibe check, not perl's opinion ✨
• utf8_upgrade scalar — converts the string content of the scalar in-place to its UTF8-encoded form (and also returns it).
• utf8_downgrade scalar[, fail_ok=0] — tries 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 can't be represented in a single byte 😭. if that happens, it leaves the scalar unchanged and either returns false, or — if "fail_ok" isn't true (and the default is not-true) — it croaks. so like, be aware.
• utf8_encode scalar — converts the string value of the scalar to UTF8-encoded, but then turns off the "SvUTF8" flag so it looks like bytes to perl again. (might be removed in future versions 👀 so don't get too attached.)
• utf8_length scalar — returns the number of characters in the string, counting wide UTF8 characters as a single character, no matter whether the scalar is marked as containing bytes or mulitbyte characters. one char is one char, periodt.
• $old = readonly scalar[, $new] — returns whether the scalar is currently readonly, and sets or clears the readonly status if you give it a new status.
• readonly_on scalar — sets the readonly flag on the scalar 🔒
• readonly_off scalar — clears the readonly flag on the scalar 🔓
• unmagic scalar, type — removes the specified magic from the scalar. (DANGEROUS! 💀)
• weaken scalar — weakens a reference. (see also WeakRef)
• taint scalar — taints the scalar ☠️
• tainted scalar — returns true when the scalar is tainted, false otherwise.
• untaint scalar — removes the tainted flag from the specified scalar 🧼
• length = len scalar — returns SvLEN (scalar), which is the actual number of bytes allocated to the string value, or "undef" if 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 — it's only useful to "pre-allocate" memory space if you already know the scalar is gonna grow. the return value is the modified scalar (which got modified in-place, obviously 💅).
• 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 won't be affected. the modified scalar also gets returned.

this one is made for making append workloads efficient — if you append a short string to a scalar a gazillion times (millions of times, fr fr), perl would otherwise have to reallocate and copy the scalar basically every single time 😭

but if you use "extend $scalar, length $shortstring" instead, then Convert::Scalar uses a "size to next power of two, roughly" algorithm, so as the scalar grows, perl has to resize and copy it less and less often. iconic behaviour honestly.

• nread = extend_read fh, scalar, addlen=64 — calls "extend scalar, addlen" to make sure some space is available, then does the equivalent of "sysread" to the end to try and fill that extra space. returns how many bytes have been read, 0 on EOF, or undef on error — just like "sysread".

this is the one for implementing protocols where you read some data, see if it's enough to decode, and if it isn't, read a bit more. because the naive / easy way of doing that gets bad performance 🫠

• nread = read_all fh, scalar, length — tries to read length bytes into scalar. unlike "read" or "sysread", it will keep trying to read more bytes if it couldn't get them all in one go (in C this is often called "xread").

returns the total number of bytes read (normally length, unless an error or EOF happened), 0 on EOF, and "undef" on errors.

• nwritten = write_all fh, scalar — like "readall", but for writes — the equivalent of the "xwrite" function you often see 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 for. better yet: don't use this module in this case 😭
• refcnt_rv scalar[, newrefcnt] — works like "refcnt", but dereferences the given reference first. useful for finding the reference count of arrays or hashes, which can't be passed directly. remember that taking a reference of some object increases its reference count, so the reference count used by the *_rv-functions tends 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 — these call SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar, respectively. one each, matching the name, no mystery 🌈

---

🔮 CANDIDATES FOR FUTURE RELEASES 🔮

the following API functions (perlapi) are being 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/

---

and that's the whole thing bestie 🫶 this page is from perl v5.42.3, dated 2026-08-19 — so like, go forth and convert your scalars responsibly 💖✨🎀🦋🌸💅