GNU Radio 3.6.0 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 #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 ¬_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 */