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