3 * Copyright 2006,2009,2010 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
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)
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.
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.
23 #ifndef INCLUDED_PMT_H
24 #define INCLUDED_PMT_H
26 #include <boost/intrusive_ptr.hpp>
27 #include <boost/shared_ptr.hpp>
28 #include <boost/any.hpp>
40 * This file defines a polymorphic type and the operations on it.
42 * It draws heavily on the idea of scheme and lisp data types.
43 * The interface parallels that in Guile 1.8, with the notable
44 * exception that these objects are transparently reference counted.
50 * \brief base class of all pmt types
55 * \brief typedef for shared pointer (transparent reference counting).
56 * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
58 typedef boost::intrusive_ptr<pmt_base> pmt_t;
60 extern void intrusive_ptr_add_ref(pmt_base*);
61 extern void intrusive_ptr_release(pmt_base*);
63 class pmt_exception : public std::logic_error
66 pmt_exception(const std::string &msg, pmt_t obj);
69 class pmt_wrong_type : public pmt_exception
72 pmt_wrong_type(const std::string &msg, pmt_t obj);
75 class pmt_out_of_range : public pmt_exception
78 pmt_out_of_range(const std::string &msg, pmt_t obj);
81 class pmt_notimplemented : public pmt_exception
84 pmt_notimplemented(const std::string &msg, pmt_t obj);
88 * ------------------------------------------------------------------------
89 * Booleans. Two constants, #t and #f.
91 * In predicates, anything that is not #f is considered true.
92 * I.e., there is a single false value, #f.
93 * ------------------------------------------------------------------------
95 extern const pmt_t PMT_T; //< \#t : boolean true constant
96 extern const pmt_t PMT_F; //< \#f : boolean false constant
98 //! Return true if obj is \#t or \#f, else return false.
99 bool pmt_is_bool(pmt_t obj);
101 //! Return false if obj is \#f, else return true.
102 bool pmt_is_true(pmt_t obj);
104 //! Return true if obj is \#f, else return true.
105 bool pmt_is_false(pmt_t obj);
107 //! Return \#f is val is false, else return \#t.
108 pmt_t pmt_from_bool(bool val);
110 //! Return true if val is PMT_T, return false when val is PMT_F,
111 // else raise wrong_type exception.
112 bool pmt_to_bool(pmt_t val);
115 * ------------------------------------------------------------------------
117 * ------------------------------------------------------------------------
120 //! Return true if obj is a symbol, else false.
121 bool pmt_is_symbol(const pmt_t& obj);
123 //! Return the symbol whose name is \p s.
124 pmt_t pmt_string_to_symbol(const std::string &s);
126 //! Alias for pmt_string_to_symbol
127 pmt_t pmt_intern(const std::string &s);
131 * If \p is a symbol, return the name of the symbol as a string.
132 * Otherwise, raise the wrong_type exception.
134 const std::string pmt_symbol_to_string(const pmt_t& sym);
137 * ------------------------------------------------------------------------
138 * Numbers: we support integer, real and complex
139 * ------------------------------------------------------------------------
142 //! Return true if obj is any kind of number, else false.
143 bool pmt_is_number(pmt_t obj);
146 * ------------------------------------------------------------------------
148 * ------------------------------------------------------------------------
151 //! Return true if \p x is an integer number, else false
152 bool pmt_is_integer(pmt_t x);
154 //! Return the pmt value that represents the integer \p x.
155 pmt_t pmt_from_long(long x);
158 * \brief Convert pmt to long if possible.
160 * When \p x represents an exact integer that fits in a long,
161 * return that integer. Else raise an exception, either wrong_type
162 * when x is not an exact integer, or out_of_range when it doesn't fit.
164 long pmt_to_long(pmt_t x);
167 * ------------------------------------------------------------------------
169 * ------------------------------------------------------------------------
172 //! Return true if \p x is an uint64 number, else false
173 bool pmt_is_uint64(pmt_t x);
175 //! Return the pmt value that represents the uint64 \p x.
176 pmt_t pmt_from_uint64(uint64_t x);
179 * \brief Convert pmt to uint64 if possible.
181 * When \p x represents an exact integer that fits in a uint64,
182 * return that uint64. Else raise an exception, either wrong_type
183 * when x is not an exact uint64, or out_of_range when it doesn't fit.
185 uint64_t pmt_to_uint64(pmt_t x);
188 * ------------------------------------------------------------------------
190 * ------------------------------------------------------------------------
194 * \brief Return true if \p obj is a real number, else false.
196 bool pmt_is_real(pmt_t obj);
198 //! Return the pmt value that represents double \p x.
199 pmt_t pmt_from_double(double x);
202 * \brief Convert pmt to double if possible.
204 * Returns the number closest to \p val that is representable
205 * as a double. The argument \p val must be a real or integer, otherwise
206 * a wrong_type exception is raised.
208 double pmt_to_double(pmt_t x);
211 * ------------------------------------------------------------------------
213 * ------------------------------------------------------------------------
217 * \brief return true if \p obj is a complex number, false otherwise.
219 bool pmt_is_complex(pmt_t obj);
221 //! Return a complex number constructed of the given real and imaginary parts.
222 pmt_t pmt_make_rectangular(double re, double im);
225 * If \p z is complex, real or integer, return the closest complex<double>.
226 * Otherwise, raise the wrong_type exception.
228 std::complex<double> pmt_to_complex(pmt_t z);
231 * ------------------------------------------------------------------------
233 * ------------------------------------------------------------------------
236 extern const pmt_t PMT_NIL; //< the empty list
238 //! Return true if \p x is the empty list, otherwise return false.
239 bool pmt_is_null(const pmt_t& x);
241 //! Return true if \p obj is a pair, else false.
242 bool pmt_is_pair(const pmt_t& obj);
244 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
245 pmt_t pmt_cons(const pmt_t& x, const pmt_t& y);
247 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
248 pmt_t pmt_car(const pmt_t& pair);
250 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
251 pmt_t pmt_cdr(const pmt_t& pair);
253 //! Stores \p value in the car field of \p pair.
254 void pmt_set_car(pmt_t pair, pmt_t value);
256 //! Stores \p value in the cdr field of \p pair.
257 void pmt_set_cdr(pmt_t pair, pmt_t value);
259 pmt_t pmt_caar(pmt_t pair);
260 pmt_t pmt_cadr(pmt_t pair);
261 pmt_t pmt_cdar(pmt_t pair);
262 pmt_t pmt_cddr(pmt_t pair);
263 pmt_t pmt_caddr(pmt_t pair);
264 pmt_t pmt_cadddr(pmt_t pair);
267 * ------------------------------------------------------------------------
270 * Store a fixed number of objects. Tuples are not modifiable, and thus
271 * are excellent for use as messages. Indexing is zero based.
272 * Access time to an element is O(1).
273 * ------------------------------------------------------------------------
276 //! Return true if \p x is a tuple, othewise false.
277 bool pmt_is_tuple(pmt_t x);
279 pmt_t pmt_make_tuple();
280 pmt_t pmt_make_tuple(const pmt_t &e0);
281 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1);
282 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2);
283 pmt_t pmt_make_tuple(const pmt_t &e0, const pmt_t &e1, const pmt_t &e2, const pmt_t &e3);
284 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);
285 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);
286 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);
287 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);
288 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);
289 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);
292 * If \p x is a vector or proper list, return a tuple containing the elements of x
294 pmt_t pmt_to_tuple(const pmt_t &x);
297 * Return the contents of position \p k of \p tuple.
298 * \p k must be a valid index of \p tuple.
300 pmt_t pmt_tuple_ref(const pmt_t &tuple, size_t k);
303 * ------------------------------------------------------------------------
306 * These vectors can hold any kind of objects. Indexing is zero based.
307 * ------------------------------------------------------------------------
310 //! Return true if \p x is a vector, othewise false.
311 bool pmt_is_vector(pmt_t x);
313 //! Make a vector of length \p k, with initial values set to \p fill
314 pmt_t pmt_make_vector(size_t k, pmt_t fill);
317 * Return the contents of position \p k of \p vector.
318 * \p k must be a valid index of \p vector.
320 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
322 //! Store \p obj in position \p k.
323 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
325 //! Store \p fill in every position of \p vector
326 void pmt_vector_fill(pmt_t vector, pmt_t fill);
329 * ------------------------------------------------------------------------
330 * Binary Large Objects (BLOBs)
332 * Handy for passing around uninterpreted chunks of memory.
333 * ------------------------------------------------------------------------
336 //! Return true if \p x is a blob, othewise false.
337 bool pmt_is_blob(pmt_t x);
340 * \brief Make a blob given a pointer and length in bytes
342 * \param buf is the pointer to data to use to create blob
343 * \param len is the size of the data in bytes.
345 * The data is copied into the blob.
347 pmt_t pmt_make_blob(const void *buf, size_t len);
349 //! Return a pointer to the blob's data
350 const void *pmt_blob_data(pmt_t blob);
352 //! Return the blob's length in bytes
353 size_t pmt_blob_length(pmt_t blob);
357 * ------------------------------------------------------------------------
358 * Uniform Numeric Vectors
360 * A uniform numeric vector is a vector whose elements are all of single
361 * numeric type. pmt offers uniform numeric vectors for signed and
362 * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
363 * floating point values, and complex floating-point numbers of these
364 * two sizes. Indexing is zero based.
366 * The names of the functions include these tags in their names:
368 * u8 unsigned 8-bit integers
369 * s8 signed 8-bit integers
370 * u16 unsigned 16-bit integers
371 * s16 signed 16-bit integers
372 * u32 unsigned 32-bit integers
373 * s32 signed 32-bit integers
374 * u64 unsigned 64-bit integers
375 * s64 signed 64-bit integers
376 * f32 the C++ type float
377 * f64 the C++ type double
378 * c32 the C++ type complex<float>
379 * c64 the C++ type complex<double>
380 * ------------------------------------------------------------------------
384 //! true if \p x is any kind of uniform numeric vector
385 bool pmt_is_uniform_vector(pmt_t x);
387 bool pmt_is_u8vector(pmt_t x);
388 bool pmt_is_s8vector(pmt_t x);
389 bool pmt_is_u16vector(pmt_t x);
390 bool pmt_is_s16vector(pmt_t x);
391 bool pmt_is_u32vector(pmt_t x);
392 bool pmt_is_s32vector(pmt_t x);
393 bool pmt_is_u64vector(pmt_t x);
394 bool pmt_is_s64vector(pmt_t x);
395 bool pmt_is_f32vector(pmt_t x);
396 bool pmt_is_f64vector(pmt_t x);
397 bool pmt_is_c32vector(pmt_t x);
398 bool pmt_is_c64vector(pmt_t x);
400 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
401 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
402 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
403 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
404 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
405 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
406 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
407 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
408 pmt_t pmt_make_f32vector(size_t k, float fill);
409 pmt_t pmt_make_f64vector(size_t k, double fill);
410 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
411 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
413 pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
414 pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
415 pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
416 pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
417 pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
418 pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
419 pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
420 pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
421 pmt_t pmt_init_f32vector(size_t k, const float *data);
422 pmt_t pmt_init_f64vector(size_t k, const double *data);
423 pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
424 pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
426 uint8_t pmt_u8vector_ref(pmt_t v, size_t k);
427 int8_t pmt_s8vector_ref(pmt_t v, size_t k);
428 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
429 int16_t pmt_s16vector_ref(pmt_t v, size_t k);
430 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
431 int32_t pmt_s32vector_ref(pmt_t v, size_t k);
432 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
433 int64_t pmt_s64vector_ref(pmt_t v, size_t k);
434 float pmt_f32vector_ref(pmt_t v, size_t k);
435 double pmt_f64vector_ref(pmt_t v, size_t k);
436 std::complex<float> pmt_c32vector_ref(pmt_t v, size_t k);
437 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
439 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x); //< v[k] = x
440 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
441 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
442 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
443 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
444 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
445 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
446 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
447 void pmt_f32vector_set(pmt_t v, size_t k, float x);
448 void pmt_f64vector_set(pmt_t v, size_t k, double x);
449 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
450 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
452 // Return const pointers to the elements
454 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
456 const uint8_t *pmt_u8vector_elements(pmt_t v, size_t &len); //< len is in elements
457 const int8_t *pmt_s8vector_elements(pmt_t v, size_t &len); //< len is in elements
458 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
459 const int16_t *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
460 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
461 const int32_t *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
462 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
463 const int64_t *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
464 const float *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
465 const double *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
466 const std::complex<float> *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
467 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
469 // Return non-const pointers to the elements
471 void *pmt_uniform_vector_writable_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
473 uint8_t *pmt_u8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
474 int8_t *pmt_s8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
475 uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
476 int16_t *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
477 uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
478 int32_t *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
479 uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
480 int64_t *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
481 float *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
482 double *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
483 std::complex<float> *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
484 std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
487 * ------------------------------------------------------------------------
488 * Dictionary (a.k.a associative array, hash, map)
490 * This is a functional data structure that is persistent. Updating a
491 * functional data structure does not destroy the existing version, but
492 * rather creates a new version that coexists with the old.
493 * ------------------------------------------------------------------------
496 //! Return true if \p obj is a dictionary
497 bool pmt_is_dict(const pmt_t &obj);
499 //! Make an empty dictionary
500 pmt_t pmt_make_dict();
502 //! Return a new dictionary with \p key associated with \p value.
503 pmt_t pmt_dict_add(const pmt_t &dict, const pmt_t &key, const pmt_t &value);
505 //! Return a new dictionary with \p key removed.
506 pmt_t pmt_dict_delete(const pmt_t &dict, const pmt_t &key);
508 //! Return true if \p key exists in \p dict
509 bool pmt_dict_has_key(const pmt_t &dict, const pmt_t &key);
511 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
512 pmt_t pmt_dict_ref(const pmt_t &dict, const pmt_t &key, const pmt_t ¬_found);
514 //! Return list of (key . value) pairs
515 pmt_t pmt_dict_items(pmt_t dict);
517 //! Return list of keys
518 pmt_t pmt_dict_keys(pmt_t dict);
520 //! Return list of values
521 pmt_t pmt_dict_values(pmt_t dict);
524 * ------------------------------------------------------------------------
525 * Any (wraps boost::any -- can be used to wrap pretty much anything)
527 * Cannot be serialized or used across process boundaries.
528 * See http://www.boost.org/doc/html/any.html
529 * ------------------------------------------------------------------------
532 //! Return true if \p obj is an any
533 bool pmt_is_any(pmt_t obj);
536 pmt_t pmt_make_any(const boost::any &any);
538 //! Return underlying boost::any
539 boost::any pmt_any_ref(pmt_t obj);
541 //! Store \p any in \p obj
542 void pmt_any_set(pmt_t obj, const boost::any &any);
546 * ------------------------------------------------------------------------
547 * msg_accepter -- pmt representation of gruel::msg_accepter
548 * ------------------------------------------------------------------------
550 //! Return true if \p obj is a msg_accepter
551 bool pmt_is_msg_accepter(const pmt_t &obj);
553 //! make a msg_accepter
554 pmt_t pmt_make_msg_accepter(boost::shared_ptr<gruel::msg_accepter> ma);
556 //! Return underlying msg_accepter
557 boost::shared_ptr<gruel::msg_accepter> pmt_msg_accepter_ref(const pmt_t &obj);
560 * ------------------------------------------------------------------------
562 * ------------------------------------------------------------------------
565 //! Return true if x and y are the same object; otherwise return false.
566 bool pmt_eq(const pmt_t& x, const pmt_t& y);
569 * \brief Return true if x and y should normally be regarded as the same object, else false.
572 * eqv returns true if:
573 * x and y are the same object.
574 * x and y are both \#t or both \#f.
575 * x and y are both symbols and their names are the same.
576 * x and y are both numbers, and are numerically equal.
577 * x and y are both the empty list (nil).
578 * x and y are pairs or vectors that denote same location in store.
581 bool pmt_eqv(const pmt_t& x, const pmt_t& y);
584 * pmt_equal recursively compares the contents of pairs and vectors,
585 * applying pmt_eqv on other objects such as numbers and symbols.
586 * pmt_equal may fail to terminate if its arguments are circular data
589 bool pmt_equal(const pmt_t& x, const pmt_t& y);
592 //! Return the number of elements in v
593 size_t pmt_length(const pmt_t& v);
596 * \brief Find the first pair in \p alist whose car field is \p obj
597 * and return that pair.
599 * \p alist (for "association list") must be a list of pairs. If no pair
600 * in \p alist has \p obj as its car then \#f is returned.
601 * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
603 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
606 * \brief Find the first pair in \p alist whose car field is \p obj
607 * and return that pair.
609 * \p alist (for "association list") must be a list of pairs. If no pair
610 * in \p alist has \p obj as its car then \#f is returned.
611 * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
613 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
616 * \brief Find the first pair in \p alist whose car field is \p obj
617 * and return that pair.
619 * \p alist (for "association list") must be a list of pairs. If no pair
620 * in \p alist has \p obj as its car then \#f is returned.
621 * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
623 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
626 * \brief Apply \p proc element-wise to the elements of list and returns
627 * a list of the results, in order.
629 * \p list must be a list. The dynamic order in which \p proc is
630 * applied to the elements of \p list is unspecified.
632 pmt_t pmt_map(pmt_t proc(const pmt_t&), pmt_t list);
635 * \brief reverse \p list.
637 * \p list must be a proper list.
639 pmt_t pmt_reverse(pmt_t list);
642 * \brief destructively reverse \p list.
644 * \p list must be a proper list.
646 pmt_t pmt_reverse_x(pmt_t list);
649 * \brief (acons x y a) == (cons (cons x y) a)
652 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
654 return pmt_cons(pmt_cons(x, y), a);
658 * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
660 pmt_t pmt_nth(size_t n, pmt_t list);
663 * \brief returns the tail of \p list that would be obtained by calling
664 * cdr \p n times in succession.
666 pmt_t pmt_nthcdr(size_t n, pmt_t list);
669 * \brief Return the first sublist of \p list whose car is \p obj.
670 * If \p obj does not occur in \p list, then \#f is returned.
671 * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
673 pmt_t pmt_memq(pmt_t obj, pmt_t list);
676 * \brief Return the first sublist of \p list whose car is \p obj.
677 * If \p obj does not occur in \p list, then \#f is returned.
678 * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
680 pmt_t pmt_memv(pmt_t obj, pmt_t list);
683 * \brief Return the first sublist of \p list whose car is \p obj.
684 * If \p obj does not occur in \p list, then \#f is returned.
685 * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
687 pmt_t pmt_member(pmt_t obj, pmt_t list);
690 * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
691 * Comparisons are done with pmt_eqv.
693 bool pmt_subsetp(pmt_t list1, pmt_t list2);
696 * \brief Return a list of length 1 containing \p x1
698 pmt_t pmt_list1(const pmt_t& x1);
701 * \brief Return a list of length 2 containing \p x1, \p x2
703 pmt_t pmt_list2(const pmt_t& x1, const pmt_t& x2);
706 * \brief Return a list of length 3 containing \p x1, \p x2, \p x3
708 pmt_t pmt_list3(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3);
711 * \brief Return a list of length 4 containing \p x1, \p x2, \p x3, \p x4
713 pmt_t pmt_list4(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4);
716 * \brief Return a list of length 5 containing \p x1, \p x2, \p x3, \p x4, \p x5
718 pmt_t pmt_list5(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4, const pmt_t& x5);
721 * \brief Return a list of length 6 containing \p x1, \p x2, \p x3, \p x4, \p
724 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);
727 * \brief Return \p list with \p item added to it.
729 pmt_t pmt_list_add(pmt_t list, const pmt_t& item);
733 * ------------------------------------------------------------------------
735 * ------------------------------------------------------------------------
737 extern const pmt_t PMT_EOF; //< The end of file object
739 //! return true if obj is the EOF object, otherwise return false.
740 bool pmt_is_eof_object(pmt_t obj);
743 * read converts external representations of pmt objects into the
744 * objects themselves. Read returns the next object parsable from
745 * the given input port, updating port to point to the first
746 * character past the end of the external representation of the
749 * If an end of file is encountered in the input before any
750 * characters are found that can begin an object, then an end of file
751 * object is returned. The port remains open, and further attempts
752 * to read will also return an end of file object. If an end of file
753 * is encountered after the beginning of an object's external
754 * representation, but the external representation is incomplete and
755 * therefore not parsable, an error is signaled.
757 pmt_t pmt_read(std::istream &port);
760 * Write a written representation of \p obj to the given \p port.
762 void pmt_write(pmt_t obj, std::ostream &port);
765 * Return a string representation of \p obj.
766 * This is the same output as would be generated by pmt_write.
768 std::string pmt_write_string(pmt_t obj);
771 std::ostream& operator<<(std::ostream &os, pmt_t obj);
775 * ------------------------------------------------------------------------
776 * portable byte stream representation
777 * ------------------------------------------------------------------------
780 * \brief Write portable byte-serial representation of \p obj to \p sink
782 bool pmt_serialize(pmt_t obj, std::streambuf &sink);
785 * \brief Create obj from portable byte-serial representation
787 pmt_t pmt_deserialize(std::streambuf &source);
790 void pmt_dump_sizeof(); // debugging
792 } /* namespace pmt */
795 #include <gruel/pmt_sugar.h>
797 #endif /* INCLUDED_PMT_H */