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

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2006,2009,2010 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 3, 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., 51 Franklin Street,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 #ifndef INCLUDED_PMT_H
  24 #define INCLUDED_PMT_H
  25
  26 #include <boost/intrusive_ptr.hpp>
  27 #include <boost/shared_ptr.hpp>
  28 #include <boost/any.hpp>
  29 #include <complex>
  30 #include <string>
  31 #include <stdint.h>
  32 #include <iosfwd>
  33 #include <stdexcept>
  34
  35 namespace gruel {
  36   class msg_accepter;
  37 };
  38
  39 /*!
  40  * This file defines a polymorphic type and the operations on it.
  41  *
  42  * It draws heavily on the idea of scheme and lisp data types.
  43  * The interface parallels that in Guile 1.8, with the notable
  44  * exception that these objects are transparently reference counted.
  45  */
  46
  47 namespace pmt {
  48
  49 /*!
  50  * \brief base class of all pmt types
  51  */
  52 class pmt_base;
  53
  54 /*!
  55  * \brief typedef for shared pointer (transparent reference counting).
  56  * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
  57  */
  58 typedef boost::intrusive_ptr<pmt_base> pmt_t;
  59
  60 extern void intrusive_ptr_add_ref(pmt_base*);
  61 extern void intrusive_ptr_release(pmt_base*);
  62
  63 class pmt_exception : public std::logic_error
  64 {
  65 public:
  66   pmt_exception(const std::string &msg, pmt_t obj);
  67 };
  68
  69 class pmt_wrong_type : public pmt_exception
  70 {
  71 public:
  72   pmt_wrong_type(const std::string &msg, pmt_t obj);
  73 };
  74
  75 class pmt_out_of_range : public pmt_exception
  76 {
  77 public:
  78   pmt_out_of_range(const std::string &msg, pmt_t obj);
  79 };
  80
  81 class pmt_notimplemented : public pmt_exception
  82 {
  83 public:
  84   pmt_notimplemented(const std::string &msg, pmt_t obj);
  85 };
  86
  87 /*
  88  * ------------------------------------------------------------------------
  89  * Booleans.  Two constants, #t and #f.
  90  *
  91  * In predicates, anything that is not #f is considered true.
  92  * I.e., there is a single false value, #f.
  93  * ------------------------------------------------------------------------
  94  */
  95 extern const pmt_t PMT_T;       //< \#t : boolean true constant
  96 extern const pmt_t PMT_F;       //< \#f : boolean false constant
  97
  98 //! Return true if obj is \#t or \#f, else return false.
  99 bool pmt_is_bool(pmt_t obj);
 100
 101 //! Return false if obj is \#f, else return true.
 102 bool pmt_is_true(pmt_t obj);
 103
 104 //! Return true if obj is \#f, else return true.
 105 bool pmt_is_false(pmt_t obj);
 106
 107 //! Return \#f is val is false, else return \#t.
 108 pmt_t pmt_from_bool(bool val);
 109
 110 //! Return true if val is PMT_T, return false when val is PMT_F,
 111 // else raise wrong_type exception.
 112 bool pmt_to_bool(pmt_t val);
 113
 114 /*
 115  * ------------------------------------------------------------------------
 116  *                             Symbols
 117  * ------------------------------------------------------------------------
 118  */
 119
 120 //! Return true if obj is a symbol, else false.
 121 bool pmt_is_symbol(const pmt_t& obj);
 122
 123 //! Return the symbol whose name is \p s.
 124 pmt_t pmt_string_to_symbol(const std::string &s);
 125
 126 //! Alias for pmt_string_to_symbol
 127 pmt_t pmt_intern(const std::string &s);
 128
 129
 130 /*!
 131  * If \p is a symbol, return the name of the symbol as a string.
 132  * Otherwise, raise the wrong_type exception.
 133  */
 134 const std::string pmt_symbol_to_string(const pmt_t& sym);
 135
 136 /*
 137  * ------------------------------------------------------------------------
 138  *           Numbers: we support integer, real and complex
 139  * ------------------------------------------------------------------------
 140  */
 141
 142 //! Return true if obj is any kind of number, else false.
 143 bool pmt_is_number(pmt_t obj);
 144
 145 /*
 146  * ------------------------------------------------------------------------
 147  *                             Integers
 148  * ------------------------------------------------------------------------
 149  */
 150
 151 //! Return true if \p x is an integer number, else false
 152 bool pmt_is_integer(pmt_t x);
 153
 154 //! Return the pmt value that represents the integer \p x.
 155 pmt_t pmt_from_long(long x);
 156
 157 /*!
 158  * \brief Convert pmt to long if possible.
 159  *
 160  * When \p x represents an exact integer that fits in a long,
 161  * return that integer.  Else raise an exception, either wrong_type
 162  * when x is not an exact integer, or out_of_range when it doesn't fit.
 163  */
 164 long pmt_to_long(pmt_t x);
 165
 166 /*
 167  * ------------------------------------------------------------------------
 168  *                              Reals
 169  * ------------------------------------------------------------------------
 170  */
 171
 172 /*
 173  * \brief Return true if \p obj is a real number, else false.
 174  */
 175 bool pmt_is_real(pmt_t obj);
 176
 177 //! Return the pmt value that represents double \p x.
 178 pmt_t pmt_from_double(double x);
 179
 180 /*!
 181  * \brief Convert pmt to double if possible.
 182  *
 183  * Returns the number closest to \p val that is representable
 184  * as a double.  The argument \p val must be a real or integer, otherwise
 185  * a wrong_type exception is raised.
 186  */
 187 double pmt_to_double(pmt_t x);
 188
 189 /*
 190  * ------------------------------------------------------------------------
 191  *                             Complex
 192  * ------------------------------------------------------------------------
 193  */
 194
 195 /*!
 196  * \brief return true if \p obj is a complex number, false otherwise.
 197  */
 198 bool pmt_is_complex(pmt_t obj);
 199
 200 //! Return a complex number constructed of the given real and imaginary parts.
 201 pmt_t pmt_make_rectangular(double re, double im);
 202
 203 /*!
 204  * If \p z is complex, real or integer, return the closest complex<double>.
 205  * Otherwise, raise the wrong_type exception.
 206  */
 207 std::complex<double> pmt_to_complex(pmt_t z);
 208
 209 /*
 210  * ------------------------------------------------------------------------
 211  *                              Pairs
 212  * ------------------------------------------------------------------------
 213  */
 214
 215 extern const pmt_t PMT_NIL;     //< the empty list
 216
 217 //! Return true if \p x is the empty list, otherwise return false.
 218 bool pmt_is_null(const pmt_t& x);
 219
 220 //! Return true if \p obj is a pair, else false.
 221 bool pmt_is_pair(const pmt_t& obj);
 222
 223 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
 224 pmt_t pmt_cons(const pmt_t& x, const pmt_t& y);
 225
 226 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
 227 pmt_t pmt_car(const pmt_t& pair);
 228
 229 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
 230 pmt_t pmt_cdr(const pmt_t& pair);
 231
 232 //! Stores \p value in the car field of \p pair.
 233 void pmt_set_car(pmt_t pair, pmt_t value);
 234
 235 //! Stores \p value in the cdr field of \p pair.
 236 void pmt_set_cdr(pmt_t pair, pmt_t value);
 237
 238 pmt_t pmt_caar(pmt_t pair);
 239 pmt_t pmt_cadr(pmt_t pair);
 240 pmt_t pmt_cdar(pmt_t pair);
 241 pmt_t pmt_cddr(pmt_t pair);
 242 pmt_t pmt_caddr(pmt_t pair);
 243 pmt_t pmt_cadddr(pmt_t pair);
 244
 245 /*
 246  * ------------------------------------------------------------------------
 247  *                                Tuples
 248  *
 249  * Store a fixed number of objects.  Tuples are not modifiable, and thus
 250  * are excellent for use as messages.  Indexing is zero based.
 251  * Access time to an element is O(1).
 252  * ------------------------------------------------------------------------
 253  */
 254
 255 //! Return true if \p x is a tuple, othewise false.
 256 bool pmt_is_tuple(pmt_t x);
 257
 258 pmt_t pmt_make_tuple();
 259 pmt_t pmt_make_tuple(const pmt_t &e0);
 260 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1);
 261 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2);
 262 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3);
 263 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4);
 264 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4, const pmt_t &e5);
 265 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4, const pmt_t &e5, const pmt_t &e6);
 266 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4, const pmt_t &e5, const pmt_t &e6, const pmt_t &e7);
 267 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4, const pmt_t &e5, const pmt_t &e6, const pmt_t &e7, const pmt_t &e8);
 268 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3, const pmt_t &e4, const pmt_t &e5, const pmt_t &e6, const pmt_t &e7, const pmt_t &e8, const pmt_t &e9);
 269
 270 /*!
 271  * If \p x is a vector or proper list, return a tuple containing the elements of x
 272  */
 273 pmt_t pmt_to_tuple(const pmt_t &x);
 274
 275 /*!
 276  * Return the contents of position \p k of \p tuple.
 277  * \p k must be a valid index of \p tuple.
 278  */
 279 pmt_t pmt_tuple_ref(const pmt_t &tuple, size_t k);
 280
 281 /*
 282  * ------------------------------------------------------------------------
 283  *                             Vectors
 284  *
 285  * These vectors can hold any kind of objects.  Indexing is zero based.
 286  * ------------------------------------------------------------------------
 287  */
 288
 289 //! Return true if \p x is a vector, othewise false.
 290 bool pmt_is_vector(pmt_t x);
 291
 292 //! Make a vector of length \p k, with initial values set to \p fill
 293 pmt_t pmt_make_vector(size_t k, pmt_t fill);
 294
 295 /*!
 296  * Return the contents of position \p k of \p vector.
 297  * \p k must be a valid index of \p vector.
 298  */
 299 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
 300
 301 //! Store \p obj in position \p k.
 302 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
 303
 304 //! Store \p fill in every position of \p vector
 305 void pmt_vector_fill(pmt_t vector, pmt_t fill);
 306
 307 /*
 308  * ------------------------------------------------------------------------
 309  *                    Binary Large Objects (BLOBs)
 310  *
 311  * Handy for passing around uninterpreted chunks of memory.
 312  * ------------------------------------------------------------------------
 313  */
 314
 315 //! Return true if \p x is a blob, othewise false.
 316 bool pmt_is_blob(pmt_t x);
 317
 318 /*!
 319  * \brief Make a blob given a pointer and length in bytes
 320  *
 321  * \param buf is the pointer to data to use to create blob
 322  * \param len is the size of the data in bytes.
 323  *
 324  * The data is copied into the blob.
 325  */
 326 pmt_t pmt_make_blob(const void *buf, size_t len);
 327
 328 //! Return a pointer to the blob's data
 329 const void *pmt_blob_data(pmt_t blob);
 330
 331 //! Return the blob's length in bytes
 332 size_t pmt_blob_length(pmt_t blob);
 333
 334 /*!
 335  * <pre>
 336  * ------------------------------------------------------------------------
 337  *                     Uniform Numeric Vectors
 338  *
 339  * A uniform numeric vector is a vector whose elements are all of single
 340  * numeric type.  pmt offers uniform numeric vectors for signed and
 341  * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
 342  * floating point values, and complex floating-point numbers of these
 343  * two sizes.  Indexing is zero based.
 344  *
 345  * The names of the functions include these tags in their names:
 346  *
 347  *    u8  unsigned 8-bit integers
 348  *    s8  signed 8-bit integers
 349  *   u16  unsigned 16-bit integers
 350  *   s16  signed 16-bit integers
 351  *   u32  unsigned 32-bit integers
 352  *   s32  signed 32-bit integers
 353  *   u64  unsigned 64-bit integers
 354  *   s64  signed 64-bit integers
 355  *   f32  the C++ type float
 356  *   f64  the C++ type double
 357  *   c32  the C++ type complex<float>
 358  *   c64  the C++ type complex<double>
 359  * ------------------------------------------------------------------------
 360  * </pre>
 361  */
 362
 363 //! true if \p x is any kind of uniform numeric vector
 364 bool pmt_is_uniform_vector(pmt_t x);
 365
 366 bool pmt_is_u8vector(pmt_t x);
 367 bool pmt_is_s8vector(pmt_t x);
 368 bool pmt_is_u16vector(pmt_t x);
 369 bool pmt_is_s16vector(pmt_t x);
 370 bool pmt_is_u32vector(pmt_t x);
 371 bool pmt_is_s32vector(pmt_t x);
 372 bool pmt_is_u64vector(pmt_t x);
 373 bool pmt_is_s64vector(pmt_t x);
 374 bool pmt_is_f32vector(pmt_t x);
 375 bool pmt_is_f64vector(pmt_t x);
 376 bool pmt_is_c32vector(pmt_t x);
 377 bool pmt_is_c64vector(pmt_t x);
 378
 379 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
 380 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
 381 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
 382 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
 383 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
 384 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
 385 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
 386 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
 387 pmt_t pmt_make_f32vector(size_t k, float fill);
 388 pmt_t pmt_make_f64vector(size_t k, double fill);
 389 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
 390 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
 391
 392 pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
 393 pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
 394 pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
 395 pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
 396 pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
 397 pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
 398 pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
 399 pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
 400 pmt_t pmt_init_f32vector(size_t k, const float *data);
 401 pmt_t pmt_init_f64vector(size_t k, const double *data);
 402 pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
 403 pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
 404
 405 uint8_t  pmt_u8vector_ref(pmt_t v, size_t k);
 406 int8_t   pmt_s8vector_ref(pmt_t v, size_t k);
 407 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
 408 int16_t  pmt_s16vector_ref(pmt_t v, size_t k);
 409 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
 410 int32_t  pmt_s32vector_ref(pmt_t v, size_t k);
 411 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
 412 int64_t  pmt_s64vector_ref(pmt_t v, size_t k);
 413 float    pmt_f32vector_ref(pmt_t v, size_t k);
 414 double   pmt_f64vector_ref(pmt_t v, size_t k);
 415 std::complex<float>  pmt_c32vector_ref(pmt_t v, size_t k);
 416 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
 417
 418 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x);  //< v[k] = x
 419 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
 420 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
 421 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
 422 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
 423 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
 424 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
 425 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
 426 void pmt_f32vector_set(pmt_t v, size_t k, float x);
 427 void pmt_f64vector_set(pmt_t v, size_t k, double x);
 428 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
 429 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
 430
 431 // Return const pointers to the elements
 432
 433 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 434
 435 const uint8_t  *pmt_u8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 436 const int8_t   *pmt_s8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 437 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
 438 const int16_t  *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
 439 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
 440 const int32_t  *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
 441 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
 442 const int64_t  *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
 443 const float    *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
 444 const double   *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
 445 const std::complex<float>  *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
 446 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
 447
 448 // Return non-const pointers to the elements
 449
 450 void *pmt_uniform_vector_writable_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 451
 452 uint8_t  *pmt_u8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
 453 int8_t   *pmt_s8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
 454 uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 455 int16_t  *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 456 uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 457 int32_t  *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 458 uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 459 int64_t  *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 460 float    *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 461 double   *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 462 std::complex<float>  *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 463 std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
 464
 465 /*
 466  * ------------------------------------------------------------------------
 467  *         Dictionary (a.k.a associative array, hash, map)
 468  *
 469  * This is a functional data structure that is persistent.  Updating a
 470  * functional data structure does not destroy the existing version, but
 471  * rather creates a new version that coexists with the old.
 472  * ------------------------------------------------------------------------
 473  */
 474
 475 //! Return true if \p obj is a dictionary
 476 bool pmt_is_dict(const pmt_t &obj);
 477
 478 //! Make an empty dictionary
 479 pmt_t pmt_make_dict();
 480
 481 //! Return a new dictionary with \p key associated with \p value.
 482 pmt_t pmt_dict_add(const pmt_t &dict, const pmt_t &key, const pmt_t &value);
 483
 484 //! Return a new dictionary with \p key removed.
 485 pmt_t pmt_dict_delete(const pmt_t &dict, const pmt_t &key);
 486
 487 //! Return true if \p key exists in \p dict
 488 bool  pmt_dict_has_key(const pmt_t &dict, const pmt_t &key);
 489
 490 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
 491 pmt_t pmt_dict_ref(const pmt_t &dict, const pmt_t &key, const pmt_t &not_found);
 492
 493 //! Return list of (key . value) pairs
 494 pmt_t pmt_dict_items(pmt_t dict);
 495
 496 //! Return list of keys
 497 pmt_t pmt_dict_keys(pmt_t dict);
 498
 499 //! Return list of values
 500 pmt_t pmt_dict_values(pmt_t dict);
 501
 502 /*
 503  * ------------------------------------------------------------------------
 504  *   Any (wraps boost::any -- can be used to wrap pretty much anything)
 505  *
 506  * Cannot be serialized or used across process boundaries.
 507  * See http://www.boost.org/doc/html/any.html
 508  * ------------------------------------------------------------------------
 509  */
 510
 511 //! Return true if \p obj is an any
 512 bool pmt_is_any(pmt_t obj);
 513
 514 //! make an any
 515 pmt_t pmt_make_any(const boost::any &any);
 516
 517 //! Return underlying boost::any
 518 boost::any pmt_any_ref(pmt_t obj);
 519
 520 //! Store \p any in \p obj
 521 void pmt_any_set(pmt_t obj, const boost::any &any);
 522
 523
 524 /*
 525  * ------------------------------------------------------------------------
 526  *    msg_accepter -- pmt representation of gruel::msg_accepter
 527  * ------------------------------------------------------------------------
 528  */
 529 //! Return true if \p obj is a msg_accepter
 530 bool pmt_is_msg_accepter(const pmt_t &obj);
 531
 532 //! make a msg_accepter
 533 pmt_t pmt_make_msg_accepter(boost::shared_ptr<gruel::msg_accepter> ma);
 534
 535 //! Return underlying msg_accepter
 536 boost::shared_ptr<gruel::msg_accepter> pmt_msg_accepter_ref(const pmt_t &obj);
 537
 538 /*
 539  * ------------------------------------------------------------------------
 540  *                        General functions
 541  * ------------------------------------------------------------------------
 542  */
 543
 544 //! Return true if x and y are the same object; otherwise return false.
 545 bool pmt_eq(const pmt_t& x, const pmt_t& y);
 546
 547 /*!
 548  * \brief Return true if x and y should normally be regarded as the same object, else false.
 549  *
 550  * <pre>
 551  * eqv returns true if:
 552  *   x and y are the same object.
 553  *   x and y are both \#t or both \#f.
 554  *   x and y are both symbols and their names are the same.
 555  *   x and y are both numbers, and are numerically equal.
 556  *   x and y are both the empty list (nil).
 557  *   x and y are pairs or vectors that denote same location in store.
 558  * </pre>
 559  */
 560 bool pmt_eqv(const pmt_t& x, const pmt_t& y);
 561
 562 /*!
 563  * pmt_equal recursively compares the contents of pairs and vectors,
 564  * applying pmt_eqv on other objects such as numbers and symbols.
 565  * pmt_equal may fail to terminate if its arguments are circular data
 566  * structures.
 567  */
 568 bool pmt_equal(const pmt_t& x, const pmt_t& y);
 569
 570
 571 //! Return the number of elements in v
 572 size_t pmt_length(const pmt_t& v);
 573
 574 /*!
 575  * \brief Find the first pair in \p alist whose car field is \p obj
 576  *  and return that pair.
 577  *
 578  * \p alist (for "association list") must be a list of pairs.  If no pair
 579  * in \p alist has \p obj as its car then \#f is returned.
 580  * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
 581  */
 582 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
 583
 584 /*!
 585  * \brief Find the first pair in \p alist whose car field is \p obj
 586  *  and return that pair.
 587  *
 588  * \p alist (for "association list") must be a list of pairs.  If no pair
 589  * in \p alist has \p obj as its car then \#f is returned.
 590  * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
 591  */
 592 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
 593
 594 /*!
 595  * \brief Find the first pair in \p alist whose car field is \p obj
 596  *  and return that pair.
 597  *
 598  * \p alist (for "association list") must be a list of pairs.  If no pair
 599  * in \p alist has \p obj as its car then \#f is returned.
 600  * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
 601  */
 602 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
 603
 604 /*!
 605  * \brief Apply \p proc element-wise to the elements of list and returns
 606  * a list of the results, in order.
 607  *
 608  * \p list must be a list.  The dynamic order in which \p proc is
 609  * applied to the elements of \p list is unspecified.
 610  */
 611 pmt_t pmt_map(pmt_t proc(const pmt_t&), pmt_t list);
 612
 613 /*!
 614  * \brief reverse \p list.
 615  *
 616  * \p list must be a proper list.
 617  */
 618 pmt_t pmt_reverse(pmt_t list);
 619
 620 /*!
 621  * \brief destructively reverse \p list.
 622  *
 623  * \p list must be a proper list.
 624  */
 625 pmt_t pmt_reverse_x(pmt_t list);
 626
 627 /*!
 628  * \brief (acons x y a) == (cons (cons x y) a)
 629  */
 630 inline static pmt_t
 631 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
 632 {
 633   return pmt_cons(pmt_cons(x, y), a);
 634 }
 635
 636 /*!
 637  * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
 638  */
 639 pmt_t pmt_nth(size_t n, pmt_t list);
 640
 641 /*!
 642  * \brief returns the tail of \p list that would be obtained by calling
 643  * cdr \p n times in succession.
 644  */
 645 pmt_t pmt_nthcdr(size_t n, pmt_t list);
 646
 647 /*!
 648  * \brief Return the first sublist of \p list whose car is \p obj.
 649  * If \p obj does not occur in \p list, then \#f is returned.
 650  * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
 651  */
 652 pmt_t pmt_memq(pmt_t obj, pmt_t list);
 653
 654 /*!
 655  * \brief Return the first sublist of \p list whose car is \p obj.
 656  * If \p obj does not occur in \p list, then \#f is returned.
 657  * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
 658  */
 659 pmt_t pmt_memv(pmt_t obj, pmt_t list);
 660
 661 /*!
 662  * \brief Return the first sublist of \p list whose car is \p obj.
 663  * If \p obj does not occur in \p list, then \#f is returned.
 664  * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
 665  */
 666 pmt_t pmt_member(pmt_t obj, pmt_t list);
 667
 668 /*!
 669  * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
 670  * Comparisons are done with pmt_eqv.
 671  */
 672 bool pmt_subsetp(pmt_t list1, pmt_t list2);
 673
 674 /*!
 675  * \brief Return a list of length 1 containing \p x1
 676  */
 677 pmt_t pmt_list1(const pmt_t& x1);
 678
 679 /*!
 680  * \brief Return a list of length 2 containing \p x1, \p x2
 681  */
 682 pmt_t pmt_list2(const pmt_t& x1, const pmt_t& x2);
 683
 684 /*!
 685  * \brief Return a list of length 3 containing \p x1, \p x2, \p x3
 686  */
 687 pmt_t pmt_list3(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3);
 688
 689 /*!
 690  * \brief Return a list of length 4 containing \p x1, \p x2, \p x3, \p x4
 691  */
 692 pmt_t pmt_list4(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4);
 693
 694 /*!
 695  * \brief Return a list of length 5 containing \p x1, \p x2, \p x3, \p x4, \p x5
 696  */
 697 pmt_t pmt_list5(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4, const pmt_t& x5);
 698
 699 /*!
 700  * \brief Return a list of length 6 containing \p x1, \p x2, \p x3, \p x4, \p
 701  * x5, \p x6
 702  */
 703 pmt_t pmt_list6(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4, const pmt_t& x5, const pmt_t& x6);
 704
 705 /*!
 706  * \brief Return \p list with \p item added to it.
 707  */
 708 pmt_t pmt_list_add(pmt_t list, const pmt_t& item);
 709
 710
 711 /*
 712  * ------------------------------------------------------------------------
 713  *                           read / write
 714  * ------------------------------------------------------------------------
 715  */
 716 extern const pmt_t PMT_EOF;     //< The end of file object
 717
 718 //! return true if obj is the EOF object, otherwise return false.
 719 bool pmt_is_eof_object(pmt_t obj);
 720
 721 /*!
 722  * read converts external representations of pmt objects into the
 723  * objects themselves.  Read returns the next object parsable from
 724  * the given input port, updating port to point to the first
 725  * character past the end of the external representation of the
 726  * object.
 727  *
 728  * If an end of file is encountered in the input before any
 729  * characters are found that can begin an object, then an end of file
 730  * object is returned.   The port remains open, and further attempts
 731  * to read will also return an end of file object.  If an end of file
 732  * is encountered after the beginning of an object's external
 733  * representation, but the external representation is incomplete and
 734  * therefore not parsable, an error is signaled.
 735  */
 736 pmt_t pmt_read(std::istream &port);
 737
 738 /*!
 739  * Write a written representation of \p obj to the given \p port.
 740  */
 741 void pmt_write(pmt_t obj, std::ostream &port);
 742
 743 /*!
 744  * Return a string representation of \p obj.
 745  * This is the same output as would be generated by pmt_write.
 746  */
 747 std::string pmt_write_string(pmt_t obj);
 748
 749
 750 std::ostream& operator<<(std::ostream &os, pmt_t obj);
 751
 752
 753 /*
 754  * ------------------------------------------------------------------------
 755  *                    portable byte stream representation
 756  * ------------------------------------------------------------------------
 757  */
 758 /*!
 759  * \brief Write portable byte-serial representation of \p obj to \p sink
 760  */
 761 bool pmt_serialize(pmt_t obj, std::streambuf &sink);
 762
 763 /*!
 764  * \brief Create obj from portable byte-serial representation
 765  */
 766 pmt_t pmt_deserialize(std::streambuf &source);
 767
 768
 769 void pmt_dump_sizeof(); // debugging
 770
 771 } /* namespace pmt */
 772
 773
 774 #include <gruel/pmt_sugar.h>
 775
 776 #endif /* INCLUDED_PMT_H */