/**************************************************************
 * 
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 *************************************************************/


#ifndef _COMPHELPER_LOCALE_HXX_
#define _COMPHELPER_LOCALE_HXX_

//_______________________________________________
// includes

#include <vector>
#include <rtl/ustring.hxx>
#include "comphelper/comphelperdllapi.h"

// These are specified by i386 ABI suppl. but
// only affect Solaris i386/illumos so far.

#if !defined(_XPG4_2) || defined(__EXTENSIONS__)
#undef	CS
#undef	ES
#endif

//_______________________________________________
// namespace

namespace comphelper{

//_______________________________________________
// definitions

/** @short  A Locale object represents a specific geographical, political, or cultural region.

    @descr  This Locale class can be used to:
            - provide the different parts of a Locale (Language, Country, Variant)
            - converting it from/to ISO formated string values (like e.g. "en-US")
            - provide some predefined (static) Locale objects
 */
class COMPHELPER_DLLPUBLIC Locale
{
    //-------------------------------------------
    // const

    public:
    
        /** @short separates LANGUAGE and COUNTRY part of an ISO formated Locale. */
        static const sal_Unicode SEPERATOR_LC;
        
        /** @short separates COUNTRY and VARIANT part of an ISO formated Locale. */
        static const sal_Unicode SEPERATOR_CV;
        
        /** @short separates COUNTRY and VARIANT part of an ISO formated Locale.
            @descr Its true for some linux derivates only :-( */
        static const sal_Unicode SEPERATOR_CV_LINUX;
        
        /** @short some predefined Locale objects. */
        static const Locale& EN_US();
        static const Locale& EN();
        static const Locale& DE_DE();
        static const Locale& DE_CH();
        static const Locale& DE_AT();
        static const Locale& AR();
        static const Locale& CA();
        static const Locale& CS();
        static const Locale& DA();
        static const Locale& EL();
        static const Locale& ES();
        static const Locale& FI();
        static const Locale& FR();
        static const Locale& HE();
        static const Locale& HI_IN();
        static const Locale& HU();
        static const Locale& IT();
        static const Locale& JA();
        static const Locale& KO();
        static const Locale& NL();
        static const Locale& PL();
        static const Locale& PT();
        static const Locale& PT_BR();
        static const Locale& RU();
        static const Locale& SK();
        static const Locale& SL();
        static const Locale& SV();
        static const Locale& TH();
        static const Locale& TR();
        static const Locale& X_DEFAULT();
        static const Locale& X_COMMENT();
        static const Locale& X_TRANSLATE();
        static const Locale& X_NOTRANSLATE();
        static const Locale& ZH_CN();
        static const Locale& ZH_TW();
                            
    //-------------------------------------------
    // types
    
    public:
    
        /** @short will be throw during conversion, if a Locale can't be interpreted. */
        struct MalFormedLocaleException
        {
            public:
                ::rtl::OUString Message;
                
                MalFormedLocaleException()
                {}
            
                MalFormedLocaleException(const ::rtl::OUString& sMessage)
                    : Message(sMessage)
                {}
        };
    
    //-------------------------------------------
    // member

    private :

        //---------------------------------------
        /** @short  must be a valid ISO	Language Code.
        
            @descr  These codes are the lower-case two-letter codes as defined by ISO-639.
                    You can find a full list of these codes at a number of sites, such as:
                    <BR><a href ="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
                    http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</a>
         */
        ::rtl::OUString m_sLanguage;
        
        //---------------------------------------
        /** @short  must be a valid ISO Country	Code.
            @descr  These codes are the upper-case two-letter codes	as defined by ISO-3166.
                    You can find a full list of these codes at a number of sites, such as:
                    <BR><a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
                    http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html</a>
         */
        ::rtl::OUString m_sCountry;
        
        //---------------------------------------
        /** @short  Variant codes are vendor and browser-specific.
            @descr  For example, use WIN for Windows, MAC for Macintosh, and POSIX for POSIX.
                    Where there are two variants, separate them with an underscore, and
                    put the most important one first. For example, a Traditional Spanish collation
                    might be referenced, with "ES", "ES", "Traditional_WIN".
         */
        ::rtl::OUString m_sVariant;

