Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r69073 - trunk/libs/filesystem/v3/doc
From: bdawes_at_[hidden]
Date: 2011-02-20 07:44:19

Next message: chris_at_[hidden]: "[Boost-commit] svn:boost r69074 - website/public_html/beta/feed/history"
Previous message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r69072 - trunk/tools/release"

Author: bemandawes
Date: 2011-02-20 07:44:19 EST (Sun, 20 Feb 2011)
New Revision: 69073
URL: http://svn.boost.org/trac/boost/changeset/69073

Log:
Add links, add missing imbue/locale functions, clarify codecvt functionality.
Text files modified:
trunk/libs/filesystem/v3/doc/reference.html | 111 ++++++++++++++++++++++++++-------------
1 files changed, 73 insertions(+), 38 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-02-20 07:44:19 EST (Sun, 20 Feb 2011)
@@ -573,25 +573,25 @@
 void swap(path& rhs);

 // native format observers
- const string_type& native() const; // native format, encoding
- const value_type* c_str() const; // native().c_str()
+ const string_type& native() const; // native format, encoding
+ const value_type* c_str() const; // native().c_str()

 template <class String>
- String string(const codecvt_type& cvt=codecvt()) const; // native format
+ String string(const codecvt_type& cvt=codecvt()) const; // native format

- const string string(const codecvt_type& cvt=codecvt()) const; // native format
- const wstring wstring(const codecvt_type& cvt=codecvt()) const; // ditto
- const u16string u16string() const; // ditto
- const u32string u32string() const; // ditto
+ const string string(const codecvt_type& cvt=codecvt()) const; // native format
+ const wstring wstring(const codecvt_type& cvt=codecvt()) const; // ditto
+ const u16string u16string() const; // ditto
+ const u32string u32string() const; // ditto

 // generic format observers
 template <class String>
- String generic_string() const;
+ String generic_string() const;

- const string generic_string(const codecvt_type& cvt=codecvt()) const; // generic format
- const wstring generic_wstring(const codecvt_type& cvt=codecvt()) const; // ditto
- const u16string generic_u16string() const; // ditto
- const u32string generic_u32string() const; // ditto
+ const string generic_string(const codecvt_type& cvt=codecvt()) const; // generic format
+ const wstring generic_wstring(const codecvt_type& cvt=codecvt()) const; // ditto
+ const u16string generic_u16string() const; // ditto
+ const u32string generic_u32string() const; // ditto

 // decomposition
 path root_name() const;
@@ -623,9 +623,9 @@
 iterator begin() const;
 iterator end() const;

- // encoding conversion
- static std::locale imbue( const std::locale& loc );
- static const codecvt_type & codecvt();
+ // encoding conversion
+ static std::locale imbue( const std::locale& loc );
+ static const codecvt_type & codecvt();

 private:
 string_type pathname; // exposition only
@@ -633,16 +633,37 @@

 } // namespace filesystem
 } // namespace boost</pre>
-<code><a name="value_type">value_type</a></code> is an implementation-defined typedef for the
+<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.
-<blockquote>
-[Note: For POSIX-like implementations, including Unixes, Linux,
-and Mac OS X, <code>path::value_type</code>
-is <code>char</code> .
+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>,
+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.
+<blockquote>
+For Apple OS X implementations, <code>path::value_type</code>
+is <code>char</code>. The default imbued locale provides a UTF-8 <code>codecvt</code>
+facet. [Rationale: "All BSD system functions expect their string
+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
 <a href="http://www.cygwin.com/">Cygwin</a> and
<a href="http://www.mingw.org/">MinGW</a>, <code>path::value_type</code> is <code>
-wchar_t</code>. --end note]
+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>
+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
+paths. Changing this in the Filesystem library would be too surprising,
+particularly where user input is involved. -- end rationale]
+For all other implementations, including Linux, <code>path::value_type</code>
+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
</blockquote>
For member functions described as returning <code>const string</code>, <code>
const wstring</code>, <code>const u16string</code>, or <code>const u32string</code>,
@@ -672,7 +693,7 @@
 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 certain <code>path</code> functions require that
+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
@@ -684,7 +705,7 @@
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 regular file and directory pathnames, so this paragraph does not apply to
+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%">
@@ -725,8 +746,9 @@
<blockquote>
 Effects: Stores the contents [<code>begin</code>,<code>end</code>)
 or <code>source</code> in <code>pathname</code>. If the contents are in the
