All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
as_integer.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2014 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 #include <aerospike/as_util.h>
21 #include <aerospike/as_val.h>
22 
23 #include <stdint.h>
24 
25 /******************************************************************************
26  * TYPES
27  ******************************************************************************/
28 
29 /**
30  * Container for integer values.
31  *
32  * ## Initialization
33  *
34  * An as_integer should be initialized via one of the provided function.
35  * - as_integer_init()
36  * - as_integer_new()
37  *
38  * To initialize a stack allocated as_integer, use as_integer_init():
39  *
40  * ~~~~~~~~~~{.c}
41  * as_integer i;
42  * as_integer_init(&i, 100);
43  * ~~~~~~~~~~
44  *
45  * To create and initialize a heap allocated as_integer, use as_integer_new():
46  *
47  * ~~~~~~~~~~{.c}
48  * as_integer * i = as_integer_new(100);
49  * ~~~~~~~~~~
50  *
51  * ## Destruction
52  *
53  * When the as_integer instance is no longer required, then you should
54  * release the resources associated with it via as_integer_destroy():
55  *
56  * ~~~~~~~~~~{.c}
57  * as_integer_destroy(i);
58  * ~~~~~~~~~~
59  *
60  * ## Usage
61  *
62  * There are two functions for getting the boxed value contained by
63  * as_integer:
64  *
65  * as_integer_get() returns the contained value. If an error occurred, then
66  * 0 (zero) is returned. Possible errors is the as_integer instance is NULL.
67  *
68  * ~~~~~~~~~~{.c}
69  * int64_t ival = as_integer_get(i);
70  * ~~~~~~~~~~
71  *
72  * as_integer_getorelse() allows you to return a default value if an error
73  * occurs:
74  *
75  * ~~~~~~~~~~{.c}
76  * int64_t ival = as_integer_getorelse(i, -1);
77  * ~~~~~~~~~~
78  *
79  * ## Conversions
80  *
81  * as_integer is derived from as_val, so it is generally safe to down cast:
82  *
83  * ~~~~~~~~~~{.c}
84  * as_val val = (as_val) i;
85  * ~~~~~~~~~~
86  *
87  * However, upcasting is more error prone. When doing so, you should use
88  * as_integer_fromval(). If conversion fails, then the return value is NULL.
89  *
90  * ~~~~~~~~~~{.c}
91  * as_integer * i = as_integer_fromval(val);
92  * ~~~~~~~~~~
93  *
94  *
95  *
96  * @extends as_val
97  * @ingroup aerospike_t
98  */
99 typedef struct as_integer_s {
100 
101  /**
102  * @private
103  * as_boolean is a subtype of as_val.
104  * You can cast as_boolean to as_val.
105  */
107 
108  /**
109  * The integer value
110  */
111  int64_t value;
112 
113 } as_integer;
114 
115 /******************************************************************************
116  * FUNCTIONS
117  ******************************************************************************/
118 
119 /**
120  * Initialize a stack allocated `as_integer` with the given integer value.
121  *
122  * ~~~~~~~~~~{.c}
123  * as_integer i;
124  * as_integer_init(&i, 123);
125  * ~~~~~~~~~~
126  *
127  * When the `as_integer` is no longer needed, you should release it an it's
128  * resources:
129  *
130  * ~~~~~~~~~~{.c}
131  * as_integer_destroy(&i);
132  * ~~~~~~~~~~
133  *
134  * @param integer The `as_integer` to initialize.
135  * @param value The integer value.
136  *
137  * @return On success, the initialized value. Otherwise NULL.
138  *
139  * @relatesalso as_integer
140  */
141 as_integer * as_integer_init(as_integer * integer, int64_t value);
142 
143 /**
144  * Creates a new heap allocated as_integer.
145  *
146  * ~~~~~~~~~~{.c}
147  * as_integer * i = as_integer_new(123);
148  * ~~~~~~~~~~
149  *
150  * When the `as_integer` is no longer needed, you should release it an it's
151  * resources:
152  *
153  * ~~~~~~~~~~{.c}
154  * as_integer_destroy(&i);
155  * ~~~~~~~~~~
156  *
157  * @param value The integer value.
158  *
159  * @return On success, the initialized value. Otherwise NULL.
160  *
161  * @relatesalso as_integer
162  */
163 as_integer * as_integer_new(int64_t value);
164 
165 /**
166  * Destroy the `as_integer` and release resources.
167  *
168  * ~~~~~~~~~~{.c}
169  * as_integer_destroy(i);
170  * ~~~~~~~~~~
171  *
172  * @param integer The integer to destroy.
173  *
174  * @relatesalso as_integer
175  */
176 static inline void as_integer_destroy(as_integer * integer) {
177  as_val_destroy((as_val *) integer);
178 }
179 
180 /******************************************************************************
181  * VALUE FUNCTIONS
182  ******************************************************************************/
183 
184 /**
185  * Get the int64_t value. If integer is NULL, then return the fallback value.
186  *
187  * @relatesalso as_integer
188  */
189 static inline int64_t as_integer_getorelse(const as_integer * integer, int64_t fallback) {
190  return integer ? integer->value : fallback;
191 }
192 
193 /**
194  * Get the int64_t value.
195  *
196  * @relatesalso as_integer
197  */
198 static inline int64_t as_integer_get(const as_integer * integer) {
199  return as_integer_getorelse(integer, 0);
200 }
201 
202 /**
203  * Get the int64_t value.
204  * @deprecated Use as_integer_get() instead.
205  *
206  * @relatesalso as_integer
207  */
208 static inline int64_t as_integer_toint(const as_integer * integer) {
209  return as_integer_getorelse(integer, 0);
210 }
211 
212 /******************************************************************************
213  * CONVERSION FUNCTIONS
214  ******************************************************************************/
215 
216 /**
217  * Convert to an as_val.
218  *
219  * @relatesalso as_integer
220  */
221 static inline as_val * as_integer_toval(const as_integer * i) {
222  return (as_val *) i;
223 }
224 
225 /**
226  * Convert from an as_val.
227  *
228  * @relatesalso as_integer
229  */
230 static inline as_integer * as_integer_fromval(const as_val * v) {
232 }
233 
234 /******************************************************************************
235  * as_val FUNCTIONS
236  ******************************************************************************/
237 
238 /**
239  * @private
240  * Internal helper function for destroying an as_val.
241  */
243 
244 /**
245  * @private
246  * Internal helper function for getting the hashcode of an as_val.
247  */
248 uint32_t as_integer_val_hashcode(const as_val * v);
249 
250 /**
251  * @private
252  * Internal helper function for getting the string representation of an as_val.
253  */
254 char * as_integer_val_tostring(const as_val * v);
255 
AS_INTEGER
Definition: as_val.h:205
static as_integer * as_integer_fromval(const as_val *v)
Definition: as_integer.h:230
static int64_t as_integer_getorelse(const as_integer *integer, int64_t fallback)
Definition: as_integer.h:189
static void as_integer_destroy(as_integer *integer)
Definition: as_integer.h:176
#define as_util_fromval(object, type_id, type)
Definition: as_util.h:38
static int64_t as_integer_toint(const as_integer *integer)
Definition: as_integer.h:208
uint32_t as_integer_val_hashcode(const as_val *v)
as_integer * as_integer_new(int64_t value)
Definition: as_val.h:51
as_val _
Definition: as_integer.h:106
int64_t value
Definition: as_integer.h:111
char * as_integer_val_tostring(const as_val *v)
void as_integer_val_destroy(as_val *v)
as_integer * as_integer_init(as_integer *integer, int64_t value)
#define as_val_destroy(__v)
Definition: as_val.h:104
static int64_t as_integer_get(const as_integer *integer)
Definition: as_integer.h:198
static as_val * as_integer_toval(const as_integer *i)
Definition: as_integer.h:221