    //-------------------------------------------
    // interface

    public :

        //---------------------------------------
        /** @short  needed by outside users!
        
            @descr  Otherwise it wouldnt be possible to use
                    any instance of such Locale static ...
         */
        Locale();
        
        //---------------------------------------
        /** @short      construct a Locale from an ISO formated string value.
        
            @seealso    fromISO()
            
            @param      sISO
                        an ISO formated string value, which can be parsed and
                        tokenized into a Lamnguage, Country and Variant part.
                        
            @throw      MalFormedLocaleException
                        if conversion failed.
          */
        Locale(const ::rtl::OUString& sISO)
            throw(MalFormedLocaleException);
        
        //---------------------------------------
        /** @short      construct a Locale from language, country and variant.
        
            @seealso    setLanguage()
            @seealso    setCountry()
            @seealso    setVariant()
            
            @param      sLanguage
                        lowercase two-letter ISO-639 code.
                        
            @param      sCountry
                        uppercase two-letter ISO-3166 code.
                        
            @param      sVariant
                        vendor and browser specific code.
          */
        Locale(const ::rtl::OUString& sLanguage                   ,
               const ::rtl::OUString& sCountry                    ,
               const ::rtl::OUString& sVariant = ::rtl::OUString());

        //---------------------------------------
        /** @short  copy constructor.
        
            @param  aCopy
                    the copy object.
         */
        Locale(const Locale& aCopy);
               
        //---------------------------------------
        /** @short  returns the language code for this locale.
        
            @descr  That will either be the empty string or
                    a lowercase ISO 639 code.
        
            @return [string]
                    the language code.
         */
        ::rtl::OUString getLanguage() const;

        //---------------------------------------
        /** @short  returns the country/region code for this locale.
        
            @descr  That will either be the empty string or an
                    upercase ISO 3166 2-letter code.
        
            @return [string]
                    the country code.
         */
        ::rtl::OUString getCountry() const;
        
        //---------------------------------------
        /** @short  returns the variant code for this locale.
        
            @return [string]
                    the variant code.
         */
        ::rtl::OUString getVariant() const;

        //---------------------------------------
        /** @short  set the new language code for this locale.
        
            @descr  That will either be the empty string or
                    a lowercase ISO 639 code.
        
            @param  sLanguage
                    the language code.
         */
        void setLanguage(const ::rtl::OUString& sLanguage);

        //---------------------------------------
        /** @short  set the new country/region code for this locale.
        
            @descr  That will either be the empty string or an
                    upercase ISO 3166 2-letter code.
        
            @param  sCountry
                    the country code.
         */
        void setCountry(const ::rtl::OUString& sCountry);
        
        //---------------------------------------
        /** @short  set the new variant code for this locale.
        
            @param  sVariant
                    the variant code.
         */
        void setVariant(const ::rtl::OUString& sVariant);
        
        //---------------------------------------
        /** @short      take over new Locale informations.
        
            @seealso    Locale(const ::rtl::OUString& sISO)
            
            @param      sISO
                        an ISO formated string value, which can be parsed and
                        tokenized into a Lamnguage, Country and Variant part.
                        e.g. "en-US" or "en-US_WIN"
                        
            @throw      MalFormedLocaleException
                        if conversion failed.
          */
        void fromISO(const ::rtl::OUString& sISO)
            throw(MalFormedLocaleException);
        
        //---------------------------------------
        /** @short  converts this Locale to an ISO formated string value.
        
            @descr  The different parts of this Locale will be assempled
                    e.g. to "en-US" or "en-US_WIN"
                    
            @return [string]
                    the ISO formated string.
          */
        ::rtl::OUString toISO() const;

