3 * Copyright 2006,2009 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/shared_ptr.hpp>
27 #include <boost/any.hpp>
35 * This file defines a polymorphic type and the operations on it.
37 * It draws heavily on the idea of scheme and lisp data types.
38 * The interface parallels that in Guile 1.8, with the notable
39 * exception that these objects are transparently reference counted.
45 * \brief base class of all pmt types
50 * \brief typedef for shared pointer (transparent reference counting).
51 * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
53 typedef boost::shared_ptr<pmt_base> pmt_t;
56 class pmt_exception : public std::logic_error
59 pmt_exception(const std::string &msg, pmt_t obj);
62 class pmt_wrong_type : public pmt_exception
65 pmt_wrong_type(const std::string &msg, pmt_t obj);
68 class pmt_out_of_range : public pmt_exception
71 pmt_out_of_range(const std::string &msg, pmt_t obj);
74 class pmt_notimplemented : public pmt_exception
77 pmt_notimplemented(const std::string &msg, pmt_t obj);
81 * ------------------------------------------------------------------------
82 * Booleans. Two constants, #t and #f.
84 * In predicates, anything that is not #f is considered true.
85 * I.e., there is a single false value, #f.
86 * ------------------------------------------------------------------------
88 extern const pmt_t PMT_T; //< \#t : boolean true constant
89 extern const pmt_t PMT_F; //< \#f : boolean false constant
91 //! Return true if obj is \#t or \#f, else return false.
92 bool pmt_is_bool(pmt_t obj);
94 //! Return false if obj is \#f, else return true.
95 bool pmt_is_true(pmt_t obj);
97 //! Return true if obj is \#f, else return true.
98 bool pmt_is_false(pmt_t obj);
100 //! Return \#f is val is false, else return \#t.
101 pmt_t pmt_from_bool(bool val);
103 //! Return true if val is PMT_T, return false when val is PMT_F,
104 // else raise wrong_type exception.
105 bool pmt_to_bool(pmt_t val);
108 * ------------------------------------------------------------------------
110 * ------------------------------------------------------------------------
113 //! Return true if obj is a symbol, else false.
114 bool pmt_is_symbol(const pmt_t& obj);
116 //! Return the symbol whose name is \p s.
117 pmt_t pmt_string_to_symbol(const std::string &s);
119 //! Alias for pmt_string_to_symbol
120 pmt_t pmt_intern(const std::string &s);
124 * If \p is a symbol, return the name of the symbol as a string.
125 * Otherwise, raise the wrong_type exception.
127 const std::string pmt_symbol_to_string(const pmt_t& sym);
130 * ------------------------------------------------------------------------
131 * Numbers: we support integer, real and complex
132 * ------------------------------------------------------------------------
135 //! Return true if obj is any kind of number, else false.
136 bool pmt_is_number(pmt_t obj);
139 * ------------------------------------------------------------------------
141 * ------------------------------------------------------------------------
144 //! Return true if \p x is an integer number, else false
145 bool pmt_is_integer(pmt_t x);
147 //! Return the pmt value that represents the integer \p x.
148 pmt_t pmt_from_long(long x);
151 * \brief Convert pmt to long if possible.
153 * When \p x represents an exact integer that fits in a long,
154 * return that integer. Else raise an exception, either wrong_type
155 * when x is not an exact integer, or out_of_range when it doesn't fit.
157 long pmt_to_long(pmt_t x);
160 * ------------------------------------------------------------------------
162 * ------------------------------------------------------------------------
166 * \brief Return true if \p obj is a real number, else false.
168 bool pmt_is_real(pmt_t obj);
170 //! Return the pmt value that represents double \p x.
171 pmt_t pmt_from_double(double x);
174 * \brief Convert pmt to double if possible.
176 * Returns the number closest to \p val that is representable
177 * as a double. The argument \p val must be a real or integer, otherwise
178 * a wrong_type exception is raised.
180 double pmt_to_double(pmt_t x);
183 * ------------------------------------------------------------------------
185 * ------------------------------------------------------------------------
189 * \brief return true if \p obj is a complex number, false otherwise.
191 bool pmt_is_complex(pmt_t obj);
193 //! Return a complex number constructed of the given real and imaginary parts.
194 pmt_t pmt_make_rectangular(double re, double im);
197 * If \p z is complex, real or integer, return the closest complex<double>.
198 * Otherwise, raise the wrong_type exception.
200 std::complex<double> pmt_to_complex(pmt_t z);
203 * ------------------------------------------------------------------------
205 * ------------------------------------------------------------------------
208 extern const pmt_t PMT_NIL; //< the empty list
210 //! Return true if \p x is the empty list, otherwise return false.
211 bool pmt_is_null(const pmt_t& x);
213 //! Return true if \p obj is a pair, else false.
214 bool pmt_is_pair(const pmt_t& obj);
216 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
217 pmt_t pmt_cons(const pmt_t& x, const pmt_t& y);
219 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
220 pmt_t pmt_car(const pmt_t& pair);
222 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
223 pmt_t pmt_cdr(const pmt_t& pair);
225 //! Stores \p value in the car field of \p pair.
226 void pmt_set_car(pmt_t pair, pmt_t value);
228 //! Stores \p value in the cdr field of \p pair.
229 void pmt_set_cdr(pmt_t pair, pmt_t value);
231 pmt_t pmt_caar(pmt_t pair);
232 pmt_t pmt_cadr(pmt_t pair);
233 pmt_t pmt_cdar(pmt_t pair);
234 pmt_t pmt_cddr(pmt_t pair);
235 pmt_t pmt_caddr(pmt_t pair);
236 pmt_t pmt_cadddr(pmt_t pair);
239 * ------------------------------------------------------------------------
242 * These vectors can hold any kind of objects. Indexing is zero based.
243 * ------------------------------------------------------------------------
246 //! Return true if \p x is a vector, othewise false.
247 bool pmt_is_vector(pmt_t x);
249 //! Make a vector of length \p k, with initial values set to \p fill
250 pmt_t pmt_make_vector(size_t k, pmt_t fill);
253 * Return the contents of position \p k of \p vector.
254 * \p k must be a valid index of \p vector.
256 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
258 //! Store \p obj in position \p k.
259 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
261 //! Store \p fill in every position of \p vector
262 void pmt_vector_fill(pmt_t vector, pmt_t fill);
266 * ------------------------------------------------------------------------
267 * Uniform Numeric Vectors
269 * A uniform numeric vector is a vector whose elements are all of single
270 * numeric type. pmt offers uniform numeric vectors for signed and
271 * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
272 * floating point values, and complex floating-point numbers of these
273 * two sizes. Indexing is zero based.
275 * The names of the functions include these tags in their names:
277 * u8 unsigned 8-bit integers
278 * s8 signed 8-bit integers
279 * u16 unsigned 16-bit integers
280 * s16 signed 16-bit integers
281 * u32 unsigned 32-bit integers
282 * s32 signed 32-bit integers
283 * u64 unsigned 64-bit integers
284 * s64 signed 64-bit integers
285 * f32 the C++ type float
286 * f64 the C++ type double
287 * c32 the C++ type complex<float>
288 * c64 the C++ type complex<double>
289 * ------------------------------------------------------------------------
293 //! true if \p x is any kind of uniform numeric vector
294 bool pmt_is_uniform_vector(pmt_t x);
296 bool pmt_is_u8vector(pmt_t x);
297 bool pmt_is_s8vector(pmt_t x);
298 bool pmt_is_u16vector(pmt_t x);
299 bool pmt_is_s16vector(pmt_t x);
300 bool pmt_is_u32vector(pmt_t x);
301 bool pmt_is_s32vector(pmt_t x);
302 bool pmt_is_u64vector(pmt_t x);
303 bool pmt_is_s64vector(pmt_t x);
304 bool pmt_is_f32vector(pmt_t x);
305 bool pmt_is_f64vector(pmt_t x);
306 bool pmt_is_c32vector(pmt_t x);
307 bool pmt_is_c64vector(pmt_t x);
309 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
310 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
311 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
312 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
313 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
314 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
315 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
316 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
317 pmt_t pmt_make_f32vector(size_t k, float fill);
318 pmt_t pmt_make_f64vector(size_t k, double fill);
319 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
320 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
322 pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
323 pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
324 pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
325 pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
326 pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
327 pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
328 pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
329 pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
330 pmt_t pmt_init_f32vector(size_t k, const float *data);
331 pmt_t pmt_init_f64vector(size_t k, const double *data);
332 pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
333 pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
335 uint8_t pmt_u8vector_ref(pmt_t v, size_t k);
336 int8_t pmt_s8vector_ref(pmt_t v, size_t k);
337 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
338 int16_t pmt_s16vector_ref(pmt_t v, size_t k);
339 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
340 int32_t pmt_s32vector_ref(pmt_t v, size_t k);
341 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
342 int64_t pmt_s64vector_ref(pmt_t v, size_t k);
343 float pmt_f32vector_ref(pmt_t v, size_t k);
344 double pmt_f64vector_ref(pmt_t v, size_t k);
345 std::complex<float> pmt_c32vector_ref(pmt_t v, size_t k);
346 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
348 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x); //< v[k] = x
349 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
350 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
351 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
352 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
353 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
354 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
355 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
356 void pmt_f32vector_set(pmt_t v, size_t k, float x);
357 void pmt_f64vector_set(pmt_t v, size_t k, double x);
358 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
359 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
361 // Return const pointers to the elements
363 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
365 const uint8_t *pmt_u8vector_elements(pmt_t v, size_t &len); //< len is in elements
366 const int8_t *pmt_s8vector_elements(pmt_t v, size_t &len); //< len is in elements
367 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
368 const int16_t *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
369 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
370 const int32_t *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
371 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
372 const int64_t *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
373 const float *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
374 const double *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
375 const std::complex<float> *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
376 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
378 // Return non-const pointers to the elements
380 void *pmt_uniform_vector_writable_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
382 uint8_t *pmt_u8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
383 int8_t *pmt_s8vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
384 uint16_t *pmt_u16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
385 int16_t *pmt_s16vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
386 uint32_t *pmt_u32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
387 int32_t *pmt_s32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
388 uint64_t *pmt_u64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
389 int64_t *pmt_s64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
390 float *pmt_f32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
391 double *pmt_f64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
392 std::complex<float> *pmt_c32vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
393 std::complex<double> *pmt_c64vector_writable_elements(pmt_t v, size_t &len); //< len is in elements
396 * ------------------------------------------------------------------------
397 * Dictionary (a.k.a associative array, hash, map)
398 * ------------------------------------------------------------------------
401 //! Return true if \p obj is a dictionary
402 bool pmt_is_dict(pmt_t obj);
404 //! make an empty dictionary
405 pmt_t pmt_make_dict();
407 //! dict[key] = value
408 void pmt_dict_set(pmt_t dict, pmt_t key, pmt_t value);
410 //! Return true if \p key exists in \p dict
411 bool pmt_dict_has_key(pmt_t dict, pmt_t key);
413 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
414 pmt_t pmt_dict_ref(pmt_t dict, pmt_t key, pmt_t not_found);
416 //! Return list of (key . value) pairs
417 pmt_t pmt_dict_items(pmt_t dict);
419 //! Return list of keys
420 pmt_t pmt_dict_keys(pmt_t dict);
422 //! Return list of values
423 pmt_t pmt_dict_values(pmt_t dict);
426 * ------------------------------------------------------------------------
427 * Any (wraps boost::any -- can be used to wrap pretty much anything)
429 * Cannot be serialized or used across process boundaries.
430 * See http://www.boost.org/doc/html/any.html
431 * ------------------------------------------------------------------------
434 //! Return true if \p obj is an any
435 bool pmt_is_any(pmt_t obj);
438 pmt_t pmt_make_any(const boost::any &any);
440 //! Return underlying boost::any
441 boost::any pmt_any_ref(pmt_t obj);
443 //! Store \p any in \p obj
444 void pmt_any_set(pmt_t obj, const boost::any &any);
448 * ------------------------------------------------------------------------
450 * ------------------------------------------------------------------------
453 //! Return true if x and y are the same object; otherwise return false.
454 bool pmt_eq(const pmt_t& x, const pmt_t& y);
457 * \brief Return true if x and y should normally be regarded as the same object, else false.
460 * eqv returns true if:
461 * x and y are the same object.
462 * x and y are both \#t or both \#f.
463 * x and y are both symbols and their names are the same.
464 * x and y are both numbers, and are numerically equal.
465 * x and y are both the empty list (nil).
466 * x and y are pairs or vectors that denote same location in store.
469 bool pmt_eqv(const pmt_t& x, const pmt_t& y);
472 * pmt_equal recursively compares the contents of pairs and vectors,
473 * applying pmt_eqv on other objects such as numbers and symbols.
474 * pmt_equal may fail to terminate if its arguments are circular data
477 bool pmt_equal(const pmt_t& x, const pmt_t& y);
480 //! Return the number of elements in v
481 size_t pmt_length(const pmt_t& v);
484 * \brief Find the first pair in \p alist whose car field is \p obj
485 * and return that pair.
487 * \p alist (for "association list") must be a list of pairs. If no pair
488 * in \p alist has \p obj as its car then \#f is returned.
489 * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
491 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
494 * \brief Find the first pair in \p alist whose car field is \p obj
495 * and return that pair.
497 * \p alist (for "association list") must be a list of pairs. If no pair
498 * in \p alist has \p obj as its car then \#f is returned.
499 * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
501 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
504 * \brief Find the first pair in \p alist whose car field is \p obj
505 * and return that pair.
507 * \p alist (for "association list") must be a list of pairs. If no pair
508 * in \p alist has \p obj as its car then \#f is returned.
509 * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
511 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
514 * \brief Apply \p proc element-wise to the elements of list and returns
515 * a list of the results, in order.
517 * \p list must be a list. The dynamic order in which \p proc is
518 * applied to the elements of \p list is unspecified.
520 pmt_t pmt_map(pmt_t proc(const pmt_t&), pmt_t list);
523 * \brief reverse \p list.
525 * \p list must be a proper list.
527 pmt_t pmt_reverse(pmt_t list);
530 * \brief destructively reverse \p list.
532 * \p list must be a proper list.
534 pmt_t pmt_reverse_x(pmt_t list);
537 * \brief (acons x y a) == (cons (cons x y) a)
540 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
542 return pmt_cons(pmt_cons(x, y), a);
546 * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
548 pmt_t pmt_nth(size_t n, pmt_t list);
551 * \brief returns the tail of \p list that would be obtained by calling
552 * cdr \p n times in succession.
554 pmt_t pmt_nthcdr(size_t n, pmt_t list);
557 * \brief Return the first sublist of \p list whose car is \p obj.
558 * If \p obj does not occur in \p list, then \#f is returned.
559 * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
561 pmt_t pmt_memq(pmt_t obj, pmt_t list);
564 * \brief Return the first sublist of \p list whose car is \p obj.
565 * If \p obj does not occur in \p list, then \#f is returned.
566 * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
568 pmt_t pmt_memv(pmt_t obj, pmt_t list);
571 * \brief Return the first sublist of \p list whose car is \p obj.
572 * If \p obj does not occur in \p list, then \#f is returned.
573 * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
575 pmt_t pmt_member(pmt_t obj, pmt_t list);
578 * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
579 * Comparisons are done with pmt_eqv.
581 bool pmt_subsetp(pmt_t list1, pmt_t list2);
584 * \brief Return a list of length 1 containing \p x1
586 pmt_t pmt_list1(const pmt_t& x1);
589 * \brief Return a list of length 2 containing \p x1, \p x2
591 pmt_t pmt_list2(const pmt_t& x1, const pmt_t& x2);
594 * \brief Return a list of length 3 containing \p x1, \p x2, \p x3
596 pmt_t pmt_list3(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3);
599 * \brief Return a list of length 4 containing \p x1, \p x2, \p x3, \p x4
601 pmt_t pmt_list4(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4);
604 * \brief Return a list of length 5 containing \p x1, \p x2, \p x3, \p x4, \p x5
606 pmt_t pmt_list5(const pmt_t& x1, const pmt_t& x2, const pmt_t& x3, const pmt_t& x4, const pmt_t& x5);
609 * \brief Return a list of length 6 containing \p x1, \p x2, \p x3, \p x4, \p
612 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);
615 * \brief Return \p list with \p item added to it.
617 pmt_t pmt_list_add(pmt_t list, const pmt_t& item);
621 * ------------------------------------------------------------------------
623 * ------------------------------------------------------------------------
625 extern const pmt_t PMT_EOF; //< The end of file object
627 //! return true if obj is the EOF object, otherwise return false.
628 bool pmt_is_eof_object(pmt_t obj);
631 * read converts external representations of pmt objects into the
632 * objects themselves. Read returns the next object parsable from
633 * the given input port, updating port to point to the first
634 * character past the end of the external representation of the
637 * If an end of file is encountered in the input before any
638 * characters are found that can begin an object, then an end of file
639 * object is returned. The port remains open, and further attempts
640 * to read will also return an end of file object. If an end of file
641 * is encountered after the beginning of an object's external
642 * representation, but the external representation is incomplete and
643 * therefore not parsable, an error is signaled.
645 pmt_t pmt_read(std::istream &port);
648 * Write a written representation of \p obj to the given \p port.
650 void pmt_write(pmt_t obj, std::ostream &port);
653 * Return a string representation of \p obj.
654 * This is the same output as would be generated by pmt_write.
656 std::string pmt_write_string(pmt_t obj);
659 std::ostream& operator<<(std::ostream &os, pmt_t obj);
663 * ------------------------------------------------------------------------
664 * portable byte stream representation
665 * ------------------------------------------------------------------------
668 * \brief Write portable byte-serial representation of \p obj to \p sink
670 bool pmt_serialize(pmt_t obj, std::streambuf &sink);
673 * \brief Create obj from portable byte-serial representation
675 pmt_t pmt_deserialize(std::streambuf &source);
678 void pmt_dump_sizeof(); // debugging
680 } /* namespace pmt */
682 #endif /* INCLUDED_PMT_H */