dmlite  0.4
any.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/any.h
2  * @brief Opaque handler to pass different types of values to the API.
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  * @note Basically it wraps boost::any and dmlite::Extensible.
5  */
6 #ifndef DMLITE_ANY_H
7 #define DMLITE_ANY_H
8 
9 #include <stddef.h>
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /**
16  * @brief Used to pass configuration values.
17  */
18 typedef struct dmlite_any dmlite_any;
19 
20 /**
21  * @brief Handles key->value pairs.
22  */
24 
25 /**
26  * @brief Creates a new dmlite_any.
27  * @param str The string that will be wrapped. It is safe to free afterwards.
28  * @return A newly allocated dmlite_any.
29  */
30 dmlite_any* dmlite_any_new_string(const char* str);
31 
32 /**
33  * @brief Creates a new dmlite_any.
34  * @param n The number of elements.
35  * @param strv The strings that will be wrapped. It is safe to free afterwards.
36  * @return A newly allocated dmlite_any.
37  */
38 dmlite_any* dmlite_any_new_string_array(unsigned n, const char** strv);
39 
40 /**
41  * @brief Creates a new dmlite_any.
42  * @param l The long that will be wrapped.
43  * @return A newly allocated dmlite_any.
44  */
46 
47 /**
48  * @brief Creates a new dmlite_any.
49  * @param n The number of elements.
50  * @param lv The longs that will be wrapped.
51  * @return A newly allocated dmlite_any.
52  */
53 dmlite_any* dmlite_any_new_long_array(unsigned n, long* lv);
54 
55 /**
56  * @brief Frees a dmlite_any.
57  * @param any The dmlite_any to destroy.
58  */
59 void dmlite_any_free(dmlite_any* any);
60 
61 /**
62  * @brief Gets the string interpretation of the dmlite_any.
63  * @details Defaults to "".
64  * @param any The dmlite_any to convert.
65  * @param buffer Where to put the string.
66  * @param bsize The size of the buffer.
67  */
68 void dmlite_any_to_string(const dmlite_any* any, char* buffer, size_t bsize);
69 
70 /**
71  * @brief Returns the long interpretation of they dmlite_any.
72  * @details Defaults to 0.
73  * @param any The dmlite_any to convert.
74  */
75 long dmlite_any_to_long(const dmlite_any* any);
76 
77 
78 /**
79  * @brief Created a new generic dictionary.
80  * @return A newly allocated dmlite_any_dict.
81  */
83 
84 /**
85  * @brief Make a copy of the dictionary.
86  * @param dict The original
87  * @return A newly allocated copy of dict.
88  */
90 
91 /**
92  * @brief Frees a dmlite_any_dict
93  */
95 
96 /**
97  * @brief Clears the dictionary.
98  */
100 
101 /**
102  * @brief Insert a new dmlite_any value into the dictionary.
103  * @details Replaces if already present.
104  * @param d The dictionary.
105  * @param k The key.
106  * @param v The value.
107  */
108 void dmlite_any_dict_insert(dmlite_any_dict* d, const char* k, const dmlite_any* v);
109 
110 /**
111  * @brief Returns how many elements there are in a specific dictionary.
112  */
113 unsigned long dmlite_any_dict_count(const dmlite_any_dict* d);
114 
115 /**
116  * @brief Returns the value associated with the key k.
117  * @return NULL if not found.
118  */
119 dmlite_any* dmlite_any_dict_get(const dmlite_any_dict* d, const char* k);
120 
121 /**
122  * @brief Removes a key-value from the dictionary.
123  * @param d The dictionary.
124  * @param k The key to be removed.
125  */
126 void dmlite_any_dict_erase(dmlite_any_dict* d, const char* k);
127 
128 /**
129  * @brief Generates a JSON serialization of the dictionary.
130  * @return The same pointer as buffer.
131  */
132 char* dmlite_any_dict_to_json(const dmlite_any_dict* d, char* buffer, size_t bsize);
133 
134 /**
135  * @brief Populates a dmlite_any_dict from a JSON string.
136  */
137 dmlite_any_dict* dmlite_any_dict_from_json(const char* json);
138 
139 /**
140  * @brief Puts in keys a pointer to an array of strings with all the available
141  * keys in d.
142  * @details Use dmlite_any_dict_keys_free to free.
143  * @param d The Dictionary.
144  * @param nkeys Will be set to the number of stored keys.
145  */
146 void dmlite_any_dict_keys(const dmlite_any_dict* d, unsigned* nkeys, char*** keys);
147 
148 /**
149  * @brief Frees an array of strings allocated by dmlite_any_dict_keys.
150  * @param n The number of keys in **keys
151  * @param keys The array of keys.
152  */
153 void dmlite_any_dict_keys_free(unsigned n, char** keys);
154 
155 #ifdef __cplusplus
156 }
157 #endif
158 
159 #endif /* DMLITE_ANY_H */
160