        //---------------------------------------
        /** @short  check, if two Locale objects are equals.
        
            @descr  All parts of a Locale (means Language, Country and Variant)
                    will be checked.
                    
            @param  aComparable
                    the Locale object for compare.
                    
            @return [boolean]
                    TRUE if both objects uses the same values for
                    Language, Country and Variant.
         */
        sal_Bool equals(const Locale& aComparable) const;

        //---------------------------------------
        /** @short  check, if two Locale objects
                    uses the same language.
        
            @descr  The Country and Variant parts of a Locale
                    wont be checked here.
                    
            @return [boolean]
                    TRUE if both objects uses the same
                    Language value.
         */
        sal_Bool similar(const Locale& aComparable) const;

        //---------------------------------------
        /** @short      search for an equal or at least for a similar
                        Locale in a list of possible ones.
                        
            @descr      First it searches for a Locale, which is equals
                        to the reference Locale.
                        (means: same Language, Country, Variant)
                        
                        If the reference Locale couldnt be located, it will
                        tried again - but we are checking for "similar" Locales then.
                        (means: same Language)
                        
                        If no similar Locale could be located, we search
                        for a Locale "en-US" inside the given Locale list.
                        
                        If "en-US" could not be located, we search for
                        a Locale "en" inside the given list.
                        
                        If no "same" nor any "similar" locale could be found,
                        we try "x-default" and "x-notranslate" explicitly.
                        Sometimes localized variables are optimized and doesn't use
                        localzation really. E.g. in case the localized value is a fix
                        product name.
                        
                        If no locale match till now, we use any other existing
                        locale, which exists inside the set of given ones!
                        
            @seealso    equals()                    
            @seealso    similar()
            
            @param      lISOList
                        the list of possible Locales
                        (as formated ISO strings).
                        
            @param      sReferenceISO
                        the reference Locale, which should be searched
                        if its equals or similar to any Locale inside
                        the provided Locale list.
                        
            @return     An iterator, which points to the found element
                        inside the given Locale list.
                        If no matching Locale could be found, it points
                        to the end of the list.                        
                        
            @throw      [MalFormedLocaleException]
                        if at least one ISO formated string couldnt
                        be converted to a valid Locale Object.
         */
        static ::std::vector< ::rtl::OUString >::const_iterator getFallback(const ::std::vector< ::rtl::OUString >& lISOList     ,
                                                                            const ::rtl::OUString&                  sReferenceISO)
            throw(MalFormedLocaleException);
            
        //---------------------------------------
        /** @short      search for the next possible fallback locale.
        
            @descr      Instead of getFallback(vector<>, string) this method
                        uses the given locale and decide by using an algorithm
                        which locale can be the next possible one.
                        
                        Algorithm:
                        - if locale has country return language only
                        - if locale different "en-US" return "en-US"
                        - if locale "en-US" return "en"
                        
            @param      aLocale [in/out]!
                        the incoming value will be used to start
                        search for a possible fallback ...
                        and in case such fallback was found this parameter
                        will be used for return too.

            @return     TRUE if the parameter aLocale contains a new fallback value;
                        FALSE otherwise.                        
         */
        static sal_Bool getFallback(Locale& aLocale);            

        //---------------------------------------
        /** @short      assign elements of another locale
                        to this instance.
                        
            @param      rCopy
                        another locale object.
         */
        void operator=(const Locale& rCopy);
        
        //---------------------------------------
        /** @short      check if two Locale objects are equals.
        
            @seealso    equals()
            
            @param      aComparable
                        the Locale object for compare.
                        
            @return     [boolean]
                        TRUE if both objects uses the same values for
                        Language, Country and Variant.
         */
        sal_Bool operator==(const Locale& aComparable) const;
        
        //---------------------------------------
        /** @short  check if two Locale objects are different.
        
            @param  aComparable
                    the Locale object for compare.
                    
            @return [boolean]
                    TRUE if at least one part of such Locale
                    isn't the same.
         */
        sal_Bool operator!=(const Locale& aComparable) const;
};

} // namespace salhelper

#endif // _COMPHELPER_LOCALE_HXX_