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