Merge "Update deprecated libprivilege-control API functions." into tizen
[platform/framework/native/appfw.git] / inc / FBaseInteger.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16
17 /**
18  * @file                FBaseInteger.h
19  * @brief               This is the header file for the %Integer class.
20  *
21  * @see                 Number() class()
22  *
23  * This header file contains the declarations of the %Integer class.
24  */
25 #ifndef _FBASE_INTEGER_H_
26 #define _FBASE_INTEGER_H_
27
28 #include <FBaseNumber.h>
29
30 namespace Tizen { namespace Base
31 {
32 /**
33  *      @class  Integer
34  *      @brief  This class is the wrapper class for the @c signed @c int built-in type.
35  *
36  *      @since 2.0
37  *
38  *      The %Integer class represents an integer value ranging from -2147483648 to 2147483647,
39  *      that is, -(2^31) to +((2^31)-1). This class is useful when passing a 32-bit @c signed
40  *      integral value to a method that accepts only an instance of Object. Furthermore,
41  *      this class provides methods for converting %Integer (and @c int) to String, and %String
42  *      to %Integer (and @c int).
43  *
44  * The following example demonstrates how to use the %Integer class.
45  *
46  *      @code
47  *
48  *      #include <FBase.h>
49  *
50  *      using namespace Tizen::Base;
51  *
52  *      // This method checks whether the given string object contains a string
53  *      // representation of the pre-defined minimum 32-bit integral value.
54  *      result
55  *      MyClass::Verify(String& string, bool& out)
56  *      {
57  *              static const Integer MINIMUM(1230);
58  *
59  *              result r = E_SUCCESS;
60  *
61  *              int i;
62  *              r = Integer::Parse(string, i);
63  *              if (IsFailed(r))
64  *              {
65  *                      goto CATCH;
66  *              }
67  *
68  *              out = (MINIMUM.CompareTo(i) == 0) ? true: false;
69  *
70  *              return r;
71  *      CATCH:
72  *              return r;
73  *      }
74  *      @endcode
75  */
76 class _OSP_EXPORT_ Integer
77         : public Number
78 {
79 public:
80         /**
81          *      Initializes this instance of %Integer with the specified value.
82          *
83          *      @since 2.0
84          *
85          *  @param[in]  value   An integer value
86          */
87         Integer(int value = 0);
88
89         /**
90          *      Copying of objects using this copy constructor is allowed.
91          *
92          *      @since 2.0
93          *
94          *      @param[in]      value   An instance of %Integer
95          */
96         Integer(const Integer& value);
97
98         /**
99          *      This destructor overrides Tizen::Base::Object::~Object().
100          *
101          *      @since 2.0
102          */
103         virtual ~Integer(void);
104
105         /**
106          *      Copying of objects using this copy assignment operator is allowed.
107          *
108          *      @since 2.0
109          *
110          *  @param[in]  rhs     An instance of %Integer
111          */
112         Integer& operator =(const Integer& rhs);
113
114         /**
115          *      Compares two @c int values.
116          *
117          *      @since 2.0
118          *
119          *      @return         A 32-bit @c signed integer value
120          *      @code
121          *      <  0  if the value of @c i1 is less than the value of @c i2
122          *      == 0  if the value of @c i1 is equal to the value of @c i2
123          *      >  0  if the value of @c i1 is greater than the value of @c i2
124          *      @endcode
125          *      @param[in]      i1      The first @c int value to compare
126          *      @param[in]      i2      The second @c int value to compare
127          */
128         static int Compare(int i1, int i2);
129
130         /**
131          *      Compares the value of the current instance with the value of the specified instance of the %Integer class.
132          *
133          *      @since 2.0
134          *
135          *      @return A 32-bit @c signed integer value
136          *
137          *      @code
138          *      <  0  if the value of the current instance is less than the value of the specified instance
139          *      == 0  if the value of the current instance is equal to the value of the specified instance
140          *      >  0  if the value of the current instance is greater than the value of the specified instance
141          *      @endcode
142          *      @param[in]      value   An instance of the %Integer class to compare
143          */
144         int CompareTo(const Integer& value) const;
145
146         /**
147          *      Checks whether the value of the specified instance of Object is equal to the value of the current instance of %Integer.
148          *
149          *      @since 2.0
150          *
151          *      @return         @c true if the value of the specified instance of Object is equal to the value of the current instance of %Integer, @n
152          *                              else @c false
153          *      @param[in]      obj An instance of Object to compare
154          *      @see            Tizen::Base::Object::Equals()
155          */
156         virtual bool Equals(const Object& obj) const;
157
158         /**
159          *      Decodes a string into a @c signed @c int.
160          *
161          *      @since 2.0
162          *
163          *      @return         An error code
164          *      @param[in]      s               A string representing the numeric value
165          *      @param[out]     ret             The result of the operation
166          *      @exception      E_SUCCESS       The method is successful.
167          *      @exception      E_NUM_FORMAT    The specified string does not contain a number that can be parsed.
168          *      @exception      E_OUT_OF_RANGE  The decoded value is not between VALUE_MIN and VALUE_MAX range.
169          *
170          *      @remarks        
171          *                      - This method guarantees that the original value of out-parameter is not changed when the method returns error.
172          *                      - This method accepts decimal, hexadecimal, and octal numbers given by the
173          *                              following grammar:
174          *      @code
175          *      - DecodableString:
176          *              Sign[opt] DecimalNumeral
177          *              Sign[opt] 0x HexDigits
178          *              Sign[opt] 0X HexDigits
179          *              Sign[opt] # HexDigits
180          *              Sign[opt] 0 OctalDigits
181          *      - Sign:
182          *              '-'
183          *      @endcode
184          */
185         static result Decode(const String& s, int& ret);
186
187         /**
188          *      Gets the hash value of the current instance of %Integer.
189          *
190          *      @since 2.0
191          *
192          *      @return         An integer value indicating the hash value of the current instance of %Integer
193          *      @remarks        Two equal instances must return the same hash value. For better performance,
194          *                              the used hash function must generate a random distribution for all inputs. @n
195          *                              The default implementation of this method returns the value of the current instance.
196          */
197         virtual int GetHashCode(void) const;
198
199         /**
200         *        Gets the hash value of the specified @c int value.
201         *
202         *        @since 2.0
203         *
204         *        @return        An integer value indicating the hash value of the specified @c int value
205         *        @param[in]   val   A @c int value to get the hash value
206         */
207         static int GetHashCode(int val);
208
209         /**
210          *      Parses the @c signed @c int equivalent of the specified string representing a numeric value.
211          *
212          *      @since 2.0
213          *
214          *      @return         An error code
215          *      @param[in]      s                               A string representing a numeric value
216          *      @param[out]     ret                             The result of the operation
217          *      @exception      E_SUCCESS       The method is successful.
218          *      @exception      E_NUM_FORMAT    The specified string does not contain a number that can be parsed.
219          *      @exception      E_OUT_OF_RANGE  The parsed value is not between VALUE_MIN and VALUE_MAX range.
220          *
221          *      @remarks
222          *                              - This method assumes that the string representing the numeric value uses a radix 10.
223          *                              - This method guarantees that the original value of out-parameter is not changed when the method returns error.
224          */
225         static result Parse(const String& s, int& ret);
226
227         /**
228          *      Parses the @c signed @c int equivalent of the specified string representing a numeric value using the specified radix.
229          *
230          *      @since 2.0
231          *
232          *      @return         An error code
233          *      @param[in]      s                               A string representing a numeric value
234          *      @param[in]      radix                   The radix of the string representing the numeric value @n
235          *                                              Radix value range is from 2 to 36.
236          *      @param[out]     ret                             The result of the operation
237          *      @exception      E_SUCCESS       The method is successful.
238          *      @exception      E_NUM_FORMAT    The specified string does not contain a number that can be parsed.
239          *      @exception      E_OUT_OF_RANGE  The specified @c radix is invalid or
240          *                                      The parsed value is not between VALUE_MIN and VALUE_MAX range.
241          *
242          *      @remarks        This method guarantees that the original value of out-parameter is not changed when the method returns error.
243          */
244         static result Parse(const String& s, int radix, int& ret);
245
246         /**
247          *      Gets the @c char equivalent of the current instance of the %Integer class.
248          *
249          *      @since 2.0
250          *      @brief  <i> [Deprecated] </i>
251          *
252          *      @deprecated     This method has portability issue.
253          *                      Return value may not be @c signed @c char since char is treated as unsigned char in ARM architecture. @n
254          *                      Use ToInt8() method to get @c int8_t
255          *
256          *      @return         A @c char equivalent of the current instance
257          *
258          */
259         virtual char ToChar(void) const;
260
261         /**
262          *      Gets the @c int8_t equivalent of the current instance of %Integer.
263          *
264          *      @since 3.0
265          *
266          *      @return The @c int8_t equivalent of the current instance
267          *
268          */
269         virtual int8_t ToInt8(void) const;
270
271         /**
272          *      Gets the @c signed @c short equivalent of the current instance of the %Integer class.
273          *
274          *      @since 2.0
275          *
276          *      @return         A @c signed @c short equivalent of the current instance
277          */
278         virtual short ToShort(void) const;
279
280         /**
281          *      Gets the @c signed @c int equivalent of the current instance of the %Integer class.
282          *
283          *      @since 2.0
284          *
285          *      @return         A @c signed @c int equivalent of the current instance
286          */
287         virtual int ToInt(void) const;
288
289         /**
290          *      Gets the @c signed @c long equivalent of the current instance of the %Integer class.
291          *
292          *      @since 2.0
293          *
294          *      @return         A @c signed @c long equivalent of the current instance
295          */
296         virtual long ToLong(void) const;
297
298         /**
299          *      Gets the @c signed @c long @c long equivalent of the current instance of the %Integer class.
300          *
301          *      @since 2.0
302          *
303          *      @return         A @c signed @c long @c long equivalent of the current instance
304          */
305         virtual long long ToLongLong(void) const;
306
307         /**
308          *      Gets the @c signed @c float equivalent of the current instance of the %Integer class.
309          *
310          *      @since 2.0
311          *
312          *      @return         A @c signed @c float equivalent of the current instance
313          */
314         virtual float ToFloat(void) const;
315
316         /**
317          *      Gets the @c signed @c double equivalent of the current instance of the %Integer class.
318          *
319          *      @since 2.0
320          *
321          *      @return         A @c signed @c double equivalent of the current instance
322          */
323         virtual double ToDouble(void) const;
324
325         /**
326          *      Gets the string representing the value of the current instance of the %Integer class.
327          *
328          *      @since 2.0
329          *
330          *      @return         A string representing the value of the current instance
331          */
332         virtual String ToString(void) const;
333
334         /**
335          *      Gets the string representing the specified @c signed @c int value.
336          *
337          *      @since 2.0
338          *
339          *      @return         A string containing a Unicode representation of the specified @c signed @c int value
340          *      @param[in]      value   A @c signed @c int value to convert
341          */
342         static String ToString(int value);
343
344         /**
345          *      A constant holding the maximum value of type @c int. @n
346          *  A @c short integer can hold a value of upto 2^31-1.
347          *
348          *      @since 2.0
349          */
350         static const int VALUE_MAX = static_cast< int >(0x7FFFFFFF);
351
352         /**
353          *      A constant holding the minimum value of type @c int. @n
354          *  A @c short integer can hold a value of upto -2^31.
355          *
356          *      @since 2.0
357          */
358         static const int VALUE_MIN = static_cast< int >(0x80000000);
359
360         /**
361          * An integer value of this instance.
362          *
363          * @since 2.0
364          */
365         int value;
366
367
368 private:
369         friend class _IntegerImpl;
370         class _IntegerImpl* __pIntegerImpl;
371
372 }; // Integer
373
374 }} //Tizen::Base
375
376 #endif //_FBASE_INTEGER_H_