Deprecate the ability to change the FS encoding separate from the locale

Changing the encoding used by filenames separately from the locale
encoding is a broken concept and cannot work properly. This creates
ambiguity depending on the data source and how it's being treated.

Instead, enforce that the locale encoding is the only possibility to
deal with file names.

The QFile::encodeName and decodeName functions are retained due to the
Mac-specific issues and due to the sheer number of current
uses. There's no point in deprecating them and moving away from them.

Change-Id: Iedb2d8715d166a59a824f05bc11d107fd44f9c17
Discussed-on: http://lists.qt-project.org/pipermail/development/2012-May/003782.html
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>

dist/changes-5.0.0

@@ -347,6 +347,14 @@ QtCore
   QCoreApplication::Encoding value CodecForTr is now obsolete, use
   DefaultCodec instead. For reasoning, see the codecForCStrings() removal above.
 
+* QFile::setEncodingFunction and QFile::setDecodingFunction are obsolete and do
+  nothing in Qt 5. The QFile::encodeName and QFile::decodeName functions are now
+  hardcoded to operate on QString::fromLocal8Bit and QString::toLocal8Bit
+  only. Therefore, it's still possible to obtain the old behaviour by calling
+  QTextCodec::setCodecForLocale. However, that is not recommended: new code
+  should not make assumptions about the filesystem encoding and older code should
+  have those assumptions removed.
+
 * QIntValidator and QDoubleValidator no longer fall back to using the C locale if
   the requested locale fails to validate the input.
 

src/corelib/io/qfile.cpp

@@ -59,30 +59,7 @@
 
 QT_BEGIN_NAMESPACE
 
-static QByteArray locale_encode(const QString &f)
-{
-#if defined(Q_OS_DARWIN)
-    // Mac always expects UTF-8... and decomposed...
-    return f.normalized(QString::NormalizationForm_D).toUtf8();
-#else
-    return f.toLocal8Bit();
-#endif
-}
-
-static QString locale_decode(const QByteArray &f)
-{
-#if defined(Q_OS_DARWIN)
-    // Mac always gives us UTF-8 and decomposed, we want that composed...
-    return QString::fromUtf8(f).normalized(QString::NormalizationForm_C);
-#else
-    return QString::fromLocal8Bit(f);
-#endif
-}
-
 //************* QFilePrivate
-QFile::EncoderFn QFilePrivate::encoder = locale_encode;
-QFile::DecoderFn QFilePrivate::decoder = locale_decode;
-
 QFilePrivate::QFilePrivate()
 {
 }
@@ -358,22 +335,19 @@ QFile::setFileName(const QString &name)
 */
 
 /*!
-    By default, this function converts \a fileName to the local 8-bit
+    \fn QByteArray QFile::encodeName(const QString &fileName)
+
+    Converts \a fileName to the local 8-bit
     encoding determined by the user's locale. This is sufficient for
     file names that the user chooses. File names hard-coded into the
     application should only use 7-bit ASCII filename characters.
 
-    \sa decodeName(), setEncodingFunction()
+    \sa decodeName()
 */
 
-QByteArray
-QFile::encodeName(const QString &fileName)
-{
-    return (*QFilePrivate::encoder)(fileName);
-}
-
 /*!
     \typedef QFile::EncoderFn
+    \obsolete
 
     This is a typedef for a pointer to a function with the following
     signature:
@@ -384,36 +358,24 @@ QFile::encodeName(const QString &fileName)
 */
 
 /*!
+    \fn QString QFile::decodeName(const QByteArray &localFileName)
+
     This does the reverse of QFile::encodeName() using \a localFileName.
 
-    \sa setDecodingFunction(), encodeName()
+    \sa encodeName()
 */
 
-QString
-QFile::decodeName(const QByteArray &localFileName)
-{
-    return (*QFilePrivate::decoder)(localFileName);
-}
-
 /*!
     \fn void QFile::setEncodingFunction(EncoderFn function)
+    \obsolete
 
-    \nonreentrant
-
-    Sets the \a function for encoding Unicode file names. The
-    default encodes in the locale-specific 8-bit encoding.
+    This function does nothing. It is provided for compatibility with Qt 4 code
+    that attempted to set a different encoding function for file names. That
+    feature is flawed and no longer supported in Qt 5.
 
     \sa encodeName(), setDecodingFunction()
 */
 
-void
-QFile::setEncodingFunction(EncoderFn f)
-{
-    if (!f)
-        f = locale_encode;
-    QFilePrivate::encoder = f;
-}
-
 /*!
     \typedef QFile::DecoderFn
 
@@ -427,23 +389,15 @@ QFile::setEncodingFunction(EncoderFn f)
 
 /*!
     \fn void QFile::setDecodingFunction(DecoderFn function)
+    \obsolete
 
-    \nonreentrant
-
-    Sets the \a function for decoding 8-bit file names. The
-    default uses the locale-specific 8-bit encoding.
+    This function does nothing. It is provided for compatibility with Qt 4 code
+    that attempted to set a different decoding function for file names. That
+    feature is flawed and no longer supported in Qt 5.
 
     \sa setEncodingFunction(), decodeName()
 */
 
-void
-QFile::setDecodingFunction(DecoderFn f)
-{
-    if (!f)
-        f = locale_decode;
-    QFilePrivate::decoder = f;
-}
-
 /*!
     \overload
 

src/corelib/io/qfile.h

@@ -76,14 +76,35 @@ public:
     QString fileName() const;
     void setFileName(const QString &name);
 
-    typedef QByteArray (*EncoderFn)(const QString &fileName);
-    typedef QString (*DecoderFn)(const QByteArray &localfileName);
-    static QByteArray encodeName(const QString &fileName);
-    static QString decodeName(const QByteArray &localFileName);
+#if defined(Q_OS_DARWIN)
+    // Mac always expects filenames in UTF-8... and decomposed...
+    static inline QByteArray encodeName(const QString &fileName)
+    {
+        return fileName.normalized(QString::NormalizationForm_D).toUtf8();
+    }
+    static QString decodeName(const QByteArray &localFileName)
+    {
+        return QString::fromUtf8(localFileName).normalized(QString::NormalizationForm_C);
+    }
+#else
+    static inline QByteArray encodeName(const QString &fileName)
+    {
+        return fileName.toLocal8Bit();
+    }
+    static QString decodeName(const QByteArray &localFileName)
+    {
+        return QString::fromLocal8Bit(localFileName);
+    }
+#endif
     inline static QString decodeName(const char *localFileName)
         { return decodeName(QByteArray(localFileName)); }
-    static void setEncodingFunction(EncoderFn);
-    static void setDecodingFunction(DecoderFn);
+
+#if QT_DEPRECATED_SINCE(5,0)
+    typedef QByteArray (*EncoderFn)(const QString &fileName);
+    typedef QString (*DecoderFn)(const QByteArray &localfileName);
+    QT_DEPRECATED static void setEncodingFunction(EncoderFn) {}
+    QT_DEPRECATED static void setDecodingFunction(DecoderFn) {}
+#endif
 
     bool exists() const;
     static bool exists(const QString &fileName);

src/corelib/io/qfile_p.h

@@ -75,10 +75,6 @@ protected:
     virtual QAbstractFileEngine *engine() const;
 
     QString fileName;
-
-private:
-    static QFile::EncoderFn encoder;
-    static QFile::DecoderFn decoder;
 };
 
 QT_END_NAMESPACE