GNU Radio v3.5.2.1-32-g7e3f4b84 C++ API
|
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 ¬_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 */