| Home | Libraries | People | FAQ | More

## Class template period_formatter

boost::date_time::period_formatter — Not a facet, but a class used to specify and control period formats.

## Synopsis

    // In header: <boost/date_time/period_formatter.hpp>

    template<typename CharT,
             typename OutItrT = std::ostreambuf_iterator<CharT, std::char_traits<CharT> > >
    class period_formatter {
    public:
      // types
      typedef std::basic_string< CharT >                     string_type;
      typedef CharT                                          char_type;
      typedef std::basic_string< char_type >::const_iterator const_itr_type;
      typedef std::vector< std::basic_string< CharT > >      collection_type;

      enum range_display_options { AS_OPEN_RANGE, AS_CLOSED_RANGE };

      // construct/copy/destruct
      period_formatter(range_display_options = AS_CLOSED_RANGE,
                       const char_type *const = default_period_separator,
                       const char_type *const = default_period_start_delimeter,
                       const char_type *const = default_period_open_range_end_delimeter,
                       const char_type *const = default_period_closed_range_end_delimeter);

      // public member functions
      OutItrT put_period_separator(OutItrT &) const;
      OutItrT put_period_start_delimeter(OutItrT &) const;
      OutItrT put_period_end_delimeter(OutItrT &) const;
      range_display_options range_option() const;
      void range_option(range_display_options) const;
      void delimiter_strings(const string_type &, const string_type &,
                             const string_type &, const string_type &);
      template<typename period_type, typename facet_type>
        OutItrT put_period(OutItrT, std::ios_base &, char_type,
                           const period_type &, const facet_type &) const;

      // public data members
      static const char_type default_period_separator;
      static const char_type default_period_start_delimeter;
      static const char_type default_period_open_range_end_delimeter;
      static const char_type default_period_closed_range_end_delimeter;
    };

## Description

Provides settings for the following:

- period_separator – default '/'

- period_open_start_delimeter – default '['

- period_open_range_end_delimeter – default ')'

- period_closed_range_end_delimeter – default ']'

- display_as_open_range, display_as_closed_range – default closed_range

Thus the default formatting for a period is as follows:

    [period.start()/period.last()]

So for a typical date_period this would be

    [2004-Jan-04/2004-Feb-01]

where the date formatting is controlled by the date facet

### `period_formatter` public construct/copy/destruct

1.     period_formatter(range_display_options range_option_in = AS_CLOSED_RANGE,
                        const char_type *const period_separator = default_period_separator,
                        const char_type *const period_start_delimeter = default_period_start_delimeter,
                        const char_type *const period_open_range_end_delimeter = default_period_open_range_end_delimeter,
                        const char_type *const period_closed_range_end_delimeter = default_period_closed_range_end_delimeter);

   Constructor that sets up period formatter options – default should suffice most cases.

### `period_formatter` public member functions

1.     OutItrT put_period_separator(OutItrT & oitr) const;

   Puts the characters between period elements into stream – default is /.

2.     OutItrT put_period_start_delimeter(OutItrT & oitr) const;

   Puts the period start characters into stream – default is [.

3.     OutItrT put_period_end_delimeter(OutItrT & oitr) const;

   Puts the period end characters into stream as controled by open/closed range setting.

4.     range_display_options range_option() const;

5.     void range_option(range_display_options option) const;

   Reset the range_option control.

6.     void delimiter_strings(const string_type & separator,
                              const string_type & start_delim,
                              const string_type & open_end_delim,
                              const string_type & closed_end_delim);

   Change the delimiter strings.

7.     template<typename period_type, typename facet_type>
         OutItrT put_period(OutItrT next, std::ios_base & a_ios, char_type a_fill,
                            const period_type & p, const facet_type & facet) const;

   Generic code to output a period – no matter the period type.

   This generic code will output any period using a facet to to output the 'elements'. For example, in the case of a date_period the elements will be instances of a date which will be formatted according the to setup in the passed facet parameter.

   The steps for formatting a period are always the same:

   - put the start delimiter

   - put start element

   - put the separator

   - put either last or end element depending on range settings

   - put end delimeter depending on range settings

   Thus for a typical date period the result might look like this:

       [March 01, 2004/June 07, 2004]   <-- closed range
       [March 01, 2004/June 08, 2004)   <-- open range