1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
//
// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
/**
* @file FLocCoordinates.h
* @brief This is the header file for the %Coordinates class.
*
* This header file contains the declarations of the %Coordinates class.
*/
#ifndef _FLOC_COORDINATES_H_
#define _FLOC_COORDINATES_H_
#include <FBaseObject.h>
#include <FLocTypes.h>
namespace Tizen { namespace Base
{
class String;
}}
namespace Tizen { namespace Locations
{
/**
* @class Coordinates
* @brief This class represents a geographical point.
*
* @since 2.0
*
* @final This class is not intended for extension.
*
* The %Coordinates class represents a geographical point specified by latitude, longitude, and altitude values and provides
* geographic calculations between two points.
*
* The latitude and longitude in decimal degrees are sometimes represented in degrees, minutes, and seconds format. For example, 40.1874 degrees
* can also be represented in "40:11.25"(40 degrees and 11.25 minutes) or "40:11:15.0" (40 degrees, 11 minutes and 15.0 seconds).
* This class provides methods for converting a coordinate value to degrees and minutes or degrees, minutes, and seconds representation.
*/
class _OSP_EXPORT_ Coordinates
: public Tizen::Base::Object
{
public:
/**
* Initializes an instance of %Coordinates with the values of latitude, longitude, and altitude to Not-a-Number. @n
* An application should set values of the coordinates using Set() method to specify it.
*
* @since 2.0
*/
Coordinates(void);
/**
* Copying of objects using this copy constructor is allowed.
*
* @since 2.0
*
* @param[in] rhs An instance of %Coordinates to copy
*/
Coordinates(const Coordinates& rhs);
/**
* This destructor overrides Tizen::Base::Object::~Object().
*
* @since 2.0
*/
virtual ~Coordinates(void);
/**
* Compares the calling instance with the specified instance for equality.
*
* @since 2.0
*
* @return @c true if all the fields in the objects are equal, @n
* else @c false
* @param[in] rhs The object to compare
*/
virtual bool Equals(const Tizen::Base::Object& rhs) const;
/**
* Gets the hash value of the calling instance.
*
* @since 2.0
*
* @return The hash value of the calling instance
*/
virtual int GetHashCode(void) const;
/**
* Sets the latitude, longitude, and altitude values of the coordinates. @n
* An application should specify latitude and longitude values in the valid ranges of [-90.0, +90.0] and [-180.0, +180.0], respectively. @n
* Otherwise, the %Set() method returns an @c E_INVALID_ARG exception.
*
* @since 2.0
*
* @return An error code
* @param[in] latitude The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0]
* @param[in] longitude The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0]
* @param[in] altitude The altitude of the coordinates in meters
* @exception E_SUCCESS This method is successful.
* @exception E_INVALID_ARG The specified @c latitude or @c longitude is invalid.
* @see GetLatitude()
* @see GetLongitude()
* @see GetAltitude()
*/
result Set(double latitude, double longitude, double altitude);
/**
* Sets the latitude value of the coordinates. @n
* An application should specify latitude value in the valid range of [-90.0, +90.0]. @n
* Otherwise, the %SetLatitude() method returns an @c E_INVALID_ARG exception.
*
* @since 2.0
*
* @return An error code
* @param[in] latitude The latitude of the coordinates in decimal degrees within the range [-90.0, +90.0]
* @exception E_SUCCESS This method is successful.
* @exception E_INVALID_ARG The specified @c latitude is invalid.
* @see GetLatitude()
*/
result SetLatitude(double latitude);
/**
* Sets the longitude value of the coordinates. @n
* An application should specify longitude value in the valid range of [-180.0, +180.0]. @n
* Otherwise, the %SetLongitude() method returns an @c E_INVALID_ARG exception.
*
* @since 2.0
*
* @return An error code
* @param[in] longitude The longitude of the coordinates in decimal degrees within the range [-180.0, +180.0]
* @exception E_SUCCESS This method is successful.
* @exception E_INVALID_ARG The specified @c longitude is invalid.
* @see GetLongitude()
*/
result SetLongitude(double longitude);
/**
* Sets the altitude value of the coordinates.
*
* @since 2.0
*
* @param[in] altitude The altitude of the coordinates in meters
* @see GetAltitude()
*/
void SetAltitude(double altitude);
/**
* Gets the latitude value of the coordinates.
*
* @since 2.0
*
* @return The latitude in decimal degrees within the range [-90.0, +90.0], @n
* else @c NaN if it is not available
* @see SetLatitude()
*/
double GetLatitude(void) const;
/**
* Gets the longitude value of the coordinates.
*
* @since 2.0
*
* @return The longitude in decimal degrees within the range [-180.0, +180.0], @n
* else @c NaN if it is not available
* @see SetLongitude()
*/
double GetLongitude(void) const;
/**
* Gets the altitude value of the coordinates.
*
* @since 2.0
*
* @return The altitude in meters, @n
* else @c NaN if it is not available
* @see SetAltitude()
*/
double GetAltitude(void) const;
/**
* Calculates the azimuth value. @n
* The coordinates are the starting point and @c dest is the destination for the azimuth calculation. @n
* The azimuth is measured clockwise from true north based on the WGS84 ellipsoid model. @n
* The altitude value is not considered in calculation.
*
* @since 2.0
*
* @return The azimuth value in decimal degrees within the range [0.0, +360.0], @n
* else @c NaN if the latitude or the longitude of two points has an @c NaN value
* @param[in] dest The destination coordinates
*/
double GetAzimuth(const Coordinates& dest) const;
/**
* Calculates the geodetic distance for the given coordinates. @n
* The distance calculation is based on the WGS84 ellipsoid model. @n
* The altitude value is not considered in calculation.
*
* @since 2.0
*
* @return The distance for the given coordinates in meters, @n
* else @c NaN if the latitude or the longitude of two points has an @c NaN value
* @param[in] to The destination coordinates
*/
double GetDistanceTo(const Coordinates& to) const;
/**
* Converts the coordinate value into string. @n
* An application specifies formats like @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND for the result string.
*
* @since 2.0
*
* @return An error code
* @param[in] degree The coordinate in degrees within the range [-180.0, +180.0]
* @param[in] format The desired format
* @param[out] string The converted result in string
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c degree or @c format is invalid.
* @see Parse()
*/
static result ToString(double degree, CoordinateFormat format, Tizen::Base::String& string);
/**
* Converts a string into coordinate degree. @n
* The @c string should be in @c COORDINATE_FORMAT_DEGREE_MINUTE or @c COORDINATE_FORMAT_DEGREE_MINUTE_SECOND format.
*
* @since 2.0
*
* @return An error code
* @param[in] string The string in degree-minute or degree-minute-second representation
* @param[out] degree The converted result in decimal degrees
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c string is not in CoordinateFormat.
* @see ToString()
*/
static result Parse(const Tizen::Base::String& string, double& degree);
/**
* Copying of objects using this copy assignment operator is allowed.
*
* @since 2.0
*
* @return A reference to the current instance
* @param[in] rhs An instance of %Coordinates to assign
*/
Coordinates& operator =(const Coordinates& rhs);
private:
double __latitude;
double __longitude;
double __altitude;
class _CoordinatesImpl* __pImpl;
friend class _CoordinatesImpl;
}; // Coordinates
}} // Tizen::Locations
#endif // _FLOC_COORDINATES_H_
|
