3 * Copyright 2006 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 2, 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., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #ifndef INCLUDED_PMT_H
24 #define INCLUDED_PMT_H
26 #include <boost/shared_ptr.hpp>
33 * This file defines a polymorphic type and the operations on it.
35 * It draws heavily on the idea of scheme and lisp data types.
36 * The interface parallels that in Guile 1.8, with the notable
37 * exception that these objects are transparently reference counted.
41 * \brief base class of all pmt types
46 * \brief typedef for shared pointer (transparent reference counting).
47 * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
49 typedef boost::shared_ptr<pmt_base> pmt_t;
58 pmt_exception(const char *msg, pmt_t obj);
59 const char *msg() { return d_msg; }
60 pmt_t obj() { return d_obj; }
63 class pmt_wrong_type : public pmt_exception
66 pmt_wrong_type(const char *msg, pmt_t obj);
69 class pmt_out_of_range : public pmt_exception
72 pmt_out_of_range(const char *msg, pmt_t obj);
76 * ------------------------------------------------------------------------
77 * Booleans. Two constants, #t and #f.
79 * In predicates, anything that is not #f is considered true.
80 * I.e., there is a single false value, #f.
81 * ------------------------------------------------------------------------
83 extern const pmt_t PMT_BOOL_T; //< #t : boolean true constant
84 extern const pmt_t PMT_BOOL_F; //< #f : boolean false constant
86 //! Return true if obj is #t or #f, else return false.
87 bool pmt_is_bool(pmt_t obj);
89 //! Return false if obj is #f, else return true.
90 bool pmt_is_true(pmt_t obj);
92 //! Return true if obj is #f, else return true.
93 bool pmt_is_false(pmt_t obj);
95 //! Return #f is val is false, else return #t.
96 pmt_t pmt_from_bool(bool val);
98 //! Return true if val is PMT_BOOL_T, return false when val is PMT_BOOL_F,
99 // else raise wrong_type exception.
100 bool pmt_to_bool(pmt_t val);
103 * ------------------------------------------------------------------------
105 * ------------------------------------------------------------------------
108 //! Return true if obj is a symbol, else false.
109 bool pmt_is_symbol(pmt_t obj);
111 //! Return the symbol whose name is \p s.
112 pmt_t pmt_string_to_symbol(const std::string &s);
115 * If \p is a symbol, return the name of the symbol as a string.
116 * Otherwise, raise the wrong_type exception.
118 const std::string pmt_symbol_to_string(pmt_t sym);
121 * ------------------------------------------------------------------------
122 * Numbers: we support integer, real and complex
123 * ------------------------------------------------------------------------
126 //! Return true if obj is any kind of number, else false.
127 bool pmt_is_number(pmt_t obj);
130 * ------------------------------------------------------------------------
132 * ------------------------------------------------------------------------
135 //! Return true if \p x is an integer number, else false
136 bool pmt_is_integer(pmt_t x);
138 //! Return the pmt value that represents the integer \p x.
139 pmt_t pmt_from_long(long x);
142 * \brief Convert pmt to long if possible.
144 * When \p x represents an exact integer that fits in a long,
145 * return that integer. Else raise an exception, either wrong_type
146 * when x is not an exact integer, or out_of_range when it doesn't fit.
148 long pmt_to_long(pmt_t x);
151 * ------------------------------------------------------------------------
153 * ------------------------------------------------------------------------
157 * \brief Return true if \p obj is a real number, else false.
159 bool pmt_is_real(pmt_t obj);
161 //! Return the pmt value that represents double \p x.
162 pmt_t pmt_from_double(double x);
165 * \brief Convert pmt to double if possible.
167 * Returns the number closest to \p val that is representable
168 * as a double. The argument \p val must be a real or integer, otherwise
169 * a wrong_type exception is raised.
171 double pmt_to_double(pmt_t x);
174 * ------------------------------------------------------------------------
176 * ------------------------------------------------------------------------
180 * \brief return true if \p obj is a complex number, false otherwise.
182 bool pmt_is_complex(pmt_t obj);
184 //! Return a complex number constructed of the given real and imaginary parts.
185 pmt_t pmt_make_rectangular(double re, double im);
188 * If \p z is complex, real or integer, return the closest complex<double>.
189 * Otherwise, raise the wrong_type exception.
191 std::complex<double> pmt_to_complex(pmt_t z);
194 * ------------------------------------------------------------------------
196 * ------------------------------------------------------------------------
199 extern const pmt_t PMT_NIL; //< the empty list
201 //! Return true if \p x is the empty list, otherwise return false.
202 bool pmt_is_null(pmt_t x);
204 //! Return true if \p obj is a pair, else false.
205 bool pmt_is_pair(pmt_t obj);
207 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
208 pmt_t pmt_cons(pmt_t x, pmt_t y);
210 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
211 pmt_t pmt_car(pmt_t pair);
213 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
214 pmt_t pmt_cdr(pmt_t pair);
216 //! Stores \p value in the car field of \p pair.
217 void pmt_set_car(pmt_t pair, pmt_t value);
219 //! Stores \p value in the cdr field of \p pair.
220 void pmt_set_cdr(pmt_t pair, pmt_t value);
223 * ------------------------------------------------------------------------
226 * These vectors can hold any kind of objects. Indexing is zero based.
227 * ------------------------------------------------------------------------
230 //! Return true if \p x is a vector, othewise false.
231 bool pmt_is_vector(pmt_t x);
233 //! Make a vector of length \p k, with initial values set to \p fill
234 pmt_t pmt_make_vector(size_t k, pmt_t fill);
237 * Return the contents of position \p k of \p vector.
238 * \p k must be a valid index of \p vector.
240 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
242 //! Store \p obj in position \p k.
243 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
245 //! Store \p fill in every position of \p vector
246 void pmt_vector_fill(pmt_t vector, pmt_t fill);
250 * ------------------------------------------------------------------------
251 * Uniform Numeric Vectors
253 * A uniform numeric vector is a vector whose elements are all of single
254 * numeric type. pmt offers uniform numeric vectors for signed and
255 * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
256 * floating point values, and complex floating-point numbers of these
257 * two sizes. Indexing is zero based.
259 * The names of the functions include these tags in their names:
261 * u8 unsigned 8-bit integers
262 * s8 signed 8-bit integers
263 * u16 unsigned 16-bit integers
264 * s16 signed 16-bit integers
265 * u32 unsigned 32-bit integers
266 * s32 signed 32-bit integers
267 * u64 unsigned 64-bit integers
268 * s64 signed 64-bit integers
269 * f32 the C++ type float
270 * f64 the C++ type double
271 * c32 the C++ type complex<float>
272 * c64 the C++ type complex<double>
273 * ------------------------------------------------------------------------
277 //! true if \p x is any kind of uniform numeric vector
278 bool pmt_is_uniform_vector(pmt_t x);
280 bool pmt_is_u8vector(pmt_t x);
281 bool pmt_is_s8vector(pmt_t x);
282 bool pmt_is_u16vector(pmt_t x);
283 bool pmt_is_s16vector(pmt_t x);
284 bool pmt_is_u32vector(pmt_t x);
285 bool pmt_is_s32vector(pmt_t x);
286 bool pmt_is_u64vector(pmt_t x);
287 bool pmt_is_s64vector(pmt_t x);
288 bool pmt_is_f32vector(pmt_t x);
289 bool pmt_is_f64vector(pmt_t x);
290 bool pmt_is_c32vector(pmt_t x);
291 bool pmt_is_c64vector(pmt_t x);
293 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
294 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
295 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
296 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
297 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
298 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
299 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
300 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
301 pmt_t pmt_make_f32vector(size_t k, float fill);
302 pmt_t pmt_make_f64vector(size_t k, double fill);
303 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
304 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
306 pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
307 pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
308 pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
309 pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
310 pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
311 pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
312 pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
313 pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
314 pmt_t pmt_init_f32vector(size_t k, const float *data);
315 pmt_t pmt_init_f64vector(size_t k, const double *data);
316 pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
317 pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
319 uint8_t pmt_u8vector_ref(pmt_t v, size_t k);
320 int8_t pmt_s8vector_ref(pmt_t v, size_t k);
321 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
322 int16_t pmt_s16vector_ref(pmt_t v, size_t k);
323 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
324 int32_t pmt_s32vector_ref(pmt_t v, size_t k);
325 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
326 int64_t pmt_s64vector_ref(pmt_t v, size_t k);
327 float pmt_f32vector_ref(pmt_t v, size_t k);
328 double pmt_f64vector_ref(pmt_t v, size_t k);
329 std::complex<float> pmt_c32vector_ref(pmt_t v, size_t k);
330 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
332 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x); //< v[k] = x
333 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
334 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
335 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
336 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
337 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
338 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
339 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
340 void pmt_f32vector_set(pmt_t v, size_t k, float x);
341 void pmt_f64vector_set(pmt_t v, size_t k, double x);
342 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
343 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
345 // Return const pointers to the elements
347 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
349 const uint8_t *pmt_u8vector_elements(pmt_t v, size_t &len); //< len is in elements
350 const int8_t *pmt_s8vector_elements(pmt_t v, size_t &len); //< len is in elements
351 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
352 const int16_t *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
353 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
354 const int32_t *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
355 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
356 const int64_t *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
357 const float *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
358 const double *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
359 const std::complex<float> *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
360 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
362 // Return non-const pointers to the elements
364 void *pmt_uniform_vector_writeable_elements(pmt_t v, size_t &len); //< works with any; len is in bytes
366 uint8_t *pmt_u8vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
367 int8_t *pmt_s8vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
368 uint16_t *pmt_u16vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
369 int16_t *pmt_s16vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
370 uint32_t *pmt_u32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
371 int32_t *pmt_s32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
372 uint64_t *pmt_u64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
373 int64_t *pmt_s64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
374 float *pmt_f32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
375 double *pmt_f64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
376 std::complex<float> *pmt_c32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
377 std::complex<double> *pmt_c64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
380 * ------------------------------------------------------------------------
381 * Dictionary (a.k.a associative array, hash, map)
382 * ------------------------------------------------------------------------
385 //! Return true if \p obj is a dictionary
386 bool pmt_is_dict(pmt_t obj);
388 //! make an empty dictionary
389 pmt_t pmt_make_dict();
391 //! dict[key] = value
392 void pmt_dict_set(pmt_t dict, pmt_t key, pmt_t value);
394 //! Return true if \p key exists in \p dict
395 bool pmt_dict_has_key(pmt_t dict, pmt_t key);
397 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
398 pmt_t pmt_dict_ref(pmt_t dict, pmt_t key, pmt_t not_found);
400 //! Return list of (key . value) pairs
401 pmt_t pmt_dict_items(pmt_t dict);
403 //! Return list of keys
404 pmt_t pmt_dict_keys(pmt_t dict);
406 //! Return list of values
407 pmt_t pmt_dict_values(pmt_t dict);
410 * ------------------------------------------------------------------------
412 * ------------------------------------------------------------------------
415 //! Return true if x and y are the same object; otherwise return false.
416 bool pmt_eq(pmt_t x, pmt_t y);
419 * \brief Return true if x and y should normally be regarded as the same object, else false.
422 * eqv returns true if:
423 * x and y are the same object.
424 * x and y are both #t or both #f.
425 * x and y are both symbols and their names are the same.
426 * x and y are both numbers, and are numerically equal.
427 * x and y are both the empty list (nil).
428 * x and y are pairs or vectors that denote same location in store.
431 bool pmt_eqv(pmt_t x, pmt_t y);
434 * pmt_equal recursively compares the contents of pairs and vectors,
435 * applying pmt_eqv on other objects such as numbers and symbols.
436 * pmt_equal may fail to terminate if its arguments are circular data
439 bool pmt_equal(pmt_t x, pmt_t y);
442 //! Return the number of elements in v
443 size_t pmt_length(pmt_t v);
446 * \brief Find the first pair in \p alist whose car field is \p obj
447 * and return that pair.
449 * \p alist (for "association list") must be a list of pairs. If no pair
450 * in \p alist has \p obj as its car then #f is returned.
451 * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
453 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
456 * \brief Find the first pair in \p alist whose car field is \p obj
457 * and return that pair.
459 * \p alist (for "association list") must be a list of pairs. If no pair
460 * in \p alist has \p obj as its car then #f is returned.
461 * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
463 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
466 * \brief Find the first pair in \p alist whose car field is \p obj
467 * and return that pair.
469 * \p alist (for "association list") must be a list of pairs. If no pair
470 * in \p alist has \p obj as its car then #f is returned.
471 * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
473 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
476 * \brief Apply \p proc element-wise to the elements of list and returns
477 * a list of the results, in order.
479 * \p list must be a list. The dynamic order in which \p proc is
480 * applied to the elements of \p list is unspecified.
482 pmt_t pmt_map(pmt_t proc(pmt_t), pmt_t list);
485 * \brief reverse \p list.
487 * \p list must be a proper list.
489 pmt_t pmt_reverse(pmt_t list);
492 * \brief destructively reverse \p list.
494 * \p list must be a proper list.
496 pmt_t pmt_reverse_x(pmt_t list);
499 * \brief (acons x y a) == (cons (cons x y) a)
502 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
504 return pmt_cons(pmt_cons(x, y), a);
508 * ------------------------------------------------------------------------
510 * ------------------------------------------------------------------------
512 extern const pmt_t PMT_EOF; //< The end of file object
514 //! return true if obj is the EOF object, otherwise return false.
515 bool pmt_is_eof_object(pmt_t obj);
518 * read converts external representations of pmt objects into the
519 * objects themselves. Read returns the next object parsable from
520 * the given input port, updating port to point to the first
521 * character past the end of the external representation of the
524 * If an end of file is encountered in the input before any
525 * characters are found that can begin an object, then an end of file
526 * object is returned. The port remains open, and further attempts
527 * to read will also return an end of file object. If an end of file
528 * is encountered after the beginning of an object's external
529 * representation, but the external representation is incomplete and
530 * therefore not parsable, an error is signaled.
532 pmt_t pmt_read(std::istream &port);
535 * Write a written representation of \p obj to the given \p port.
537 void pmt_write(pmt_t obj, std::ostream &port);
540 * ------------------------------------------------------------------------
541 * portable byte stream representation
542 * ------------------------------------------------------------------------
545 * \brief Write portable byte-serial representation of \p obj to \p sink
547 void pmt_serialize(pmt_t obj, std::ostream &sink);
550 * \brief Create obj from portable byte-serial representation
552 pmt_t pmt_deserialize(std::istream &source);
554 #endif /* INCLUDED_PMT_H */