git.gag.com Git - debian/gnuradio/blob - pmt/src/lib/pmt.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2006 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 2, 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 <boost/shared_ptr.hpp>
  27 #include <complex>
  28 #include <string>
  29 #include <stdint.h>
  30 #include <iostream>
  31 #include <stdexcept>
  32
  33 /*!
  34  * This file defines a polymorphic type and the operations on it.
  35  *
  36  * It draws heavily on the idea of scheme and lisp data types.
  37  * The interface parallels that in Guile 1.8, with the notable
  38  * exception that these objects are transparently reference counted.
  39  */
  40
  41 /*!
  42  * \brief base class of all pmt types
  43  */
  44 class pmt_base;
  45
  46 /*!
  47  * \brief typedef for shared pointer (transparent reference counting).
  48  * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
  49  */
  50 typedef boost::shared_ptr<pmt_base> pmt_t;
  51
  52
  53 class pmt_exception : public std::logic_error
  54 {
  55 public:
  56   pmt_exception(const std::string &msg, pmt_t obj);
  57 };
  58
  59 class pmt_wrong_type : public pmt_exception
  60 {
  61 public:
  62   pmt_wrong_type(const std::string &msg, pmt_t obj);
  63 };
  64
  65 class pmt_out_of_range : public pmt_exception
  66 {
  67 public:
  68   pmt_out_of_range(const std::string &msg, pmt_t obj);
  69 };
  70
  71 class pmt_notimplemented : public pmt_exception
  72 {
  73 public:
  74   pmt_notimplemented(const std::string &msg, pmt_t obj);
  75 };
  76
  77 /*
  78  * ------------------------------------------------------------------------
  79  * Booleans.  Two constants, #t and #f.
  80  *
  81  * In predicates, anything that is not #f is considered true.
  82  * I.e., there is a single false value, #f.
  83  * ------------------------------------------------------------------------
  84  */
  85 extern const pmt_t PMT_BOOL_T;  //< #t : boolean true constant
  86 extern const pmt_t PMT_BOOL_F;  //< #f : boolean false constant
  87
  88 //! Return true if obj is #t or #f, else return false.
  89 bool pmt_is_bool(pmt_t obj);
  90
  91 //! Return false if obj is #f, else return true.
  92 bool pmt_is_true(pmt_t obj);
  93
  94 //! Return true if obj is #f, else return true.
  95 bool pmt_is_false(pmt_t obj);
  96
  97 //! Return #f is val is false, else return #t.
  98 pmt_t pmt_from_bool(bool val);
  99
 100 //! Return true if val is PMT_BOOL_T, return false when val is PMT_BOOL_F,
 101 // else raise wrong_type exception.
 102 bool pmt_to_bool(pmt_t val);
 103
 104 /*
 105  * ------------------------------------------------------------------------
 106  *                             Symbols
 107  * ------------------------------------------------------------------------
 108  */
 109
 110 //! Return true if obj is a symbol, else false.
 111 bool pmt_is_symbol(pmt_t obj);
 112
 113 //! Return the symbol whose name is \p s.
 114 pmt_t pmt_string_to_symbol(const std::string &s);
 115
 116 //! Alias for pmt_string_to_symbol
 117 pmt_t pmt_intern(const std::string &s);
 118
 119
 120 /*!
 121  * If \p is a symbol, return the name of the symbol as a string.
 122  * Otherwise, raise the wrong_type exception.
 123  */
 124 const std::string pmt_symbol_to_string(pmt_t sym);
 125
 126 /*
 127  * ------------------------------------------------------------------------
 128  *           Numbers: we support integer, real and complex
 129  * ------------------------------------------------------------------------
 130  */
 131
 132 //! Return true if obj is any kind of number, else false.
 133 bool pmt_is_number(pmt_t obj);
 134
 135 /*
 136  * ------------------------------------------------------------------------
 137  *                             Integers
 138  * ------------------------------------------------------------------------
 139  */
 140
 141 //! Return true if \p x is an integer number, else false
 142 bool pmt_is_integer(pmt_t x);
 143
 144 //! Return the pmt value that represents the integer \p x.
 145 pmt_t pmt_from_long(long x);
 146
 147 /*!
 148  * \brief Convert pmt to long if possible.
 149  *
 150  * When \p x represents an exact integer that fits in a long,
 151  * return that integer.  Else raise an exception, either wrong_type
 152  * when x is not an exact integer, or out_of_range when it doesn't fit.
 153  */
 154 long pmt_to_long(pmt_t x);
 155
 156 /*
 157  * ------------------------------------------------------------------------
 158  *                              Reals
 159  * ------------------------------------------------------------------------
 160  */
 161
 162 /*
 163  * \brief Return true if \p obj is a real number, else false.
 164  */
 165 bool pmt_is_real(pmt_t obj);
 166
 167 //! Return the pmt value that represents double \p x.
 168 pmt_t pmt_from_double(double x);
 169
 170 /*!
 171  * \brief Convert pmt to double if possible.
 172  *
 173  * Returns the number closest to \p val that is representable
 174  * as a double.  The argument \p val must be a real or integer, otherwise
 175  * a wrong_type exception is raised.
 176  */
 177 double pmt_to_double(pmt_t x);
 178
 179 /*
 180  * ------------------------------------------------------------------------
 181  *                             Complex
 182  * ------------------------------------------------------------------------
 183  */
 184
 185 /*!
 186  * \brief return true if \p obj is a complex number, false otherwise.
 187  */
 188 bool pmt_is_complex(pmt_t obj);
 189
 190 //! Return a complex number constructed of the given real and imaginary parts.
 191 pmt_t pmt_make_rectangular(double re, double im);
 192
 193 /*!
 194  * If \p z is complex, real or integer, return the closest complex<double>.
 195  * Otherwise, raise the wrong_type exception.
 196  */
 197 std::complex<double> pmt_to_complex(pmt_t z);
 198
 199 /*
 200  * ------------------------------------------------------------------------
 201  *                              Pairs
 202  * ------------------------------------------------------------------------
 203  */
 204
 205 extern const pmt_t PMT_NIL;     //< the empty list
 206
 207 //! Return true if \p x is the empty list, otherwise return false.
 208 bool pmt_is_null(pmt_t x);
 209
 210 //! Return true if \p obj is a pair, else false.
 211 bool pmt_is_pair(pmt_t obj);
 212
 213 //! Return a newly allocated pair whose car is \p x and whose cdr is \p y.
 214 pmt_t pmt_cons(pmt_t x, pmt_t y);
 215
 216 //! If \p pair is a pair, return the car of the \p pair, otherwise raise wrong_type.
 217 pmt_t pmt_car(pmt_t pair);
 218
 219 //! If \p pair is a pair, return the cdr of the \p pair, otherwise raise wrong_type.
 220 pmt_t pmt_cdr(pmt_t pair);
 221
 222 //! Stores \p value in the car field of \p pair.
 223 void pmt_set_car(pmt_t pair, pmt_t value);
 224
 225 //! Stores \p value in the cdr field of \p pair.
 226 void pmt_set_cdr(pmt_t pair, pmt_t value);
 227
 228 /*
 229  * ------------------------------------------------------------------------
 230  *                             Vectors
 231  *
 232  * These vectors can hold any kind of objects.  Indexing is zero based.
 233  * ------------------------------------------------------------------------
 234  */
 235
 236 //! Return true if \p x is a vector, othewise false.
 237 bool pmt_is_vector(pmt_t x);
 238
 239 //! Make a vector of length \p k, with initial values set to \p fill
 240 pmt_t pmt_make_vector(size_t k, pmt_t fill);
 241
 242 /*!
 243  * Return the contents of position \p k of \p vector.
 244  * \p k must be a valid index of \p vector.
 245  */
 246 pmt_t pmt_vector_ref(pmt_t vector, size_t k);
 247
 248 //! Store \p obj in position \p k.
 249 void pmt_vector_set(pmt_t vector, size_t k, pmt_t obj);
 250
 251 //! Store \p fill in every position of \p vector
 252 void pmt_vector_fill(pmt_t vector, pmt_t fill);
 253
 254 /*!
 255  * <pre>
 256  * ------------------------------------------------------------------------
 257  *                     Uniform Numeric Vectors
 258  *
 259  * A uniform numeric vector is a vector whose elements are all of single
 260  * numeric type.  pmt offers uniform numeric vectors for signed and
 261  * unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
 262  * floating point values, and complex floating-point numbers of these
 263  * two sizes.  Indexing is zero based.
 264  *
 265  * The names of the functions include these tags in their names:
 266  *
 267  *    u8  unsigned 8-bit integers
 268  *    s8  signed 8-bit integers
 269  *   u16  unsigned 16-bit integers
 270  *   s16  signed 16-bit integers
 271  *   u32  unsigned 32-bit integers
 272  *   s32  signed 32-bit integers
 273  *   u64  unsigned 64-bit integers
 274  *   s64  signed 64-bit integers
 275  *   f32  the C++ type float
 276  *   f64  the C++ type double
 277  *   c32  the C++ type complex<float>
 278  *   c64  the C++ type complex<double>
 279  * ------------------------------------------------------------------------
 280  * </pre>
 281  */
 282
 283 //! true if \p x is any kind of uniform numeric vector
 284 bool pmt_is_uniform_vector(pmt_t x);
 285
 286 bool pmt_is_u8vector(pmt_t x);
 287 bool pmt_is_s8vector(pmt_t x);
 288 bool pmt_is_u16vector(pmt_t x);
 289 bool pmt_is_s16vector(pmt_t x);
 290 bool pmt_is_u32vector(pmt_t x);
 291 bool pmt_is_s32vector(pmt_t x);
 292 bool pmt_is_u64vector(pmt_t x);
 293 bool pmt_is_s64vector(pmt_t x);
 294 bool pmt_is_f32vector(pmt_t x);
 295 bool pmt_is_f64vector(pmt_t x);
 296 bool pmt_is_c32vector(pmt_t x);
 297 bool pmt_is_c64vector(pmt_t x);
 298
 299 pmt_t pmt_make_u8vector(size_t k, uint8_t fill);
 300 pmt_t pmt_make_s8vector(size_t k, int8_t fill);
 301 pmt_t pmt_make_u16vector(size_t k, uint16_t fill);
 302 pmt_t pmt_make_s16vector(size_t k, int16_t fill);
 303 pmt_t pmt_make_u32vector(size_t k, uint32_t fill);
 304 pmt_t pmt_make_s32vector(size_t k, int32_t fill);
 305 pmt_t pmt_make_u64vector(size_t k, uint64_t fill);
 306 pmt_t pmt_make_s64vector(size_t k, int64_t fill);
 307 pmt_t pmt_make_f32vector(size_t k, float fill);
 308 pmt_t pmt_make_f64vector(size_t k, double fill);
 309 pmt_t pmt_make_c32vector(size_t k, std::complex<float> fill);
 310 pmt_t pmt_make_c64vector(size_t k, std::complex<double> fill);
 311
 312 pmt_t pmt_init_u8vector(size_t k, const uint8_t *data);
 313 pmt_t pmt_init_s8vector(size_t k, const int8_t *data);
 314 pmt_t pmt_init_u16vector(size_t k, const uint16_t *data);
 315 pmt_t pmt_init_s16vector(size_t k, const int16_t *data);
 316 pmt_t pmt_init_u32vector(size_t k, const uint32_t *data);
 317 pmt_t pmt_init_s32vector(size_t k, const int32_t *data);
 318 pmt_t pmt_init_u64vector(size_t k, const uint64_t *data);
 319 pmt_t pmt_init_s64vector(size_t k, const int64_t *data);
 320 pmt_t pmt_init_f32vector(size_t k, const float *data);
 321 pmt_t pmt_init_f64vector(size_t k, const double *data);
 322 pmt_t pmt_init_c32vector(size_t k, const std::complex<float> *data);
 323 pmt_t pmt_init_c64vector(size_t k, const std::complex<double> *data);
 324
 325 uint8_t  pmt_u8vector_ref(pmt_t v, size_t k);
 326 int8_t   pmt_s8vector_ref(pmt_t v, size_t k);
 327 uint16_t pmt_u16vector_ref(pmt_t v, size_t k);
 328 int16_t  pmt_s16vector_ref(pmt_t v, size_t k);
 329 uint32_t pmt_u32vector_ref(pmt_t v, size_t k);
 330 int32_t  pmt_s32vector_ref(pmt_t v, size_t k);
 331 uint64_t pmt_u64vector_ref(pmt_t v, size_t k);
 332 int64_t  pmt_s64vector_ref(pmt_t v, size_t k);
 333 float    pmt_f32vector_ref(pmt_t v, size_t k);
 334 double   pmt_f64vector_ref(pmt_t v, size_t k);
 335 std::complex<float>  pmt_c32vector_ref(pmt_t v, size_t k);
 336 std::complex<double> pmt_c64vector_ref(pmt_t v, size_t k);
 337
 338 void pmt_u8vector_set(pmt_t v, size_t k, uint8_t x);  //< v[k] = x
 339 void pmt_s8vector_set(pmt_t v, size_t k, int8_t x);
 340 void pmt_u16vector_set(pmt_t v, size_t k, uint16_t x);
 341 void pmt_s16vector_set(pmt_t v, size_t k, int16_t x);
 342 void pmt_u32vector_set(pmt_t v, size_t k, uint32_t x);
 343 void pmt_s32vector_set(pmt_t v, size_t k, int32_t x);
 344 void pmt_u64vector_set(pmt_t v, size_t k, uint64_t x);
 345 void pmt_s64vector_set(pmt_t v, size_t k, int64_t x);
 346 void pmt_f32vector_set(pmt_t v, size_t k, float x);
 347 void pmt_f64vector_set(pmt_t v, size_t k, double x);
 348 void pmt_c32vector_set(pmt_t v, size_t k, std::complex<float> x);
 349 void pmt_c64vector_set(pmt_t v, size_t k, std::complex<double> x);
 350
 351 // Return const pointers to the elements
 352
 353 const void *pmt_uniform_vector_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 354
 355 const uint8_t  *pmt_u8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 356 const int8_t   *pmt_s8vector_elements(pmt_t v, size_t &len);  //< len is in elements
 357 const uint16_t *pmt_u16vector_elements(pmt_t v, size_t &len); //< len is in elements
 358 const int16_t  *pmt_s16vector_elements(pmt_t v, size_t &len); //< len is in elements
 359 const uint32_t *pmt_u32vector_elements(pmt_t v, size_t &len); //< len is in elements
 360 const int32_t  *pmt_s32vector_elements(pmt_t v, size_t &len); //< len is in elements
 361 const uint64_t *pmt_u64vector_elements(pmt_t v, size_t &len); //< len is in elements
 362 const int64_t  *pmt_s64vector_elements(pmt_t v, size_t &len); //< len is in elements
 363 const float    *pmt_f32vector_elements(pmt_t v, size_t &len); //< len is in elements
 364 const double   *pmt_f64vector_elements(pmt_t v, size_t &len); //< len is in elements
 365 const std::complex<float>  *pmt_c32vector_elements(pmt_t v, size_t &len); //< len is in elements
 366 const std::complex<double> *pmt_c64vector_elements(pmt_t v, size_t &len); //< len is in elements
 367
 368 // Return non-const pointers to the elements
 369
 370 void *pmt_uniform_vector_writeable_elements(pmt_t v, size_t &len);  //< works with any; len is in bytes
 371
 372 uint8_t  *pmt_u8vector_writeable_elements(pmt_t v, size_t &len);  //< len is in elements
 373 int8_t   *pmt_s8vector_writeable_elements(pmt_t v, size_t &len);  //< len is in elements
 374 uint16_t *pmt_u16vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 375 int16_t  *pmt_s16vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 376 uint32_t *pmt_u32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 377 int32_t  *pmt_s32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 378 uint64_t *pmt_u64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 379 int64_t  *pmt_s64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 380 float    *pmt_f32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 381 double   *pmt_f64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 382 std::complex<float>  *pmt_c32vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 383 std::complex<double> *pmt_c64vector_writeable_elements(pmt_t v, size_t &len); //< len is in elements
 384
 385 /*
 386  * ------------------------------------------------------------------------
 387  *         Dictionary (a.k.a associative array, hash, map)
 388  * ------------------------------------------------------------------------
 389  */
 390
 391 //! Return true if \p obj is a dictionary
 392 bool pmt_is_dict(pmt_t obj);
 393
 394 //! make an empty dictionary
 395 pmt_t pmt_make_dict();
 396
 397 //! dict[key] = value
 398 void  pmt_dict_set(pmt_t dict, pmt_t key, pmt_t value);
 399
 400 //! Return true if \p key exists in \p dict
 401 bool  pmt_dict_has_key(pmt_t dict, pmt_t key);
 402
 403 //! If \p key exists in \p dict, return associated value; otherwise return \p not_found.
 404 pmt_t pmt_dict_ref(pmt_t dict, pmt_t key, pmt_t not_found);
 405
 406 //! Return list of (key . value) pairs
 407 pmt_t pmt_dict_items(pmt_t dict);
 408
 409 //! Return list of keys
 410 pmt_t pmt_dict_keys(pmt_t dict);
 411
 412 //! Return list of values
 413 pmt_t pmt_dict_values(pmt_t dict);
 414
 415 /*
 416  * ------------------------------------------------------------------------
 417  *                        General functions
 418  * ------------------------------------------------------------------------
 419  */
 420
 421 //! Return true if x and y are the same object; otherwise return false.
 422 bool pmt_eq(pmt_t x, pmt_t y);
 423
 424 /*!
 425  * \brief Return true if x and y should normally be regarded as the same object, else false.
 426  *
 427  * <pre>
 428  * eqv returns true if:
 429  *   x and y are the same object.
 430  *   x and y are both #t or both #f.
 431  *   x and y are both symbols and their names are the same.
 432  *   x and y are both numbers, and are numerically equal.
 433  *   x and y are both the empty list (nil).
 434  *   x and y are pairs or vectors that denote same location in store.
 435  * </pre>
 436  */
 437 bool pmt_eqv(pmt_t x, pmt_t y);
 438
 439 /*!
 440  * pmt_equal recursively compares the contents of pairs and vectors,
 441  * applying pmt_eqv on other objects such as numbers and symbols.
 442  * pmt_equal may fail to terminate if its arguments are circular data
 443  * structures.
 444  */
 445 bool pmt_equal(pmt_t x, pmt_t y);
 446
 447
 448 //! Return the number of elements in v
 449 size_t pmt_length(pmt_t v);
 450
 451 /*!
 452  * \brief Find the first pair in \p alist whose car field is \p obj
 453  *  and return that pair.
 454  *
 455  * \p alist (for "association list") must be a list of pairs.  If no pair
 456  * in \p alist has \p obj as its car then #f is returned.
 457  * Uses pmt_eq to compare \p obj with car fields of the pairs in \p alist.
 458  */
 459 pmt_t pmt_assq(pmt_t obj, pmt_t alist);
 460
 461 /*!
 462  * \brief Find the first pair in \p alist whose car field is \p obj
 463  *  and return that pair.
 464  *
 465  * \p alist (for "association list") must be a list of pairs.  If no pair
 466  * in \p alist has \p obj as its car then #f is returned.
 467  * Uses pmt_eqv to compare \p obj with car fields of the pairs in \p alist.
 468  */
 469 pmt_t pmt_assv(pmt_t obj, pmt_t alist);
 470
 471 /*!
 472  * \brief Find the first pair in \p alist whose car field is \p obj
 473  *  and return that pair.
 474  *
 475  * \p alist (for "association list") must be a list of pairs.  If no pair
 476  * in \p alist has \p obj as its car then #f is returned.
 477  * Uses pmt_equal to compare \p obj with car fields of the pairs in \p alist.
 478  */
 479 pmt_t pmt_assoc(pmt_t obj, pmt_t alist);
 480
 481 /*!
 482  * \brief Apply \p proc element-wise to the elements of list and returns
 483  * a list of the results, in order.
 484  *
 485  * \p list must be a list.  The dynamic order in which \p proc is
 486  * applied to the elements of \p list is unspecified.
 487  */
 488 pmt_t pmt_map(pmt_t proc(pmt_t), pmt_t list);
 489
 490 /*!
 491  * \brief reverse \p list.
 492  *
 493  * \p list must be a proper list.
 494  */
 495 pmt_t pmt_reverse(pmt_t list);
 496
 497 /*!
 498  * \brief destructively reverse \p list.
 499  *
 500  * \p list must be a proper list.
 501  */
 502 pmt_t pmt_reverse_x(pmt_t list);
 503
 504 /*!
 505  * \brief (acons x y a) == (cons (cons x y) a)
 506  */
 507 inline static pmt_t
 508 pmt_acons(pmt_t x, pmt_t y, pmt_t a)
 509 {
 510   return pmt_cons(pmt_cons(x, y), a);
 511 }
 512
 513 /*!
 514  * \brief locates \p nth element of \n list where the car is the 'zeroth' element.
 515  */
 516 pmt_t pmt_nth(size_t n, pmt_t list);
 517
 518 /*!
 519  * \brief returns the tail of \p list that would be obtained by calling
 520  * cdr \p n times in succession.
 521  */
 522 pmt_t pmt_nthcdr(size_t n, pmt_t list);
 523
 524 /*!
 525  * \brief Return the first sublist of \p list whose car is \p obj.
 526  * If \p obj does not occur in \p list, then #f is returned.
 527  * pmt_memq use pmt_eq to compare \p obj with the elements of \p list.
 528  */
 529 pmt_t pmt_memq(pmt_t obj, pmt_t list);
 530
 531 /*!
 532  * \brief Return the first sublist of \p list whose car is \p obj.
 533  * If \p obj does not occur in \p list, then #f is returned.
 534  * pmt_memv use pmt_eqv to compare \p obj with the elements of \p list.
 535  */
 536 pmt_t pmt_memv(pmt_t obj, pmt_t list);
 537
 538 /*!
 539  * \brief Return the first sublist of \p list whose car is \p obj.
 540  * If \p obj does not occur in \p list, then #f is returned.
 541  * pmt_member use pmt_equal to compare \p obj with the elements of \p list.
 542  */
 543 pmt_t pmt_member(pmt_t obj, pmt_t list);
 544
 545 /*!
 546  * \brief Return true if every element of \p list1 appears in \p list2, and false otherwise.
 547  * Comparisons are done with pmt_eqv.
 548  */
 549 bool pmt_subsetp(pmt_t list1, pmt_t list2);
 550
 551 /*
 552  * ------------------------------------------------------------------------
 553  *                           read / write
 554  * ------------------------------------------------------------------------
 555  */
 556 extern const pmt_t PMT_EOF;     //< The end of file object
 557
 558 //! return true if obj is the EOF object, otherwise return false.
 559 bool pmt_is_eof_object(pmt_t obj);
 560
 561 /*!
 562  * read converts external representations of pmt objects into the
 563  * objects themselves.  Read returns the next object parsable from
 564  * the given input port, updating port to point to the first
 565  * character past the end of the external representation of the
 566  * object.
 567  *
 568  * If an end of file is encountered in the input before any
 569  * characters are found that can begin an object, then an end of file
 570  * object is returned.   The port remains open, and further attempts
 571  * to read will also return an end of file object.  If an end of file
 572  * is encountered after the beginning of an object's external
 573  * representation, but the external representation is incomplete and
 574  * therefore not parsable, an error is signaled.
 575  */
 576 pmt_t pmt_read(std::istream &port);
 577
 578 /*!
 579  * Write a written representation of \p obj to the given \p port.
 580  */
 581 void pmt_write(pmt_t obj, std::ostream &port);
 582
 583 /*!
 584  * Return a string representation of \p obj.
 585  * This is the same output as would be generated by pmt_write.
 586  */
 587 std::string pmt_write_string(pmt_t obj);
 588
 589
 590 std::ostream& operator<<(std::ostream &os, pmt_t obj);
 591
 592
 593 /*
 594  * ------------------------------------------------------------------------
 595  *                    portable byte stream representation
 596  * ------------------------------------------------------------------------
 597  */
 598 /*!
 599  * \brief Write portable byte-serial representation of \p obj to \p sink
 600  */
 601 void pmt_serialize(pmt_t obj, std::ostream &sink);
 602
 603 /*!
 604  * \brief Create obj from portable byte-serial representation
 605  */
 606 pmt_t pmt_deserialize(std::istream &source);
 607
 608 #endif /* INCLUDED_PMT_H */