Arcane bits of path trivia

base/file_path.h

 // Copyright (c) 2008 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // FilePath is a container for pathnames stored in a platform's native string
 // type, providing containers for manipulation in according with the
 // platform's conventions for pathnames.  It supports the following path
 // types:
 //
 //                   POSIX            Windows
 //                   ---------------  ----------------------------------
 // Fundamental type  char[]           wchar_t[]
 // Encoding          unspecified*     UTF-16
 // Separator         /                \, tolerant of /
 // Drive letters     no               case-insensitive A-Z followed by :
 // Alternate root    // (surprise!)   \\, for UNC paths
 //
 // * The encoding need not be specified on POSIX systems, although some
 //   POSIX-compliant systems do specify an encoding.  Mac OS X uses UTF-8.
 //   Linux does not specify an encoding, but in practice, the locale's
 //   character set may be used.
 //
+// For more arcane bits of path trivia, see below.
+//
 // FilePath objects are intended to be used anywhere paths are.  An
 // application may pass FilePath objects around internally, masking the
 // underlying differences between systems, only differing in implementation
 // where interfacing directly with the system.  For example, a single
 // OpenFile(const FilePath &) function may be made available, allowing all
 // callers to operate without regard to the underlying implementation.  On
 // POSIX-like platforms, OpenFile might wrap fopen, and on Windows, it might
 // wrap _wfopen_s, perhaps both by calling file_path.value().c_str().  This
 // allows each platform to pass pathnames around without requiring conversions
 // between encodings, which has an impact on performance, but more imporantly,
@@ skipping 28 matching lines @@
 // |   FilePath log_file_path(kLogFileName);
 // |   [...]
 // | }
 //
 // WARNING: FilePaths should ALWAYS be displayed with LTR directionality, even
 // when the UI language is RTL. This means you always need to pass filepaths
 // through l10n_util::WrapPathWithLTRFormatting() before displaying it in the
 // RTL UI.
 //
 // This is a very common source of bugs, please try to keep this in mind.
+//
+// ARCANE BITS OF PATH TRIVIA
+//
+//  - A double leading slash is actually part of the POSIX standard.  Systems
+//    are allowed to treat // as an alternate root, as Windows does for UNC
+//    (network share) paths.  Most POSIX systems don't do anything special
+//    with two leading slashes, but FilePath handles this case properly
+//    in case it ever comes across such a system.  FilePath needs this support
+//    for Windows UNC paths, anyway.
+//    References:
+//    The Open Group Base Specifications Issue 7, sections 3.266 ("Pathname")
+//    and 4.12 ("Pathname Resolution"), available at:
+//    http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_266
+//    http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12
+//
+//  - Windows treats c:\\ the same way it treats \\.  This was intended to
+//    allow older applications that require drive letters to support UNC paths
+//    like \\server\share\path, by permitting c:\\server\share\path as an
+//    equivalent.  Since the OS treats these paths specially, FilePath needs
+//    to do the same.  Since Windows can use either / or \ as the separator,
+//    FilePath treats c://, c:\\, //, and \\ all equivalently.
+//    Reference:
+//    The Old New Thing, "Why is a drive letter permitted in front of UNC
+//    paths (sometimes)?", available at:
+//    http://blogs.msdn.com/oldnewthing/archive/2005/11/22/495740.aspx
+
 #ifndef BASE_FILE_PATH_H_
 #define BASE_FILE_PATH_H_
 
 #include <string>
 #include <vector>
 
 #include "base/basictypes.h"
 #include "base/compiler_specific.h"
 #include "base/hash_tables.h"
 #include "base/string_piece.h"  // For implicit conversions.
@@ skipping 215 matching lines @@
 namespace stdext {
 
 inline size_t hash_value(const FilePath& f) {
   return hash_value(f.value());
 }
 
 }  // namespace stdext
 #endif  // COMPILER
 
 #endif  // BASE_FILE_PATH_H_