NAME
    Data::Decrement - Provide extra magic for auto-decrement

VERSION
    This document describes version 0.001 of Data::Decrement (from Perl
    distribution Data-Decrement), released on 2019-01-25.

SYNOPSIS
    To import the "decr" function that implements the logic of
    auto-decrement magic:

     use Data::Decrement 'decr';

     print decr("b00"); # prints "a99"

DESCRIPTION
    Perl's auto-increment operator ("++") has some convenience feature built
    in. Quoting perlop:

     The auto-increment operator has a little extra builtin magic to it. If you
     increment a variable that is numeric, or that has ever been used in a numeric
     context, you get a normal increment. If, however, the variable has been used in
     only string contexts since it was set, and has a value that is not the empty
     string and matches the pattern "/^[a-zA-Z]*[0-9]*\z/", the increment is done as
     a string, preserving each character within its range, with carry:

      print ++($foo = "99");      # prints "100"
      print ++($foo = "a0");      # prints "a1"
      print ++($foo = "Az");      # prints "Ba"
      print ++($foo = "zz");      # prints "aaa"

     "undef" is always treated as numeric, and in particular is changed to 0 before
     incrementing (so that a post-increment of an undef value will return 0 rather
     than "undef").

     The auto-decrement operator is not magical.

    This module provides the counterpart for auto-decrement. Note that the
    decrement operation is not the exact reverse of auto-increment. In
    general, the rule is that "decr($a++)" will return the same value as the
    original $a before auto-increment, but when the carrying over to the
    leftmost character and it is already "A", "a", or "0", the original
    value is returned and a warning "Cannot decrement '<VALUE>'" is
    generated. Examples:

     print decr(-123);            # prints "-124", treated as number
     print decr(123);             # prints "122", treated as STRING
     print decr(100);             # prints "099", treated as STRING
     print decr(0);               # prints "0", warns "Cannot decrement '0'"
     print decr("a1");            # prints "a0"
     print decr("b0");            # prints "a9"
     print decr("a0");            # prints "a0", warns "Cannot decrement 'a0'"
     print decr("bZz0");          # prints "bZy9"
     print decr("bZa0");          # prints "bYz9"
     print decr("bAa0");          # prints "aZz9"
     print decr("aAa0");          # prints "aAa0", warns "Cannot decrement 'aAa0'"

FUNCTIONS
  decr
    Usage:

     decr($val) => $dec_val

    Accept a value and return decremented value. If *$val* matches the
    pattern "/^[a-zA-Z]*[0-9]*\z/", it will decremented as a string (note
    that positive integers match this pattern). Otherwise, it will be
    decremented numerically. "undef" is regarded as numeric 0.

    Will emit a warning if cannot decrement a value.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Data-Decrement>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Data-Decrement>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Decrement>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    "++" in perlop

    dec-pl in App::IncrementUtils

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019 by perlancar@cpan.org.

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