third-party/mruby/include/mruby/hash.h

   1 /*
   2 ** mruby/hash.h - Hash class
   3 **
   4 ** See Copyright Notice in mruby.h
   5 */
   6
   7 #ifndef MRUBY_HASH_H
   8 #define MRUBY_HASH_H
   9
  10 #include "common.h"
  11
  12 /**
  13  * Hash class
  14  */
  15 MRB_BEGIN_DECL
  16
  17 struct RHash {
  18   MRB_OBJECT_HEADER;
  19   struct iv_tbl *iv;
  20   struct htable *ht;
  21 };
  22
  23 #define mrb_hash_ptr(v)    ((struct RHash*)(mrb_ptr(v)))
  24 #define mrb_hash_value(p)  mrb_obj_value((void*)(p))
  25
  26 MRB_API mrb_value mrb_hash_new_capa(mrb_state*, mrb_int);
  27 MRB_API mrb_value mrb_ensure_hash_type(mrb_state *mrb, mrb_value hash);
  28 MRB_API mrb_value mrb_check_hash_type(mrb_state *mrb, mrb_value hash);
  29
  30 /*
  31  * Initializes a new hash.
  32  *
  33  * Equivalent to:
  34  *
  35  *      Hash.new
  36  *
  37  * @param mrb The mruby state reference.
  38  * @return The initialized hash.
  39  */
  40 MRB_API mrb_value mrb_hash_new(mrb_state *mrb);
  41
  42 /*
  43  * Sets a keys and values to hashes.
  44  *
  45  * Equivalent to:
  46  *
  47  *      hash[key] = val
  48  *
  49  * @param mrb The mruby state reference.
  50  * @param hash The target hash.
  51  * @param key The key to set.
  52  * @param val The value to set.
  53  * @return The value.
  54  */
  55 MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val);
  56
  57 /*
  58  * Gets a value from a key. If the key is not found, the default of the
  59  * hash is used.
  60  *
  61  * Equivalent to:
  62  *
  63  *     hash[key]
  64  *
  65  * @param mrb The mruby state reference.
  66  * @param hash The target hash.
  67  * @param key The key to get.
  68  * @return The found value.
  69  */
  70 MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key);
  71
  72 /*
  73  * Gets a value from a key. If the key is not found, the default parameter is
  74  * used.
  75  *
  76  * Equivalent to:
  77  *
  78  *     hash.key?(key) ? hash[key] : def
  79  *
  80  * @param mrb The mruby state reference.
  81  * @param hash The target hash.
  82  * @param key The key to get.
  83  * @param def The default value.
  84  * @return The found value.
  85  */
  86 MRB_API mrb_value mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def);
  87
  88 /*
  89  * Deletes hash key and value pair.
  90  *
  91  * Equivalent to:
  92  *
  93  *     hash.delete(key)
  94  *
  95  * @param mrb The mruby state reference.
  96  * @param hash The target hash.
  97  * @param key The key to delete.
  98  * @return The deleted value.
  99  */
 100 MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key);
 101
 102 /*
 103  * Gets an array of keys.
 104  *
 105  * Equivalent to:
 106  *
 107  *     hash.keys
 108  *
 109  * @param mrb The mruby state reference.
 110  * @param hash The target hash.
 111  * @return An array with the keys of the hash.
 112  */
 113 MRB_API mrb_value mrb_hash_keys(mrb_state *mrb, mrb_value hash);
 114 /*
 115  * Check if the hash has the key.
 116  *
 117  * Equivalent to:
 118  *
 119  *     hash.key?(key)
 120  *
 121  * @param mrb The mruby state reference.
 122  * @param hash The target hash.
 123  * @param key The key to check existence.
 124  * @return True if the hash has the key
 125  */
 126 MRB_API mrb_bool mrb_hash_key_p(mrb_state *mrb, mrb_value hash, mrb_value key);
 127
 128 /*
 129  * Check if the hash is empty
 130  *
 131  * Equivalent to:
 132  *
 133  *     hash.empty?
 134  *
 135  * @param mrb The mruby state reference.
 136  * @param self The target hash.
 137  * @return True if the hash is empty, false otherwise.
 138  */
 139 MRB_API mrb_bool mrb_hash_empty_p(mrb_state *mrb, mrb_value self);
 140
 141 /*
 142  * Gets an array of values.
 143  *
 144  * Equivalent to:
 145  *
 146  *     hash.values
 147  *
 148  * @param mrb The mruby state reference.
 149  * @param hash The target hash.
 150  * @return An array with the values of the hash.
 151  */
 152 MRB_API mrb_value mrb_hash_values(mrb_state *mrb, mrb_value hash);
 153
 154 /*
 155  * Clears the hash.
 156  *
 157  * Equivalent to:
 158  *
 159  *     hash.clear
 160  *
 161  * @param mrb The mruby state reference.
 162  * @param hash The target hash.
 163  * @return The hash
 164  */
 165 MRB_API mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash);
 166
 167 /*
 168  * Get hash size.
 169  *
 170  * Equivalent to:
 171  *
 172  *      hash.size
 173  *
 174  * @param mrb The mruby state reference.
 175  * @param hash The target hash.
 176  * @return The hash size.
 177  */
 178 MRB_API mrb_int mrb_hash_size(mrb_state *mrb, mrb_value hash);
 179
 180 /*
 181  * Copies the hash.
 182  *
 183  *
 184  * @param mrb The mruby state reference.
 185  * @param hash The target hash.
 186  * @return The copy of the hash
 187  */
 188 MRB_API mrb_value mrb_hash_dup(mrb_state *mrb, mrb_value hash);
 189
 190 /*
 191  * Merges two hashes. The first hash will be modified by the
 192  * second hash.
 193  *
 194  * @param mrb The mruby state reference.
 195  * @param hash1 The target hash.
 196  * @param hash2 Updating hash
 197  */
 198 MRB_API void mrb_hash_merge(mrb_state *mrb, mrb_value hash1, mrb_value hash2);
 199
 200 /* declaration of struct mrb_hash_value */
 201 /* be careful when you touch the internal */
 202 typedef struct {
 203   mrb_value v;
 204   mrb_int n;
 205 } mrb_hash_value;
 206
 207 /* RHASH_TBL allocates st_table if not available. */
 208 #define RHASH(obj)   ((struct RHash*)(mrb_ptr(obj)))
 209 #define RHASH_TBL(h)          (RHASH(h)->ht)
 210 #define RHASH_IFNONE(h)       mrb_iv_get(mrb, (h), mrb_intern_lit(mrb, "ifnone"))
 211 #define RHASH_PROCDEFAULT(h)  RHASH_IFNONE(h)
 212
 213 #define MRB_HASH_DEFAULT      1
 214 #define MRB_HASH_PROC_DEFAULT 2
 215 #define MRB_RHASH_DEFAULT_P(h) (RHASH(h)->flags & MRB_HASH_DEFAULT)
 216 #define MRB_RHASH_PROCDEFAULT_P(h) (RHASH(h)->flags & MRB_HASH_PROC_DEFAULT)
 217
 218 /* GC functions */
 219 void mrb_gc_mark_hash(mrb_state*, struct RHash*);
 220 size_t mrb_gc_mark_hash_size(mrb_state*, struct RHash*);
 221 void mrb_gc_free_hash(mrb_state*, struct RHash*);
 222
 223 /* return non zero to break the loop */
 224 typedef int (mrb_hash_foreach_func)(mrb_state *mrb, mrb_value key, mrb_value val, void *data);
 225 MRB_API void mrb_hash_foreach(mrb_state *mrb, struct RHash *hash, mrb_hash_foreach_func *func, void *p);
 226
 227 MRB_END_DECL
 228
 229 #endif  /* MRUBY_HASH_H */