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

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

SYNOPSIS
     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 "decr()" function to do the decrement
    equivalent, although it is not exactly the reverse of the increment
    operation. In general, the rule is that "decr(++$a)" should return the
    same value as the original $a before the auto-increment, with a couple
    of exception.

    *   Positive integers are decremented as string

        Positive integers, including those with zero prefix, are decremented
        as string.

         print decr(-123);            # prints "-124", treated as number
         print decr(123);             # prints "122", treated as string
         print decr(100);             # prints "099", treated as string

        "undef" like in auto-increment is treated as number 0.

         print decr(undef);            # prints "-1", treated as number

    *   Decrementing is not done when leftmost digit is already "A", "a", or
        0

        When carrying over to the left-most digit, and the digit is already
        "A", "a", or "0", decrementing is not done. The original value is
        returned and a warning "Cannot decrement '<VALUE>'" is issued.
        Examples:

         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 return the original value and 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.