core/library/textual/list_parsing.h

   1 #ifndef LIST_PARSING_CLASS
   2 #define LIST_PARSING_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : list_parsing                                                      *
   7 *  Author : Chris Koeritz                                                     *
   8 *  Author : Gary Hardley                                                      *
   9 *                                                                             *
  10 *******************************************************************************
  11 * Copyright (c) 2002-$now By Author.  This program is free software; you can  *
  12 * redistribute it and/or modify it under the terms of the GNU General Public  *
  13 * License as published by the Free Software Foundation; either version 2 of   *
  14 * the License or (at your option) any later version.  This is online at:      *
  15 *     http://www.fsf.org/copyleft/gpl.html                                    *
  16 * Please send any updates to: fred@gruntose.com                               *
  17 \*****************************************************************************/
  18
  19 #include <basis/contracts.h>
  20 #include <structures/set.h>
  21 #include <structures/string_array.h>
  22 #include <structures/string_table.h>
  23
  24 namespace textual {
  25
  26 //! A set of functions that help out with parsing lists of things.
  27
  28 class list_parsing
  29 {
  30 public:
  31   virtual ~list_parsing();
  32   DEFINE_CLASS_NAME("list_parsing");
  33
  34   static bool get_ids_from_string(const basis::astring &string, structures::int_set &ids);
  35     //!< returns true if a set of unique ids can be extracted from "string".
  36     /*!< valid separators are spaces, commas, hyphens.  note that this
  37     returns an int_set although the integers will all be non-negative.
  38     e.g. "1-4,5 6 7,30-25" is a valid string. */
  39
  40   static bool get_ids_from_string(const basis::astring &string, basis::int_array &ids);
  41     //!< same as above except result is an array -- to preserve order.
  42     /*!< this also retains duplicates. */
  43
  44   static basis::astring put_ids_in_string(const structures::int_set &ids, char separator = ',');
  45     //!< returns a string containing a "separator" separated list of ids.
  46     /*!< spaces are also used between entries for readability. */
  47   static basis::astring put_ids_in_string(const basis::int_array &ids, char separator = ',');
  48     //!< operates on an array instead of a set.
  49
  50   static basis::astring emit_quoted_chunk(const basis::astring &to_emit);
  51      //!< ensures that quotes inside the string "to_emit" are escaped.
  52
  53   static bool parse_csv_line(const basis::astring &to_parse, structures::string_array &fields);
  54     //!< examines the string "to_parse" which should be in csv format.
  55     /*!< the "fields" list is set to the entries found on the line.  true is
  56     returned if the line parsed without any errors.  this method will accept
  57     a backslash as an escape character if it is immediately followed by a
  58     quote character or another backslash character.  no other escapes are
  59     currently supported; backslashes will be taken literally otherwise. */
  60
  61   static void create_csv_line(const structures::string_array &to_csv, basis::astring &target);
  62   static void create_csv_line(const structures::string_table &to_csv, basis::astring &target);
  63     //!< writes a CSV line of text into the "target" from the items in "to_csv".
  64     /*!< the "target" is reset before the line is stored there; thus, this is
  65     not cumulative.  further, the end of line character is not appended.  this
  66     will escape quote and backslash characters with a prepended backslash. */
  67 };
  68
  69 } //namespace.
  70
  71 #endif
  72