This file is indexed.

/usr/include/x86_64-linux-gnu/Gyoto/GyotoConverters.h is in libgyoto6-dev 1.2.0-4.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
/**
 * \file GyotoConverters.h
 * \brief GYOTO converters
 *
 *  As a (recommended) option, Gyoto can use the libudunits2 library
 *  by UCAR/Unidata
 *  (http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html)
 *  to perform conversions to and from various units. Since udunits
 *  parses units, the following are equivalent for instance:
 *  "mJy.sr-1", "mJy/sr", "1e-3Jy/sr". Gyoto considers every string as
 *  UTF-8: either use UTF-8 or stay with ASCII. This means "µ" can be
 *  used for "micro" and powers can be noted as superscripts: m³,
 *  pix².
 *
 *  In addition to the stock units known by udunits2, Gyoto registers
 *  the following (which may be used in any context): Jansky (symbol
 *  Jy), symbol "pc" for parsec, "sunradius", "sunmass", symbol "as"
 *  for "arcsec".
 *  
 *  Other units are context-sensitive: "geometrical" allows converting
 *  between geometrical units and other legnth units, but only when a
 *  Metric is defined, and may not be used (yet) in compound
 *  units. Likewise, "geometrical_time" can be used as duration unit
 *  whenever a Metric is defined, but not in a compound unit.
 *
 *  When a Screen is defined, "pix" can be used as an angle unit (you
 *  need to call Screen::mapPixUnit() and Screen::unmapScreenUnit(),
 *  which is done automatically in certain contexts).
 *
 *  Units can often be specified using the "unit" XML attribute:
 * \code
 * <Meric kind="KerrBL">
 *    <Mass unit="sunmass">
 *       4e6
 *    </Mass>
 * </Metric>
 * <Screen>
 *    <Distance unit="kpc">
 *       8
 *    </Distance>
 *    <FieldOfView unit="µas">
 *       150
 *    </FieldOfView>
 * </Metric>
 * \endcode
 *
 * Units for output quantities are specified after the name of the
 * quantity, in squared brackets, e.g.:
 * \code
 *   <Quantities>
 *     Spectrum[erg.s-1.cm-2.sr-1.Hz-1]
 *   </Quantities>
 * \endcode
 * or
 * \code
 *   <Quantities>
 *     Spectrum[mJy/pix²]
 *   </Quantities>
 * \endcode
 */

/*
    Copyright 2011-2016 Thibaut Paumard

    This file is part of Gyoto.

    Gyoto is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Gyoto is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Gyoto.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef __GyotoConverters_H_ 
#define __GyotoConverters_H_ 

#include <GyotoUtils.h>
#include <GyotoSmartPointer.h>

#ifdef HAVE_UDUNITS
#include <udunits2.h>
#endif

#include <string>
#include <sstream>

namespace Gyoto {
  namespace Metric {
    class Generic;
  }
  namespace Units {
    /**
     * \namespace Gyoto::Units
     * \brief Units-related classes and functions
     */ 
#ifdef HAVE_UDUNITS
    /**
     * \class Gyoto::Units::Unit
     * \brief Wrapper around ut_unit from udunits
     *
     * Gyoto::Units::Unit objects usually cast seamlessly to and from
     * udunits2 ut_unit* and std::string.
     */
    class Unit;

    /**
     * \class Gyoto::Units::Converter
     * \brief Wrapper around ut_converter from udunits
     *
     * A Gyoto::Units::Converter object is a functor and can be used
     * to convert efficiently between the two units specified at
     * instantiation time:
     *
     * \code
     * Gyoto::Units::Unit from_unit ("erg.s-1.cm-2.sr-1.Hz-1"),
     *                    to_unit   ("mJy/µas²");
     * double data_in[1000], data_out[1000];
     * Converter conv(from_unit, to_unit);
     * for (size_t i=0; i<1000; ++i) data_out[i] = conv(data_in[i]);
     * \endcode
     *
     * Since std::string cast automatically to Gyoto::Units::Unit
     * object, this is equivalent:
     *
     * \code
     * Converter conv("erg.s-1.cm-2.sr-1.Hz-1", "mJy/µas²");
     * for (size_t i=0; i<1000; ++i) data_out[i] = conv(data_in[i]);
     * \endcode
     */
    class Converter;

    /**
     * \brief Retrieve the unit system used in all of Gyoto
     */
    ut_system * getSystem();
