git.gag.com Git - debian/gnuradio/blob - pmt/src/lib/pmt.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2006 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with GNU Radio; see the file COPYING.  If not, write to
  19  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #ifndef INCLUDED_PMT_H
  24 #define INCLUDED_PMT_H
  25
  26 #include <boost/shared_ptr.hpp>
  27 #include <complex>
  28 #include <string>
  29 #include <stdint.h>
  30 #include <iostream>
  31
  32 /*!
  33  * This file defines a polymorphic type and the operations on it.
  34  *
  35  * It draws heavily on the idea of scheme and lisp data types.
  36  * The interface parallels that in Guile 1.8, with the notable
  37  * exception that these objects are transparently reference counted.
  38  */
  39
  40 /*!
  41  * \brief base class of all pmt types
  42  */
  43 class pmt_base;
  44
  45 /*!
  46  * \brief typedef for shared pointer (transparent reference counting).
  47  * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
  48  */
  49 typedef boost::shared_ptr<pmt_base> pmt_t;
  50
  51
  52 class pmt_exception
  53 {
  54   const char *d_msg;
  55   pmt_t       d_obj;
  56
  57 public:
  58   pmt_exception(const char *msg, pmt_t obj);
  59   const char *msg() { return d_msg; }
  60   pmt_t obj() { return d_obj; }
  61 };
  62
  63 class pmt_wrong_type : public pmt_exception
  64 {
  65 public:
  66   pmt_wrong_type(const char *msg, pmt_t obj);
  67 };
  68
  69 class pmt_out_of_range : public pmt_exception
  70 {
  71 public:
  72   pmt_out_of_range(const char *msg, pmt_t obj);
  73 };
  74
  75 /*
  76  * ------------------------------------------------------------------------
  77  * Booleans.  Two constants, #t and #f.
  78  *
  79  * In predicates, anything that is not #f is considered true.
  80  * I.e., there is a single false value, #f.
  81  * ------------------------------------------------------------------------
  82  */
  83 extern const pmt_t PMT_BOOL_T;  //< #t : boolean true constant
  84 extern const pmt_t PMT_BOOL_F;  //< #f : boolean false constant
  85
  86 //! Return true if obj is #t or #f, else return false.
  87 bool pmt_is_bool(pmt_t obj);
  88
  89 //! Return false if obj is #f, else return true.
  90 bool pmt_is_true(pmt_t obj);
  91
  92 //! Return true if obj is #f, else return true.
  93 bool pmt_is_false(pmt_t obj);
  94
  95 //! Return #f is val is false, else return #t.
  96 pmt_t pmt_from_bool(bool val);
  97
  98 //! Return true if val is PMT_BOOL_T, return false when val is PMT_BOOL_F,
  99 // else raise wrong_type exception.
 100 bool pmt_to_bool(pmt_t val);
 101
 102 /*
 103  * ------------------------------------------------------------------------
 104  *                             Symbols
 105  * ------------------------------------------------------------------------
 106  */
 107
 108 //! Return true if obj is a symbol, else false.
 109 bool pmt_is_symbol(pmt_t obj);
 110
 111 //! Return the symbol whose name is \p s.
 112 pmt_t pmt_string_to_symbol(const std::string &s);
 113
 114 /*!
 115  * If \p is a symbol, return the name of the symbol as a string.
 116  * Otherwise, raise the wrong_type exception.
 117  */
 118 const std::string pmt_symbol_to_string(pmt_t sym);
 119
 120 /*
 121  * ------------------------------------------------------------------------
 122  *           Numbers: we support integer, real and complex
 123  * ------------------------------------------------------------------------
 124  */
 125
 126 //! Return true if obj is any kind of number, else false.
 127 bool pmt_is_number(pmt_t obj);
 128
 129 /*
 130  * ------------------------------------------------------------------------
 131  *                             Integers
 132  * ------------------------------------------------------------------------
 133  */
 134
 135 //! Return true if \p x is an integer number, else false
 136 bool pmt_is_integer(pmt_t x);
 137
 138 //! Return the pmt value that represents the integer \p x.
 139 pmt_t pmt_from_long(long x);
 140
 141 /*!
 142  * \brief Convert pmt to long if possible.
 143  *
 144  * When \p x represents an exact integer that fits in a long,
 145  * return that integer.  Else raise an exception, either wrong_type
 146  * when x is not an exact integer, or out_of_range when it doesn't fit.
 147  */
 148 long pmt_to_long(pmt_t x);
 149
 150 /*
 151  * ------------------------------------------------------------------------
 152  *                              Reals
 153  * ------------------------------------------------------------------------
 154  */
 155
 156 /*
 157  * \brief Return true if \p obj is a real number, else false.
 158  */
 159 bool pmt_is_real(pmt_t obj);
 160
 161 //! Return the pmt value that represents double \p x.
 162 pmt_t pmt_from_double(double x);
 163
 164 /*!
 165  * \brief Convert pmt to double if possible.
 166  *
 167  * Returns the number closest to \p val that is representable
 168  * as a double.  The argument \p val must be a real or integer, otherwise
 169  * a wrong_type exception is raised.
 170  */
 171 double pmt_to_double(pmt_t x);
 172
 173 /*
 174  * ------------------------------------------------------------------------
 175  *                             Complex
 176  * ------------------------------------------------------------------------
 177  */
 178
 179 /*!
 180  * \brief return true if \p obj is a complex number, false otherwise.
 181  */
 182 bool pmt_is_complex(pmt_t obj);
 183
 184 //! Return a complex number constructed of the given real and imaginary parts.
 185 pmt_t pmt_make_rectangular(double re, double im);
 186
 187 /*!
 188  * If \p z is complex, real or integer, return the closest complex<double>.
 189  * Otherwise, raise the wrong_type exception.
 190  */
 191 std::complex<double> pmt_to_complex(pmt_t z);
 192
 193 /*
 194  * ------------------------------------------------------------------------
 195  *                              Pairs
 196  * ------------------------------------------------------------------------
 197  */
 198
 199 extern const pmt_t PMT_NIL;     //< the empty list
 200
 201 //! Return true if \p x is the empty list, otherwise return false.
 202 bool pmt_is_null(pmt_t x);
 203
 204 //! Return true if \p obj is a pair, else false.
 205 bool pmt_is_pair(pmt_t obj);
 206
 207 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
 208 pmt_t pmt_cons(pmt_t x, pmt_t y);
 209
 210 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
 211 pmt_t pmt_car(pmt_t pair);
 212
 213 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
 214 pmt_t pmt_cdr(pmt_t pair);
 215
 216 //! Stores \p value in the car field of \p pair.
 217 void pmt_set_car(pmt_t pair, pmt_t value);
 218
 219 //! Stores \p value in the cdr field of \p pair.
 220 void pmt_set_cdr(pmt_t pair, pmt_t value);
 221
 222 /*
 223  * ------------------------------------------------------------------------
 224  *                             Vectors
 225  *
 226  * These vectors can hold any kind of objects.  Indexing is zero based.
 227  * ------------------------------------------------------------------------
 228  */
 229
 230 //! Return true if \p x is a vector, othewise false.
 231 bool pmt_is_vector(pmt_t x);
 232
 233 //! Make a vector of length \p k, with initial values set to \p fill
 234 pmt_t pmt_make_vector(size_t k, pmt_t fill);
 235
 236 /*!
 237  * Return the contents of position \p k of \p vector.
 238  * \p k must be a valid index of \p vector.
 239  */
 240 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
 241
 242 //! Store \p obj in position \p k.
 243 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
 244
 245 //! Store \p fill in every position of \p vector
 246 void pmt_vector_fill(pmt_t vector, pmt_t fill);
 247
 248 /*!
 249  * <pre>
 250  * ------------------------------------------------------------------------
 251  *                     Uniform Numeric Vectors
 252  *
 253  * A uniform numeric vector is a vector whose elements are all of single
 254  * numeric type.  pmt offers uniform numeric vectors for signed and
 255  * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
 256  * floating point values, and complex floating-point numbers of these
 257  * two sizes.  Indexing is zero based.
 258  *
 259  * The names of the functions include these tags in their names:
 260  *
 261  *    u8  unsigned 8-bit integers
 262  *    s8  signed 8-bit integers
 263  *   u16  unsigned 16-bit integers
 264  *   s16  signed 16-bit integers
 265  *   u32  unsigned 32-bit integers
 266  *   s32  signed 32-bit integers
 267  *   u64  unsigned 64-bit integers
 268  *   s64  signed 64-bit integers
 269  *   f32  the C++ type float
 270  *   f64  the C++ type double
 271  *   c32  the C++ type complex<float>
 272  *   c64  the C++ type complex<double>
 273  * ------------------------------------------------------------------------
 274  * </pre>
 275  */
 276
 277 //! true if \p x is any kind of uniform numeric vector
 278 bool pmt_is_uniform_vector(pmt_t x);
 279
 280 bool pmt_is_u8vector(pmt_t x);
 281 bool pmt_is_s8vector(pmt_t x);
 282 bool pmt_is_u16vector(pmt_t x);
 283 bool pmt_is_s16vector(pmt_t x);
 284 bool pmt_is_u32vector(pmt_t x);
 285 bool pmt_is_s32vector(pmt_t x);
 286 bool pmt_is_u64vector(pmt_t x);
 287 bool pmt_is_s64vector(pmt_t x);
 288 bool pmt_is_f32vector(pmt_t x);
 289 bool pmt_is_f64vector(pmt_t x);
 290 bool pmt_is_c32vector(pmt_t x);
 291 bool pmt_is_c64vector(pmt_t x);
 292
 293 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
 294 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
 295 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
 296 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
 297 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
 298 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
 299 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
 300 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
 301 pmt_t pmt_make_f32vector(size_t k, float fill);
 302 pmt_t pmt_make_f64vector(size_t k, double fill);
 303 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
 304 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
 305
 306 pmt_t pmt_init_u8vector(size_t k, uint8_t *data);
 307 pmt_t pmt_init_s8vector(size_t k, int8_t *data);
 308 pmt_t pmt_init_u16vector(size_t k, uint16_t *data);
 309 pmt_t pmt_init_s16vector(size_t k, int16_t *data);
 310 pmt_t pmt_init_u32vector(size_t k, uint32_t *data);
 311 pmt_t pmt_init_s32vector(size_t k, int32_t *data);
 312 pmt_t pmt_init_u64vector(size_t k, uint64_t *data);
 313 pmt_t pmt_init_s64vector(size_t k, int64_t *data);
 314 pmt_t pmt_init_f32vector(size_t k, float *data);
 315 pmt_t pmt_init_f64vector(size_t k, double *data);
 316 pmt_t pmt_init_c32vector(size_t k, std::complex<float> *data);
 317 pmt_t pmt_init_c64vector(size_t k, std::complex<double> *data);
 318
 319 uint8_t  pmt_u8vector_ref(pmt_t v, size_t k);
 320 int8_t   pmt_s8vector_ref(pmt_t v, size_t k);
 321 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
 322 int16_t  pmt_s16vector_ref(pmt_t v, size_t k);
 323 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
 324 int32_t  pmt_s32vector_ref(pmt_t v, size_t k);
 325 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
 326 int64_t  pmt_s64vector_ref(pmt_t v, size_t k);
 327 float    pmt_f32vector_ref(pmt_t v, size_t k);
 328 double   pmt_f64vector_ref(pmt_t v, size_t k);
 329 std::complex<float>  pmt_c32vector_ref(pmt_t v, size_t k);
 330 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
 331
 332 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x);  //< v[k] = x
 333 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
 334 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
 335 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
 336 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
 337 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
 338 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
 339 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
 340 void pmt_f32vector_set(pmt_t v, size_t k, float x);
 341 void pmt_f64vector_set(pmt_t v, size_t k, double x);
 342 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
 343 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
 344
 345 // Return const pointers to the elements
 346
 347 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 348
 349 const uint8_t  *pmt_u8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 350 const int8_t   *pmt_s8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 351 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
 352 const int16_t  *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
 353 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
 354 const int32_t  *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
 355 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
 356 const int64_t  *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
 357 const float    *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
 358 const double   *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
 359 const std::complex<float>  *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
 360 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
 361
 362 // Return non-const pointers to the elements
 363
 364 void *pmt_uniform_vector_writeable_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 365
 366 uint8_t  *pmt_u8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
 367 int8_t   *pmt_s8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
 368 uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 369 int16_t  *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 370 uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 371 int32_t  *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 372 uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 373 int64_t  *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 374 float    *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 375 double   *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 376 std::complex<float>  *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 377 std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 378
 379 /*
 380  * ------------------------------------------------------------------------
 381  *         Dictionary (a.k.a associative array, hash, map)
 382  * ------------------------------------------------------------------------
 383  */
 384
 385 //! Return true if \p obj is a dictionary
 386 bool pmt_is_dict(pmt_t obj);
 387
 388 //! make an empty dictionary
 389 pmt_t pmt_make_dict();
 390
 391 //! dict[key] = value
 392 void  pmt_dict_set(pmt_t dict, pmt_t key, pmt_t value);
 393
 394 //! Return true if \p key exists in \p dict
 395 bool  pmt_dict_has_key(pmt_t dict, pmt_t key);
 396
 397 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
 398 pmt_t pmt_dict_ref(pmt_t dict, pmt_t key, pmt_t not_found);
 399
 400 //! Return list of (key . value) pairs
 401 pmt_t pmt_dict_items(pmt_t dict);
 402
 403 //! Return list of keys
 404 pmt_t pmt_dict_keys(pmt_t dict);
 405
 406 //! Return list of values
 407 pmt_t pmt_dict_values(pmt_t dict);
 408
 409 /*
 410  * ------------------------------------------------------------------------
 411  *                        General functions
 412  * ------------------------------------------------------------------------
 413  */
 414
 415 //! Return true if x and y are the same object; otherwise return false.
 416 bool pmt_eq(pmt_t x, pmt_t y);
 417
 418 /*!
 419  * \brief Return true if x and y should normally be regarded as the same object, else false.
 420  *
 421  * <pre>
 422  * eqv returns true if:
 423  *   x and y are the same object.
 424  *   x and y are both #t or both #f.
 425  *   x and y are both symbols and their names are the same.
 426  *   x and y are both numbers, and are numerically equal.
 427  *   x and y are both the empty list (nil).
 428  *   x and y are pairs or vectors that denote same location in store.
 429  * </pre>
 430  */
 431 bool pmt_eqv(pmt_t x, pmt_t y);
 432
 433 /*!
 434  * pmt_equal recursively compares the contents of pairs and vectors,
 435  * applying pmt_eqv on other objects such as numbers and symbols.
 436  * pmt_equal may fail to terminate if its arguments are circular data
 437  * structures.
 438  */
 439 bool pmt_equal(pmt_t x, pmt_t y);
 440
 441
 442 //! Return the number of elements in v
 443 size_t pmt_length(pmt_t v);
 444
 445 /*!
 446  * \brief Find the first pair in \p alist whose car field is \p obj
 447  *  and return that pair.
 448  *
 449  * \p alist (for "association list") must be a list of pairs.  If no pair
 450  * in \p alist has \p obj as its car then #f is returned.
 451  * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
 452  */
 453 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
 454
 455 /*!
 456  * \brief Find the first pair in \p alist whose car field is \p obj
 457  *  and return that pair.
 458  *
 459  * \p alist (for "association list") must be a list of pairs.  If no pair
 460  * in \p alist has \p obj as its car then #f is returned.
 461  * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
 462  */
 463 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
 464
 465 /*!
 466  * \brief Find the first pair in \p alist whose car field is \p obj
 467  *  and return that pair.
 468  *
 469  * \p alist (for "association list") must be a list of pairs.  If no pair
 470  * in \p alist has \p obj as its car then #f is returned.
 471  * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
 472  */
 473 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
 474
 475 /*!
 476  * \brief Apply \p proc element-wise to the elements of list and returns
 477  * a list of the results, in order.
 478  *
 479  * \p list must be a list.  The dynamic order in which \p proc is
 480  * applied to the elements of \p list is unspecified.
 481  */
 482 pmt_t pmt_map(pmt_t proc(pmt_t), pmt_t list);
 483
 484 /*!
 485  * \brief reverse \p list.
 486  *
 487  * \p list must be a proper list.
 488  */
 489 pmt_t pmt_reverse(pmt_t list);
 490
 491 /*!
 492  * \brief destructively reverse \p list.
 493  *
 494  * \p list must be a proper list.
 495  */
 496 pmt_t pmt_reverse_x(pmt_t list);
 497
 498 /*!
 499  * \brief (acons x y a) == (cons (cons x y) a)
 500  */
 501 inline static pmt_t
 502 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
 503 {
 504   return pmt_cons(pmt_cons(x, y), a);
 505 }
 506
 507 /*
 508  * ------------------------------------------------------------------------
 509  *                           read / write
 510  * ------------------------------------------------------------------------
 511  */
 512 extern const pmt_t PMT_EOF;     //< The end of file object
 513
 514 //! return true if obj is the EOF object, otherwise return false.
 515 bool pmt_is_eof_object(pmt_t obj);
 516
 517 /*!
 518  * read converts external representations of pmt objects into the
 519  * objects themselves.  Read returns the next object parsable from
 520  * the given input port, updating port to point to the first
 521  * character past the end of the external representation of the
 522  * object.
 523  *
 524  * If an end of file is encountered in the input before any
 525  * characters are found that can begin an object, then an end of file
 526  * object is returned.   The port remains open, and further attempts
 527  * to read will also return an end of file object.  If an end of file
 528  * is encountered after the beginning of an object's external
 529  * representation, but the external representation is incomplete and
 530  * therefore not parsable, an error is signaled.
 531  */
 532 pmt_t pmt_read(std::istream &port);
 533
 534 /*!
 535  * Write a written representation of \p obj to the given \p port.
 536  */
 537 void pmt_write(pmt_t obj, std::ostream &port);
 538
 539 /*
 540  * ------------------------------------------------------------------------
 541  *                    portable byte stream representation
 542  * ------------------------------------------------------------------------
 543  */
 544 /*!
 545  * \brief Write portable byte-serial representation of \p obj to \p sink
 546  */
 547 void pmt_serialize(pmt_t obj, std::ostream &sink);
 548
 549 /*!
 550  * \brief Create obj from portable byte-serial representation
 551  */
 552 pmt_t pmt_deserialize(std::istream &source);
 553
 554 #endif /* INCLUDED_PMT_H */