src/hb-map.cc

   1 /*
   2  * Copyright © 2018  Google, Inc.
   3  *
   4  *  This is part of HarfBuzz, a text shaping library.
   5  *
   6  * Permission is hereby granted, without written agreement and without
   7  * license or royalty fees, to use, copy, modify, and distribute this
   8  * software and its documentation for any purpose, provided that the
   9  * above copyright notice and the following two paragraphs appear in
  10  * all copies of this software.
  11  *
  12  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
  13  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  14  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
  15  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  16  * DAMAGE.
  17  *
  18  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  19  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  20  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  21  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
  22  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  23  *
  24  * Google Author(s): Behdad Esfahbod
  25  */
  26
  27 #include "hb-map.hh"
  28
  29
  30 /**
  31  * SECTION:hb-map
  32  * @title: hb-map
  33  * @short_description: Object representing integer to integer mapping
  34  * @include: hb.h
  35  *
  36  * Map objects are integer-to-integer hash-maps.  Currently they are
  37  * not used in the HarfBuzz public API, but are provided for client's
  38  * use if desired.
  39  **/
  40
  41
  42 /**
  43  * hb_map_create:
  44  *
  45  * Creates a new, initially empty map.
  46  *
  47  * Return value: (transfer full): The new #hb_map_t
  48  *
  49  * Since: 1.7.7
  50  **/
  51 hb_map_t *
  52 hb_map_create ()
  53 {
  54   hb_map_t *map;
  55
  56   if (!(map = hb_object_create<hb_map_t> ()))
  57     return hb_map_get_empty ();
  58
  59   return map;
  60 }
  61
  62 /**
  63  * hb_map_get_empty:
  64  *
  65  * Fetches the singleton empty #hb_map_t.
  66  *
  67  * Return value: (transfer full): The empty #hb_map_t
  68  *
  69  * Since: 1.7.7
  70  **/
  71 hb_map_t *
  72 hb_map_get_empty ()
  73 {
  74   return const_cast<hb_map_t *> (&Null (hb_map_t));
  75 }
  76
  77 /**
  78  * hb_map_reference: (skip)
  79  * @map: A map
  80  *
  81  * Increases the reference count on a map.
  82  *
  83  * Return value: (transfer full): The map
  84  *
  85  * Since: 1.7.7
  86  **/
  87 hb_map_t *
  88 hb_map_reference (hb_map_t *map)
  89 {
  90   return hb_object_reference (map);
  91 }
  92
  93 /**
  94  * hb_map_destroy: (skip)
  95  * @map: A map
  96  *
  97  * Decreases the reference count on a map. When
  98  * the reference count reaches zero, the map is
  99  * destroyed, freeing all memory.
 100  *
 101  * Since: 1.7.7
 102  **/
 103 void
 104 hb_map_destroy (hb_map_t *map)
 105 {
 106   if (!hb_object_destroy (map)) return;
 107
 108   hb_free (map);
 109 }
 110
 111 /**
 112  * hb_map_set_user_data: (skip)
 113  * @map: A map
 114  * @key: The user-data key to set
 115  * @data: A pointer to the user data to set
 116  * @destroy: (nullable): A callback to call when @data is not needed anymore
 117  * @replace: Whether to replace an existing data with the same key
 118  *
 119  * Attaches a user-data key/data pair to the specified map.
 120  *
 121  * Return value: `true` if success, `false` otherwise
 122  *
 123  * Since: 1.7.7
 124  **/
 125 hb_bool_t
 126 hb_map_set_user_data (hb_map_t           *map,
 127                       hb_user_data_key_t *key,
 128                       void *              data,
 129                       hb_destroy_func_t   destroy,
 130                       hb_bool_t           replace)
 131 {
 132   return hb_object_set_user_data (map, key, data, destroy, replace);
 133 }
 134
 135 /**
 136  * hb_map_get_user_data: (skip)
 137  * @map: A map
 138  * @key: The user-data key to query
 139  *
 140  * Fetches the user data associated with the specified key,
 141  * attached to the specified map.
 142  *
 143  * Return value: (transfer none): A pointer to the user data
 144  *
 145  * Since: 1.7.7
 146  **/
 147 void *
 148 hb_map_get_user_data (const hb_map_t     *map,
 149                       hb_user_data_key_t *key)
 150 {
 151   return hb_object_get_user_data (map, key);
 152 }
 153
 154
 155 /**
 156  * hb_map_allocation_successful:
 157  * @map: A map
 158  *
 159  * Tests whether memory allocation for a set was successful.
 160  *
 161  * Return value: `true` if allocation succeeded, `false` otherwise
 162  *
 163  * Since: 1.7.7
 164  **/
 165 hb_bool_t
 166 hb_map_allocation_successful (const hb_map_t  *map)
 167 {
 168   return map->successful;
 169 }
 170
 171 /**
 172  * hb_map_copy:
 173  * @map: A map
 174  *
 175  * Allocate a copy of @map.
 176  *
 177  * Return value: (transfer full): Newly-allocated map.
 178  *
 179  * Since: 4.4.0
 180  **/
 181 hb_map_t *
 182 hb_map_copy (const hb_map_t *map)
 183 {
 184   hb_map_t *copy = hb_map_create ();
 185   if (unlikely (copy->in_error ()))
 186     return hb_map_get_empty ();
 187
 188   *copy = *map;
 189   return copy;
 190 }
 191
 192 /**
 193  * hb_map_set:
 194  * @map: A map
 195  * @key: The key to store in the map
 196  * @value: The value to store for @key
 197  *
 198  * Stores @key:@value in the map.
 199  *
 200  * Since: 1.7.7
 201  **/
 202 void
 203 hb_map_set (hb_map_t       *map,
 204             hb_codepoint_t  key,
 205             hb_codepoint_t  value)
 206 {
 207   /* Immutable-safe. */
 208   map->set (key, value);
 209 }
 210
 211 /**
 212  * hb_map_get:
 213  * @map: A map
 214  * @key: The key to query
 215  *
 216  * Fetches the value stored for @key in @map.
 217  *
 218  * Since: 1.7.7
 219  **/
 220 hb_codepoint_t
 221 hb_map_get (const hb_map_t *map,
 222             hb_codepoint_t  key)
 223 {
 224   return map->get (key);
 225 }
 226
 227 /**
 228  * hb_map_del:
 229  * @map: A map
 230  * @key: The key to delete
 231  *
 232  * Removes @key and its stored value from @map.
 233  *
 234  * Since: 1.7.7
 235  **/
 236 void
 237 hb_map_del (hb_map_t       *map,
 238             hb_codepoint_t  key)
 239 {
 240   /* Immutable-safe. */
 241   map->del (key);
 242 }
 243
 244 /**
 245  * hb_map_has:
 246  * @map: A map
 247  * @key: The key to query
 248  *
 249  * Tests whether @key is an element of @map.
 250  *
 251  * Return value: `true` if @key is found in @map, `false` otherwise
 252  *
 253  * Since: 1.7.7
 254  **/
 255 hb_bool_t
 256 hb_map_has (const hb_map_t *map,
 257             hb_codepoint_t  key)
 258 {
 259   return map->has (key);
 260 }
 261
 262
 263 /**
 264  * hb_map_clear:
 265  * @map: A map
 266  *
 267  * Clears out the contents of @map.
 268  *
 269  * Since: 1.7.7
 270  **/
 271 void
 272 hb_map_clear (hb_map_t *map)
 273 {
 274   return map->clear ();
 275 }
 276
 277 /**
 278  * hb_map_is_empty:
 279  * @map: A map
 280  *
 281  * Tests whether @map is empty (contains no elements).
 282  *
 283  * Return value: `true` if @map is empty
 284  *
 285  * Since: 1.7.7
 286  **/
 287 hb_bool_t
 288 hb_map_is_empty (const hb_map_t *map)
 289 {
 290   return map->is_empty ();
 291 }
 292
 293 /**
 294  * hb_map_get_population:
 295  * @map: A map
 296  *
 297  * Returns the number of key-value pairs in the map.
 298  *
 299  * Return value: The population of @map
 300  *
 301  * Since: 1.7.7
 302  **/
 303 unsigned int
 304 hb_map_get_population (const hb_map_t *map)
 305 {
 306   return map->get_population ();
 307 }
 308
 309 /**
 310  * hb_map_is_equal:
 311  * @map: A map
 312  * @other: Another map
 313  *
 314  * Tests whether @map and @other are equal (contain the same
 315  * elements).
 316  *
 317  * Return value: `true` if the two maps are equal, `false` otherwise.
 318  *
 319  * Since: 4.3.0
 320  **/
 321 hb_bool_t
 322 hb_map_is_equal (const hb_map_t *map,
 323                  const hb_map_t *other)
 324 {
 325   return map->is_equal (*other);
 326 }
 327
 328 /**
 329  * hb_map_hash:
 330  * @map: A map
 331  *
 332  * Creates a hash representing @map.
 333  *
 334  * Return value:
 335  * A hash of @map.
 336  *
 337  * Since: 4.4.0
 338  **/
 339 unsigned int
 340 hb_map_hash (const hb_map_t *map)
 341 {
 342   return map->hash ();
 343 }
 344
 345 /**
 346  * hb_map_update:
 347  * @map: A map
 348  * @other: Another map
 349  *
 350  * Add the contents of @other to @map.
 351  *
 352  * Since: 7.0.0
 353  **/
 354 HB_EXTERN void
 355 hb_map_update (hb_map_t *map,
 356                const hb_map_t *other)
 357 {
 358   map->update (*other);
 359 }
 360
 361 /**
 362  * hb_map_next:
 363  * @map: A map
 364  * @idx: (inout): Iterator internal state
 365  * @key: (out): Key retrieved
 366  * @value: (out): Value retrieved
 367  *
 368  * Fetches the next key/value pair in @map.
 369  *
 370  * Set @idx to -1 to get started.
 371  *
 372  * If the map is modified during iteration, the behavior is undefined.
 373  *
 374  * The order in which the key/values are returned is undefined.
 375  *
 376  * Return value: `true` if there was a next value, `false` otherwise
 377  *
 378  * Since: 7.0.0
 379  **/
 380 hb_bool_t
 381 hb_map_next (const hb_map_t *map,
 382              int *idx,
 383              hb_codepoint_t *key,
 384              hb_codepoint_t *value)
 385 {
 386   return map->next (idx, key, value);
 387 }
 388
 389 /**
 390  * hb_map_keys:
 391  * @map: A map
 392  * @keys: A set
 393  *
 394  * Add the keys of @map to @keys.
 395  *
 396  * Since: 7.0.0
 397  **/
 398 void
 399 hb_map_keys (const hb_map_t *map,
 400              hb_set_t *keys)
 401 {
 402   hb_copy (map->keys() , *keys);
 403 }
 404
 405 /**
 406  * hb_map_values:
 407  * @map: A map
 408  * @values: A set
 409  *
 410  * Add the values of @map to @values.
 411  *
 412  * Since: 7.0.0
 413  **/
 414 void
 415 hb_map_values (const hb_map_t *map,
 416                hb_set_t *values)
 417 {
 418   hb_copy (map->values() , *values);
 419 }