- generic format, they are converted to the native format. [Note: For
- POSIX and Windows based implementations, the generic format is already
+ generic format and the generic format is unacceptable to the operating
+ system's API, they are converted to the native format. [Note: For
+ POSIX and Windows implementations, the generic format is already
 acceptable as a native format, so no generic to native conversion is
 performed. --end note]
 
@@ -860,27 +882,27 @@
native format observers</a></h3>
The string returned by all native format observers is in the
<a href="#native-pathname-format">native pathname format</a>.
-<pre>const string_type& native() const;</pre>
+<pre>const string_type& <a name="native">native</a>() const;</pre>
<blockquote>
Returns: <code>pathname</code>.
Throws: nothing.
</blockquote>
-<pre>const value_type* c_str() const;</pre>
+<pre>const value_type* <a name="c_str">c_str</a>() const;</pre>
<blockquote>
Returns: <code>pathname.c_str()</code>.
Throws: nothing.
</blockquote>
<pre>template <class String>
-String string(const codecvt_type& cvt=codecvt()) const;</pre>
+String <a name="string-template">string</a>(const codecvt_type& cvt=codecvt()) const;</pre>
<blockquote>
 Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than <code>
String</code>, conversion is performed by <code>cvt</code>.
</blockquote>
-<pre>const string string(const codecvt_type& cvt=codecvt()) const;
-const wstring wstring(const codecvt_type& cvt=codecvt()) const;
-const u16string u16string() const;
-const u32wstring u32wstring() const; </pre>
+<pre>const string <a name="string">string</a>(const codecvt_type& cvt=codecvt()) const;
+const wstring <a name="wstring">wstring</a>(const codecvt_type& cvt=codecvt()) const;
+const u16string <a name="u16string">u16string</a>() const;
+const u32wstring <a name="u32wstring">u32wstring</a>() const; </pre>
<blockquote>
Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than
@@ -899,17 +921,17 @@
generic format are the same. For Windows, backslashes are converted to slashes
--end note]
<pre>template <class String>
-String generic_string(const codecvt_type& cvt=codecvt()) const;</pre>
+String <a name="generic_string-template">generic_string</a>(const codecvt_type& cvt=codecvt()) const;</pre>
<blockquote>
 Returns: <code>pathname</code>.
Remarks: If <code>string_type</code> is a different type than <code>
String</code>, conversion is performed by
<code>cvt</code>.
</blockquote>
-<pre>const string generic_string(const codecvt_type& cvt=codecvt()) const;
-const wstring generic_wstring(const codecvt_type& cvt=codecvt()) const;
-const u16string generic_u16string() const;
-const u32wstring generic_u32wstring() const; </pre>
+<pre>const string <a name="generic_string">generic_string</a>(const codecvt_type& cvt=codecvt()) const;
+const wstring <a name="generic_wstring">generic_wstring</a>(const codecvt_type& cvt=codecvt()) const;
+const u16string <a name="generic_u16string">generic_u16string</a>() const;
+const u32wstring <a name="generic_u32wstring">generic_u32wstring</a>() const; </pre>
<blockquote>
Returns: <code>pathname</code>.
Remarks:  If <code>string_type</code> is a different type than
@@ -1084,6 +1106,19 @@
<blockquote>
 Returns: The end iterator.
</blockquote>
+ <h3><a name="path_encoding"><code> path</code> encoding</a> conversion</h3>
+ <pre>static std::locale <a name="path-imbue">imbue</a>(const std::locale& loc);</pre>
+<blockquote>
+ Effects: Stores <code>loc</code> as the default locale for all
+ objects of type <code>path</code>.
+ Returns: The previous default locale for all objects of type <code>
+ path</code>.
+</blockquote>
+<pre>static const codecvt_type& <a name="path-codecvt">codecvt</a>();</pre>
+<blockquote>
+ Returns: The <code>codecvt</code> facet for the default locale for
+ all objects of type <code>path</code>.
+</blockquote>
<h3> <a name="path-deprecated-functions"><code> path</code> deprecated functions</a></h3>
 Several member functions from previous versions of <code>class path</code>
have been deprecated, either because they have been renamed or because the
@@ -3221,7 +3256,7 @@
Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>
Revised
-12 February 2011
+18 February 2011

</body>

Next message: chris_at_[hidden]: "[Boost-commit] svn:boost r69074 - website/public_html/beta/feed/history"
Previous message: bdawes_at_[hidden]: "[Boost-commit] svn:boost r69072 - trunk/tools/release"

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