StdLib/Include/Containers/ModuloUtil.h

   1 /** @file
   2   Utility functions for performing basic math operations constrained within a
   3   modulus.
   4
   5   These functions are intended to simplify small changes to a value which much
   6   remain within a specified modulus.  Changes must be less than or equal to
   7   the modulus specified by MaxVal.
   8
   9   Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>
  10   This program and the accompanying materials are licensed and made available
  11   under the terms and conditions of the BSD License which accompanies this
  12   distribution.  The full text of the license may be found at
  13   http://opensource.org/licenses/bsd-license.php.
  14
  15   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17 **/
  18 #ifndef _MODULO_UTIL_H
  19 #define _MODULO_UTIL_H
  20 #include  <Uefi.h>
  21 #include  <sys/EfiCdefs.h>
  22
  23 __BEGIN_DECLS
  24
  25 /** Counter = (Counter + 1) % MaxVal;
  26
  27     Counter is always expected to be LESS THAN MaxVal.
  28         0 <= Counter < MaxVal
  29
  30     @param[in]    Counter   The value to be incremented.
  31     @param[in]    MaxVal    Modulus of the operation.
  32
  33     @return   Returns the result of incrementing Counter, modulus MaxVal.
  34               If Counter >= MaxVal, returns -1.
  35 **/
  36 INT32
  37 EFIAPI
  38 ModuloIncrement(
  39   UINT32  Counter,
  40   UINT32  MaxVal
  41   );
  42
  43 /** Counter = (Counter - 1) % MaxVal;
  44
  45     Counter is always expected to be LESS THAN MaxVal.
  46         0 <= Counter < MaxVal
  47
  48     @param[in]    Counter   The value to be decremented.
  49     @param[in]    MaxVal    Modulus of the operation.
  50
  51     @return   Returns the result of decrementing Counter, modulus MaxVal.
  52               If Counter >= MaxVal, returns -1.
  53 **/
  54 INT32
  55 EFIAPI
  56 ModuloDecrement(
  57   UINT32  Counter,
  58   UINT32  MaxVal
  59   );
  60
  61 /** Counter = (Counter + Increment) % MaxVal;
  62
  63     @param[in]    Counter   The value to be incremented.
  64     @param[in]    Increment The value to add to Counter.
  65     @param[in]    MaxVal    Modulus of the operation.
  66
  67     @return   Returns the result of adding Increment to Counter, modulus MaxVal,
  68               or -1 if Increment is larger than MaxVal.
  69 **/
  70 INT32
  71 EFIAPI
  72 ModuloAdd (
  73   UINT32  Counter,
  74   UINT32  Increment,
  75   UINT32  MaxVal
  76   );
  77
  78 /** Increment Counter but don't increment past MaxVal.
  79
  80     @param[in]    Counter   The value to be decremented.
  81     @param[in]    MaxVal    The upper bound for Counter.  Counter < MaxVal.
  82
  83     @return   Returns the result of incrementing Counter.
  84 **/
  85 UINT32
  86 EFIAPI
  87 BoundIncrement(
  88   UINT32  Counter,
  89   UINT32  MaxVal
  90   );
  91
  92 /** Decrement Counter but don't decrement past zero.
  93
  94     @param[in]    Counter   The value to be decremented.
  95
  96     @return   Returns the result of decrementing Counter.
  97 **/
  98 UINT32
  99 EFIAPI
 100 BoundDecrement(
 101   UINT32  Counter
 102   );
 103
 104 __END_DECLS
 105 #endif  /* _MODULO_UTIL_H */