hphp/runtime/base/array-util.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present 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/type-variant.h"
  21 #include "hphp/runtime/base/req-hash-set.h"
  22 #include "hphp/util/functional.h" // for pointer_hash
  23
  24 #include "hphp/util/hdf.h"
  25
  26 namespace HPHP {
  27 ///////////////////////////////////////////////////////////////////////////////
  28
  29 struct Array;
  30
  31 /**
  32  * Utility array functions.
  33  */
  34 struct ArrayUtil final {
  35   /////////////////////////////////////////////////////////////////////////////
  36   // Compositions.
  37
  38   /**
  39    * Removes the elements designated by offset and length and replace them
  40    * with supplied array.
  41    */
  42   static Variant Splice(const Array& input, int offset, int64_t length = 0,
  43                         const Variant& replacement = uninit_variant,
  44                         Array *removed = nullptr);
  45
  46   /**
  47    * Returns a copy of input array padded with pad_value to size pad_size.
  48    */
  49   static Variant PadLeft(const Array& input, const Variant& pad_value,
  50                          int pad_size);
  51   static Variant PadRight(const Array& input, const Variant& pad_value,
  52                           int pad_size);
  53
  54   /**
  55    * Create an array containing the range of integers or characters from low
  56    * to high (inclusive).
  57    */
  58   static Variant Range(unsigned char low, unsigned char high, int64_t step = 1);
  59   static Variant Range(double low, double high, double step = 1.0);
  60   static Variant Range(int64_t low, int64_t high, int64_t step = 1);
  61
  62   /////////////////////////////////////////////////////////////////////////////
  63   // Information and calculations.
  64
  65   /**
  66    * Return the value as key and the frequency of that value in input
  67    * as value.
  68    */
  69   static Variant CountValues(const Array& input);
  70
  71   /////////////////////////////////////////////////////////////////////////////
  72   // Manipulations. Note, all these functions will create a new array than
  73   // modifying input, although names of these functions sound like mutating.
  74
  75   /**
  76    * Retuns an array with all string keys lowercased [or uppercased].
  77    */
  78   static Variant ChangeKeyCase(const Array& input, bool lower);
  79
  80   /**
  81    * Return input as a new array with the order of the entries reversed.
  82    */
  83   static Variant Reverse(const Array& input, bool preserve_keys = false);
  84
  85   /**
  86    * Randomly shuffle the contents of an array.
  87    */
  88   static Variant Shuffle(const Array& input);
  89
  90   /**
  91    * Return key/keys for random entry/entries in the array.
  92    */
  93   static Variant RandomKeys(const Array& input, int num_req = 1);
  94
  95   /**
  96    * Removes duplicate string values from array.
  97    */
  98   static Variant StringUnique(const Array& input);
  99
 100   /**
 101    * Removes values whose numeric conversion is duplicate from array.
 102    */
 103   static Variant NumericUnique(const Array& input);
 104
 105   /**
 106    * Removes values that compare as equal and that end up in contiguous
 107    * positions if the input array is sorted.
 108    */
 109   static Variant RegularSortUnique(const Array& input);
 110
 111   /////////////////////////////////////////////////////////////////////////////
 112   // Iterations.
 113
 114   using PointerSet = req::fast_set<const ArrayData*,
 115                                    pointer_hash<const ArrayData>>;
 116
 117   /**
 118    * Apply a user function to every member of an array.
 119    */
 120   using PFUNC_WALK = void (*)(Variant& value, const Variant& key,
 121                               const Variant& userdata, const void *data);
 122   static void Walk(Variant &input, PFUNC_WALK walk_function, const void *data,
 123                    bool recursive = false, PointerSet *seen = nullptr,
 124                    const Variant& userdata = uninit_variant);
 125
 126   /**
 127    * Iteratively reduce the array to a single value via the callback.
 128    */
 129   using PFUNC_REDUCE = Variant (*)(const Variant& result,
 130                                    const Variant& operand,
 131                                    const void *data);
 132   static Variant Reduce(const Array& input, PFUNC_REDUCE reduce_function,
 133                     const void *data, const Variant& initial = uninit_variant);
 134 };
 135
 136 ///////////////////////////////////////////////////////////////////////////////
 137 }
 138
 139 #endif // incl_HPHP_ARRAY_UTIL_H_