#endif

    /**
     * \brief Load and initialize all (non-context-sensitive) units
     *
     * If udunits is used (preprocessor macro HAVE_UDUNITS), Init()
     * initializes the ut_system used throughout Gyoto and maps a few
     * additional units to the unit system.
     */
    void Init();

    /**
     * \brief Convert from arbitrary length unit to meters
     *
     * Convert value from unit represented by "unit" to meters.
     *
     * If gg is provided (and not NULL), use it to interpret the
     * string "geometrical" as representing
     * gg->Gyoto::Metric::Generic::unitLength().
     *
     * ToMeters() will also convert time, frequency and energy units
     * to meters (as in frequency -> wavelength).
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit"
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "km", "sunradius" or "geometrical". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &,
     *   NULL if not specified) optional metric to interpret
     *   "geometrical".
     *
     * \return value, expressed in meters.
     */
    double ToMeters(double value, const std::string &unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> &gg=NULL);

    /**
     * \brief Convert to arbitrary length unit from meters
     *
     * Convert value to unit represented by "unit" from meters.
     *
     * If gg is provided (and not NULL), use it to interpret the
     * string "geometrical" as representing
     * gg->Gyoto::Metric::Generic::unitLength().
     *
     * ToMeters() will also convert to time, frequency and energy
     * units (as in wavelength -> frequency).
     *
     * \param value
     *   (double) the value to convert, expressed in meters.
     * \param unit (std::string) the "unit" to which to convert,
     *   e.g. "km", "sunradius" or "geometrical". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &,
     *   NULL if not specified) optional metric to interpret
     *   "geometrical".
     *
     * \return value, expressed in "unit".
     */
    double FromMeters(double value, const std::string &unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> &gg=NULL);

    /**
     * \brief Convert from arbitrary time unit to seconds
     *
     * Convert value from unit represented by "unit" to seconds.
     *
     * If gg is provided (and not NULL), use it to interpret the
     * string "geometrical_time" as representing
     * gg->Gyoto::Metric::Generic::unitLength()/GYOTO_C.
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit"
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "s", "yr" or "geometrical_time". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &,
     *   NULL if not specified) optional metric to interpret
     *   "geometrical".
     *
     * \return value, expressed in seconds.
     */
    double ToSeconds(double value, const std::string &unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> &gg=NULL);

    /**
     * \brief Convert to arbitrary time unit from seconds
     *
     * Convert value to unit represented by "unit" from seconds.
     *
     * If gg is provided (and not NULL), use it to interpret the
     * string "geometrical_time" as representing
     * gg->Gyoto::Metric::Generic::unitLength()/GYOTO_C.
     *
     * \param value
     *   (double) the value to convert, expressed in seconds.
     * \param unit (std::string) the "unit" to which to convert,
     *   e.g. "s", "yr" or "geometrical_time". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &,
     *   NULL if not specified) optional metric to interpret
     *   "geometrical".
     *
     * \return value, expressed in "unit".
     */
    double FromSeconds(double value, const std::string &unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> &gg=NULL);

    /**
     * \brief Convert from arbitrary mass unit to kilograms
     *
     * Convert value from unit represented by "unit" to kilograms.
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit"
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "g", "kg" or "sunmass". More units are
     *   supported if Gyoto was compiled with udunits support.
     *
     * \return value, expressed in kilograms.
     */
    double ToKilograms(double value, const std::string & unit);

    /**
     * \brief Convert to arbitrary mass unit from kilograms
     *
     * Convert value from unit represented by "unit" from kilograms.
     *
     * \param value
     *   (double) the value to convert, expressed inkilograms.
     * \param unit (std::string) the "unit" to which to convert,
     *   e.g. "g", "kg" or "sunmass". More units are
     *   supported if Gyoto was compiled with udunits support.
     *
     * \return value, expressed in "unit".
     */
    double FromKilograms(double value, const std::string & unit);

    /**
     * \brief Convert from arbitrary length unit to geometrical units
     *
     * Convert value from unit represented by "unit" to geometrical units.
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit".
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "km", "sunradius" or "geometrical". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &)
     *   metric to interpret "geometrical".
     *
     * \return value, expressed in geometrical units.
     */
    double ToGeometrical(double value, const std::string & unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> & gg);

    /**
     * \brief Convert to arbitrary length unit from geometrical units
     *
     * Convert value to unit represented by "unit" from geometrical units.
     *
     * \param value
     *   (double) the value to convert, expressed in geometrical units.
     * \param unit (std::string) the "unit" to which to convert,
     *   e.g. "km", "sunradius" or "geometrical". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &)
     *   metric to interpret "geometrical".
     *
     * \return value, expressed in "unit".
     */
    double FromGeometrical(double value, const std::string & unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> & gg);

    /**
     * \brief Convert from arbitrary time unit to geometrical units
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit".
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "s", "kyr" or "geometrical_time". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &)
     *   metric to interpret "geometrical_time".
     *
     * \return value, expressed in geometrical (time) units.
     */
    double ToGeometricalTime(double value, const std::string & unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> & gg);

    /**
     * \brief Convert to arbitrary time unit from geometrical units
     *
     * \param value
     *   (double) the value to convert, expressed in geometrical units.
     * \param unit (std::string) the "unit" to which to convert,
     *   e.g. "yr", "s" or "geometrical_time". More units are
     *   supported if Gyoto was compiled with udunits support.
     * \param gg (const Gyoto::SmartPointer<Gyoto::Metric::Generic> &)
     *   metric to interpret "geometrical_time".
     *
     * \return value, expressed in "unit".
     */
    double FromGeometricalTime(double value, const std::string & unit,
		  const Gyoto::SmartPointer<Gyoto::Metric::Generic> &gg);


    /**
     * \brief Convert from arbitrary frequency unit to Herz
     *
     * ToHerz will also convert from length and energy units (such as
     * "eV").
     *
     * \param value
     *   (double) the value to convert, expressed according to "unit".
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "MHz", "keV"
     *
     * \return value, expressed in "Hz".
     */
    double ToHerz(double value, const std::string &unit);

    /**
     * \brief Convert to arbitrary frequency unit from Herz
     *
     * FromHerz will also convert to length and energy units (such as
     * "eV").
     *
     * \param value
     *   (double) the value to convert, expressed according in "Hz".
     * \param unit (std::string) the "unit" from which to convert,
     *   e.g. "MHz", "keV"
     *
     * \return value, expressed in "units".
     */
    double FromHerz(double value, const std::string &unit);

