GNU Radio 3.6.4 C++ API
pmt.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2006,2009,2010 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * GNU Radio is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 3, or (at your option)
10  * any later version.
11  *
12  * GNU Radio is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with GNU Radio; see the file COPYING. If not, write to
19  * the Free Software Foundation, Inc., 51 Franklin Street,
20  * Boston, MA 02110-1301, USA.
21  */
22 
23 #ifndef INCLUDED_PMT_H
24 #define INCLUDED_PMT_H
25 
26 #include <gruel/api.h>
27 #include <boost/intrusive_ptr.hpp>
28 #include <boost/shared_ptr.hpp>
29 #include <boost/any.hpp>
30 #include <complex>
31 #include <string>
32 #include <stdint.h>
33 #include <iosfwd>
34 #include <stdexcept>
35 #include <vector>
36 
37 namespace gruel {
38  class msg_accepter;
39 };
40 
41 /*!
42  * This file defines a polymorphic type and the operations on it.
43  *
44  * It draws heavily on the idea of scheme and lisp data types.
45  * The interface parallels that in Guile 1.8, with the notable
46  * exception that these objects are transparently reference counted.
47  */
48 
49 namespace pmt {
50 
51 /*!
52  * \brief base class of all pmt types
53  */
54 class pmt_base;
55 
56 /*!
57  * \brief typedef for shared pointer (transparent reference counting).
58  * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
59  */
60 typedef boost::intrusive_ptr<pmt_base> pmt_t;
61 
64 
65 class GRUEL_API pmt_exception : public std::logic_error
66 {
67 public:
68  pmt_exception(const std::string &msg, pmt_t obj);
69 };
70 
72 {
73 public:
74  pmt_wrong_type(const std::string &msg, pmt_t obj);
75 };
76 
78 {
79 public:
80  pmt_out_of_range(const std::string &msg, pmt_t obj);
81 };
82 
84 {
85 public:
86  pmt_notimplemented(const std::string &msg, pmt_t obj);
87 };
88 
89 /*
90  * ------------------------------------------------------------------------
91  * Booleans. Two constants, #t and #f.
92  *
93  * In predicates, anything that is not #f is considered true.
94  * I.e., there is a single false value, #f.
95  * ------------------------------------------------------------------------
96  */
97 extern GRUEL_API const pmt_t PMT_T; //< \#t : boolean true constant
98 extern GRUEL_API const pmt_t PMT_F; //< \#f : boolean false constant
99 
100 //! Return true if obj is \#t or \#f, else return false.
101 GRUEL_API bool pmt_is_bool(pmt_t obj);
102 
103 //! Return false if obj is \#f, else return true.
104 GRUEL_API bool pmt_is_true(pmt_t obj);
105 
106 //! Return true if obj is \#f, else return true.
107 GRUEL_API bool pmt_is_false(pmt_t obj);
108 
109 //! Return \#f is val is false, else return \#t.
110 GRUEL_API pmt_t pmt_from_bool(bool val);
111 
112 //! Return true if val is PMT_T, return false when val is PMT_F,
113 // else raise wrong_type exception.
114 GRUEL_API bool pmt_to_bool(pmt_t val);
115 
116 /*
117  * ------------------------------------------------------------------------
118  * Symbols
119  * ------------------------------------------------------------------------
120  */
121 
122 //! Return true if obj is a symbol, else false.
123 GRUEL_API bool pmt_is_symbol(const pmt_t& obj);
124 
125 //! Return the symbol whose name is \p s.
126 GRUEL_API pmt_t pmt_string_to_symbol(const std::string &s);
127 
128 //! Alias for pmt_string_to_symbol
129 GRUEL_API pmt_t pmt_intern(const std::string &s);
130 
131 
132 /*!
133  * If \p is a symbol, return the name of the symbol as a string.
134  * Otherwise, raise the wrong_type exception.
135  */
136 GRUEL_API const std::string pmt_symbol_to_string(const pmt_t& sym);
137 
138 /*
139  * ------------------------------------------------------------------------
140  * Numbers: we support integer, real and complex
141  * ------------------------------------------------------------------------
142  */
143 
144 //! Return true if obj is any kind of number, else false.
145 GRUEL_API bool pmt_is_number(pmt_t obj);
146 
147 /*
148  * ------------------------------------------------------------------------
149  * Integers
150  * ------------------------------------------------------------------------
151  */
152 
153 //! Return true if \p x is an integer number, else false
155 
156 //! Return the pmt value that represents the integer \p x.
158 
159 /*!
160  * \brief Convert pmt to long if possible.
161  *
162  * When \p x represents an exact integer that fits in a long,
163  * return that integer. Else raise an exception, either wrong_type
164  * when x is not an exact integer, or out_of_range when it doesn't fit.
165  */
166 GRUEL_API long pmt_to_long(pmt_t x);
167 
168 /*
169  * ------------------------------------------------------------------------
170  * uint64_t
171  * ------------------------------------------------------------------------
172  */
173 
174 //! Return true if \p x is an uint64 number, else false
176 
177 //! Return the pmt value that represents the uint64 \p x.
179 
180 /*!
181  * \brief Convert pmt to uint64 if possible.
182  *
183  * When \p x represents an exact integer that fits in a uint64,
184  * return that uint64. Else raise an exception, either wrong_type
185  * when x is not an exact uint64, or out_of_range when it doesn't fit.
186  */
188 
189 /*
190  * ------------------------------------------------------------------------
191  * Reals
192  * ------------------------------------------------------------------------
193  */
194 
195 /*
196  * \brief Return true if \p obj is a real number, else false.
197  */
198 GRUEL_API bool pmt_is_real(pmt_t obj);
199 
200 //! Return the pmt value that represents double \p x.
202 
203 /*!
204  * \brief Convert pmt to double if possible.
205  *
206  * Returns the number closest to \p val that is representable
207  * as a double. The argument \p val must be a real or integer, otherwise
208  * a wrong_type exception is raised.
209  */
210 GRUEL_API double pmt_to_double(pmt_t x);
211 
212 /*
213  * ------------------------------------------------------------------------
214  * Complex
215  * ------------------------------------------------------------------------
216  */
217 
218 /*!
219  * \brief return true if \p obj is a complex number, false otherwise.
220  */
221 GRUEL_API bool pmt_is_complex(pmt_t obj);
222 
223 //! Return a complex number constructed of the given real and imaginary parts.
224 GRUEL_API pmt_t pmt_make_rectangular(double re, double im);
225 
226 //! Return a complex number constructed of the given real and imaginary parts.
227 GRUEL_API pmt_t pmt_from_complex(double re, double im);
228 
229 //! Return a complex number constructed of the given a complex number.
230 GRUEL_API pmt_t pmt_from_complex(const std::complex<double> &z);
231 
232 /*!
233  * If \p z is complex, real or integer, return the closest complex<double>.
234  * Otherwise, raise the wrong_type exception.
235  */
236 GRUEL_API std::complex<double> pmt_to_complex(pmt_t z);
237 
238 /*
239  * ------------------------------------------------------------------------
240  * Pairs
241  * ------------------------------------------------------------------------
242  */
243 
244 extern GRUEL_API const pmt_t PMT_NIL; //< the empty list
245 
246 //! Return true if \p x is the empty list, otherwise return false.
247 GRUEL_API bool pmt_is_null(const pmt_t& x);
248 
249 //! Return true if \p obj is a pair, else false.
250 GRUEL_API bool pmt_is_pair(const pmt_t& obj);
251 
252 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
253 GRUEL_API pmt_t pmt_cons(const pmt_t& x, const pmt_t& y);
254 
255 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
256 GRUEL_API pmt_t pmt_car(const pmt_t& pair);
257 
258 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
259 GRUEL_API pmt_t pmt_cdr(const pmt_t& pair);
260 
261 //! Stores \p value in the car field of \p pair.
262 GRUEL_API void pmt_set_car(pmt_t pair, pmt_t value);
263 
264 //! Stores \p value in the cdr field of \p pair.
265 GRUEL_API void pmt_set_cdr(pmt_t pair, pmt_t value);
266 
273 
274 /*
275  * ------------------------------------------------------------------------
276  * Tuples
277  *
278  * Store a fixed number of objects. Tuples are not modifiable, and thus
279  * are excellent for use as messages. Indexing is zero based.
280  * Access time to an element is O(1).
281  * ------------------------------------------------------------------------
282  */
283 
284 //! Return true if \p x is a tuple, othewise false.
286 
289 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1);
290 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2);
291 GRUEL_API pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3);
292 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);
293 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);
294 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);
295 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);
296 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);
297 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);
298 
299 /*!
300  * If \p x is a vector or proper list, return a tuple containing the elements of x
301  */
303 
304 /*!
305  * Return the contents of position \p k of \p tuple.
306  * \p k must be a valid index of \p tuple.
307  */
308 GRUEL_API pmt_t pmt_tuple_ref(const pmt_t &tuple, size_t k);
309 
310 /*
311  * ------------------------------------------------------------------------
312  * Vectors
313  *
314  * These vectors can hold any kind of objects. Indexing is zero based.
315  * ------------------------------------------------------------------------
316  */
317 
318 //! Return true if \p x is a vector, othewise false.
320 
321 //! Make a vector of length \p k, with initial values set to \p fill
322 GRUEL_API pmt_t pmt_make_vector(size_t k, pmt_t fill);
323 
324 /*!
325  * Return the contents of position \p k of \p vector.
326  * \p k must be a valid index of \p vector.
327  */
328 GRUEL_API pmt_t pmt_vector_ref(pmt_t vector, size_t k);
329 
330 //! Store \p obj in position \p k.
331 GRUEL_API void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
332 
333 //! Store \p fill in every position of \p vector
334 GRUEL_API void pmt_vector_fill(pmt_t vector, pmt_t fill);
335 
336 /*
337  * ------------------------------------------------------------------------
338  * Binary Large Objects (BLOBs)
339  *
340  * Handy for passing around uninterpreted chunks of memory.
341  * ------------------------------------------------------------------------
342  */
343 
344 //! Return true if \p x is a blob, othewise false.
345 GRUEL_API bool pmt_is_blob(pmt_t x);
346 
347 /*!
348  * \brief Make a blob given a pointer and length in bytes
349  *
350  * \param buf is the pointer to data to use to create blob
351  * \param len is the size of the data in bytes.
352  *
353  * The data is copied into the blob.
354  */
355 GRUEL_API pmt_t pmt_make_blob(const void *buf, size_t len);
356 
357 //! Return a pointer to the blob's data
358 GRUEL_API const void *pmt_blob_data(pmt_t blob);
359 
360 //! Return the blob's length in bytes
361 GRUEL_API size_t pmt_blob_length(pmt_t blob);
362 
363 /*!
364  * <pre>
365  * ------------------------------------------------------------------------
366  * Uniform Numeric Vectors
367  *
368  * A uniform numeric vector is a vector whose elements are all of single
369  * numeric type. pmt offers uniform numeric vectors for signed and
370  * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
371  * floating point values, and complex floating-point numbers of these
372  * two sizes. Indexing is zero based.
373  *
374  * The names of the functions include these tags in their names:
375  *
376  * u8 unsigned 8-bit integers
377  * s8 signed 8-bit integers
378  * u16 unsigned 16-bit integers
379  * s16 signed 16-bit integers
380  * u32 unsigned 32-bit integers
381  * s32 signed 32-bit integers
382  * u64 unsigned 64-bit integers
383  * s64 signed 64-bit integers
384  * f32 the C++ type float
385  * f64 the C++ type double
386  * c32 the C++ type complex<float>
387  * c64 the C++ type complex<double>
388  * ------------------------------------------------------------------------
389  * </pre>
390  */
391 
392 //! true if \p x is any kind of uniform numeric vector
394 
407 
408 GRUEL_API pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
409 GRUEL_API pmt_t pmt_make_s8vector(size_t k, int8_t fill);
411 GRUEL_API pmt_t pmt_make_s16vector(size_t k, int16_t fill);
413 GRUEL_API pmt_t pmt_make_s32vector(size_t k, int32_t fill);
415 GRUEL_API pmt_t pmt_make_s64vector(size_t k, int64_t fill);
416 GRUEL_API pmt_t pmt_make_f32vector(size_t k, float fill);
417 GRUEL_API pmt_t pmt_make_f64vector(size_t k, double fill);
418 GRUEL_API pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
419 GRUEL_API pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
420 
421 GRUEL_API pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
422 GRUEL_API pmt_t pmt_init_u8vector(size_t k, const std::vector<uint8_t> &data);
423 GRUEL_API pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
424 GRUEL_API pmt_t pmt_init_s8vector(size_t k, const std::vector<int8_t> &data);
425 GRUEL_API pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
426 GRUEL_API pmt_t pmt_init_u16vector(size_t k, const std::vector<uint16_t> &data);
427 GRUEL_API pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
428 GRUEL_API pmt_t pmt_init_s16vector(size_t k, const std::vector<int16_t> &data);
429 GRUEL_API pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
430 GRUEL_API pmt_t pmt_init_u32vector(size_t k, const std::vector<uint32_t> &data);
431 GRUEL_API pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
432 GRUEL_API pmt_t pmt_init_s32vector(size_t k, const std::vector<int32_t> &data);
433 GRUEL_API pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
434 GRUEL_API pmt_t pmt_init_u64vector(size_t k, const std::vector<uint64_t> &data);
435 GRUEL_API pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
436 GRUEL_API pmt_t pmt_init_s64vector(size_t k, const std::vector<int64_t> &data);
437 GRUEL_API pmt_t pmt_init_f32vector(size_t k, const float *data);
438 GRUEL_API pmt_t pmt_init_f32vector(size_t k, const std::vector<float> &data);
439 GRUEL_API pmt_t pmt_init_f64vector(size_t k, const double *data);
440 GRUEL_API pmt_t pmt_init_f64vector(size_t k, const std::vector<double> &data);
441 GRUEL_API pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
442 GRUEL_API pmt_t pmt_init_c32vector(size_t k, const std::vector<std::complex<float> > &data);
443 GRUEL_API pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
444 GRUEL_API pmt_t pmt_init_c64vector(size_t k, const std::vector<std::complex<double> > &data);
445 
454 GRUEL_API float pmt_f32vector_ref(pmt_t v, size_t k);
455 GRUEL_API double pmt_f64vector_ref(pmt_t v, size_t k);
456 GRUEL_API std::complex<float> pmt_c32vector_ref(pmt_t v, size_t k);
457 GRUEL_API std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
458 
459 GRUEL_API void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x); //< v[k] = x
460 GRUEL_API void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
461 GRUEL_API void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
462 GRUEL_API void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
463 GRUEL_API void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
464 GRUEL_API void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
465 GRUEL_API void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
466 GRUEL_API void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
467 GRUEL_API void pmt_f32vector_set(pmt_t v, size_t k, float x);
468 GRUEL_API void pmt_f64vector_set(pmt_t v, size_t k, double x);
469 GRUEL_API void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
470 GRUEL_API void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
471 
472 // Return const pointers to the elements
473 
474 GRUEL_API const void *pmt_uniform_vector_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
475 
476 GRUEL_API const uint8_t *pmt_u8vector_elements(pmt_t v, size_t &len); //< len is in elements
477 GRUEL_API const int8_t *pmt_s8vector_elements(pmt_t v, size_t &len); //< len is in elements
478 GRUEL_API const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
479 GRUEL_API const int16_t *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
480 GRUEL_API const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
481 GRUEL_API const int32_t *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
482 GRUEL_API const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
483 GRUEL_API const int64_t *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
484 GRUEL_API const float *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
485 GRUEL_API const double *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
486 GRUEL_API const std::complex<float> *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
487 GRUEL_API const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
488 
489 // len is in elements
490 GRUEL_API const std::vector<uint8_t> pmt_u8vector_elements(pmt_t v);
491 GRUEL_API const std::vector<int8_t> pmt_s8vector_elements(pmt_t v);
492 GRUEL_API const std::vector<uint16_t> pmt_u16vector_elements(pmt_t v);
493 GRUEL_API const std::vector<int16_t> pmt_s16vector_elements(pmt_t v);
494 GRUEL_API const std::vector<uint32_t> pmt_u32vector_elements(pmt_t v);
495 GRUEL_API const std::vector<int32_t> pmt_s32vector_elements(pmt_t v);
496 GRUEL_API const std::vector<uint64_t> pmt_u64vector_elements(pmt_t v);
497 GRUEL_API const std::vector<int64_t> pmt_s64vector_elements(pmt_t v);
498 GRUEL_API const std::vector<float> pmt_f32vector_elements(pmt_t v);
499 GRUEL_API const std::vector<double> pmt_f64vector_elements(pmt_t v);
500 GRUEL_API const std::vector<std::complex<float> > pmt_c32vector_elements(pmt_t v);
501 GRUEL_API const std::vector<std::complex<double> > pmt_c64vector_elements(pmt_t v);
502 
503 // Return non-const pointers to the elements
504 
505 GRUEL_API void *pmt_uniform_vector_writable_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
506 
507 GRUEL_API uint8_t *pmt_u8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
508 GRUEL_API int8_t *pmt_s8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
509 GRUEL_API uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
510 GRUEL_API int16_t *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
511 GRUEL_API uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
512 GRUEL_API int32_t *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
513 GRUEL_API uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
514 GRUEL_API int64_t *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
515 GRUEL_API float *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
516 GRUEL_API double *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
517 GRUEL_API std::complex<float> *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
518 GRUEL_API std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
519 
520 /*
521  * ------------------------------------------------------------------------
522  * Dictionary (a.k.a associative array, hash, map)
523  *
524  * This is a functional data structure that is persistent. Updating a
525  * functional data structure does not destroy the existing version, but
526  * rather creates a new version that coexists with the old.
527  * ------------------------------------------------------------------------
528  */
529 
530 //! Return true if \p obj is a dictionary
531 GRUEL_API bool pmt_is_dict(const pmt_t &obj);
532 
533 //! Make an empty dictionary
535 
536 //! Return a new dictionary with \p key associated with \p value.
537 GRUEL_API pmt_t pmt_dict_add(const pmt_t &dict, const pmt_t &key, const pmt_t &value);
538 
539 //! Return a new dictionary with \p key removed.
540 GRUEL_API pmt_t pmt_dict_delete(const pmt_t &dict, const pmt_t &key);
541 
542 //! Return true if \p key exists in \p dict
543 GRUEL_API bool pmt_dict_has_key(const pmt_t &dict, const pmt_t &key);
544 
545 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
546 GRUEL_API pmt_t pmt_dict_ref(const pmt_t &dict, const pmt_t &key, const pmt_t &not_found);
547 
548 //! Return list of (key . value) pairs
550 
551 //! Return list of keys
553 
554 //! Return list of values
556 
557 /*
558  * ------------------------------------------------------------------------
559  * Any (wraps boost::any -- can be used to wrap pretty much anything)
560  *
561  * Cannot be serialized or used across process boundaries.
562  * See http://www.boost.org/doc/html/any.html
563  * ------------------------------------------------------------------------
564  */
565 
566 //! Return true if \p obj is an any
567 GRUEL_API bool pmt_is_any(pmt_t obj);
568 
569 //! make an any
570 GRUEL_API pmt_t pmt_make_any(const boost::any &any);
571 
572 //! Return underlying boost::any
573 GRUEL_API boost::any pmt_any_ref(pmt_t obj);
574 
575 //! Store \p any in \p obj
576 GRUEL_API void pmt_any_set(pmt_t obj, const boost::any &any);
577 
578 
579 /*
580  * ------------------------------------------------------------------------
581  * msg_accepter -- pmt representation of gruel::msg_accepter
582  * ------------------------------------------------------------------------
583  */
584 //! Return true if \p obj is a msg_accepter
585 GRUEL_API bool pmt_is_msg_accepter(const pmt_t &obj);
586 
587 //! make a msg_accepter
589 
590 //! Return underlying msg_accepter
592 
593 /*
594  * ------------------------------------------------------------------------
595  * General functions
596  * ------------------------------------------------------------------------
597  */
598 
599 //! Return true if x and y are the same object; otherwise return false.
600 GRUEL_API bool pmt_eq(const pmt_t& x, const pmt_t& y);
601 
602 /*!
603  * \brief Return true if x and y should normally be regarded as the same object, else false.
604  *
605  * <pre>
606  * eqv returns true if:
607  * x and y are the same object.
608  * x and y are both \#t or both \#f.
609  * x and y are both symbols and their names are the same.
610  * x and y are both numbers, and are numerically equal.
611  * x and y are both the empty list (nil).
612  * x and y are pairs or vectors that denote same location in store.
613  * </pre>
614  */
615 GRUEL_API bool pmt_eqv(const pmt_t& x, const pmt_t& y);
616 
617 /*!
618  * pmt_equal recursively compares the contents of pairs and vectors,
619  * applying pmt_eqv on other objects such as numbers and symbols.
620  * pmt_equal may fail to terminate if its arguments are circular data
621  * structures.
622  */
623 GRUEL_API bool pmt_equal(const pmt_t& x, const pmt_t& y);
624 
625 
626 //! Return the number of elements in v
627 GRUEL_API size_t pmt_length(const pmt_t& v);
628 
629 /*!
630  * \brief Find the first pair in \p alist whose car field is \p obj
631  * and return that pair.
632  *
633  * \p alist (for "association list") must be a list of pairs. If no pair
634  * in \p alist has \p obj as its car then \#f is returned.
635  * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
636  */
637 GRUEL_API pmt_t pmt_assq(pmt_t obj, pmt_t alist);
638 
639 /*!
640  * \brief Find the first pair in \p alist whose car field is \p obj
641  * and return that pair.
642  *
643  * \p alist (for "association list") must be a list of pairs. If no pair
644  * in \p alist has \p obj as its car then \#f is returned.
645  * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
646  */
647 GRUEL_API pmt_t pmt_assv(pmt_t obj, pmt_t alist);
648 
649 /*!
650  * \brief Find the first pair in \p alist whose car field is \p obj
651  * and return that pair.
652  *
653  * \p alist (for "association list") must be a list of pairs. If no pair
654  * in \p alist has \p obj as its car then \#f is returned.
655  * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
656  */
657 GRUEL_API pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
658 
659 /*!
660  * \brief Apply \p proc element-wise to the elements of list and returns
661  * a list of the results, in order.
662  *
663  * \p list must be a list. The dynamic order in which \p proc is
664  * applied to the elements of \p list is unspecified.
665  */
666 GRUEL_API pmt_t pmt_map(pmt_t proc(const pmt_t&), pmt_t list);
667 
668 /*!
669  * \brief reverse \p list.
670  *
671  * \p list must be a proper list.
672  */
674 
675 /*!
676  * \brief destructively reverse \p list.
677  *
678  * \p list must be a proper list.
679  */
681 
682 /*!
683  * \brief (acons x y a) == (cons (cons x y) a)
684  */
685 inline static pmt_t
687 {
688  return pmt_cons(pmt_cons(x, y), a);
689 }
690 
691 /*!
692  * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
693  */
694 GRUEL_API pmt_t pmt_nth(size_t n, pmt_t list);
695 
696 /*!
697  * \brief returns the tail of \p list that would be obtained by calling
698  * cdr \p n times in succession.
699  */
700 GRUEL_API pmt_t pmt_nthcdr(size_t n, pmt_t list);
701 
702 /*!
703  * \brief Return the first sublist of \p list whose car is \p obj.
704  * If \p obj does not occur in \p list, then \#f is returned.
705  * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
706  */
707 GRUEL_API pmt_t pmt_memq(pmt_t obj, pmt_t list);
708 
709 /*!
710  * \brief Return the first sublist of \p list whose car is \p obj.
711  * If \p obj does not occur in \p list, then \#f is returned.
712  * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
713  */
714 GRUEL_API pmt_t pmt_memv(pmt_t obj, pmt_t list);
715 
716 /*!
717  * \brief Return the first sublist of \p list whose car is \p obj.
718  * If \p obj does not occur in \p list, then \#f is returned.
719  * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
720  */
722 
723 /*!
724  * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
725  * Comparisons are done with pmt_eqv.
726  */
727 GRUEL_API bool pmt_subsetp(pmt_t list1, pmt_t list2);
728 
729 /*!
730  * \brief Return a list of length 1 containing \p x1
731  */
732 GRUEL_API pmt_t pmt_list1(const pmt_t& x1);
733 
734 /*!
735  * \brief Return a list of length 2 containing \p x1, \p x2
736  */
737 GRUEL_API pmt_t pmt_list2(const pmt_t& x1, const pmt_t& x2);
738 
739 /*!
740  * \brief Return a list of length 3 containing \p x1, \p x2, \p x3
741  */
742 GRUEL_API pmt_t pmt_list3(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3);
743 
744 /*!
745  * \brief Return a list of length 4 containing \p x1, \p x2, \p x3, \p x4
746  */
747 GRUEL_API pmt_t pmt_list4(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4);
748 
749 /*!
750  * \brief Return a list of length 5 containing \p x1, \p x2, \p x3, \p x4, \p x5
751  */
752 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);
753 
754 /*!
755  * \brief Return a list of length 6 containing \p x1, \p x2, \p x3, \p x4, \p
756  * x5, \p x6
757  */
758 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);
759 
760 /*!
761  * \brief Return \p list with \p item added to it.
762  */
763 GRUEL_API pmt_t pmt_list_add(pmt_t list, const pmt_t& item);
764 
765 /*!
766  * \brief Return \p list with \p item removed from it.
767  */
768 GRUEL_API pmt_t pmt_list_rm(pmt_t list, const pmt_t& item);
769 
770 /*!
771  * \brief Return bool of \p list contains \p item
772  */
773 GRUEL_API bool pmt_list_has(pmt_t list, const pmt_t& item);
774 
775 
776 /*
777  * ------------------------------------------------------------------------
778  * read / write
779  * ------------------------------------------------------------------------
780  */
781 extern GRUEL_API const pmt_t PMT_EOF; //< The end of file object
782 
783 //! return true if obj is the EOF object, otherwise return false.
785 
786 /*!
787  * read converts external representations of pmt objects into the
788  * objects themselves. Read returns the next object parsable from
789  * the given input port, updating port to point to the first
790  * character past the end of the external representation of the
791  * object.
792  *
793  * If an end of file is encountered in the input before any
794  * characters are found that can begin an object, then an end of file
795  * object is returned. The port remains open, and further attempts
796  * to read will also return an end of file object. If an end of file
797  * is encountered after the beginning of an object's external
798  * representation, but the external representation is incomplete and
799  * therefore not parsable, an error is signaled.
800  */
801 GRUEL_API pmt_t pmt_read(std::istream &port);
802 
803 /*!
804  * Write a written representation of \p obj to the given \p port.
805  */
806 GRUEL_API void pmt_write(pmt_t obj, std::ostream &port);
807 
808 /*!
809  * Return a string representation of \p obj.
810  * This is the same output as would be generated by pmt_write.
811  */
812 GRUEL_API std::string pmt_write_string(pmt_t obj);
813 
814 
815 GRUEL_API std::ostream& operator<<(std::ostream &os, pmt_t obj);
816 
817 /*!
818  * \brief Write pmt string representation to stdout.
819  */
820 GRUEL_API void pmt_print(pmt_t v);
821 
822 
823 /*
824  * ------------------------------------------------------------------------
825  * portable byte stream representation
826  * ------------------------------------------------------------------------
827  */
828 /*!
829  * \brief Write portable byte-serial representation of \p obj to \p sink
830  */
831 GRUEL_API bool pmt_serialize(pmt_t obj, std::streambuf &sink);
832 
833 /*!
834  * \brief Create obj from portable byte-serial representation
835  */
836 GRUEL_API pmt_t pmt_deserialize(std::streambuf &source);
837 
838 
839 GRUEL_API void pmt_dump_sizeof(); // debugging
840 
841 /*!
842  * \brief Provide a simple string generating interface to pmt's serialize function
843  */
844 GRUEL_API std::string pmt_serialize_str(pmt_t obj);
845 
846 /*!
847  * \brief Provide a simple string generating interface to pmt's deserialize function
848  */
849 GRUEL_API pmt_t pmt_deserialize_str(std::string str);
850 
851 /*!
852  * \brief Provide a comparator function object to allow pmt use in stl types
853  */
855  public:
856  bool operator()(pmt::pmt_t const& p1, pmt::pmt_t const& p2) const
857  { return pmt::pmt_eqv(p1,p2)?false:p1.get()>p2.get(); }
858  };
859 
860 } /* namespace pmt */
861 
862 #include <gruel/pmt_sugar.h>
863 
864 #endif /* INCLUDED_PMT_H */