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

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