Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r75187 - trunk/libs/filesystem/v3/doc
From: bdawes_at_[hidden]
Date: 2011-10-31 08:09:07

Next message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r75188 - sandbox/multiprecision/libs/multiprecision/test"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r75186 - in trunk/boost/chrono: . io"

Author: bemandawes
Date: 2011-10-31 08:09:06 EDT (Mon, 31 Oct 2011)
New Revision: 75187
URL: http://svn.boost.org/trac/boost/changeset/75187

Log:
Reorganize, clarify, class path docs for conversions
Text files modified:
trunk/libs/filesystem/v3/doc/reference.html | 181 ++++++++++++++++++++++++---------------
1 files changed, 113 insertions(+), 68 deletions(-)

Modified: trunk/libs/filesystem/v3/doc/reference.html
==============================================================================
--- trunk/libs/filesystem/v3/doc/reference.html (original)
+++ trunk/libs/filesystem/v3/doc/reference.html 2011-10-31 08:09:06 EDT (Mon, 31 Oct 2011)
@@ -62,6 +62,14 @@
 Header <code><boost/filesystem.hpp></code> synopsis</a> 
 <a href="#Error-reporting">Error reporting</a> 
 <a href="#class-path">Class <code>path</code></a> 
+    path conversions 
+    <a href="#path-Conversions-to-native-format"><code>path</code>
+ conversions to native format</a> 
+    <a href="#path-Conversions-to-generic-format"><code>path</code>
+ conversions to generic format</a> 
+    <a href="#path-Encoding-conversions"><code>path</code>
+ encoding conversions</a> 
+    path requirements 
     path constructors 
    path assignments 
    path appends 
@@ -118,12 +126,12 @@
   &nbsp exists 
   &nbsp equivalent 
   &nbsp file_size 
-     hard_link_count</code></td>
- <td width="34%" valign="top">
- <code>     initial_path 
+     hard_link_count 
+      initial_path 
   &nbsp is_directory 
-   &nbsp is_empty 
-   &nbsp is_other 
+   &nbsp is_empty</code></td>
+ <td width="34%" valign="top">
+ <code>   &nbsp is_other 
   &nbsp is_regular_file 
   &nbsp is_symlink 
   &nbsp last_write_time 
@@ -202,6 +210,7 @@
no elements which are symbolic links, and no dot or dot dot elements.
<a name="Pathname">Pathname</a>: A character string that represents a
path. Pathnames are formatted according to the generic pathname format or the
+implementation defined
native pathname format.
<a name="generic-pathname-format">Generic pathname format:</a>
<blockquote>
@@ -678,9 +687,96 @@
 } // namespace boost</pre>