#   ifdef HAVE_UDUNITS
    /**
     * \brief Is it possible to convert between unit1 and unit2?
     *
     * e.g. areConvertible("m", "kg") == 0; areConvertible("m", "km")==1.
     *
     * Warning: angle units are dimensionless, therefore e.g.
     * areConvertible("Jy", "Jy/microacsec2")==1. Numerically, "Jy" is
     * the same as "Jy/sr2".
     *
     * \param unit1 (Gyoto::Units::Unit) first unit
     * \param unit2 (Gyoto::Units::Unit) second unit
     *
     * \return bool, True if it is possible to convert between the two
     * units, 0 otherwise.
     */
    bool areConvertible(const Unit &unit1, const Unit &unit2);
#   endif
  }
}

#ifdef HAVE_UDUNITS
class Gyoto::Units::Unit : public Gyoto::SmartPointee {
  friend class Gyoto::SmartPointer<Gyoto::Units::Unit>;
  friend class Gyoto::Units::Converter;
 private:
  ut_unit * unit_; ///< the underlying ut_unit (from udunits)
  std::string kind_; ///< the string used to instantiate this unit
 public:

  /**
   * \brief Build Unit described by string
   *
   * Throws a Gyoto::Error if anything goes wrong.
   *
   * \param unit string description of the unit, e.g. "mJy/sr2" or "sunmass".
   */
  Unit(const std::string &unit);

  /**
   * \brief Build Unit described by C string
   *
   * Throws a Gyoto::Error if anything goes wrong.
   *
   * \param unit char const * const description of the unit,
   *        e.g. "mJy/sr2" or "sunmass".
   */
  Unit(char const * const unit);

  /**
   * \brief Destructor
   *
   * Frees unit_.
   */
  ~Unit();

  /**
   * \brief Convert to Unit
   *
   * \param val double to convert
   * \param from_unit Unit from which to convert
   * 
   * \return value converted to unit_.
   */
  double To (double val, const Unit &from_unit);

  /**
   * \brief Convert from Unit
   *
   * \param val double to convert
   * \param to_unit Unit to which to convert
   * 
   * \return value converted to "to_unit".
   */
  double From (double val, const Unit &to_unit);

  /**
   * \brief Cast to string
   *
   * \return kind_
   */
  operator std::string() const ;

  /**
   * \brief Cast to ut_unit*
   *
   * \return unit_
   */
  operator ut_unit*() const ;
};

class Gyoto::Units::Converter : public Gyoto::SmartPointee {
  friend class Gyoto::SmartPointer<Gyoto::Units::Converter>;
 private:
  cv_converter * converter_; ///< Underlying ut_converter object from udunits

 public:
  Converter(); ///< Construct trivial Converter (Converter()(x)==x)
  Converter(const Gyoto::Units::Unit& from,
	    const Gyoto::Units::Unit& to);
  ///< Construct Converter from two Unit
  ~Converter();
  ///< Destruct converter, freeing converter_

  void reset(); ///< Reset to trivial Converter (Converter()(x)==x)
  void reset(const Gyoto::Units::Unit& from,
	const Gyoto::Units::Unit& to);
  ///< Reset to converter from "from" to "to"

  /**
   * \brief Actually convert data
   *
   * The entire Gyoto::Units::Converter class is there just for this
   * operator, which converts value from unit "from" to unit "to"
   * where "from" and "to" are the two Units passed to the constructor
   * Gyoto::Units::Converter::Converter(const Gyoto::Units::Unit&
   * from, const Gyoto::Units::Unit& to).
   *
   * \param value double expressed in Unit from
   *
   * \return converted value expressed in Unit to
   */
  double operator()(double value) const ;
};

#endif

#endif