hphp/runtime/base/array-util.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-2014 Facebook, Inc. (http://www.facebook.com)     |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef incl_HPHP_ARRAY_UTIL_H_
  18 #define incl_HPHP_ARRAY_UTIL_H_
  19
  20 #include "hphp/runtime/base/complex-types.h"
  21 #include "hphp/util/hdf.h"
  22
  23 namespace HPHP {
  24 ///////////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * Utility array functions.
  28  */
  29 class ArrayUtil {
  30 public:
  31   /////////////////////////////////////////////////////////////////////////////
  32   // Compositions.
  33
  34   /**
  35    * Removes the elements designated by offset and length and replace them
  36    * with supplied array.
  37    */
  38   static Variant Splice(CArrRef input, int offset, int64_t length = 0,
  39                         CVarRef replacement = null_variant,
  40                         Array *removed = nullptr);
  41
  42   /**
  43    * Returns a copy of input array padded with pad_value to size pad_size.
  44    */
  45   static Variant Pad(CArrRef input, CVarRef pad_value, int pad_size,
  46                      bool pad_right = true);
  47
  48   /**
  49    * Create an array containing the range of integers or characters from low
  50    * to high (inclusive).
  51    */
  52   static Variant Range(unsigned char low, unsigned char high, int64_t step = 1);
  53   static Variant Range(double low, double high, double step = 1.0);
  54   static Variant Range(double low, double high, int64_t step = 1);
  55
  56   /////////////////////////////////////////////////////////////////////////////
  57   // Information and calculations.
  58
  59   /**
  60    * Computes the sum of the array entries as int64 or double.
  61    */
  62   static DataType Sum(CArrRef input, int64_t *isum, double *dsum);
  63
  64   /**
  65    * Computes the product of the array entries as int64 or double.
  66    */
  67   static DataType Product(CArrRef input, int64_t *iprod, double *dprod);
  68
  69   /**
  70    * Return the value as key and the frequency of that value in input
  71    * as value.
  72    */
  73   static Variant CountValues(CArrRef input);
  74
  75   /////////////////////////////////////////////////////////////////////////////
  76   // Manipulations. Note, all these functions will create a new array than
  77   // modifying input, although names of these functions sound like mutating.
  78
  79   /**
  80    * Retuns an array with all string keys lowercased [or uppercased].
  81    */
  82   static Variant ChangeKeyCase(CArrRef input, bool lower);
  83
  84   /**
  85    * Return input as a new array with the order of the entries reversed.
  86    */
  87   static Variant Reverse(CArrRef input, bool preserve_keys = false);
  88
  89   /**
  90    * Randomly shuffle the contents of an array.
  91    */
  92   static Variant Shuffle(CArrRef input);
  93
  94   /**
  95    * Return key/keys for random entry/entries in the array.
  96    */
  97   static Variant RandomKeys(CArrRef input, int num_req = 1);
  98
  99   /**
 100    * Removes duplicate string values from array.
 101    */
 102   static Variant StringUnique(CArrRef input);
 103
 104   /**
 105    * Removes values whose numeric conversion is duplicate from array.
 106    */
 107   static Variant NumericUnique(CArrRef input);
 108
 109   /**
 110    * Removes values that compare as equal and that end up in contiguous
 111    * positions if the input array is sorted.
 112    */
 113   static Variant RegularSortUnique(CArrRef input);
 114
 115   /////////////////////////////////////////////////////////////////////////////
 116   // Iterations.
 117
 118   /**
 119    * Apply a user function to every member of an array.
 120    */
 121   typedef void (*PFUNC_WALK)(VRefParam value, CVarRef key, CVarRef userdata,
 122                              const void *data);
 123   static void Walk(VRefParam input, PFUNC_WALK walk_function, const void *data,
 124                    bool recursive = false, PointerSet *seen = nullptr,
 125                    CVarRef userdata = null_variant);
 126
 127   /**
 128    * Iteratively reduce the array to a single value via the callback.
 129    */
 130   typedef Variant (*PFUNC_REDUCE)(CVarRef result, CVarRef operand,
 131                                   const void *data);
 132   static Variant Reduce(CArrRef input, PFUNC_REDUCE reduce_function,
 133                         const void *data, CVarRef initial = null_variant);
 134 };
 135
 136 ///////////////////////////////////////////////////////////////////////////////
 137 }
 138
 139 #endif // incl_HPHP_ARRAY_UTIL_H_