// -*- c++ -*-

/*
 * Jakelib2 - General purpose C++ library
 * Copyright (C) 2001 Florian Wolff  (florian@donuz.de)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * $Id: Format.h,v 1.8 2003/09/16 20:16:24 florian Exp $
 */

#ifndef INCLUDE_JAKELIB2_TEXT_FORMAT_H
# define INCLUDE_JAKELIB2_TEXT_FORMAT_H

namespace jakelib {
  namespace text {
    class ParsePosition;
    class FieldPosition;

    /**
     *
     * @author Alex Fabijanic <fabijanica@nucorsteel.com>(jakelib2 port)
     */
    class Format : public jakelib::lang::Object
    {
    public:

      /**
       * This method initializes a new instance of Format.
       * It performs no actions, but acts as a default constructor for
       * subclasses.
       */
      Format ();

      /**
       * This method formats an \c Object into a \c String.
       * 
       * @param obj The \c Object to format.
       * @return The formatted \c String.
       * @exception IllegalArgumentException If the \c Object
       * cannot be formatted. 
       */
      virtual jakelib::lang::String* format(jakelib::lang::Object *obj); 

      /**
       * This method formats an \c Object into a \c String and
       * appends the \c String to a \c StringBuffer.
       *
       * @param obj The \c Object to format.
       * @param sbuf The \c StringBuffer to append to.
       * @param fp  The desired \c FieldPosition, which is also
       *            updated by this call. 
       * @return The updated \c StringBuffer.
       *
       * @exception IllegalArgumentException If the \c Object
       *            cannot be formatted. 
       */
      virtual jakelib::lang::StringBuffer* format(jakelib::lang::Object *obj, 
                                                  jakelib::lang::StringBuffer *sbuf,
                                                  FieldPosition *fp) = 0;

      /**
       * This method parses a <code>String</code> and converts the parsed 
       * contents into an <code>Object</code>.
       *
       * @param str The \c String to parse.
       *
       * @return The resulting \c Object.
       *
       * @exception ParseException If the \c String cannot be parsed.
       */
      virtual jakelib::lang::Object* parseObject(jakelib::lang::String *str); 

      /**
       * This method parses a \c String and converts the parsed
       * contents into an \c Object.
       *
       * @param str The \c String to parse.
       * @param pos The starting parse index on input, the ending parse
       *            index on output.
       * @return The parsed \c Object, or \c null in case of an error.
       */
      virtual jakelib::lang::Object* parseObject(jakelib::lang::String *str,
                                                 jakelib::text::ParsePosition *pos) = 0;

      /**
       * Creates a copy of this object.
       *
       * @return The copied \c Object.
       */
      jakelib::lang::Object* clone();

      JAKELIB_DECLARE_CLASS(Format);
    };

    JAKELIB_DECLARE_ARRAY(Format);
  }
}

#endif
