All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_integer.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2015 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 
18 #pragma once
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 #include <aerospike/as_util.h>
25 #include <aerospike/as_val.h>
26 
27 #include <stdint.h>
28 
29 /******************************************************************************
30  * TYPES
31  ******************************************************************************/
32 
33 /**
34  * Container for integer values.
35  *
36  * ## Initialization
37  *
38  * An as_integer should be initialized via one of the provided function.
39  * - as_integer_init()
40  * - as_integer_new()
41  *
42  * To initialize a stack allocated as_integer, use as_integer_init():
43  *
44  * ~~~~~~~~~~{.c}
45  * as_integer i;
46  * as_integer_init(&i, 100);
47  * ~~~~~~~~~~
48  *
49  * To create and initialize a heap allocated as_integer, use as_integer_new():
50  *
51  * ~~~~~~~~~~{.c}
52  * as_integer * i = as_integer_new(100);
53  * ~~~~~~~~~~
54  *
55  * ## Destruction
56  *
57  * When the as_integer instance is no longer required, then you should
58  * release the resources associated with it via as_integer_destroy():
59  *
60  * ~~~~~~~~~~{.c}
61  * as_integer_destroy(i);
62  * ~~~~~~~~~~
63  *
64  * ## Usage
65  *
66  * There are two functions for getting the boxed value contained by
67  * as_integer:
68  *
69  * as_integer_get() returns the contained value. If an error occurred, then
70  * 0 (zero) is returned. Possible errors is the as_integer instance is NULL.
71  *
72  * ~~~~~~~~~~{.c}
73  * int64_t ival = as_integer_get(i);
74  * ~~~~~~~~~~
75  *
76  * as_integer_getorelse() allows you to return a default value if an error
77  * occurs:
78  *
79  * ~~~~~~~~~~{.c}
80  * int64_t ival = as_integer_getorelse(i, -1);
81  * ~~~~~~~~~~
82  *
83  * ## Conversions
84  *
85  * as_integer is derived from as_val, so it is generally safe to down cast:
86  *
87  * ~~~~~~~~~~{.c}
88  * as_val val = (as_val) i;
89  * ~~~~~~~~~~
90  *
91  * However, upcasting is more error prone. When doing so, you should use
92  * as_integer_fromval(). If conversion fails, then the return value is NULL.
93  *
94  * ~~~~~~~~~~{.c}
95  * as_integer * i = as_integer_fromval(val);
96  * ~~~~~~~~~~
97  *
98  *
99  *
100  * @extends as_val
101  * @ingroup aerospike_t
102  */
103 typedef struct as_integer_s {
104 
105  /**
106  * @private
107  * as_boolean is a subtype of as_val.
108  * You can cast as_boolean to as_val.
109  */
111 
112  /**
113  * The integer value
114  */
115  int64_t value;
116 
117 } as_integer;
118 
119 /******************************************************************************
120  * FUNCTIONS
121  ******************************************************************************/
122 
123 /**
124  * Initialize a stack allocated `as_integer` with the given integer value.
125  *
126  * ~~~~~~~~~~{.c}
127  * as_integer i;
128  * as_integer_init(&i, 123);
129  * ~~~~~~~~~~
130  *
131  * When the `as_integer` is no longer needed, you should release it an it's
132  * resources:
133  *
134  * ~~~~~~~~~~{.c}
135  * as_integer_destroy(&i);
136  * ~~~~~~~~~~
137  *
138  * @param integer The `as_integer` to initialize.
139  * @param value The integer value.
140  *
141  * @return On success, the initialized value. Otherwise NULL.
142  *
143  * @relatesalso as_integer
144  */
145 as_integer * as_integer_init(as_integer * integer, int64_t value);
146 
147 /**
148  * Creates a new heap allocated as_integer.
149  *
150  * ~~~~~~~~~~{.c}
151  * as_integer * i = as_integer_new(123);
152  * ~~~~~~~~~~
153  *
154  * When the `as_integer` is no longer needed, you should release it an it's
155  * resources:
156  *
157  * ~~~~~~~~~~{.c}
158  * as_integer_destroy(&i);
159  * ~~~~~~~~~~
160  *
161  * @param value The integer value.
162  *
163  * @return On success, the initialized value. Otherwise NULL.
164  *
165  * @relatesalso as_integer
166  */
167 as_integer * as_integer_new(int64_t value);
168 
169 /**
170  * Destroy the `as_integer` and release resources.
171  *
172  * ~~~~~~~~~~{.c}
173  * as_integer_destroy(i);
174  * ~~~~~~~~~~
175  *
176  * @param integer The integer to destroy.
177  *
178  * @relatesalso as_integer
179  */
180 static inline void as_integer_destroy(as_integer * integer) {
181  as_val_destroy((as_val *) integer);
182 }
183 
184 /******************************************************************************
185  * VALUE FUNCTIONS
186  ******************************************************************************/
187 
188 /**
189  * Get the int64_t value. If integer is NULL, then return the fallback value.
190  *
191  * @relatesalso as_integer
192  */
193 static inline int64_t as_integer_getorelse(const as_integer * integer, int64_t fallback) {
194  return integer ? integer->value : fallback;
195 }
196 
197 /**
198  * Get the int64_t value.
199  *
200  * @relatesalso as_integer
201  */
202 static inline int64_t as_integer_get(const as_integer * integer) {
203  return as_integer_getorelse(integer, 0);
204 }
205 
206 /**
207  * Get the int64_t value.
208  * @deprecated Use as_integer_get() instead.
209  *
210  * @relatesalso as_integer
211  */
212 static inline int64_t as_integer_toint(const as_integer * integer) {
213  return as_integer_getorelse(integer, 0);
214 }
215 
216 /******************************************************************************
217  * CONVERSION FUNCTIONS
218  ******************************************************************************/
219 
220 /**
221  * Convert to an as_val.
222  *
223  * @relatesalso as_integer
224  */
225 static inline as_val * as_integer_toval(const as_integer * i) {
226  return (as_val *) i;
227 }
228 
229 /**
230  * Convert from an as_val.
231  *
232  * @relatesalso as_integer
233  */
234 static inline as_integer * as_integer_fromval(const as_val * v) {
236 }
237 
238 /******************************************************************************
239  * as_val FUNCTIONS
240  ******************************************************************************/
241 
242 /**
243  * @private
244  * Internal helper function for destroying an as_val.
245  */
247 
248 /**
249  * @private
250  * Internal helper function for getting the hashcode of an as_val.
251  */
252 uint32_t as_integer_val_hashcode(const as_val * v);
253 
254 /**
255  * @private
256  * Internal helper function for getting the string representation of an as_val.
257  */
258 char * as_integer_val_tostring(const as_val * v);
259 
260 #ifdef __cplusplus
261 } // end extern "C"
262 #endif