Scalar::String(3pm)

💖 Scalar::String 💖

okay bestie so this is the Scalar::String page from your User Contributed Perl Documentation era, and we're about to get deep into the string side of plain Perl scalars. buckle up 🎀

---

✨ NAME ✨

Scalar::String — string aspects of scalars. that's it, that's the whole vibe 🦋

---

✨ SYNOPSIS ✨

so like, here's how you actually use it:

use Scalar::String
        qw(sclstr_is_upgraded sclstr_is_downgraded);

if(sclstr_is_upgraded($value)) { ...
if(sclstr_is_downgraded($value)) { ...

use Scalar::String qw(
        sclstr_upgrade_inplace sclstr_upgraded
        sclstr_downgrade_inplace sclstr_downgraded
);

sclstr_upgrade_inplace($value);
$value = sclstr_upgraded($value);
sclstr_downgrade_inplace($value);
$value = sclstr_downgraded($value);

---

✨ DESCRIPTION ✨

okay so. this module is about the string part of plain Perl scalars. a scalar has a string value, and notionally that's a sequence of Unicode codepoints, but internally it might be encoded in either ISO-8859-1 or UTF-8. and in some places — and way more so in older Perls — that internal encoding leaks through where you can see it. so if you wanna fully understand Perl strings, bestie, you lowkey have to understand these implementation details. no cap. 💅

what the module actually gives you: functions to classify a string by encoding, and functions to encode a string the way you want it.

also, it's implemented in XS, with a pure Perl backup version for systems that literally can't handle XS. considerate queen behavior. 👑

---

🌈 STRING ENCODING 🌈

the two flavors, explained

ISO-8859-1 is a simple 8-bit character encoding — it represents the first 256 Unicode characters (codepoints 0x00 to 0xff) in one octet each. this is how strings were historically represented in Perl. a string represented this way is referred to as "downgraded".

UTF-8 is a variable-width character encoding, and it represents all possible Unicode codepoints in differing numbers of octets. cute design feature: ASCII characters (codepoints 0x00 to 0x7f) each fit in a single octet, identically to their ISO-8859-1 encoding. but ✨ plot twist ✨ — Perl has its own variant of UTF-8, which can handle a wider range of codepoints than Unicode formally allows. a string in this variant UTF-8 is referred to as "upgraded".

how a Perl string is physically built

a Perl string is physically represented as a string of octets plus a flag that says whether the string is downgraded or upgraded. at this level, to figure out what Unicode codepoints are actually being represented, you have to look at both parts of the representation. if the string contains only ASCII characters then the octet sequence is identical in either encoding — but Perl still maintains an encoding flag on such a string. and the rule is absolute: a string is always either downgraded or upgraded. it is never both, and never neither. periodt. 💅

the good form era

when you're handling string input, good form is to operate only on the Unicode characters that the string represents, and ignore the way they're encoded. 💖 basic string ops like concatenation work this way (except for a bug in perl 5.6.0 — 🙈 we don't talk about her). so simple pure Perl code is generally safe on this front. pieces of character-based code can pass strings around among themselves, always get consistent behavior, and never have to worry about how the characters are encoded. slay.

the historical accident 😭

however — and this is the messy part — due to a historical accident, a LOT of C code that interfaces with Perl looks at the octets used to represent a string without also examining the encoding flag. such code gives inconsistent behaviour for the same character sequence represented in the different ways. 💀

• in perl 5.6, many pure Perl operations (like regular expression matching) also work this way, though some of them can be induced to work correctly by using the utf8 pragma.
• in perl 5.8, regular expression matching is character-based by default, but many I/O functions (such as "open") are still octet-based.

so what do you do when worlds collide

where code that operates on the octets of a string must be used by code that operates on characters, the latter needs to pay attention to the encoding of its strings. commonly, the octet-based code expects its input to be represented in a particular encoding, in which case the character-based code must oblige by forcing strings to that encoding before they are passed in. there are other usage patterns too. iykyk. 🦋

the mindset, bestie 🧚

you will be least confused if you think about a Perl string as a character sequence plus an encoding flag. you should normally operate on the character sequence and not care about the encoding flag. occasionally you must pay attention to the flag in addition to the characters. unless you're writing C code, you should try not to think about a string the other way round, as an octet sequence plus encoding flag. flip the mental model and you're golden ✨

---

🔥 FUNCTIONS 🔥

each sclstr_ function takes one or more scalar string arguments to operate on. these arguments must be strings; giving non-string arguments will cause mayhem. 💀 see "is_string" in Params::Classify for a way to check for stringness. only the string value of the scalar is used; the numeric value is completely ignored, so dualvars are not a problem. we love a low-maintenance function. 🫶

🎀 Classification

• sclstr_is_upgraded(VALUE) — returns a truth value indicating whether the provided string VALUE is in upgraded form. 💅
• sclstr_is_downgraded(VALUE) — returns a truth value indicating whether the provided string VALUE is in downgraded form. 💅

🎀 Regrading

• sclstr_upgrade_inplace(VALUE) — modifies the string VALUE in-place, so that it's in upgraded form, regardless of how it was encoded before. the character sequence that it represents is unchanged.

a cleaner interface to this operation is the non-mutating "sclstr_upgraded". ✨

• sclstr_upgraded(VALUE) — returns a string that represents the same character sequence as the string VALUE, and is in upgraded form (regardless of how VALUE is encoded). non-mutating, so it's giving immaculate vibes. 🦋
• sclstr_downgrade_inplace(VALUE[, FAIL_OK]) — modifies the string VALUE in-place, so that it's in downgraded form, regardless of how it was encoded before. the character sequence that it represents is unchanged. if the string cannot be downgraded, because it contains a non-ISO-8859-1 character, then by default the function "die"s 😭, but if FAIL_OK is present and true then it will return leaving VALUE unmodified.

a cleaner interface to this operation is the non-mutating "sclstr_downgraded". ✨

• sclstr_downgraded(VALUE[, FAIL_OK]) — returns a string that represents the same character sequence as the string VALUE, and is in downgraded form (regardless of how VALUE is encoded). if the string cannot be represented in downgraded form, because it contains a non-ISO-8859-1 character, then by default the function "die"s 😭, but if FAIL_OK is present and true then it will return VALUE in its original upgraded form.

⚠️ heads up bestie: that "die" is the default behavior for both downgrade functions when a non-ISO-8859-1 character shows up. pass FAIL_OK if you don't want the drama. 💀

---

👀 SEE ALSO 👀

utf8

---

👑 AUTHOR 👑

Andrew Main (Zefram) <zefram@fysh.org>

---

📜 COPYRIGHT 📜

Copyright (C) 2009, 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

---

📜 LICENSE 📜

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🫶 this was perl v5.42.3, dated 2026-08-19, byeee 💖✨🌸