include/mruby/hash.h

   1 /**
   2 ** @file 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 /* offset of `iv` must be 3 words */
  18 struct RHash {
  19   MRB_OBJECT_HEADER;
  20 #ifdef MRB_64BIT
  21   uint32_t size;
  22   struct iv_tbl *iv;
  23   uint32_t ea_capa;
  24   uint32_t ea_n_used;
  25 #else
  26   struct iv_tbl *iv;
  27   uint32_t size;
  28 #endif
  29   union {
  30     struct hash_entry *ea;
  31     struct hash_table *ht;
  32   } hsh;
  33 };
  34
  35 #define mrb_hash_ptr(v)    ((struct RHash*)(mrb_ptr(v)))
  36 #define mrb_hash_value(p)  mrb_obj_value((void*)(p))
  37
  38 size_t mrb_hash_memsize(mrb_value obj);
  39 MRB_API mrb_value mrb_hash_new_capa(mrb_state *mrb, mrb_int capa);
  40
  41 /*
  42  * Initializes a new hash.
  43  *
  44  * Equivalent to:
  45  *
  46  *      Hash.new
  47  *
  48  * @param mrb The mruby state reference.
  49  * @return The initialized hash.
  50  */
  51 MRB_API mrb_value mrb_hash_new(mrb_state *mrb);
  52
  53 /*
  54  * Sets a keys and values to hashes.
  55  *
  56  * Equivalent to:
  57  *
  58  *      hash[key] = val
  59  *
  60  * @param mrb The mruby state reference.
  61  * @param hash The target hash.
  62  * @param key The key to set.
  63  * @param val The value to set.
  64  * @return The value.
  65  */
  66 MRB_API void mrb_hash_set(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value val);
  67
  68 /*
  69  * Gets a value from a key. If the key is not found, the default of the
  70  * hash is used.
  71  *
  72  * Equivalent to:
  73  *
  74  *     hash[key]
  75  *
  76  * @param mrb The mruby state reference.
  77  * @param hash The target hash.
  78  * @param key The key to get.
  79  * @return The found value.
  80  */
  81 MRB_API mrb_value mrb_hash_get(mrb_state *mrb, mrb_value hash, mrb_value key);
  82
  83 /*
  84  * Gets a value from a key. If the key is not found, the default parameter is
  85  * used.
  86  *
  87  * Equivalent to:
  88  *
  89  *     hash.key?(key) ? hash[key] : def
  90  *
  91  * @param mrb The mruby state reference.
  92  * @param hash The target hash.
  93  * @param key The key to get.
  94  * @param def The default value.
  95  * @return The found value.
  96  */
  97 MRB_API mrb_value mrb_hash_fetch(mrb_state *mrb, mrb_value hash, mrb_value key, mrb_value def);
  98
  99 /*
 100  * Deletes hash key and value pair.
 101  *
 102  * Equivalent to:
 103  *
 104  *     hash.delete(key)
 105  *
 106  * @param mrb The mruby state reference.
 107  * @param hash The target hash.
 108  * @param key The key to delete.
 109  * @return The deleted value. This value is not protected from GC. Use `mrb_gc_protect()` if necessary.
 110  */
 111 MRB_API mrb_value mrb_hash_delete_key(mrb_state *mrb, mrb_value hash, mrb_value key);
 112
 113 /*
 114  * Gets an array of keys.
 115  *
 116  * Equivalent to:
 117  *
 118  *     hash.keys
 119  *
 120  * @param mrb The mruby state reference.
 121  * @param hash The target hash.
 122  * @return An array with the keys of the hash.
 123  */
 124 MRB_API mrb_value mrb_hash_keys(mrb_state *mrb, mrb_value hash);
 125 /*
 126  * Check if the hash has the key.
 127  *
 128  * Equivalent to:
 129  *
 130  *     hash.key?(key)
 131  *
 132  * @param mrb The mruby state reference.
 133  * @param hash The target hash.
 134  * @param key The key to check existence.
 135  * @return True if the hash has the key
 136  */
 137 MRB_API mrb_bool mrb_hash_key_p(mrb_state *mrb, mrb_value hash, mrb_value key);
 138
 139 /*
 140  * Check if the hash is empty
 141  *
 142  * Equivalent to:
 143  *
 144  *     hash.empty?
 145  *
 146  * @param mrb The mruby state reference.
 147  * @param self The target hash.
 148  * @return True if the hash is empty, false otherwise.
 149  */
 150 MRB_API mrb_bool mrb_hash_empty_p(mrb_state *mrb, mrb_value self);
 151
 152 /*
 153  * Gets an array of values.
 154  *
 155  * Equivalent to:
 156  *
 157  *     hash.values
 158  *
 159  * @param mrb The mruby state reference.
 160  * @param hash The target hash.
 161  * @return An array with the values of the hash.
 162  */
 163 MRB_API mrb_value mrb_hash_values(mrb_state *mrb, mrb_value hash);
 164
 165 /*
 166  * Clears the hash.
 167  *
 168  * Equivalent to:
 169  *
 170  *     hash.clear
 171  *
 172  * @param mrb The mruby state reference.
 173  * @param hash The target hash.
 174  * @return The hash
 175  */
 176 MRB_API mrb_value mrb_hash_clear(mrb_state *mrb, mrb_value hash);
 177
 178 /*
 179  * Get hash size.
 180  *
 181  * Equivalent to:
 182  *
 183  *      hash.size
 184  *
 185  * @param mrb The mruby state reference.
 186  * @param hash The target hash.
 187  * @return The hash size.
 188  */
 189 MRB_API mrb_int mrb_hash_size(mrb_state *mrb, mrb_value hash);
 190
 191 /*
 192  * Copies the hash. This function does NOT copy the instance variables
 193  * (except for the default value). Use mrb_obj_dup() to copy the instance
 194  * variables as well.
 195  *
 196  * @param mrb The mruby state reference.
 197  * @param hash The target hash.
 198  * @return The copy of the hash
 199  */
 200 MRB_API mrb_value mrb_hash_dup(mrb_state *mrb, mrb_value hash);
 201
 202 /*
 203  * Merges two hashes. The first hash will be modified by the
 204  * second hash.
 205  *
 206  * @param mrb The mruby state reference.
 207  * @param hash1 The target hash.
 208  * @param hash2 Updating hash
 209  */
 210 MRB_API void mrb_hash_merge(mrb_state *mrb, mrb_value hash1, mrb_value hash2);
 211
 212 #define RHASH(hash) ((struct RHash*)(mrb_ptr(hash)))
 213
 214 #define MRB_HASH_IB_BIT_BIT         5
 215 #define MRB_HASH_AR_EA_CAPA_BIT     5
 216 #define MRB_HASH_IB_BIT_SHIFT       0
 217 #define MRB_HASH_AR_EA_CAPA_SHIFT   0
 218 #define MRB_HASH_AR_EA_N_USED_SHIFT MRB_HASH_AR_EA_CAPA_BIT
 219 #define MRB_HASH_SIZE_FLAGS_SHIFT   (MRB_HASH_AR_EA_CAPA_BIT * 2)
 220 #define MRB_HASH_IB_BIT_MASK        ((1 << MRB_HASH_IB_BIT_BIT) - 1)
 221 #define MRB_HASH_AR_EA_CAPA_MASK    ((1 << MRB_HASH_AR_EA_CAPA_BIT) - 1)
 222 #define MRB_HASH_AR_EA_N_USED_MASK  (MRB_HASH_AR_EA_CAPA_MASK << MRB_HASH_AR_EA_N_USED_SHIFT)
 223 #define MRB_HASH_DEFAULT            (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 0))
 224 #define MRB_HASH_PROC_DEFAULT       (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 1))
 225 #define MRB_HASH_HT                 (1 << (MRB_HASH_SIZE_FLAGS_SHIFT + 2))
 226 #define MRB_RHASH_DEFAULT_P(hash) (RHASH(hash)->flags & MRB_HASH_DEFAULT)
 227 #define MRB_RHASH_PROCDEFAULT_P(hash) (RHASH(hash)->flags & MRB_HASH_PROC_DEFAULT)
 228
 229 /* GC functions */
 230 void mrb_gc_mark_hash(mrb_state*, struct RHash*);
 231 size_t mrb_gc_mark_hash_size(mrb_state*, struct RHash*);
 232 void mrb_gc_free_hash(mrb_state*, struct RHash*);
 233
 234 /* return non zero to break the loop */
 235 typedef int (mrb_hash_foreach_func)(mrb_state *mrb, mrb_value key, mrb_value val, void *data);
 236 MRB_API void mrb_hash_foreach(mrb_state *mrb, struct RHash *hash, mrb_hash_foreach_func *func, void *p);
 237
 238 MRB_END_DECL
 239
 240 #endif  /* MRUBY_HASH_H */