<code><a name="value_type">value_type</a></code> is an implementation-defined
<code>typedef</code> for the
-character type used by the implementation to represent pathnames.
-If the value type of  [<code>begin</code>,<code>end</code>)
- or <code>source</code> arguments for member functions is not <code>value_type</code>,
+character type used by the operating system to represent pathnames.
+Member functions described as returning <code>const string</code>, <code>
+const wstring</code>, <code>const u16string</code>, or <code>const u32string</code> are permitted to return <code>const string&</code>, <code>const
+wstring&</code>, <code>const u16string&</code>, or <code>const u32string&</code>,
+respectively.
+<blockquote>
+[Note: This allows implementations to avoid unnecessary copies when no
+conversion is required.
+Return-by-value is specified as
+<code>const</code> to ensure programs won't break if moved to a return-by-reference
+implementation. --
+end note]
+</blockquote>
+<h3><a name="path-Conversions"><code>path</code> Conversions</a></h3>
+<h4><a name="path-Conversions-to-native-format"><code>path</code> Conversions to
+native format</a></h4>
+Member function arguments that take character sequences representing paths
+may use the generic pathname format or
+the native pathname format. If such an
+argument uses the generic format, an implementation defined conversion to native format is performed
+during the processing of the argument. 
+<blockquote>
+[Note: No conversion occurs on POSIX and Windows since they have
+native formats that conform to the generic format. --end note]
+[Rationale: There is no unambiguous way for an implementation to
+always be able distinguish between native format and generic format arguments.
+This is by design as it simplifies use. Should an implementation encounter an
+operating system where disambiguation is required, an implementation defined
+native format prefix can be introduced to identify the native format. -- end
+rationale]
+</blockquote>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ Class <code>path</code> does not currently map invalid characters in
+ filenames to valid characters. In the future we might add something like
+ this:<blockquote>
+When converting filenames to the native operating system format,
+implementations are encouraged, but not required, to convert otherwise invalid
+characters or character sequences to valid characters or character sequences.
+Such conversions are implementation-defined.
+<blockquote>
+[Note: Filename conversion allows much wider portability of both
+programs and filenames that would otherwise be possible.
+Implementations are encouraged to base conversion on existing standards or
+practice. Examples include the Uniform Resource Locator escape syntax of a percent sign (<code>'%'</code>)
+followed by two hex digits representing the character value. On
+OpenVMS, which does not allow percent signs in filenames, a dollar sign (<code>'$'</code>)
+followed by two hex digits is the existing practice, as is converting lowercase
+letters to uppercase. -- end note.]
+</blockquote>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+If the native format requires
+paths for regular files to be formatted differently from paths for directories, the
+path shall be treated as a directory path if last element is a separator,
+otherwise it shall be treated as a regular file path.
+
+<blockquote>
+
+[Note: The above paragraph does not apply to POSIX and Windows since
+they use the same format
+for both regular file and directory pathnames. --end note]
+
+[Example:
+On OpenVMS, a path
+constructed from <code>"/cats/jane"</code> would considered a regular file
+path, and have a native format of <code>"[CATS]JANE"</code>, while a
+path constructed from <code>"/cats/jane/"</code> would be considered a
+directory path, and have a native format of <code>"[CATS.JANE]"</code>.
+--end example]
+
+</blockquote>
+<h4><a name="path-Conversions-to-generic-format"><code>path</code> Conversions
+to generic format</a></h4>
+Generic format observer
+functions return strings formatted according to the
+generic pathname format. The conversion
+from generic to native formats is implementation defined.
+<blockquote>
+[Note: For POSIX, no conversion is performed. For Windows, backslashes are converted to
+forward slashes. -- end note]
+</blockquote>
+<h4><a name="path-Encoding-conversions"><code>path</code> Encoding conversions</a></h4>
+If the value type of member function arguments that are character sequences
+representing paths is not <code>value_type</code>,
and no <code>cvt</code> argument is supplied, conversion to <code>value_type</code>
occurs using an imbued locale. This imbued locale is initialized with a <code>
codecvt</code> facet appropriate for the operating system.
@@ -691,12 +787,11 @@
parameters to be in UTF-8 encoding and nothing else." See
<a href="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPInternational/Articles/FileEncodings.html">
Apple docs</a>. -- end rationale]
-For Windows-like implementations, including
- Cygwin and
+For Windows-like implementations, including
<a href="http://www.mingw.org/">MinGW</a>, <code>path::value_type</code> is <code>
wchar_t</code>. The default imbued locale provides a <code>codecvt</code> facet
that invokes Windows <code>MultiByteToWideChar</code> or <code>
-WideCharToMultiByte</code> API's with a codepage of <code>CP_THREAD_ACP</code>
+WideCharToMultiByte</code> API with a codepage of <code>CP_THREAD_ACP</code>
if Windows <code>AreFileApisANSI()</code>is true, otherwise codepage <code>
CP_OEMCP</code>. [Rationale: this is the current behavior of C and C++
programs that perform file operations using narrow character string to identify
@@ -706,26 +801,15 @@
is <code>char</code>. The default imbued locale is <code>std::locale("")</code>.
[Rationale: ISO C specifies this as "the locale-specific native
environment", while POSIX says it "Specifies an implementation-defined native
-environment." -- end rationale
+environment." -- end rationale]
</blockquote>
-For member functions described as returning <code>const string</code>, <code>
-const wstring</code>, <code>const u16string</code>, or <code>const u32string</code>,
-implementations are permitted to return <code>const string&</code>, <code>const
-wstring&</code>, <code>const u16string&</code>, or <code>const u32string&</code>,
-respectively.
-<blockquote>
-[Note: This allows implementations to avoid unnecessary copies when no
-conversion is required.
-Return-by-value is specified as
-<code>const</code> to ensure programs won't break if moved to a return-by-reference
-implementation. --
-end note]
-</blockquote>
-<code><a name="InputIterator">InputIterator</a></code> is required meet the
+<h3><a name="path-Requirements"><code>path</code> Requirements</a></h3>
+Template parameters named <code><a name="InputIterator">InputIterator</a></code>
+are required meet the
requirements for a C++ standard library <code>RandomIterator</code>
compliant iterator. The iterator's value type is required to be <code>char</code>, <code>
 wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.
-<code><a name="Source">Source</a></code> is required to be one of:
+Template parameters named <code><a name="Source">Source</a></code> are required to be one of:
<ul>
 <li>A container with a value type of <code>char</code>, <code>
 wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
@@ -736,45 +820,6 @@
 wchar_t</code>, <code>char16_t</code>, or <code>char32_t</code>.</li>
 <li>A <code>boost::filesystem::directory_entry</code>.</li>
</ul>
-The specifications for <code>path</code> functions require that
-arguments in the generic pathname format be converted to native pathname format
-as they are stored in <code>pathname</code>. If the native format requires
-regular file paths and directory paths to be formatted differently, the
-implementation shall determine which format to use according to whether or not
-the last element of the generic format string is a separator. [Example:
-On OpenVMS, a path
-constructed from <code>"/cats/jane"</code> would considered a regular file
-path, and have a native format of <code>"[CATS]JANE"</code>, while a
-path constructed from <code>"/cats/jane/"</code> would be considered a
-directory path, and have a native format of <code>"[CATS.JANE]"</code>.
---end example] [Note: POSIX and Windows use the same native format
-for both regular file and directory pathnames, so this paragraph does not apply to
-them. --end note]
-
-<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
- <tr>
- <td style="font-size: 10pt">
- Class <code>path</code> does not currently map invalid characters in
- filenames to valid characters. In the future we might add something like
- this:<blockquote>
-When converting filenames to the native operating system format,
-implementations are encouraged, but not required, to convert otherwise invalid
-characters or character sequences to valid characters or character sequences.
-Such conversions are implementation-defined.
-<blockquote>
-[Note: Filename conversion allows much wider portability of both
-programs and filenames that would otherwise be possible.
-Implementations are encouraged to base conversion on existing standards or
-practice. Examples include the Uniform Resource Locator escape syntax of a percent sign (<code>'%'</code>)
-followed by two hex digits representing the character value. On
-OpenVMS, which does not allow percent signs in filenames, a dollar sign (<code>'$'</code>)
-followed by two hex digits is the existing practice, as is converting lowercase
-letters to uppercase. -- end note.]
-</blockquote>
- </blockquote>
- </td>
- </tr>
-</table>

<h3> <a name="path-constructors"> <code>
path</code> constructors</a></h3>
@@ -3535,7 +3580,7 @@
The Windows API has many functions that also have Unicode versions to permit
an extended-length path for a maximum total path length of 32,767 characters.
... To specify an extended-length path, use the "\\?\" prefix. For
-example, "\\?\D:\very long path". 
+example, "\\?\D:\very long path". 
[C++ string literals require backslashes be doubled, of course.]
</blockquote>
Because most Boost.Filesystem operational functions just pass the contents of
@@ -3604,7 +3649,7 @@

<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>
Revised
-16 October 2011
+31 October 2011

</body>

Next message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r75188 - sandbox/multiprecision/libs/multiprecision/test"
Previous message: vicente.botet_at_[hidden]: "[Boost-commit] svn:boost r75186 - in trunk/boost/chrono: . io"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk