src/idxmap.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_idxmap_h__
   8 #define INCLUDE_idxmap_h__
   9
  10 #include "common.h"
  11
  12 #include "git2/index.h"
  13
  14 /** A map with `git_index_entry`s as key. */
  15 typedef struct kh_idx_s git_idxmap;
  16 /** A map with case-insensitive `git_index_entry`s as key */
  17 typedef struct kh_idxicase_s git_idxmap_icase;
  18
  19 /**
  20  * Allocate a new index entry map.
  21  *
  22  * @param out Pointer to the map that shall be allocated.
  23  * @return 0 on success, an error code if allocation has failed.
  24  */
  25 int git_idxmap_new(git_idxmap **out);
  26
  27 /**
  28  * Allocate a new case-insensitive index entry map.
  29  *
  30  * @param out Pointer to the map that shall be allocated.
  31  * @return 0 on success, an error code if allocation has failed.
  32  */
  33 int git_idxmap_icase_new(git_idxmap_icase **out);
  34
  35 /**
  36  * Free memory associated with the map.
  37  *
  38  * Note that this function will _not_ free values added to this
  39  * map.
  40  *
  41  * @param map Pointer to the map that is to be free'd. May be
  42  *            `NULL`.
  43  */
  44 void git_idxmap_free(git_idxmap *map);
  45
  46 /**
  47  * Free memory associated with the map.
  48  *
  49  * Note that this function will _not_ free values added to this
  50  * map.
  51  *
  52  * @param map Pointer to the map that is to be free'd. May be
  53  *            `NULL`.
  54  */
  55 void git_idxmap_icase_free(git_idxmap_icase *map);
  56
  57 /**
  58  * Clear all entries from the map.
  59  *
  60  * This function will remove all entries from the associated map.
  61  * Memory associated with it will not be released, though.
  62  *
  63  * @param map Pointer to the map that shall be cleared. May be
  64  *            `NULL`.
  65  */
  66 void git_idxmap_clear(git_idxmap *map);
  67
  68 /**
  69  * Clear all entries from the map.
  70  *
  71  * This function will remove all entries from the associated map.
  72  * Memory associated with it will not be released, though.
  73  *
  74  * @param map Pointer to the map that shall be cleared. May be
  75  *            `NULL`.
  76  */
  77 void git_idxmap_icase_clear(git_idxmap_icase *map);
  78
  79 /**
  80  * Resize the map by allocating more memory.
  81  *
  82  * @param map map that shall be resized
  83  * @param size count of entries that the map shall hold
  84  * @return `0` if the map was successfully resized, a negative
  85  *         error code otherwise
  86  */
  87 int git_idxmap_resize(git_idxmap *map, size_t size);
  88
  89 /**
  90  * Resize the map by allocating more memory.
  91  *
  92  * @param map map that shall be resized
  93  * @param size count of entries that the map shall hold
  94  * @return `0` if the map was successfully resized, a negative
  95  *         error code otherwise
  96  */
  97 int git_idxmap_icase_resize(git_idxmap_icase *map, size_t size);
  98
  99 /**
 100  * Return value associated with the given key.
 101  *
 102  * @param map map to search key in
 103  * @param key key to search for; the index entry will be searched
 104  *            for by its case-sensitive path
 105  * @return value associated with the given key or NULL if the key was not found
 106  */
 107 void *git_idxmap_get(git_idxmap *map, const git_index_entry *key);
 108
 109 /**
 110  * Return value associated with the given key.
 111  *
 112  * @param map map to search key in
 113  * @param key key to search for; the index entry will be searched
 114  *            for by its case-insensitive path
 115  * @return value associated with the given key or NULL if the key was not found
 116  */
 117 void *git_idxmap_icase_get(git_idxmap_icase *map, const git_index_entry *key);
 118
 119 /**
 120  * Set the entry for key to value.
 121  *
 122  * If the map has no corresponding entry for the given key, a new
 123  * entry will be created with the given value. If an entry exists
 124  * already, its value will be updated to match the given value.
 125  *
 126  * @param map map to create new entry in
 127  * @param key key to set
 128  * @param value value to associate the key with; may be NULL
 129  * @return zero if the key was successfully set, a negative error
 130  *         code otherwise
 131  */
 132 int git_idxmap_set(git_idxmap *map, const git_index_entry *key, void *value);
 133
 134 /**
 135  * Set the entry for key to value.
 136  *
 137  * If the map has no corresponding entry for the given key, a new
 138  * entry will be created with the given value. If an entry exists
 139  * already, its value will be updated to match the given value.
 140  *
 141  * @param map map to create new entry in
 142  * @param key key to set
 143  * @param value value to associate the key with; may be NULL
 144  * @return zero if the key was successfully set, a negative error
 145  *         code otherwise
 146  */
 147 int git_idxmap_icase_set(git_idxmap_icase *map, const git_index_entry *key, void *value);
 148
 149 /**
 150  * Delete an entry from the map.
 151  *
 152  * Delete the given key and its value from the map. If no such
 153  * key exists, this will do nothing.
 154  *
 155  * @param map map to delete key in
 156  * @param key key to delete
 157  * @return `0` if the key has been deleted, GIT_ENOTFOUND if no
 158  *         such key was found, a negative code in case of an
 159  *         error
 160  */
 161 int git_idxmap_delete(git_idxmap *map, const git_index_entry *key);
 162
 163 /**
 164  * Delete an entry from the map.
 165  *
 166  * Delete the given key and its value from the map. If no such
 167  * key exists, this will do nothing.
 168  *
 169  * @param map map to delete key in
 170  * @param key key to delete
 171  * @return `0` if the key has been deleted, GIT_ENOTFOUND if no
 172  *         such key was found, a negative code in case of an
 173  *         error
 174  */
 175 int git_idxmap_icase_delete(git_idxmap_icase *map, const git_index_entry *key);
 176
 177 #endif