--- name: lcfirst signature: 'lcfirst EXPR' signatures: - 'lcfirst EXPR' - 'lcfirst' since: 5.0 status: documented categories: ["SCALARs and strings"] --- ```{index} single: lcfirst; Perl built-in ``` *[SCALARs and strings](../perlfunc-by-category)* # lcfirst Return a copy of a string with its first character lowercased. `lcfirst` touches **only** the first character; the rest of the string is copied verbatim. The input is not modified — `lcfirst` returns a new string. It is the internal function implementing the `\l` escape in double-quoted strings, so `"\l$name"` and `lcfirst($name)` produce the same result. If `EXPR` is omitted, `lcfirst` operates on [`$_`](../perlvar). ## Synopsis ```perl lcfirst EXPR lcfirst ``` ## What you get back A new string equal to `EXPR` with its first character replaced by the lowercase form that character's case-folding rules produce. The rest of the string is untouched. If `EXPR` is the empty string, the empty string is returned. If `EXPR` is [`undef`](undef), the result is the empty string and an `uninitialized` warning is emitted under `use warnings`. `lcfirst` never mutates its argument. To lowercase the first character in place, assign the result back: ```perl $name = lcfirst $name; ``` For the all-characters variant, see [`lc`](lc). ## Global state it touches - [`$_`](../perlvar) — read when `EXPR` is omitted. - `LC_CTYPE` locale — consulted when `use locale` is in effect (see *Pragmas and case rules* below). ## Pragmas and case rules `lcfirst` behaves the same way under various pragmas as [`lc`](lc) does. The active rule set for the first character depends on which pragmas are in scope at the call site: - **`use bytes`** — ASCII rules only. Only the bytes `A`-`Z` are folded to `a`-`z`; every other byte is returned unchanged. - **`use locale`** (for `LC_CTYPE`) — the current locale decides the fold for code points below 256. Code points 256 and above fold by Unicode rules when the string has the UTF-8 flag set. A UTF-8 locale engages full Unicode rules from Perl 5.20 onward. - **UTF-8-flagged string** — Unicode case-folding rules apply. - **`use feature 'unicode_strings'`** or **`use locale ':not_characters'`** — Unicode rules apply regardless of the UTF-8 flag. - **Otherwise** — ASCII rules. Characters outside ASCII are returned unchanged. This means the same `lcfirst("É...")` can return `"é..."` under `use utf8` or `use feature 'unicode_strings'`, and `"É..."` (unchanged) under pure-ASCII defaults. When portability across pragmas matters, state the rule set explicitly: ```perl use feature 'unicode_strings'; my $s = lcfirst $input; # Unicode rules regardless of UTF-8 flag ``` ## Examples Basic call, lowercasing the first letter of a word: ```perl my $s = lcfirst "Hello, World"; # "hello, World" ``` Title-case normalisation for a list of names, where the caller wants the first letter lowercased for a URL slug: ```perl my @slugs = map { lcfirst } @CamelCaseNames; ``` Default-argument form reads from [`$_`](../perlvar): ```perl for ("Apple", "Banana", "Cherry") { print lcfirst, "\n"; # "apple", "banana", "cherry" } ``` Only the **first** character changes — later capitals are preserved. This matters for `camelCase` identifiers derived from `PascalCase`: ```perl my $method = lcfirst "GetUserName"; # "getUserName" ``` Unicode rules must be requested explicitly, either via a UTF-8-flagged input string or via the `unicode_strings` feature: ```perl use feature 'unicode_strings'; my $s = lcfirst "Éclair"; # "éclair" ``` ```perl my $s = lcfirst "Éclair"; # without unicode_strings and no # UTF-8 flag: "Éclair" unchanged ``` The `\l` escape in a double-quoted string is exactly `lcfirst` on the next character: ```perl my $name = "Perl"; print "\l$name\n"; # "perl\n" ``` ## Edge cases - **Empty string**: `lcfirst("")` returns `""`. No warning. - **[`undef`](undef) input**: `lcfirst(undef)` returns `""`. Emits an `uninitialized` warning under `use warnings`. - **First character already lowercase**: returned unchanged; no special case, no shortcut the user needs to know about. - **First character has no lowercase mapping** (digit, punctuation, symbol, most CJK): returned unchanged. - **Multi-codepoint case folds**: some Unicode characters lowercase to more than one code point (e.g. Turkish dotted/dotless I pairs in locale-tailored folds). `lcfirst` follows Unicode's *simple* lowercase mapping, which is always single-codepoint — it does not perform full case folding. Use [`lc`](lc) combined with normalisation, or an explicit `Unicode::CaseFold`, when full-fold semantics matter. - **Locale surprises around 255/256**: under `use locale` with a non-UTF-8 locale, a first character whose lowercase would cross the 255/256 boundary is returned unchanged, and from Perl 5.22 onward a `locale` warning is emitted. - **Not list-aware**: `lcfirst` is a scalar operator. `lcfirst @list` takes `scalar(@list)` — the element count — and lowercases its first character, almost never what the caller meant. Use `map { lcfirst } @list` for per-element lowercasing. ## Differences from upstream Fully compatible with upstream Perl 5.42. ## See also - [`lc`](lc) — lowercase every character, not only the first; same pragma-sensitivity rules - [`ucfirst`](ucfirst) — uppercase the first character; the exact inverse operation - [`uc`](uc) — uppercase every character - [`fc`](fc) — Unicode case-folding suitable for caseless comparison, not display - [`$_`](../perlvar) — default argument when `EXPR` is omitted