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