GNU Radio 3.6.0 C++ API
pmt.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2006,2009,2010 Free Software Foundation, Inc.
00004  *
00005  * This file is part of GNU Radio
00006  *
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  *
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef INCLUDED_PMT_H
00024 #define INCLUDED_PMT_H
00025 
00026 #include <gruel/api.h>
00027 #include <boost/intrusive_ptr.hpp>
00028 #include <boost/shared_ptr.hpp>
00029 #include <boost/any.hpp>
00030 #include <complex>
00031 #include <string>
00032 #include <stdint.h>
00033 #include <iosfwd>
00034 #include <stdexcept>
00035 #include <boost/function.hpp>
00036 
00037 namespace gruel {
00038   class msg_accepter;
00039 };
00040 
00041 /*!
00042  * This file defines a polymorphic type and the operations on it.
00043  *
00044  * It draws heavily on the idea of scheme and lisp data types.
00045  * The interface parallels that in Guile 1.8, with the notable
00046  * exception that these objects are transparently reference counted.
00047  */
00048 
00049 namespace pmt {
00050 
00051 /*!
00052  * \brief base class of all pmt types
00053  */
00054 class pmt_base;
00055 
00056 /*!
00057  * \brief typedef for shared pointer (transparent reference counting).
00058  * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
00059  */
00060 typedef boost::intrusive_ptr<pmt_base> pmt_t;
00061 
00062 extern GRUEL_API void intrusive_ptr_add_ref(pmt_base*);
00063 extern GRUEL_API void intrusive_ptr_release(pmt_base*);
00064 
00065 class GRUEL_API pmt_exception : public std::logic_error
00066 {
00067 public:
00068   pmt_exception(const std::string &msg, pmt_t obj);
00069 };
00070 
00071 class GRUEL_API pmt_wrong_type : public pmt_exception
00072 {
00073 public:
00074   pmt_wrong_type(const std::string &msg, pmt_t obj);
00075 };
00076 
00077 class GRUEL_API pmt_out_of_range : public pmt_exception
00078 {
00079 public:
00080   pmt_out_of_range(const std::string &msg, pmt_t obj);
00081 };
00082 
00083 class GRUEL_API pmt_notimplemented : public pmt_exception
00084 {
00085 public:
00086   pmt_notimplemented(const std::string &msg, pmt_t obj);
00087 };
00088 
00089 /*
00090  * ------------------------------------------------------------------------
00091  * Booleans.  Two constants, #t and #f.
00092  *
00093  * In predicates, anything that is not #f is considered true.
00094  * I.e., there is a single false value, #f.
00095  * ------------------------------------------------------------------------
00096  */
00097 extern GRUEL_API const pmt_t PMT_T;     //< \#t : boolean true constant
00098 extern GRUEL_API const pmt_t PMT_F;     //< \#f : boolean false constant
00099 
00100 //! Return true if obj is \#t or \#f, else return false.
00101 GRUEL_API bool pmt_is_bool(pmt_t obj);
00102 
00103 //! Return false if obj is \#f, else return true.
00104 GRUEL_API bool pmt_is_true(pmt_t obj);
00105 
00106 //! Return true if obj is \#f, else return true.
00107 GRUEL_API bool pmt_is_false(pmt_t obj);
00108 
00109 //! Return \#f is val is false, else return \#t.
00110 GRUEL_API pmt_t pmt_from_bool(bool val);
00111 
00112 //! Return true if val is PMT_T, return false when val is PMT_F,
00113 // else raise wrong_type exception.
00114 GRUEL_API bool pmt_to_bool(pmt_t val);
00115 
00116 /*
00117  * ------------------------------------------------------------------------
00118  *                             Symbols
00119  * ------------------------------------------------------------------------
00120  */
00121 
00122 //! Return true if obj is a symbol, else false.
00123 GRUEL_API bool pmt_is_symbol(const pmt_t& obj);
00124 
00125 //! Return the symbol whose name is \p s.
00126 GRUEL_API pmt_t pmt_string_to_symbol(const std::string &s);
00127 
00128 //! Alias for pmt_string_to_symbol
00129 GRUEL_API pmt_t pmt_intern(const std::string &s);
00130 
00131 
00132 /*!
00133  * If \p is a symbol, return the name of the symbol as a string.
00134  * Otherwise, raise the wrong_type exception.
00135  */
00136 GRUEL_API const std::string pmt_symbol_to_string(const pmt_t& sym);
00137 
00138 /*
00139  * ------------------------------------------------------------------------
00140  *           Numbers: we support integer, real and complex
00141  * ------------------------------------------------------------------------
00142  */
00143 
00144 //! Return true if obj is any kind of number, else false.
00145 GRUEL_API bool pmt_is_number(pmt_t obj);
00146 
00147 /*
00148  * ------------------------------------------------------------------------
00149  *                             Integers
00150  * ------------------------------------------------------------------------
00151  */
00152 
00153 //! Return true if \p x is an integer number, else false
00154 GRUEL_API bool pmt_is_integer(pmt_t x);
00155 
00156 //! Return the pmt value that represents the integer \p x.
00157 GRUEL_API pmt_t pmt_from_long(long x);
00158 
00159 /*!
00160  * \brief Convert pmt to long if possible.
00161  *
00162  * When \p x represents an exact integer that fits in a long,
00163  * return that integer.  Else raise an exception, either wrong_type
00164  * when x is not an exact integer, or out_of_range when it doesn't fit.
00165  */
00166 GRUEL_API long pmt_to_long(pmt_t x);
00167 
00168 /*
00169  * ------------------------------------------------------------------------
00170  *                             uint64_t
00171  * ------------------------------------------------------------------------
00172  */
00173 
00174 //! Return true if \p x is an uint64 number, else false
00175 GRUEL_API bool pmt_is_uint64(pmt_t x);
00176 
00177 //! Return the pmt value that represents the uint64 \p x.
00178 GRUEL_API pmt_t pmt_from_uint64(uint64_t x);
00179 
00180 /*!
00181  * \brief Convert pmt to uint64 if possible.
00182  *
00183  * When \p x represents an exact integer that fits in a uint64,
00184  * return that uint64.  Else raise an exception, either wrong_type
00185  * when x is not an exact uint64, or out_of_range when it doesn't fit.
00186  */
00187 GRUEL_API uint64_t pmt_to_uint64(pmt_t x);
00188 
00189 /*
00190  * ------------------------------------------------------------------------
00191  *                              Reals
00192  * ------------------------------------------------------------------------
00193  */
00194 
00195 /*
00196  * \brief Return true if \p obj is a real number, else false.
00197  */
00198 GRUEL_API bool pmt_is_real(pmt_t obj);
00199 
00200 //! Return the pmt value that represents double \p x.
00201 GRUEL_API pmt_t pmt_from_double(double x);
00202 
00203 /*!
00204  * \brief Convert pmt to double if possible.
00205  *
00206  * Returns the number closest to \p val that is representable
00207  * as a double.  The argument \p val must be a real or integer, otherwise
00208  * a wrong_type exception is raised.
00209  */
00210 GRUEL_API double pmt_to_double(pmt_t x);
00211 
00212 /*
00213  * ------------------------------------------------------------------------
00214  *                             Complex
00215  * ------------------------------------------------------------------------
00216  */
00217 
00218 /*!
00219  * \brief return true if \p obj is a complex number, false otherwise.
00220  */
00221 GRUEL_API bool pmt_is_complex(pmt_t obj);
00222 
00223 //! Return a complex number constructed of the given real and imaginary parts.
00224 GRUEL_API pmt_t pmt_make_rectangular(double re, double im);
00225 
00226 /*!
00227  * If \p z is complex, real or integer, return the closest complex<double>.
00228  * Otherwise, raise the wrong_type exception.
00229  */
00230 GRUEL_API std::complex<double> pmt_to_complex(pmt_t z);
00231 
00232 /*
00233  * ------------------------------------------------------------------------
00234  *                              Pairs
00235  * ------------------------------------------------------------------------
00236  */
00237 
00238 extern GRUEL_API const pmt_t PMT_NIL;   //< the empty list
00239 
00240 //! Return true if \p x is the empty list, otherwise return false.
00241 GRUEL_API bool pmt_is_null(const pmt_t& x);
00242 
00243 //! Return true if \p obj is a pair, else false.
00244 GRUEL_API bool pmt_is_pair(const pmt_t& obj);
00245 
00246 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
00247 GRUEL_API pmt_t pmt_cons(const pmt_t& x, const pmt_t& y);
00248 
00249 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
00250 GRUEL_API pmt_t pmt_car(const pmt_t& pair);
00251 
00252 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
00253 GRUEL_API pmt_t pmt_cdr(const pmt_t& pair);
00254 
00255 //! Stores \p value in the car field of \p pair.
00256 GRUEL_API void pmt_set_car(pmt_t pair, pmt_t value);
00257 
00258 //! Stores \p value in the cdr field of \p pair.
00259 GRUEL_API void pmt_set_cdr(pmt_t pair, pmt_t value);
00260 
00261 GRUEL_API pmt_t pmt_caar(pmt_t pair);
00262 GRUEL_API pmt_t pmt_cadr(pmt_t pair);
00263 GRUEL_API pmt_t pmt_cdar(pmt_t pair);
00264 GRUEL_API pmt_t pmt_cddr(pmt_t pair);
00265 GRUEL_API pmt_t pmt_caddr(pmt_t pair);
00266 GRUEL_API pmt_t pmt_cadddr(pmt_t pair);
00267 
00268 /*
00269  * ------------------------------------------------------------------------
00270  *                                Tuples
00271  *
00272  * Store a fixed number of objects.  Tuples are not modifiable, and thus
00273  * are excellent for use as messages.  Indexing is zero based.
00274  * Access time to an element is O(1).
00275  * ------------------------------------------------------------------------
00276  */
00277 
00278 //! Return true if \p x is a tuple, othewise false.
00279 GRUEL_API bool pmt_is_tuple(pmt_t x);
00280 
00281 GRUEL_API pmt_t pmt_make_tuple();
00282 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0);
00283 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1);
00284 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2);
00285 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3);
00286 GRUEL_API 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);
00287 GRUEL_API 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);
00288 GRUEL_API 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);
00289 GRUEL_API 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);
00290 GRUEL_API 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);
00291 GRUEL_API 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);
00292 
00293 /*!
00294  * If \p x is a vector or proper list, return a tuple containing the elements of x
00295  */
00296 GRUEL_API pmt_t pmt_to_tuple(const pmt_t &x);
00297 
00298 /*!
00299  * Return the contents of position \p k of \p tuple.
00300  * \p k must be a valid index of \p tuple.
00301  */
00302 GRUEL_API pmt_t pmt_tuple_ref(const pmt_t &tuple, size_t k);
00303 
00304 /*
00305  * ------------------------------------------------------------------------
00306  *                             Vectors
00307  *
00308  * These vectors can hold any kind of objects.  Indexing is zero based.
00309  * ------------------------------------------------------------------------
00310  */
00311 
00312 //! Return true if \p x is a vector, othewise false.
00313 GRUEL_API bool pmt_is_vector(pmt_t x);
00314 
00315 //! Make a vector of length \p k, with initial values set to \p fill
00316 GRUEL_API pmt_t pmt_make_vector(size_t k, pmt_t fill);
00317 
00318 /*!
00319  * Return the contents of position \p k of \p vector.
00320  * \p k must be a valid index of \p vector.
00321  */
00322 GRUEL_API pmt_t pmt_vector_ref(pmt_t vector, size_t k);
00323 
00324 //! Store \p obj in position \p k.
00325 GRUEL_API void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
00326 
00327 //! Store \p fill in every position of \p vector
00328 GRUEL_API void pmt_vector_fill(pmt_t vector, pmt_t fill);
00329 
00330 /*
00331  * ------------------------------------------------------------------------
00332  *                    Binary Large Objects (BLOBs)
00333  *
00334  * Handy for passing around uninterpreted chunks of memory.
00335  * ------------------------------------------------------------------------
00336  */
00337 
00338 //! Return true if \p x is a blob, othewise false.
00339 GRUEL_API bool pmt_is_blob(pmt_t x);
00340 
00341 /*!
00342  * \brief Make a blob given a pointer and length in bytes
00343  *
00344  * \param buf is the pointer to data to use to create blob
00345  * \param len is the size of the data in bytes.
00346  *
00347  * The data is copied into the blob.
00348  */
00349 GRUEL_API pmt_t pmt_make_blob(const void *buf, size_t len);
00350 
00351 //! Return a pointer to the blob's data
00352 GRUEL_API const void *pmt_blob_data(pmt_t blob);
00353 
00354 //! Return the blob's length in bytes
00355 GRUEL_API size_t pmt_blob_length(pmt_t blob);
00356 
00357 /*!
00358  * <pre>
00359  * ------------------------------------------------------------------------
00360  *                     Uniform Numeric Vectors
00361  *
00362  * A uniform numeric vector is a vector whose elements are all of single
00363  * numeric type.  pmt offers uniform numeric vectors for signed and
00364  * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
00365  * floating point values, and complex floating-point numbers of these
00366  * two sizes.  Indexing is zero based.
00367  *
00368  * The names of the functions include these tags in their names:
00369  *
00370  *    u8  unsigned 8-bit integers
00371  *    s8  signed 8-bit integers
00372  *   u16  unsigned 16-bit integers
00373  *   s16  signed 16-bit integers
00374  *   u32  unsigned 32-bit integers
00375  *   s32  signed 32-bit integers
00376  *   u64  unsigned 64-bit integers
00377  *   s64  signed 64-bit integers
00378  *   f32  the C++ type float
00379  *   f64  the C++ type double
00380  *   c32  the C++ type complex<float>
00381  *   c64  the C++ type complex<double>
00382  * ------------------------------------------------------------------------
00383  * </pre>
00384  */
00385 
00386 //! true if \p x is any kind of uniform numeric vector
00387 GRUEL_API bool pmt_is_uniform_vector(pmt_t x);
00388 
00389 GRUEL_API bool pmt_is_u8vector(pmt_t x);
00390 GRUEL_API bool pmt_is_s8vector(pmt_t x);
00391 GRUEL_API bool pmt_is_u16vector(pmt_t x);
00392 GRUEL_API bool pmt_is_s16vector(pmt_t x);
00393 GRUEL_API bool pmt_is_u32vector(pmt_t x);
00394 GRUEL_API bool pmt_is_s32vector(pmt_t x);
00395 GRUEL_API bool pmt_is_u64vector(pmt_t x);
00396 GRUEL_API bool pmt_is_s64vector(pmt_t x);
00397 GRUEL_API bool pmt_is_f32vector(pmt_t x);
00398 GRUEL_API bool pmt_is_f64vector(pmt_t x);
00399 GRUEL_API bool pmt_is_c32vector(pmt_t x);
00400 GRUEL_API bool pmt_is_c64vector(pmt_t x);
00401 
00402 GRUEL_API pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
00403 GRUEL_API pmt_t pmt_make_s8vector(size_t k, int8_t fill);
00404 GRUEL_API pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
00405 GRUEL_API pmt_t pmt_make_s16vector(size_t k, int16_t fill);
00406 GRUEL_API pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
00407 GRUEL_API pmt_t pmt_make_s32vector(size_t k, int32_t fill);
00408 GRUEL_API pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
00409 GRUEL_API pmt_t pmt_make_s64vector(size_t k, int64_t fill);
00410 GRUEL_API pmt_t pmt_make_f32vector(size_t k, float fill);
00411 GRUEL_API pmt_t pmt_make_f64vector(size_t k, double fill);
00412 GRUEL_API pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
00413 GRUEL_API pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
00414 
00415 GRUEL_API pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
00416 GRUEL_API pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
00417 GRUEL_API pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
00418 GRUEL_API pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
00419 GRUEL_API pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
00420 GRUEL_API pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
00421 GRUEL_API pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
00422 GRUEL_API pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
00423 GRUEL_API pmt_t pmt_init_f32vector(size_t k, const float *data);
00424 GRUEL_API pmt_t pmt_init_f64vector(size_t k, const double *data);
00425 GRUEL_API pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
00426 GRUEL_API pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
00427 
00428 GRUEL_API uint8_t  pmt_u8vector_ref(pmt_t v, size_t k);
00429 GRUEL_API int8_t   pmt_s8vector_ref(pmt_t v, size_t k);
00430 GRUEL_API uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
00431 GRUEL_API int16_t  pmt_s16vector_ref(pmt_t v, size_t k);
00432 GRUEL_API uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
00433 GRUEL_API int32_t  pmt_s32vector_ref(pmt_t v, size_t k);
00434 GRUEL_API uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
00435 GRUEL_API int64_t  pmt_s64vector_ref(pmt_t v, size_t k);
00436 GRUEL_API float    pmt_f32vector_ref(pmt_t v, size_t k);
00437 GRUEL_API double   pmt_f64vector_ref(pmt_t v, size_t k);
00438 GRUEL_API std::complex<float>  pmt_c32vector_ref(pmt_t v, size_t k);
00439 GRUEL_API std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
00440 
00441 GRUEL_API void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x);  //< v[k] = x
00442 GRUEL_API void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
00443 GRUEL_API void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
00444 GRUEL_API void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
00445 GRUEL_API void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
00446 GRUEL_API void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
00447 GRUEL_API void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
00448 GRUEL_API void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
00449 GRUEL_API void pmt_f32vector_set(pmt_t v, size_t k, float x);
00450 GRUEL_API void pmt_f64vector_set(pmt_t v, size_t k, double x);
00451 GRUEL_API void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
00452 GRUEL_API void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
00453 
00454 // Return const pointers to the elements
00455 
00456 GRUEL_API const void *pmt_uniform_vector_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
00457 
00458 GRUEL_API const uint8_t  *pmt_u8vector_elements(pmt_t v, size_t &len);  //< len is in elements
00459 GRUEL_API const int8_t   *pmt_s8vector_elements(pmt_t v, size_t &len);  //< len is in elements
00460 GRUEL_API const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
00461 GRUEL_API const int16_t  *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
00462 GRUEL_API const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
00463 GRUEL_API const int32_t  *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
00464 GRUEL_API const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
00465 GRUEL_API const int64_t  *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
00466 GRUEL_API const float    *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
00467 GRUEL_API const double   *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
00468 GRUEL_API const std::complex<float>  *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
00469 GRUEL_API const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
00470 
00471 // Return non-const pointers to the elements
00472 
00473 GRUEL_API void *pmt_uniform_vector_writable_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
00474 
00475 GRUEL_API uint8_t  *pmt_u8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
00476 GRUEL_API int8_t   *pmt_s8vector_writable_elements(pmt_t v, size_t &len);  //< len is in elements
00477 GRUEL_API uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00478 GRUEL_API int16_t  *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00479 GRUEL_API uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00480 GRUEL_API int32_t  *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00481 GRUEL_API uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00482 GRUEL_API int64_t  *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00483 GRUEL_API float    *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00484 GRUEL_API double   *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00485 GRUEL_API std::complex<float>  *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00486 GRUEL_API std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
00487 
00488 /*
00489  * ------------------------------------------------------------------------
00490  *         Dictionary (a.k.a associative array, hash, map)
00491  *
00492  * This is a functional data structure that is persistent.  Updating a
00493  * functional data structure does not destroy the existing version, but
00494  * rather creates a new version that coexists with the old.
00495  * ------------------------------------------------------------------------
00496  */
00497 
00498 //! Return true if \p obj is a dictionary
00499 GRUEL_API bool pmt_is_dict(const pmt_t &obj);
00500 
00501 //! Make an empty dictionary
00502 GRUEL_API pmt_t pmt_make_dict();
00503 
00504 //! Return a new dictionary with \p key associated with \p value.
00505 GRUEL_API pmt_t pmt_dict_add(const pmt_t &dict, const pmt_t &key, const pmt_t &value);
00506 
00507 //! Return a new dictionary with \p key removed.
00508 GRUEL_API pmt_t pmt_dict_delete(const pmt_t &dict, const pmt_t &key);
00509 
00510 //! Return true if \p key exists in \p dict
00511 GRUEL_API bool  pmt_dict_has_key(const pmt_t &dict, const pmt_t &key);
00512 
00513 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
00514 GRUEL_API pmt_t pmt_dict_ref(const pmt_t &dict, const pmt_t &key, const pmt_t &not_found);
00515 
00516 //! Return list of (key . value) pairs
00517 GRUEL_API pmt_t pmt_dict_items(pmt_t dict);
00518 
00519 //! Return list of keys
00520 GRUEL_API pmt_t pmt_dict_keys(pmt_t dict);
00521 
00522 //! Return list of values
00523 GRUEL_API pmt_t pmt_dict_values(pmt_t dict);
00524 
00525 /*
00526  * ------------------------------------------------------------------------
00527  *   Any (wraps boost::any -- can be used to wrap pretty much anything)
00528  *
00529  * Cannot be serialized or used across process boundaries.
00530  * See http://www.boost.org/doc/html/any.html
00531  * ------------------------------------------------------------------------
00532  */
00533 
00534 //! Return true if \p obj is an any
00535 GRUEL_API bool pmt_is_any(pmt_t obj);
00536 
00537 //! make an any
00538 GRUEL_API pmt_t pmt_make_any(const boost::any &any);
00539 
00540 //! Return underlying boost::any
00541 GRUEL_API boost::any pmt_any_ref(pmt_t obj);
00542 
00543 //! Store \p any in \p obj
00544 GRUEL_API void pmt_any_set(pmt_t obj, const boost::any &any);
00545 
00546 
00547 /*
00548  * ------------------------------------------------------------------------
00549  *    msg_accepter -- pmt representation of gruel::msg_accepter
00550  * ------------------------------------------------------------------------
00551  */
00552 //! Return true if \p obj is a msg_accepter
00553 GRUEL_API bool pmt_is_msg_accepter(const pmt_t &obj);
00554 
00555 //! make a msg_accepter
00556 GRUEL_API pmt_t pmt_make_msg_accepter(boost::shared_ptr<gruel::msg_accepter> ma);
00557 
00558 //! Return underlying msg_accepter
00559 GRUEL_API boost::shared_ptr<gruel::msg_accepter> pmt_msg_accepter_ref(const pmt_t &obj);
00560 
00561 /*
00562  * ------------------------------------------------------------------------
00563  *                        General functions
00564  * ------------------------------------------------------------------------
00565  */
00566 
00567 //! Return true if x and y are the same object; otherwise return false.
00568 GRUEL_API bool pmt_eq(const pmt_t& x, const pmt_t& y);
00569 
00570 /*!
00571  * \brief Return true if x and y should normally be regarded as the same object, else false.
00572  *
00573  * <pre>
00574  * eqv returns true if:
00575  *   x and y are the same object.
00576  *   x and y are both \#t or both \#f.
00577  *   x and y are both symbols and their names are the same.
00578  *   x and y are both numbers, and are numerically equal.
00579  *   x and y are both the empty list (nil).
00580  *   x and y are pairs or vectors that denote same location in store.
00581  * </pre>
00582  */
00583 GRUEL_API bool pmt_eqv(const pmt_t& x, const pmt_t& y);
00584 
00585 /*!
00586  * pmt_equal recursively compares the contents of pairs and vectors,
00587  * applying pmt_eqv on other objects such as numbers and symbols.
00588  * pmt_equal may fail to terminate if its arguments are circular data
00589  * structures.
00590  */
00591 GRUEL_API bool pmt_equal(const pmt_t& x, const pmt_t& y);
00592 
00593 
00594 //! Return the number of elements in v
00595 GRUEL_API size_t pmt_length(const pmt_t& v);
00596 
00597 /*!
00598  * \brief Find the first pair in \p alist whose car field is \p obj
00599  *  and return that pair.
00600  *
00601  * \p alist (for "association list") must be a list of pairs.  If no pair
00602  * in \p alist has \p obj as its car then \#f is returned.
00603  * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
00604  */
00605 GRUEL_API pmt_t pmt_assq(pmt_t obj, pmt_t alist);
00606 
00607 /*!
00608  * \brief Find the first pair in \p alist whose car field is \p obj
00609  *  and return that pair.
00610  *
00611  * \p alist (for "association list") must be a list of pairs.  If no pair
00612  * in \p alist has \p obj as its car then \#f is returned.
00613  * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
00614  */
00615 GRUEL_API pmt_t pmt_assv(pmt_t obj, pmt_t alist);
00616 
00617 /*!
00618  * \brief Find the first pair in \p alist whose car field is \p obj
00619  *  and return that pair.
00620  *
00621  * \p alist (for "association list") must be a list of pairs.  If no pair
00622  * in \p alist has \p obj as its car then \#f is returned.
00623  * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
00624  */
00625 GRUEL_API pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
00626 
00627 /*!
00628  * \brief Apply \p proc element-wise to the elements of list and returns
00629  * a list of the results, in order.
00630  *
00631  * \p list must be a list.  The dynamic order in which \p proc is
00632  * applied to the elements of \p list is unspecified.
00633  */
00634 GRUEL_API pmt_t pmt_map(pmt_t proc(const pmt_t&), pmt_t list);
00635 
00636 /*!
00637  * \brief reverse \p list.
00638  *
00639  * \p list must be a proper list.
00640  */
00641 GRUEL_API pmt_t pmt_reverse(pmt_t list);
00642 
00643 /*!
00644  * \brief destructively reverse \p list.
00645  *
00646  * \p list must be a proper list.
00647  */
00648 GRUEL_API pmt_t pmt_reverse_x(pmt_t list);
00649 
00650 /*!
00651  * \brief (acons x y a) == (cons (cons x y) a)
00652  */
00653 inline static pmt_t
00654 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
00655 {
00656   return pmt_cons(pmt_cons(x, y), a);
00657 }
00658 
00659 /*!
00660  * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
00661  */
00662 GRUEL_API pmt_t pmt_nth(size_t n, pmt_t list);
00663 
00664 /*!
00665  * \brief returns the tail of \p list that would be obtained by calling
00666  * cdr \p n times in succession.
00667  */
00668 GRUEL_API pmt_t pmt_nthcdr(size_t n, pmt_t list);
00669 
00670 /*!
00671  * \brief Return the first sublist of \p list whose car is \p obj.
00672  * If \p obj does not occur in \p list, then \#f is returned.
00673  * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
00674  */
00675 GRUEL_API pmt_t pmt_memq(pmt_t obj, pmt_t list);
00676 
00677 /*!
00678  * \brief Return the first sublist of \p list whose car is \p obj.
00679  * If \p obj does not occur in \p list, then \#f is returned.
00680  * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
00681  */
00682 GRUEL_API pmt_t pmt_memv(pmt_t obj, pmt_t list);
00683 
00684 /*!
00685  * \brief Return the first sublist of \p list whose car is \p obj.
00686  * If \p obj does not occur in \p list, then \#f is returned.
00687  * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
00688  */
00689 GRUEL_API pmt_t pmt_member(pmt_t obj, pmt_t list);
00690 
00691 /*!
00692  * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
00693  * Comparisons are done with pmt_eqv.
00694  */
00695 GRUEL_API bool pmt_subsetp(pmt_t list1, pmt_t list2);
00696 
00697 /*!
00698  * \brief Return a list of length 1 containing \p x1
00699  */
00700 GRUEL_API pmt_t pmt_list1(const pmt_t& x1);
00701 
00702 /*!
00703  * \brief Return a list of length 2 containing \p x1, \p x2
00704  */
00705 GRUEL_API pmt_t pmt_list2(const pmt_t& x1, const pmt_t& x2);
00706 
00707 /*!
00708  * \brief Return a list of length 3 containing \p x1, \p x2, \p x3
00709  */
00710 GRUEL_API pmt_t pmt_list3(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3);
00711 
00712 /*!
00713  * \brief Return a list of length 4 containing \p x1, \p x2, \p x3, \p x4
00714  */
00715 GRUEL_API pmt_t pmt_list4(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4);
00716 
00717 /*!
00718  * \brief Return a list of length 5 containing \p x1, \p x2, \p x3, \p x4, \p x5
00719  */
00720 GRUEL_API pmt_t pmt_list5(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4, const pmt_t& x5);
00721 
00722 /*!
00723  * \brief Return a list of length 6 containing \p x1, \p x2, \p x3, \p x4, \p
00724  * x5, \p x6
00725  */
00726 GRUEL_API 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);
00727 
00728 /*!
00729  * \brief Return \p list with \p item added to it.
00730  */
00731 GRUEL_API pmt_t pmt_list_add(pmt_t list, const pmt_t& item);
00732 
00733 
00734 /*
00735  * ------------------------------------------------------------------------
00736  *                           read / write
00737  * ------------------------------------------------------------------------
00738  */
00739 extern GRUEL_API const pmt_t PMT_EOF;   //< The end of file object
00740 
00741 //! return true if obj is the EOF object, otherwise return false.
00742 GRUEL_API bool pmt_is_eof_object(pmt_t obj);
00743 
00744 /*!
00745  * read converts external representations of pmt objects into the
00746  * objects themselves.  Read returns the next object parsable from
00747  * the given input port, updating port to point to the first
00748  * character past the end of the external representation of the
00749  * object.
00750  *
00751  * If an end of file is encountered in the input before any
00752  * characters are found that can begin an object, then an end of file
00753  * object is returned.   The port remains open, and further attempts
00754  * to read will also return an end of file object.  If an end of file
00755  * is encountered after the beginning of an object's external
00756  * representation, but the external representation is incomplete and
00757  * therefore not parsable, an error is signaled.
00758  */
00759 GRUEL_API pmt_t pmt_read(std::istream &port);
00760 
00761 /*!
00762  * Write a written representation of \p obj to the given \p port.
00763  */
00764 GRUEL_API void pmt_write(pmt_t obj, std::ostream &port);
00765 
00766 /*!
00767  * Return a string representation of \p obj.
00768  * This is the same output as would be generated by pmt_write.
00769  */
00770 GRUEL_API std::string pmt_write_string(pmt_t obj);
00771 
00772 
00773 GRUEL_API std::ostream& operator<<(std::ostream &os, pmt_t obj);
00774 
00775 /*!
00776  * \brief Write pmt string representation to stdout.
00777  */
00778 GRUEL_API void pmt_print(pmt_t v);
00779 
00780 
00781 /*
00782  * ------------------------------------------------------------------------
00783  *                    portable byte stream representation
00784  * ------------------------------------------------------------------------
00785  */
00786 /*!
00787  * \brief Write portable byte-serial representation of \p obj to \p sink
00788  */
00789 GRUEL_API bool pmt_serialize(pmt_t obj, std::streambuf &sink);
00790 
00791 /*!
00792  * \brief Create obj from portable byte-serial representation
00793  */
00794 GRUEL_API pmt_t pmt_deserialize(std::streambuf &source);
00795 
00796 
00797 GRUEL_API void pmt_dump_sizeof();       // debugging
00798 
00799 /*!
00800  * \brief Provide a simple string generating interface to pmt's serialize function
00801  */
00802 GRUEL_API std::string pmt_serialize_str(pmt_t obj);
00803 
00804 /*!
00805  * \brief Provide a simple string generating interface to pmt's deserialize function
00806  */
00807 GRUEL_API pmt_t pmt_deserialize_str(std::string str);
00808 
00809 /*
00810  * ------------------------------------------------------------------------
00811  *                    advanced
00812  * ------------------------------------------------------------------------
00813  */
00814 
00815 #define GRUEL_PMT_HAVE_PMT_SET_DELETER
00816 
00817 /*!
00818  * Set a deleter function to be called when the PMT dereferences.
00819  * User beware! This function is for extremely advanced use.
00820  * Use boost bind to bind extra parameters into the deleter function.
00821  * Set an empty function type to reset the PMT to the default deleter.
00822  * \param obj the pmt object in which to set the deleter function
00823  * \param deleter a function that gets an opaque PMT pointer type
00824  */
00825 GRUEL_API void pmt_set_deleter(pmt_t obj, boost::function<void(pmt_base *)> &deleter);
00826 
00827 } /* namespace pmt */
00828 
00829 #include <gruel/pmt_sugar.h>
00830 
00831 #endif /* INCLUDED_PMT_H */