=begin pod

=head1 NAME

Raku port of Perl's lcfirst() / ucfirst() built-ins

=head1 SYNOPSIS

=begin code :lang<raku>
use P5lcfirst;

say lcfirst "FOOBAR"; # fOOBAR
with "ZIPPO" {
    say .lcfirst;  # zIPPO
}

say ucfirst "foobar"; # Foobar
with "zippo" {
    say .ucfirst;  # Zippo
}
=end code

=head1 DESCRIPTION

This module tries to mimic the behaviour of Perl's C<lcfirst> and C<ucfirst>
built-ins as closely as possible in the Raku Programming Language.

=head1 ORIGINAL PERL 5 DOCUMENTATION

=begin output
lcfirst EXPR
lcfirst Returns the value of EXPR with the first character lowercased.
        This is the internal function implementing the "\l" escape in
        double-quoted strings.

        If EXPR is omitted, uses $_.

        This function behaves the same way under various pragmata, such as
        in a locale, as "lc" does.

ucfirst EXPR
ucfirst Returns the value of EXPR with the first character in uppercase
        (titlecase in Unicode). This is the internal function implementing
        the "\u" escape in double-quoted strings.

        If EXPR is omitted, uses $_.

        This function behaves the same way under various pragma, such as
        in a locale, as "lc" does.
=end output

=head1 PORTING CAVEATS

With the arrival of RakuAST, it has become impossible to access the
topic variable (C<$_>) of the caller's scope.  So Perl's idiom of
calling C<lcfirst> or C<ucfirst> without arguments has become
impossible.  Code such as:

=begin code :lang<raku>
say lcfirst;
=end code

should be changed to either:

=begin code :lang<raku>
say lcfirst($_);
=end code

or, using the subroutine as a method syntax, with the prefix C<.> shortcut
to use that scope's C<$_> as the invocant:

=begin code :lang<raku>
say .&lcfirst;
=end code

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://github.com/lizmat/P5lcfirst . Comments and
Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021, 2023, 2026 Elizabeth Mattijsen

Re-imagined from Perl as part of the CPAN Butterfly Plan.

This library is free software; you can redistribute it and/or modify it
under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
