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