Commit 620039ad by Benjamin Kosnik Committed by Benjamin Kosnik

*: Remove all but contents of ext/pb_ds.

2008-02-11  Benjamin Kosnik  <bkoz@redhat.com>

	* doc/html/*: Remove all but contents of ext/pb_ds.
	* doc/html/index.html: New.
	* doc/html/README: New.

From-SVN: r132250
parent c9024a78
2008-02-11 Benjamin Kosnik <bkoz@redhat.com> 2008-02-11 Benjamin Kosnik <bkoz@redhat.com>
* doc/html/*: Remove all but contents of ext/pb_ds.
* doc/html/index.html: New.
* doc/html/README: New.
2008-02-11 Benjamin Kosnik <bkoz@redhat.com>
* doc/doxygen/mainpage.html: Add in corrected links. * doc/doxygen/mainpage.html: Add in corrected links.
* README: Edit, move most into... * README: Edit, move most into...
* doc/xml/manual/appendix_contributing.xml (Directory Layout): ...here. * doc/xml/manual/appendix_contributing.xml (Directory Layout): ...here.
......
This is the list of names "reserved to the implementation" that
have been claimed by certain compilers and system headers of interest,
and should not be used in the library. It will grow, of course.
We generally are interested in names that are not all-caps, except
for those like "_T"
For Solarix:
_B
_C
_L
_N
_P
_S
_U
_X
_E1
..
_E24
Irix adds:
_A
_G
MS adds:
_T
BSD adds:
__used
__unused
__inline
_Complex
__istype
__maskrune
__tolower
__toupper
__wchar_t
__wint_t
_res
_res_ext
__tg_*
For GCC:
[Note that this list is out of date. It applies to the old
name-mangling; in G++ 3.0 and higher a different name-mangling is
used. In addition, many of the bugs relating to G++ interpreting
these names as operators have been fixed.]
The full set of __* identifiers (combined from gcc/cp/lex.c and
gcc/cplus-dem.c) that are either old or new, but are definitely
recognized by the demangler, is:
__aa
__aad
__ad
__addr
__adv
__aer
__als
__alshift
__amd
__ami
__aml
__amu
__aor
__apl
__array
__ars
__arshift
__as
__bit_and
__bit_ior
__bit_not
__bit_xor
__call
__cl
__cm
__cn
__co
__component
__compound
__cond
__convert
__delete
__dl
__dv
__eq
__er
__ge
__gt
__indirect
__le
__ls
__lt
__max
__md
__method_call
__mi
__min
__minus
__ml
__mm
__mn
__mult
__mx
__ne
__negate
__new
__nop
__nt
__nw
__oo
__op
__or
__pl
__plus
__postdecrement
__postincrement
__pp
__pt
__rf
__rm
__rs
__sz
__trunc_div
__trunc_mod
__truth_andif
__truth_not
__truth_orif
__vc
__vd
__vn
SGI badnames:
__builtin_alloca
__builtin_fsqrt
__builtin_sqrt
__builtin_fabs
__builtin_dabs
__builtin_cast_f2i
__builtin_cast_i2f
__builtin_cast_d2ll
__builtin_cast_ll2d
__builtin_copy_dhi2i
__builtin_copy_i2dhi
__builtin_copy_dlo2i
__builtin_copy_i2dlo
__add_and_fetch
__sub_and_fetch
__or_and_fetch
__xor_and_fetch
__and_and_fetch
__nand_and_fetch
__mpy_and_fetch
__min_and_fetch
__max_and_fetch
__fetch_and_add
__fetch_and_sub
__fetch_and_or
__fetch_and_xor
__fetch_and_and
__fetch_and_nand
__fetch_and_mpy
__fetch_and_min
__fetch_and_max
__lock_test_and_set
__lock_release
__lock_acquire
__compare_and_swap
__synchronize
__high_multiply
__unix
__sgi
__linux__
__i386__
__i486__
__cplusplus
__embedded_cplusplus
// long double conversion members mangled as __opr
// http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html
_opr
std::allocator
- persistent allocator
- shared memory allocator (use or link to boost::shmem::allocator)
std::string
- document __gnu_cxx::__versa_string, add new policies
(Policy-based design incorporating COW
vs. deep copy issues, MT scalability
See Andrei Alexandrescu, June 2001, C/C++ Users Journal
"Generic<Programming>: A Policy-Based basic_string Implementation"
http://www.cuj.com/documents/s=7994/cujcexp1906alexandr/)
- operator!= and utility/rel_ops operators need to be made safe with
string and vector iterator classes. basic_string::reverse_iterator may
be implemented incorrectly, or need things like
operator==(__normal_iterator, const char*&), and swap(vector)
- 'do the right thing' ctor fixing needs to be done for string. This
is still subject to some debate on the library issues list, so I
suggest punting till the dust clears.
- fix template members of basic_string<> to overload iterators and
non-iterators properly. (This is the infamous hack as in vector<> etc
23.1.1 para 10.)
std::locale
- implement __convert_to_v and __convert_from_v without "C" library
functions and and LANG environment variable dependencies.
- use localedata to implement generic named (non-MT-safe) locales?
Figure out a way to use ICU data, like libjava? Re-package and use
the glibc localedata, even if we aren't on linux? Need a generic
locale model that does something besides the "C" locale.
- make locale::classic() separate from named locale code. This will
improve the static linkage situation, but will require new
initialization code. In particular, we need lazy-initialization of
locale::classic(), and maybe the has_facet/use_facet functions for all
the required facets. The end goal is a self-contained
locale_init.cc, or one with transitive closure without the locale
instantiations (locale-inst.cc) or the named locale bits
(localename.cc).
- Jerry(?)/Paolo(?) work on __float_to_char.
- minimize ctype convertion in data facets, see numpunct/num_put/num_get
std::basic_filebuf, 27_io
- wfilebuf, get variable-encoding working and tested, including
positioning and seeking. (I think this may be done now)
- wfilebuf testsuite (getting there...)
- look ahead for unbuffered io, so know when multiple putc's can be
coalesced.
- unlocked __basic_file + new mutext class
- optimized the sentries for istream/ostream
- v2 vs. v3 speed
- add optimization hooks (esp. whitespace eating) to streambuf
- add _M_begin() and _M_end() to streambuf
- add algorithm specializations for [io]streambuf_iterator (copy find etc.)
testsuite
- valgrind hooks into make check so can tell memory leakage
Some commentary on the valgrind users list
- add hooks for qmtest, pychart, other for visual diffs
- automatic testing of interactive tests
- diffing generated output files
- provide testsuites for numerics.
- make check-abi needs to have full symbol checking. Scope the LSB
testsuite, see what's going on with the typeinfo etc. bits.
- try to do a better job of ABI testing, with instantiations of all
standard-specified types checked, not just exported symbols.
g++/binutils
- compression for wide versions of basic types, not just narrow
threads
- create MT abstraction layer for atomicity to pthreads.
- solution for threads + C++.
other/random
- relocations, work on getting these down
- issues with __builtin_memcpy and std::copy from Jerry Quinn
http://gcc.gnu.org/ml/libstdc++/2003-02/msg00056.html
http://gcc.gnu.org/ml/libstdc++/2003-02/msg00302.html
http://gcc.gnu.org/ml/gcc/2003-10/msg01305.html
- fix dependency tracking for includes (.h, .tcc) during build process.
- coordinate with "C" library people the "C" compatibility headers.
- Think about naming all member data and member functions consistently
as per
funtions: _M_verb_adverb
data: _M_noun_adjective
- A C++STYLE guide that deals with nested namespaces, and that
everybody can live with.
- exception specifications need to be reviewed for all parts of the
library support and utility areas, particularly <new>. Part of this is
a standards issue, where the 27_io standard is really in an odd
spot. Do the work to make this consistent.
- C-related issues WRT to io and filepos, mbstate_t. Seeking in wide
streams. May need to define operators for mbstate_t so that
'mbstate_t& == mbstate_t' is something that can be done.
- scoping/linking issues WRT to C structs need to be worked out. See
Nathan's commentary on cantrip, http://www.cantrip.org/cheaders.html
- auto_ptr: seems to be some disagreement on what is
standards-conformant behavior, specially on conversion operators.
- list::assignment operator needs const_cast
- a cleaner division between pointers-to-value_type and true iterators
needs to be drawn throughout the entire STL implementation.
- priority_queue conversions may be non-conformant
- Protect valarray::result_type (not Standard) and make it work with
the various helper classes.
- Make sure `valarray<bool> & == _Expr<_BinClos<logical_or,_ValArray,_ValArray,double,double>,bool>'
is defined
- All of the Library working group closed issues need to be
addressed. Some of them proposed resolutions are already in the v-3
sources, with macro-guards. Also, same with the TR.
- need to think about doing a .texi or DocBook manual, instead of all
these HTML pages. In addition, it would be nice to have a full manual,
instead of a lot of ad-hoc pages. Weaknesses include numerics, locale,
and io.
- add FAQ entries -- improve the install instructions
- add HOWTO entries
- do more doxygen manpages
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
<meta name="KEYWORDS" content="C++, libstdc++, API, evolution, deprecate" />
<meta name="DESCRIPTION" content="API evolution and deprecation history" />
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>API Evolution and Deprecation History</title>
<link rel="StyleSheet" href="lib3styles.css" type="text/css" />
<link rel="Start" href="documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Copyright" href="17_intro/license.html" type="text/html" />
</head>
<body>
<h1 class="centered"><a name="top">API Evolution and Deprecation History</a></h1>
<p class="fineprint"><em>
The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html">
http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html</a>.
</em></p>
<p><em>
To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
</em></p>
<!-- ####################################################### -->
<hr />
<h3 class="left">
<a name="intro">API Evolution, Deprecation, and History of User Visible Changes</a>
</h3>
<p> A list of user-visible changes, by release version.
</p>
<h3 class="left">
<a name="3.0">3.0</a>
</h3>
<p>
Extensions moved to <code>include/ext</code>.
</p>
<p>
Include files from the SGI/HP sources that pre-date the ISO standard
are added. These files are placed into
the <code>include/backward</code> directory and a deprecated warning
is added that notifies on inclusion (<code>-Wno-deprecated</code>
deactivates the warning.)
</p>
<p>Deprecated include &lt;backward/strstream&gt; added.</p>
<p>Removal of include &lt;builtinbuf.h&gt;, &lt;indstream.h&gt;, &lt;parsestream.h&gt;, &lt;PlotFile.h&gt;, &lt;SFile.h&gt;, &lt;stdiostream.h&gt;, and &lt;stream.h&gt;.</p>
<h3 class="left">
<a name="3.1">3.1</a>
</h3>
<p>
Extensions from SGI/HP moved from <code>namespace std</code>
to <code>namespace __gnu_cxx</code>. As part of this, the following
new includes are
added: &lt;ext/algorithm&gt;, &lt;ext/functional&gt;, &lt;ext/iterator&gt;, &lt;ext/memory&gt;, and &lt;ext/numeric&gt;.
</p>
<p>
Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>.
</p>
<p>
Extensions to tree data structures added in &lt;ext/rb_tree&gt;.
</p>
<p>
Removal of &lt;ext/tree&gt;, moved to &lt;backward/tree.h&gt;.
</p>
<h3 class="left">
<a name="3.2">3.2</a>
</h3>
<p>Symbol versioning introduced for shared library.</p>
<p>Removal of include &lt;backward/strstream.h&gt;.</p>
<h3 class="left">
<a name="3.3">3.3</a>
</h3>
<p>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </p>
<p>Error handling in iostreams cleaned up, made consistent. </p>
<h3 class="left">
<a name="3.4">3.4</a>
</h3>
<p>
Large file support.
</p>
<p> Extensions for generic characters and <code>char_traits</code> added in &lt;ext/pod_char_traits.h&gt;.
</p>
<p>
Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality.
</p>
<p>
Support for <code>char_traits</code> beyond builtin types.
</p>
<p>
Conformant <code>allocator</code> class and usage in containers. As
part of this, the following extensions are
added: &lt;ext/bitmap_allocator.h&gt;, &lt;ext/debug_allocator.h&gt;, &lt;ext/mt_allocator.h&gt;, &lt;ext/malloc_allocator.h&gt;,&lt;ext/new_allocator.h&gt;, &lt;ext/pool_allocator.h&gt;.
</p>
<p>
Debug mode first appears.
</p>
<p>
PCH support.
</p>
<p>
Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_.
</p>
<p>
Extension &lt;ext/stdio_sync_filebuf.h&gt; added.
</p>
<p>
Extension &lt;ext/demangle.h&gt; added.
</p>
<h3 class="left">
<a name="4.0">4.0</a>
</h3>
<p>
TR1 features first appear.
</p>
<p>
Extension allocator &lt;ext/array_allocator.h&gt; added.
</p>
<p>
Extension <code>codecvt</code> specializations moved to &lt;ext/codecvt_specializations.h&gt;.
</p>
<p>
Removal of &lt;ext/demangle.h&gt;.
</p>
<h3 class="left">
<a name="4.1">4.1</a>
</h3>
<p>
Removal of &lt;cassert&gt; from all standard headers: now has to be explicitly included for <code>std::assert</code> calls.
</p>
<p> Extensions for policy-based data structures first added. New includes,
types, namespace <code>pb_assoc</code>.
</p>
<p> Extensions for typelists added in &lt;ext/typelist.h&gt;.
</p>
<p> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in &lt;ext/vstring.h&gt;.
</p>
<h3 class="left">
<a name="4.2">4.2</a>
</h3>
<p> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>.
</p>
<p>TR1 &lt;random&gt;, &lt;complex&gt;, and C compatibility headers added.</p>
<p> Extensions for concurrent programming consolidated
into &lt;ext/concurrence.h&gt; and &lt;ext/atomicity.h&gt;,
including change of namespace to <code>__gnu_cxx</code> in some
cases. Added types
include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</p>
<p> Extensions for type traits consolidated
into &lt;ext/type_traits.h&gt;. Additional traits are added
(<code>__conditional_type</code>, <code>__enable_if</code>, others.)
</p>
<p> Extensions for policy-based data structures revised. New includes,
types, namespace moved to <code>__pb_ds</code>.
</p>
<p> Extensions for debug mode modified: now nested in <code>namespace
std::__debug</code> and extensions in <code>namespace
__gnu_cxx::__debug</code>.</p>
<p> Extensions added: &lt;ext/typelist.h&gt;
and &lt;ext/throw_allocator.h&gt;.
</p>
<h3 class="left">
<a name="4.3">4.3</a>
</h3>
<p>
C++0X features first appear.
</p>
<p>TR1 &lt;regex&gt; and &lt;cmath&gt;'s mathematical special function added.</p>
<p>
Backward include edit.
</p>
<ul>
<li> Removed: &lt;algobase.h&gt; &lt;algo.h&gt; &lt;alloc.h&gt; &lt;bvector.h&gt; &lt;complex.h&gt;
defalloc.h&gt; &lt;deque.h&gt; &lt;fstream.h&gt; &lt;function.h&gt; &lt;hash_map.h&gt; &lt;hash_set.h&gt;
hashtable.h&gt; &lt;heap.h&gt; &lt;iomanip.h&gt; &lt;iostream.h&gt; &lt;istream.h&gt; &lt;iterator.h&gt;
list.h&gt; &lt;map.h&gt; &lt;multimap.h&gt; &lt;multiset.h&gt; &lt;new.h&gt; &lt;ostream.h&gt; &lt;pair.h&gt; &lt;queue.h&gt; &lt;rope.h&gt; &lt;set.h&gt; &lt;slist.h&gt; &lt;stack.h&gt; &lt;streambuf.h&gt; &lt;stream.h&gt; &lt;tempbuf.h&gt;
&lt;tree.h&gt; &lt;vector.h&gt;
</li>
<li> Added: &lt;hash_map&gt; and &lt;hash_set&gt;</li>
<li> Added in C++0x: &lt;auto_ptr.h&gt; and &lt;binders.h&gt;</li>
</ul>
<p>
Header dependency streamlining.
</p>
<ul>
<li>&lt;algorithm&gt; no longer includes &lt;climits&gt;, &lt;cstring&gt;, or &lt;iosfwd&gt; </li>
<li>&lt;bitset&gt; no longer includes &lt;istream&gt; or &lt;ostream&gt;, adds &lt;iosfwd&gt; </li>
<li>&lt;functional&gt; no longer includes &lt;cstddef&gt;</li>
<li>&lt;iomanip&gt; no longer includes &lt;istream&gt;, &lt;istream&gt;, or &lt;functional&gt;, adds &lt;ioswd&gt; </li>
<li>&lt;numeric&gt; no longer includes &lt;iterator&gt;</li>
<li>&lt;string&gt; no longer includes &lt;algorithm&gt; or &lt;memory&gt;</li>
<li>&lt;valarray&gt; no longer includes &lt;numeric&gt; or &lt;cstdlib&gt;</li>
<li>&lt;tr1/hashtable&gt; no longer includes &lt;memory&gt; or &lt;functional&gt;</li>
<li>&lt;tr1/memory&gt; no longer includes &lt;algorithm&gt;</li>
<li>&lt;tr1/random&gt; no longer includes &lt;algorithm&gt; or &lt;fstream&gt;</li>
</ul>
<p>
Debug mode for &lt;unordered_map&gt; and &lt;unordered_set&gt;.
</p>
<p>
Parallel mode first appears.
</p>
<p>Variadic template implementations of items in &lt;tuple&gt; and
&lt;functional&gt;.
</p>
<p>Default <code>what</code> implementations give more elaborate
exception strings for <code>bad_cast</code>,
<code>bad_typeid</code>, <code>bad_exception</code>, and
<code>bad_alloc</code>.
</p>
<p>
PCH binary files no longer installed. Instead, the source files are installed.
</p>
<p>
Namespace pb_ds moved to __gnu_pb_ds.
</p>
</body>
</html>
This source diff could not be displayed because it is too large. You can view the blob instead.
# Blatantly ripped out of the graphviz examples and modified. -pme
digraph v3conf {
size="6,6";
node [color=lightblue2, style=filled];
"aclocal.m4" -> "acinclude.m4";
"configure" -> "aclocal.m4";
"configure" -> "configure.ac";
"configure" -> "crossconfig.m4";
"configure" -> "linkage.m4";
"[*/]Makefile.in" -> "Makefile.am";
"[*/]Makefile.in" -> "configure.ac";
"config.h.in" -> "acconfig.h";
"config.h.in" -> "configure.ac";
}
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>How to contribute</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<!--990301 slightly modified version of the GCC contribute.html file-->
<!-- #include virtual="/include/header-subpages.html"-->
<body>
<h2>How to contribute</h2>
<p> The Standard C++ Library v3, follows an open development
model. Active contributors are assigned maintainer-ship
responsibility, and given write access to the SVN repository. First
time contributors should follow this procedure:
</p>
<hr />
<h4>ONE : read the documentation</h4>
<ul>
<li> Get and read the relevant sections of the C++ language
specification. Copies of the full ISO 14882 standard are available on
line via the ISO mirror site for committee members. Non-members, or
those who have not paid for the privilege of sitting on the committee
and sustained their two meeting commitment for voting rights, may get
a copy of the standard from their respective national standards
organization. In the USA, this national standards organization is ANSI
and their web-site is right
<a href="http://www.ansi.org">here.</a>
(And if you've already registered with them, clicking this link will take you to directly to the place where you can
<a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</a>
</li>
<li> The library working group bugs, and known defects, can be obtained here:
<a href="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </a>
</li>
<li> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <a href="http://www.jamesd.demon.co.uk/csc/faq.html"> here </a>.
</li>
<li> Peruse the <a href="http://www.gnu.org/prep/standards_toc.html">GNU Coding Standards</a>, and chuckle when you hit the part about "Using Languages Other Than C."
</li>
<li> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <a href="C++STYLE"> here. </a>
</li>
<li> And last but certainly not least, read the library-specific information found <a href="../documentation.html"> here.</a>
</li>
</ul>
<hr />
<h4>TWO : copyright assignment</h4>
<p>
Small changes can be accepted without a copyright assignment form on
file. New code and additions to the library need completed copyright
assignment form on file at the FSF. Note: your employer may be required
to fill out appropriate disclaimer forms as well.
</p>
<p> Historically, the libstdc++ assignment form added the following question:
</p>
<code>[Which Belgian comic book character is better, Tintin or
Asterix, and why?]</code>
<p>
While not strictly necessary, humoring the maintainers and answering
this question would be appreciated.
</p>
<p>
For more information about getting a copyright assignment, please see
<a href="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal
Matters</a>.
</p>
<p>
Please contact <a href="mailto:bkoz+assign@redhat.com">Benjamin
Kosnik</a> if you are confused about the assignment or have general
licensing questions. When requesting an assignment form from <a
href="mailto:assign@gnu.org">assign@gnu.org</a>, please cc
the above libstdc++ maintainer so that progress can be monitored.
</p>
<hr />
<h4>THREE : submitting patches</h4>
<p>
Every patch must have several pieces of information before it can be
properly evaluated. Ideally (and to ensure the fastest possible
response from the maintainers) it would have all of these pieces:
</p>
<ul>
<li> A description of the bug and how your patch fixes this bug. For
new features a description of the feature and your implementation. </li>
<li> A ChangeLog entry as plain text; see the various ChangeLog files
for format and content. If using you are using emacs as your editor,
simply position the insertion point at the beginning of your change
and hit CX-4a to bring up the appropriate ChangeLog
entry. See--magic! Similar functionality also exists for vi. </li>
<li> A testsuite submission or sample program that will easily and
simply show the existing error or test new functionality. </li>
<li> The patch itself. If you are accessing the SVN repository
use "svn update; svn diff NEW"; else, use "diff -cp OLD NEW"
... If your version of diff does not support these options, then
get the latest version of GNU diff. The <a
href="http://gcc.gnu.org/wiki/SvnTricks">SVN Tricks</a> wiki page
has information on customising the output of <code>svn diff</code>.</li>
<li> When you have all these pieces, bundle them up in a mail message
and send it to libstdc++@gcc.gnu.org. All patches and related
discussion should be sent to the libstdc++ mailing list. </li>
</ul>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, license, licence" />
<meta name="DESCRIPTION" content="Copying restrictions for libstdc++." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ copying</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" rev="Copyright" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
</head>
<body>
<h1 class="centered"><a name="top">Licenses for the Library</a></h1>
<p>There are two licenses affecting GNU libstdc++: one for the code, and
one for the documentation. Here we will describe both of them, and try
to answer some of the widespread questions. If you have more questions,
ask the FSF or the
<a href="http://gcc.gnu.org/lists.html">gcc mailing list</a>; the person
writing this page is a programmer, not a lawyer.
</p>
<hr />
<h2>The Code: Runtime GPL</h2>
<p>The source code of libstdc++ is distributed under version 2 of the
<a href="COPYING" type="text/plain">GNU General Public License</a>, with the so-called
&quot;runtime exception,&quot; as follows (or see any header or
implementation file):
</p>
<pre>
As a special exception, you may use this file as part of a free software
library without restriction. Specifically, if other files instantiate
templates or use macros or inline functions from this file, or you compile
this file and link it with other files to produce an executable, this
file does not by itself cause the resulting executable to be covered by
the GNU General Public License. This exception does not however
invalidate any other reasons why the executable file might be covered by
the GNU General Public License.
</pre>
<p>Hopefully that text is self-explanatory. If it isn't, you need to speak
to your lawyer, or the Free Software Foundation.
</p>
<!-- Most of the Q&A's are based on, paraphrased from, and outright stolen
from this thread:
http://gcc.gnu.org/ml/libstdc++/2000-q2/subjects.html#00050
-->
<p><strong>Q: So any program which uses libstdc++ falls under the GPL?</strong>
<br />A: <strong>No.</strong> The special exception permits use of the
library in proprietary applications.
</p>
<p><strong>Q: How is that different from the GNU {Lesser,Library}
GPL?</strong>
<!-- Quoting Jason Merrill from the thread above: -->
<br />A: The LGPL requires that users be able to replace the LGPL code with a
modified version; this is trivial if the library in question is a C
shared library. But there's no way to make that work with C++, where
much of the library consists of inline functions and templates, which
are expanded inside the code that uses the library. So to allow people
to replace the library code, someone using the library would have to
distribute their own source, rendering the LGPL equivalent to the GPL.
</p>
<p><strong>Q: I see. So, what restrictions <em>are</em> there on
programs that use the library?</strong>
<br />A: None. We encourage such programs to be released as open source,
but we won't punish you or sue you if you choose otherwise.
</p>
<hr />
<h2>The Docs: GPL, FDL</h2>
<p>The documentation shipped with the library and made available over the
web, excluding the pages generated from source comments, are copyrighted
by the Free Software Foundation, and placed under
the <a href="COPYING.DOC" type="text/plain">GNU Free Documentation License version 1.1</a>.
There are no Front-Cover Texts, no Back-Cover Texts, and
<!-- as far as I know -->
no Invariant Sections.
</p>
<p> For documentation generated by doxygen or other automated tools
via processing source code comments and markup, the original source
code license applies to the generated files. Thus, the doxygen
documents are licensed GPL.
</p>
<p>If you plan on making copies of the documentation, please let us know.
We can probably offer suggestions.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
Comments and suggestions about this page are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
Comments or questions about the licenses themselves are also welcome, and
should be directed to the GCC list as descibed above.
</em></p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 19: Diagnostics</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../18_support/howto.html" type="text/html"
title="Library Support" />
<link rel="Next" href="../20_util/howto.html" type="text/html"
title="General Utilities" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 19: Diagnostics</a></h1>
<p>Chapter 19 deals with program diagnostics, such as exceptions
and assertions. You know, all the things we wish weren't even
necessary at all.
</p>
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Adding data to exceptions</a></li>
<li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="1">Adding data to exceptions</a></h2>
<p>The standard exception classes carry with them a single string as
data (usually describing what went wrong or where the 'throw' took
place). It's good to remember that you can add your own data to
these exceptions when extending the hierarchy:
</p>
<pre>
struct My_Exception : public std::runtime_error
{
public:
My_Exception (const string&amp; whatarg)
: std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
int errno_at_time_of_throw() const { return e; }
DBID id_of_thing_that_threw() const { return id; }
protected:
int e;
DBID id; // some user-defined type
};
</pre>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2>
<p>Better taste! Less fat! Literally!</p>
<p>In 1999, SGI added <em>concept checkers</em> to their implementation
of the STL: code which checked the template parameters of
instantiated pieces of the STL, in order to insure that the parameters
being used met the requirements of the standard. For example,
the Standard requires that types passed as template parameters to
<code>vector</code> be &quot;Assignable&quot; (which means what you think
it means). The checking was done during compilation, and none of
the code was executed at runtime.
</p>
<p>Unfortunately, the size of the compiler files grew significantly
as a result. The checking code itself was cumbersome. And bugs
were found in it on more than one occasion.
</p>
<p>The primary author of the checking code, Jeremy Siek, had already
started work on a replacement implementation. The new code has been
formally reviewed and accepted into
<a href="http://www.boost.org/libs/concept_check/concept_check.htm">the
Boost libraries</a>, and we are pleased to incorporate it into the
GNU C++ library.
</p>
<p>The new version imposes a much smaller space overhead on the generated
object file. The checks are also cleaner and easier to read and
understand.
</p>
<p>They are off by default for all versions of GCC from 3.0 to 3.4 (the
latest release at the time of writing).
They can be enabled at configure time with
<a href="../configopts.html"><code>--enable-concept-checks</code></a>.
You can enable them on a per-translation-unit basis with
<code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
(or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
3.1, 3.2 and 3.3).
</p>
<p>Please note that the upcoming C++ standard has first-class
support for template parameter constraints based on concepts in the core
language. This will obviate the need for the library-simulated concept
checking described above.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 20: General Utilities</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../19_diagnostics/howto.html" type="text/html"
title="Diagnostics" />
<link rel="Next" href="../21_strings/howto.html" type="text/html"
title="Strings" />
<link rel="Bookmark" href="allocator.html" type="text/html"
title="Allocators and allocation" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 20: General Utilities</a></h1>
<p>Chapter 20 deals with utility classes and functions, such as
the oft-debated <code>auto_ptr&lt;&gt;</code>.
</p>
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li>
<li><a href="#2"><code>auto_ptr</code> inside container classes</a></li>
<li><a href="#3">Functors</a></li>
<li><a href="#4">Pairs</a></li>
<li><a href="#5">Memory allocators</a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="1"><code>auto_ptr</code> is not omnipotent</a></h2>
<p>I'm not going to try and explain all of the fun and delicious
things that can happen with misuse of the auto_ptr class template
(called AP here), nor am I going to try and teach you how to use
AP safely in the presence of copying. The AP class is a really
nifty idea for a smart pointer, but it is one of the dumbest of
all the smart pointers -- and that's fine.
</p>
<p>AP is not meant to be a supersmart solution to all resource
leaks everywhere. Neither is it meant to be an effective form
of garbage collection (although it can help, a little bit).
And it can <em>not</em> be used for arrays!
</p>
<p>AP <em>is</em> meant to prevent nasty leaks in the presence of
exceptions. That's <em>all</em>. This code is AP-friendly:
</p>
<pre>
// not a recommend naming scheme, but good for web-based FAQs
typedef std::auto_ptr&lt;MyClass&gt; APMC;
extern function_taking_MyClass_pointer (MyClass*);
extern some_throwable_function ();
void func (int data)
{
APMC ap (new MyClass(data));
some_throwable_function(); // this will throw an exception
function_taking_MyClass_pointer (ap.get());
}
</pre>
<p>When an exception gets thrown, the instance of MyClass that's
been created on the heap will be <code>delete</code>'d as the stack is
unwound past <code>func()</code>.
</p>
<p>Changing that code as follows is <em>not</em> AP-friendly:
</p>
<pre>
APMC ap (new MyClass[22]);
</pre>
<p>You will get the same problems as you would without the use
of AP:
</p>
<pre>
char* array = new char[10]; // array new...
...
delete array; // ...but single-object delete
</pre>
<p>AP cannot tell whether the pointer you've passed at creation points
to one or many things. If it points to many things, you are about
to die. AP is trivial to write, however, so you could write your
own <code>auto_array_ptr</code> for that situation (in fact, this has
been done many times; check the mailing lists, Usenet, Boost, etc).
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2>
<p>All of the <a href="../23_containers/howto.html">containers</a>
described in the standard library require their contained types
to have, among other things, a copy constructor like this:
</p>
<pre>
struct My_Type
{
My_Type (My_Type const&amp;);
};
</pre>
<p>Note the const keyword; the object being copied shouldn't change.
The template class <code>auto_ptr</code> (called AP here) does not
meet this requirement. Creating a new AP by copying an existing
one transfers ownership of the pointed-to object, which means that
the AP being copied must change, which in turn means that the
copy ctors of AP do not take const objects.
</p>
<p>The resulting rule is simple: <em>Never ever use a container of
auto_ptr objects.</em> The standard says that &quot;undefined&quot;
behavior is the result, but it is guaranteed to be messy.
</p>
<p>To prevent you from doing this to yourself, the
<a href="../19_diagnostics/howto.html#3">concept checks</a> built
in to this implementation will issue an error if you try to
compile code like this:
</p>
<pre>
#include &lt;vector&gt;
#include &lt;memory&gt;
void f()
{
std::vector&lt; std::auto_ptr&lt;int&gt; &gt; vec_ap_int;
}
</pre>
<p>Should you try this with the checks enabled, you will see an error.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="3">Functors</a></h2>
<p>If you don't know what functors are, you're not alone. Many people
get slightly the wrong idea. In the interest of not reinventing
the wheel, we will refer you to the introduction to the functor
concept written by SGI as part of their STL, in
<a href="http://www.sgi.com/tech/stl/functors.html">their
http://www.sgi.com/tech/stl/functors.html</a>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="4">Pairs</a></h2>
<p>The <code>pair&lt;T1,T2&gt;</code> is a simple and handy way to
carry around a pair of objects. One is of type T1, and another of
type T2; they may be the same type, but you don't get anything
extra if they are. The two members can be accessed directly, as
<code>.first</code> and <code>.second</code>.
</p>
<p>Construction is simple. The default ctor initializes each member
with its respective default ctor. The other simple ctor,
</p>
<pre>
pair (const T1&amp; x, const T2&amp; y);
</pre>
<p>does what you think it does, <code>first</code> getting <code>x</code>
and <code>second</code> getting <code>y</code>.
</p>
<p>There is a copy constructor, but it requires that your compiler
handle member function templates:
</p>
<pre>
template &lt;class U, class V&gt; pair (const pair&lt;U,V&gt;&amp; p);
</pre>
<p>The compiler will convert as necessary from U to T1 and from
V to T2 in order to perform the respective initializations.
</p>
<p>The comparison operators are done for you. Equality
of two <code>pair&lt;T1,T2&gt;</code>s is defined as both <code>first</code>
members comparing equal and both <code>second</code> members comparing
equal; this simply delegates responsibility to the respective
<code>operator==</code> functions (for types like MyClass) or builtin
comparisons (for types like int, char, etc).
</p>
<p><a name="pairlt">
The less-than operator is a bit odd the first time you see it. It
is defined as evaluating to:
</a>
</p>
<pre>
x.first &lt; y.first ||
( !(y.first &lt; x.first) &amp;&amp; x.second &lt; y.second )
</pre>
<p>The other operators are not defined using the <code>rel_ops</code>
functions above, but their semantics are the same.
</p>
<p>Finally, there is a template function called <code>make_pair</code>
that takes two references-to-const objects and returns an
instance of a pair instantiated on their respective types:
</p>
<pre>
pair&lt;int,MyClass&gt; p = make_pair(4,myobject);
</pre>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
From: herbs@cntc.com (Herb Sutter)
Subject: Guru of the Week #29: Solution
Date: 22 Jan 1998 00:00:00 GMT
Message-ID: <6a8q26$9qa@netlab.cs.rpi.edu>
Newsgroups: comp.lang.c++.moderated
.--------------------------------------------------------------------.
| Guru of the Week problems and solutions are posted regularly on |
| news:comp.lang.c++.moderated. For past problems and solutions |
| see the GotW archive at http://www.cntc.com. |
| Is there a topic you'd like to see covered? mailto:herbs@cntc.com |
`--------------------------------------------------------------------'
_______________________________________________________
GotW #29: Strings
Difficulty: 7 / 10
_______________________________________________________
>Write a ci_string class which is identical to the
>standard 'string' class, but is case-insensitive in the
>same way as the C function stricmp():
The "how can I make a case-insensitive string?"
question is so common that it probably deserves its own
FAQ -- hence this issue of GotW.
Note 1: The stricmp() case-insensitive string
comparison function is not part of the C standard, but
it is a common extension on many C compilers.
Note 2: What "case insensitive" actually means depends
entirely on your application and language. For
example, many languages do not have "cases" at all, and
for languages that do you have to decide whether you
want accented characters to compare equal to unaccented
characters, and so on. This GotW provides guidance on
how to implement case-insensitivity for standard
strings in whatever sense applies to your particular
situation.
Here's what we want to achieve:
> ci_string s( "AbCdE" );
>
> // case insensitive
> assert( s == "abcde" );
> assert( s == "ABCDE" );
>
> // still case-preserving, of course
> assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
> assert( strcmp( s.c_str(), "abcde" ) != 0 );
The key here is to understand what a "string" actually
is in standard C++. If you look in your trusty string
header, you'll see something like this:
typedef basic_string<char> string;
So string isn't really a class... it's a typedef of a
template. In turn, the basic_string<> template is
declared as follows, in all its glory:
template<class charT,
class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string;
So "string" really means "basic_string<char,
char_traits<char>, allocator<char> >". We don't need
to worry about the allocator part, but the key here is
the char_traits part because char_traits defines how
characters interact and compare(!).
basic_string supplies useful comparison functions that
let you compare whether a string is equal to another,
less than another, and so on. These string comparisons
functions are built on top of character comparison
functions supplied in the char_traits template. In
particular, the char_traits template supplies character
comparison functions named eq(), ne(), and lt() for
equality, inequality, and less-than comparisons, and
compare() and find() functions to compare and search
sequences of characters.
If we want these to behave differently, all we have to
do is provide a different char_traits template! Here's
the easiest way:
struct ci_char_traits : public char_traits<char>
// just inherit all the other functions
// that we don't need to override
{
static bool eq( char c1, char c2 ) {
return tolower(c1) == tolower(c2);
}
static bool ne( char c1, char c2 ) {
return tolower(c1) != tolower(c2);
}
static bool lt( char c1, char c2 ) {
return tolower(c1) < tolower(c2);
}
static int compare( const char* s1,
const char* s2,
size_t n ) {
return strnicmp( s1, s2, n );
// if available on your compiler,
// otherwise you can roll your own
}
static const char*
find( const char* s, int n, char a ) {
while( n-- > 0 && tolower(*s) != tolower(a) ) {
++s;
}
return n >= 0 ? s : 0;
}
};
[N.B. A bug in the original code has been fixed for the
GCC documentation, the corrected code was taken from
Herb Sutter's book, Exceptional C++]
And finally, the key that brings it all together:
typedef basic_string<char, ci_char_traits> ci_string;
All we've done is created a typedef named "ci_string"
which operates exactly like the standard "string",
except that it uses ci_char_traits instead of
char_traits<char> to get its character comparison
rules. Since we've handily made the ci_char_traits
rules case-insensitive, we've made ci_string itself
case-insensitive without any further surgery -- that
is, we have a case-insensitive string without having
touched basic_string at all!
This GotW should give you a flavour for how the
basic_string template works and how flexible it is in
practice. If you want different comparisons than the
ones stricmp() and tolower() give you, just replace the
five functions shown above with your own code that
performs character comparisons the way that's
appropriate in your particular application.
Exercise for the reader:
Is it safe to inherit ci_char_traits from
char_traits<char> this way? Why or why not?
/*
* stringtok.h -- Breaks a string into tokens. This is an example for lib3.
*
* Template function looks like this:
*
* template <typename Container>
* void stringtok (Container &l,
* string const &s,
* char const * const ws = " \t\n");
*
* A nondestructive version of strtok() that handles its own memory and can
* be broken up by any character(s). Does all the work at once rather than
* in an invocation loop like strtok() requires.
*
* Container is any type that supports push_back(a_string), although using
* list<string> and deque<string> are indicated due to their O(1) push_back.
* (I prefer deque<> because op[]/at() is available as well.) The first
* parameter references an existing Container.
*
* s is the string to be tokenized. From the parameter declaration, it can
* be seen that s is not affected. Since references-to-const may refer to
* temporaries, you could use stringtok(some_container, readline("")) when
* using the GNU readline library.
*
* The final parameter is an array of characters that serve as whitespace.
* Whitespace characters default to one or more of tab, space, and newline,
* in any combination.
*
* 'l' need not be empty on entry. On return, 'l' will have the token
* strings appended.
*
*
* [Example:
* list<string> ls;
* stringtok (ls, " this \t is\t\n a test ");
* for (list<string>::const_iterator i = ls.begin();
* i != ls.end(); ++i)
* {
* cerr << ':' << (*i) << ":\n";
* }
*
* would print
* :this:
* :is:
* :a:
* :test:
* -end example]
*
* pedwards@jaj.com May 1999
*/
#include <string>
#include <cstring> // for strchr
/*****************************************************************
* This is the only part of the implementation that I don't like.
* It can probably be improved upon by the reader...
*/
namespace {
inline bool
isws (char c, char const * const wstr)
{
return (strchr(wstr,c) != NULL);
}
}
/*****************************************************************
* Simplistic and quite Standard, but a bit slow. This should be
* templatized on basic_string instead, or on a more generic StringT
* that just happens to support ::size_type, .substr(), and so on.
* I had hoped that "whitespace" would be a trait, but it isn't, so
* the user must supply it. Enh, this lets them break up strings on
* different things easier than traits would anyhow.
*/
template <typename Container>
void
stringtok (Container &l, string const &s, char const * const ws = " \t\n")
{
const string::size_type S = s.size();
string::size_type i = 0;
while (i < S) {
// eat leading whitespace
while ((i < S) && (isws(s[i],ws))) ++i;
if (i == S) return; // nothing left but WS
// find end of word
string::size_type j = i+1;
while ((j < S) && (!isws(s[j],ws))) ++j;
// add word
l.push_back(s.substr(i,j-i));
// set up for next loop
i = j+1;
}
}
/*
* Same as stringtok_h.txt, but doesn't (visiably) use C functions.
*/
#include <string>
// The std:: prefix is not used here, for readability, and a line like
// "using namespace std;" is dangerous to have in a header file.
template <typename Container>
void
stringtok (Container &container, string const &in,
const char * const delimiters = " \t\n")
{
const string::size_type len = in.length();
string::size_type i = 0;
while ( i < len )
{
// eat leading whitespace
i = in.find_first_not_of (delimiters, i);
if (i == string::npos)
return; // nothing left but white space
// find the end of the token
string::size_type j = in.find_first_of (delimiters, i);
// push token
if (j == string::npos) {
container.push_back (in.substr(i));
return;
} else
container.push_back (in.substr(i, j-i));
// set up for next loop
i = j + 1;
}
}
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="Notes on the ctype implementation." />
<title>Notes on the ctype implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Bookmark" href="howto.html" type="text/html" title="Localization" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1>
Notes on the ctype implementation.
</h1>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000
</em>
<h2>
1. Abstract
</h2>
<p>
Woe is me.
</p>
<h2>
2. What the standard says
</h2>
<h2>
3. Problems with &quot;C&quot; ctype : global locales, termination.
</h2>
<p>
For the required specialization codecvt&lt;wchar_t, char, mbstate_t&gt; ,
conversions are made between the internal character set (always UCS4
on GNU/Linux) and whatever the currently selected locale for the
LC_CTYPE category implements.
</p>
<h2>
4. Design
</h2>
The two required specializations are implemented as follows:
<p>
<code>
ctype&lt;char&gt;
</code>
</p>
<p>
This is simple specialization. Implementing this was a piece of cake.
</p>
<p>
<code>
ctype&lt;wchar_t&gt;
</code>
</p>
<p>
This specialization, by specifying all the template parameters, pretty
much ties the hands of implementors. As such, the implementation is
straightforward, involving mcsrtombs for the conversions between char
to wchar_t and wcsrtombs for conversions between wchar_t and char.
</p>
<p>
Neither of these two required specializations deals with Unicode
characters. As such, libstdc++ implements
</p>
<h2>
5. Examples
</h2>
<pre>
typedef ctype&lt;char&gt; cctype;
</pre>
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/ctype_char_members.cc </li>
<li> testsuite/22_locale/ctype_wchar_t_members.cc </li>
</ul>
<h2>
6. Unresolved Issues
</h2>
<ul>
<li> how to deal with the global locale issue? </li>
<li> how to deal with different types than char, wchar_t? </li>
<li> codecvt/ctype overlap: narrow/widen </li>
<li> mask typedef in codecvt_base, argument types in codecvt.
what is know about this type? </li>
<li> why mask* argument in codecvt? </li>
<li> can this be made (more) generic? is there a simple way to
straighten out the configure-time mess that is a by-product of
this class? </li>
<li> get the ctype&lt;wchar_t&gt;::mask stuff under control. Need to
make some kind of static table, and not do lookup evertime
somebody hits the do_is... functions. Too bad we can't just
redefine mask for ctype&lt;wchar_t&gt; </li>
<li> rename abstract base class. See if just smash-overriding
is a better approach. Clarify, add sanity to naming. </li>
</ul>
<h2>
7. Acknowledgments
</h2>
Ulrich Drepper for patient answering of late-night questions, skeletal
examples, and C language expertise.
<h2>
8. Bibliography / Referenced Documents
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html
</p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 22: Localization</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../21_strings/howto.html" type="text/html"
title="Strings" />
<link rel="Next" href="../23_containers/howto.html" type="text/html"
title="Containers" />
<link rel="Bookmark" href="locale.html" type="text/html" title="class locale" />
<link rel="Bookmark" href="codecvt.html" type="text/html" title="class codecvt" />
<link rel="Bookmark" href="ctype.html" type="text/html" title="class ctype" />
<link rel="Bookmark" href="messages.html" type="text/html" title="class messages" />
<link rel="Bookmark" href="http://www.research.att.com/~bs/3rd_loc0.html" type="text/html" title="Bjarne Stroustrup on Locales" />
<link rel="Bookmark" href="http://www.cantrip.org/locale.html" type="text/html" title="Nathan Myers on Locales" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 22: Localization</a></h1>
<p>Chapter 22 deals with the C++ localization facilities.
</p>
<!-- I wanted to write that sentence in something requiring an exotic font,
like Cyrllic or Kanji. Probably more work than such cuteness is worth,
but I still think it'd be funny.
-->
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">class locale</a></li>
<li><a href="#2">class codecvt</a></li>
<li><a href="#3">class ctype</a></li>
<li><a href="#4">class messages</a></li>
<li><a href="#5">Bjarne Stroustrup on Locales</a></li>
<li><a href="#6">Nathan Myers on Locales</a></li>
<li><a href="#7">Correct Transformations</a></li>
</ul>
<!-- ####################################################### -->
<hr />
<h2><a name="1">class locale</a></h2>
<p>Notes made during the implementation of locales can be found
<a href="locale.html">here</a>.
</p>
<hr />
<h2><a name="2">class codecvt</a></h2>
<p>Notes made during the implementation of codecvt can be found
<a href="codecvt.html">here</a>.
</p>
<p>The following is the abstract from the implementation notes:
</p>
<blockquote>
The standard class codecvt attempts to address conversions between
different character encoding schemes. In particular, the standard
attempts to detail conversions between the implementation-defined
wide characters (hereafter referred to as wchar_t) and the standard
type char that is so beloved in classic &quot;C&quot; (which can
now be referred to as narrow characters.) This document attempts
to describe how the GNU libstdc++ implementation deals with the
conversion between wide and narrow characters, and also presents a
framework for dealing with the huge number of other encodings that
iconv can convert, including Unicode and UTF8. Design issues and
requirements are addressed, and examples of correct usage for both
the required specializations for wide and narrow characters and the
implementation-provided extended functionality are given.
</blockquote>
<hr />
<h2><a name="3">class ctype</a></h2>
<p>Notes made during the implementation of ctype can be found
<a href="ctype.html">here</a>.
</p>
<hr />
<h2><a name="4">class messages</a></h2>
<p>Notes made during the implementation of messages can be found
<a href="messages.html">here</a>.
</p>
<hr />
<h2><a name="5">Bjarne Stroustrup on Locales</a></h2>
<p>Dr. Bjarne Stroustrup has released a
<a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a>
to Appendix D of his book,
<a href="http://www.research.att.com/~bs/3rd.html">The C++
Programming Language (3rd Edition)</a>. It is a detailed
description of locales and how to use them.
</p>
<p>He also writes:
</p>
<blockquote><em>
Please note that I still consider this detailed description of
locales beyond the needs of most C++ programmers. It is written
with experienced programmers in mind and novices will do best to
avoid it.
</em></blockquote>
<hr />
<h2><a name="6">Nathan Myers on Locales</a></h2>
<p>An article entitled &quot;The Standard C++ Locale&quot; was
published in Dr. Dobb's Journal and can be found
<a href="http://www.cantrip.org/locale.html">here</a>.
</p>
<hr />
<h2><a name="7">Correct Transformations</a></h2>
<!-- Jumping directly to here from chapter 21. -->
<p>A very common question on newsgroups and mailing lists is, &quot;How
do I do &lt;foo&gt; to a character string?&quot; where &lt;foo&gt; is
a task such as changing all the letters to uppercase, to lowercase,
testing for digits, etc. A skilled and conscientious programmer
will follow the question with another, &quot;And how do I make the
code portable?&quot;
</p>
<p>(Poor innocent programmer, you have no idea the depths of trouble
you are getting yourself into. 'Twould be best for your sanity if
you dropped the whole idea and took up basket weaving instead. No?
Fine, you asked for it...)
</p>
<p>The task of changing the case of a letter or classifying a character
as numeric, graphical, etc., all depends on the cultural context of the
program at runtime. So, first you must take the portability question
into account. Once you have localized the program to a particular
natural language, only then can you perform the specific task.
Unfortunately, specializing a function for a human language is not
as simple as declaring
<code> extern &quot;Danish&quot; int tolower (int); </code>.
</p>
<p>The C++ code to do all this proceeds in the same way. First, a locale
is created. Then member functions of that locale are called to
perform minor tasks. Continuing the example from Chapter 21, we wish
to use the following convenience functions:
</p>
<pre>
namespace std {
template &lt;class charT&gt;
charT
toupper (charT c, const locale&amp; loc) const;
template &lt;class charT&gt;
charT
tolower (charT c, const locale&amp; loc) const;
}</pre>
<p>
This function extracts the appropriate &quot;facet&quot; from the
locale <em>loc</em> and calls the appropriate member function of that
facet, passing <em>c</em> as its argument. The resulting character
is returned.
</p>
<p>For the C/POSIX locale, the results are the same as calling the
classic C <code>toupper/tolower</code> function that was used in previous
examples. For other locales, the code should Do The Right Thing.
</p>
<p>Of course, these functions take a second argument, and the
transformation algorithm's operator argument can only take a single
parameter. So we write simple wrapper structs to handle that.
</p>
<p>The next-to-final version of the code started in Chapter 21 looks like:
</p>
<pre>
#include &lt;iterator&gt; // for back_inserter
#include &lt;locale&gt;
#include &lt;string&gt;
#include &lt;algorithm&gt;
#include &lt;cctype&gt; // old &lt;ctype.h&gt;
struct ToUpper
{
ToUpper(std::locale const&amp; l) : loc(l) {;}
char operator() (char c) const { return std::toupper(c,loc); }
private:
std::locale const&amp; loc;
};
struct ToLower
{
ToLower(std::locale const&amp; l) : loc(l) {;}
char operator() (char c) const { return std::tolower(c,loc); }
private:
std::locale const&amp; loc;
};
int main ()
{
std::string s("Some Kind Of Initial Input Goes Here");
ToUpper up(std::locale::classic());
ToLower down(std::locale::classic());
// Change everything into upper case.
std::transform(s.begin(), s.end(), s.begin(), up);
// Change everything into lower case.
std::transform(s.begin(), s.end(), s.begin(), down);
// Change everything back into upper case, but store the
// result in a different string.
std::string capital_s;
std::transform(s.begin(), s.end(), std::back_inserter(capital_s), up);
}</pre>
<p>The <code>ToUpper</code> and <code>ToLower</code> structs can be
generalized for other character types by making <code>operator()</code>
a member function template.
</p>
<p>The final version of the code uses <code>bind2nd</code> to eliminate
the wrapper structs, but the resulting code is tricky. I have not
shown it here because no compilers currently available to me will
handle it.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, locale name LC_ALL" />
<meta name="DESCRIPTION" content="Notes on the locale implementation." />
<title>Notes on the locale implementation.</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Bookmark" href="howto.html" type="text/html" title="Localization" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1>
Notes on the locale implementation.
</h1>
<em>
prepared by Benjamin Kosnik (bkoz@redhat.com) on October 14, 2002
</em>
<h2>
1. Abstract
</h2>
<p>
Describes the basic locale object, including nested
classes id, facet, and the reference-counted implementation object,
class _Impl.
</p>
<h2>
2. What the standard says
</h2>
Class locale is non-templatized and has two distinct types nested
inside of it:
<blockquote>
<em>
class facet
22.1.1.1.2 Class locale::facet
</em>
</blockquote>
<p>
Facets actually implement locale functionality. For instance, a facet
called numpunct is the data objects that can be used to query for the
thousands separator is in the German locale.
</p>
Literally, a facet is strictly defined:
<ul>
<li>containing the following public data member:
<p>
<code>static locale::id id;</code>
</p>
</li>
<li>derived from another facet:
<p>
<code> class gnu_codecvt: public std::ctype&lt;user-defined-type&gt;</code>
</p>
</li>
</ul>
<p>
Of interest in this class are the memory management options explicitly
specified as an argument to facet's constructor. Each constructor of a
facet class takes a std::size_t __refs argument: if __refs == 0, the
facet is deleted when the locale containing it is destroyed. If __refs
== 1, the facet is not destroyed, even when it is no longer
referenced.
</p>
<blockquote>
<em>
class id
22.1.1.1.3 - Class locale::id
</em>
</blockquote>
<p>
Provides an index for looking up specific facets.
</p>
<h2>
3. Interacting with &quot;C&quot; locales.
</h2>
<p>
Some help on determining the underlying support for locales on a system.
Note, this is specific to linux (and glibc-2.3.x)
</p>
<ul>
<li> <code>`locale -a`</code> displays available locales.
<blockquote>
<pre>
af_ZA
ar_AE
ar_AE.utf8
ar_BH
ar_BH.utf8
ar_DZ
ar_DZ.utf8
ar_EG
ar_EG.utf8
ar_IN
ar_IQ
ar_IQ.utf8
ar_JO
ar_JO.utf8
ar_KW
ar_KW.utf8
ar_LB
ar_LB.utf8
ar_LY
ar_LY.utf8
ar_MA
ar_MA.utf8
ar_OM
ar_OM.utf8
ar_QA
ar_QA.utf8
ar_SA
ar_SA.utf8
ar_SD
ar_SD.utf8
ar_SY
ar_SY.utf8
ar_TN
ar_TN.utf8
ar_YE
ar_YE.utf8
be_BY
be_BY.utf8
bg_BG
bg_BG.utf8
br_FR
bs_BA
C
ca_ES
ca_ES@euro
ca_ES.utf8
ca_ES.utf8@euro
cs_CZ
cs_CZ.utf8
cy_GB
da_DK
da_DK.iso885915
da_DK.utf8
de_AT
de_AT@euro
de_AT.utf8
de_AT.utf8@euro
de_BE
de_BE@euro
de_BE.utf8
de_BE.utf8@euro
de_CH
de_CH.utf8
de_DE
de_DE@euro
de_DE.utf8
de_DE.utf8@euro
de_LU
de_LU@euro
de_LU.utf8
de_LU.utf8@euro
el_GR
el_GR.utf8
en_AU
en_AU.utf8
en_BW
en_BW.utf8
en_CA
en_CA.utf8
en_DK
en_DK.utf8
en_GB
en_GB.iso885915
en_GB.utf8
en_HK
en_HK.utf8
en_IE
en_IE@euro
en_IE.utf8
en_IE.utf8@euro
en_IN
en_NZ
en_NZ.utf8
en_PH
en_PH.utf8
en_SG
en_SG.utf8
en_US
en_US.iso885915
en_US.utf8
en_ZA
en_ZA.utf8
en_ZW
en_ZW.utf8
es_AR
es_AR.utf8
es_BO
es_BO.utf8
es_CL
es_CL.utf8
es_CO
es_CO.utf8
es_CR
es_CR.utf8
es_DO
es_DO.utf8
es_EC
es_EC.utf8
es_ES
es_ES@euro
es_ES.utf8
es_ES.utf8@euro
es_GT
es_GT.utf8
es_HN
es_HN.utf8
es_MX
es_MX.utf8
es_NI
es_NI.utf8
es_PA
es_PA.utf8
es_PE
es_PE.utf8
es_PR
es_PR.utf8
es_PY
es_PY.utf8
es_SV
es_SV.utf8
es_US
es_US.utf8
es_UY
es_UY.utf8
es_VE
es_VE.utf8
et_EE
et_EE.utf8
eu_ES
eu_ES@euro
eu_ES.utf8
eu_ES.utf8@euro
fa_IR
fi_FI
fi_FI@euro
fi_FI.utf8
fi_FI.utf8@euro
fo_FO
fo_FO.utf8
fr_BE
fr_BE@euro
fr_BE.utf8
fr_BE.utf8@euro
fr_CA
fr_CA.utf8
fr_CH
fr_CH.utf8
fr_FR
fr_FR@euro
fr_FR.utf8
fr_FR.utf8@euro
fr_LU
fr_LU@euro
fr_LU.utf8
fr_LU.utf8@euro
ga_IE
ga_IE@euro
ga_IE.utf8
ga_IE.utf8@euro
gl_ES
gl_ES@euro
gl_ES.utf8
gl_ES.utf8@euro
gv_GB
gv_GB.utf8
he_IL
he_IL.utf8
hi_IN
hr_HR
hr_HR.utf8
hu_HU
hu_HU.utf8
id_ID
id_ID.utf8
is_IS
is_IS.utf8
it_CH
it_CH.utf8
it_IT
it_IT@euro
it_IT.utf8
it_IT.utf8@euro
iw_IL
iw_IL.utf8
ja_JP.eucjp
ja_JP.utf8
ka_GE
kl_GL
kl_GL.utf8
ko_KR.euckr
ko_KR.utf8
kw_GB
kw_GB.utf8
lt_LT
lt_LT.utf8
lv_LV
lv_LV.utf8
mi_NZ
mk_MK
mk_MK.utf8
mr_IN
ms_MY
ms_MY.utf8
mt_MT
mt_MT.utf8
nl_BE
nl_BE@euro
nl_BE.utf8
nl_BE.utf8@euro
nl_NL
nl_NL@euro
nl_NL.utf8
nl_NL.utf8@euro
nn_NO
nn_NO.utf8
no_NO
no_NO.utf8
oc_FR
pl_PL
pl_PL.utf8
POSIX
pt_BR
pt_BR.utf8
pt_PT
pt_PT@euro
pt_PT.utf8
pt_PT.utf8@euro
ro_RO
ro_RO.utf8
ru_RU
ru_RU.koi8r
ru_RU.utf8
ru_UA
ru_UA.utf8
se_NO
sk_SK
sk_SK.utf8
sl_SI
sl_SI.utf8
sq_AL
sq_AL.utf8
sr_YU
sr_YU@cyrillic
sr_YU.utf8
sr_YU.utf8@cyrillic
sv_FI
sv_FI@euro
sv_FI.utf8
sv_FI.utf8@euro
sv_SE
sv_SE.iso885915
sv_SE.utf8
ta_IN
te_IN
tg_TJ
th_TH
th_TH.utf8
tl_PH
tr_TR
tr_TR.utf8
uk_UA
uk_UA.utf8
ur_PK
uz_UZ
vi_VN
vi_VN.tcvn
wa_BE
wa_BE@euro
yi_US
zh_CN
zh_CN.gb18030
zh_CN.gbk
zh_CN.utf8
zh_HK
zh_HK.utf8
zh_TW
zh_TW.euctw
zh_TW.utf8
</pre>
</blockquote>
</li>
<li> <code>`locale`</code> displays environmental variables
that impact how locale("") will be deduced.
<blockquote>
<pre>
LANG=en_US
LC_CTYPE="en_US"
LC_NUMERIC="en_US"
LC_TIME="en_US"
LC_COLLATE="en_US"
LC_MONETARY="en_US"
LC_MESSAGES="en_US"
LC_PAPER="en_US"
LC_NAME="en_US"
LC_ADDRESS="en_US"
LC_TELEPHONE="en_US"
LC_MEASUREMENT="en_US"
LC_IDENTIFICATION="en_US"
LC_ALL=
</pre>
</blockquote>
</li>
</ul>
<p>
From Josuttis, p. 697-698, which says, that "there is only *one*
relation (of the C++ locale mechanism) to the C locale mechanism: the
global C locale is modified if a named C++ locale object is set as the
global locale" (emphasis Paolo), that is:
</p>
<code>std::locale::global(std::locale(""));</code>
<p>affects the C functions as if the following call was made:</p>
<code>std::setlocale(LC_ALL, "");</code>
<p>
On the other hand, there is *no* viceversa, that is, calling setlocale
has *no* whatsoever on the C++ locale mechanism, in particular on the
working of locale(""), which constructs the locale object from the
environment of the running program, that is, in practice, the set of
LC_ALL, LANG, etc. variable of the shell.
</p>
<h2>
4. Design
</h2>
<p>
The major design challenge is fitting an object-orientated and
non-global locale design ontop of POSIX and other relevant stanards,
which include the Single Unix (nee X/Open.)
</p>
<p>
Because POSIX falls down so completely, portibility is an issue.
</p>
class _Impl
The internal representation of the std::locale object.
<h2>
5. Examples
</h2>
More information can be found in the following testcases:
<ul>
<li> testsuite/22_locale/all </li>
</ul>
<h2>
6. Unresolved Issues
</h2>
<ul>
<li> locale initialization: at what point does _S_classic,
_S_global get initialized? Can named locales assume this
initialization has already taken place? </li>
<li> document how named locales error check when filling data
members. Ie, a fr_FR locale that doesn't have
numpunct::truename(): does it use "true"? Or is it a blank
string? What's the convention? </li>
<li> explain how locale aliasing happens. When does "de_DE"
use "de" information? What is the rule for locales composed of
just an ISO language code (say, "de") and locales with both an
ISO language code and ISO country code (say, "de_DE"). </li>
<li> what should non-required facet instantiations do? If the
generic implemenation is provided, then how to end-users
provide specializations? </li>
</ul>
<h2>
7. Acknowledgments
</h2>
<h2>
8. Bibliography / Referenced Documents
</h2>
Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters &quot;6. Character Set Handling&quot; and &quot;7 Locales and Internationalization&quot;
<p>
Drepper, Ulrich, Numerous, late-night email correspondence
</p>
<p>
ISO/IEC 14882:1998 Programming languages - C++
</p>
<p>
ISO/IEC 9899:1999 Programming languages - C
</p>
<p>
Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000
</p>
<p>
Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000
</p>
<p>
System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x)
The Open Group/The Institute of Electrical and Electronics Engineers, Inc.
http://www.opennc.org/austin/docreg.html
</p>
</body>
</html>
/*****************************************************************
* Functions to help treat arrays in a uniform manner. These were
* inspired by a thread on comp.lang.c++.moderated, started by Dietmar
* Kuehl and contributed to by the rest of the entire planet.
*
* beginof (x), endof (x), lengthof (x) now accompany sizeof, where x
* can be either a container (currently only sequences) or a builtin
* array (/not/ a pointer). The beginof/endof are intended for use in
* the algorithms library, and lengthof is a "sizing" function.
*
* Note example:
* char an_array [17];
* cerr << lengthof(an_array) << endl;
* produces assembly code of
* mov 17,register0
* call ofstream_put
* i.e., the template function inlining really does work; g++
* requires -O3 (or -finline-functions) before it does this, though.
*
* pedwards 13Nov98
*/
// beginof
template <class T>
inline typename vector<T>::iterator beginof (vector<T> &v)
{ return v.begin(); }
template <class T, unsigned int sz>
inline T* beginof (T (&array)[sz]) { return array; }
// endof
template <class T>
inline typename vector<T>::iterator endof (vector<T> &v)
{ return v.end(); }
template <class T, unsigned int sz>
inline T* endof (T (&array)[sz]) { return array + sz; }
// lengthof
template <class T>
inline typename vector<T>::size_type lengthof (vector<T> &v)
{ return v.size(); }
template <class T, unsigned int sz>
inline unsigned int lengthof (T (&)[sz]) { return sz; }
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 24: Iterators</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../23_containers/howto.html" type="text/html"
title="Containers" />
<link rel="Next" href="../25_algorithms/howto.html" type="text/html"
title="Algorithms" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 24: Iterators</a></h1>
<p>Chapter 24 deals with the FORTRAN subroutines for automatically
transforming lemmings into gold.
</p>
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">They ain't pointers!</a></li>
<li><a href="#2">It ends <em>where?</em></a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="1">They ain't pointers!</a></h2>
<p><a href="../faq/index.html#5_1">FAQ 5.1</a> points out that iterators
are not implemented as pointers. They are a generalization of
pointers, but they are implemented in libstdc++ as separate classes.
</p>
<p>Keeping that simple fact in mind as you design your code will
prevent a whole lot of difficult-to-understand bugs.
</p>
<p>You can think of it the other way 'round, even. Since iterators
are a generalization, that means that <em>pointers</em> are
<em>iterators</em>, and that pointers can be used whenever an
iterator would be. All those functions in the Algorithms chapter
of the Standard will work just as well on plain arrays and their
pointers.
</p>
<p>That doesn't mean that when you pass in a pointer, it gets wrapped
into some special delegating iterator-to-pointer class with a layer
of overhead. (If you think that's the case anywhere, you don't
understand templates to begin with...) Oh, no; if you pass
in a pointer, then the compiler will instantiate that template
using T* as a type, and good old high-speed pointer arithmetic as
its operations, so the resulting code will be doing exactly the same
things as it would be doing if you had hand-coded it yourself (for
the 273rd time).
</p>
<p>How much overhead <em>is</em> there when using an iterator class?
Very little. Most of the layering classes contain nothing but
typedefs, and typedefs are &quot;meta-information&quot; that simply
tell the compiler some nicknames; they don't create code. That
information gets passed down through inheritance, so while the
compiler has to do work looking up all the names, your runtime code
does not. (This has been a prime concern from the beginning.)
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="2">It ends <em>where?</em></a></h2>
<p>This starts off sounding complicated, but is actually very easy,
especially towards the end. Trust me.
</p>
<p>Beginners usually have a little trouble understand the whole
'past-the-end' thing, until they remember their early algebra classes
(see, they <em>told</em> you that stuff would come in handy!) and
the concept of half-open ranges.
</p>
<p>First, some history, and a reminder of some of the funkier rules in
C and C++ for builtin arrays. The following rules have always been
true for both languages:
</p>
<ol>
<li>You can point anywhere in the array, <em>or to the first element
past the end of the array</em>. A pointer that points to one
past the end of the array is guaranteed to be as unique as a
pointer to somewhere inside the array, so that you can compare
such pointers safely.
</li>
<li>You can only dereference a pointer that points into an array.
If your array pointer points outside the array -- even to just
one past the end -- and you dereference it, Bad Things happen.
</li>
<li>Strictly speaking, simply pointing anywhere else invokes
undefined behavior. Most programs won't puke until such a
pointer is actually dereferenced, but the standards leave that
up to the platform.
</li>
</ol>
<p>The reason this past-the-end addressing was allowed is to make it
easy to write a loop to go over an entire array, e.g.,
while (*d++ = *s++);.
</p>
<p>So, when you think of two pointers delimiting an array, don't think
of them as indexing 0 through n-1. Think of them as <em>boundary
markers</em>:
</p>
<pre>
beginning end
| |
| | This is bad. Always having to
| | remember to add or subtract one.
| | Off-by-one bugs very common here.
V V
array of N elements
|---|---|--...--|---|---|
| 0 | 1 | ... |N-2|N-1|
|---|---|--...--|---|---|
^ ^
| |
| | This is good. This is safe. This
| | is guaranteed to work. Just don't
| | dereference 'end'.
beginning end
</pre>
<p>See? Everything between the boundary markers is part of the array.
Simple.
</p>
<p>Now think back to your junior-high school algebra course, when you
were learning how to draw graphs. Remember that a graph terminating
with a solid dot meant, &quot;Everything up through this point,&quot;
and a graph terminating with an open dot meant, &quot;Everything up
to, but not including, this point,&quot; respectively called closed
and open ranges? Remember how closed ranges were written with
brackets, <em>[a,b]</em>, and open ranges were written with parentheses,
<em>(a,b)</em>?
</p>
<p>The boundary markers for arrays describe a <em>half-open range</em>,
starting with (and including) the first element, and ending with (but
not including) the last element: <em>[beginning,end)</em>. See, I
told you it would be simple in the end.
</p>
<p>Iterators, and everything working with iterators, follows this same
time-honored tradition. A container's <code>begin()</code> method returns
an iterator referring to the first element, and its <code>end()</code>
method returns a past-the-end iterator, which is guaranteed to be
unique and comparable against any other iterator pointing into the
middle of the container.
</p>
<p>Container constructors, container methods, and algorithms, all take
pairs of iterators describing a range of values on which to operate.
All of these ranges are half-open ranges, so you pass the beginning
iterator as the starting parameter, and the one-past-the-end iterator
as the finishing parameter.
</p>
<p>This generalizes very well. You can operate on sub-ranges quite
easily this way; functions accepting a <em>[first,last)</em> range
don't know or care whether they are the boundaries of an entire {array,
sequence, container, whatever}, or whether they only enclose a few
elements from the center. This approach also makes zero-length
sequences very simple to recognize: if the two endpoints compare
equal, then the {array, sequence, container, whatever} is empty.
</p>
<p>Just don't dereference <code>end()</code>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 25: Algorithms</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../24_iterators/howto.html" type="text/html"
title="Iterators" />
<link rel="Next" href="../26_numerics/howto.html" type="text/html"
title="Numerics" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 25: Algorithms</a></h1>
<p>Chapter 25 deals with the generalized subroutines for automatically
transforming lemmings into gold.
</p>
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Prerequisites</a></li>
<li><a href="#2">Special <code>swap</code>s</a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="1">Prerequisites</a></h2>
<p>The neatest accomplishment of the algorithms chapter is that all the
work is done via iterators, not containers directly. This means two
important things:
</p>
<ol>
<li>Anything that behaves like an iterator can be used in one of
these algorithms. Raw pointers make great candidates, thus
built-in arrays are fine containers, as well as your own iterators.
</li>
<li>The algorithms do not (and cannot) affect the container as a
whole; only the things between the two iterator endpoints. If
you pass a range of iterators only enclosing the middle third of
a container, then anything outside that range is inviolate.
</li>
</ol>
<p>Even strings can be fed through the algorithms here, although the
string class has specialized versions of many of these functions (for
example, <code>string::find()</code>). Most of the examples on this
page will use simple arrays of integers as a playground for
algorithms, just to keep things simple.
<a name="Nsize">The use of <strong>N</strong></a> as a size in the
examples is to keep things easy to read but probably won't be valid
code. You can use wrappers such as those described in the
<a href="../23_containers/howto.html">containers chapter</a> to keep
real code readable.
</p>
<p>The single thing that trips people up the most is the definition of
<em>range</em> used with iterators; the famous
&quot;past-the-end&quot; rule that everybody loves to hate. The
<a href="../24_iterators/howto.html#2">iterators chapter</a> of this
document has a complete explanation of this simple rule that seems to
cause so much confusion. Once you get <em>range</em> into your head
(it's not that hard, honest!), then the algorithms are a cakewalk.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="2">Special <code>swap</code>s</a></h2>
<p>If you call <code> std::swap(x,y); </code> where x and y are standard
containers, then the call will automatically be replaced by a call to
<code> x.swap(y); </code> instead.
</p>
<p>This allows member functions of each container class to take over, and
containers' swap functions should have O(1) complexity according to
the standard. (And while &quot;should&quot; allows implementations to
behave otherwise and remain compliant, this implementation does in
fact use constant-time swaps.) This should not be surprising, since
for two containers of the same type to swap contents, only some
internal pointers to storage need to be exchanged.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" />
<meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ HOWTO: Chapter 26: Numerics</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Start" href="../documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Prev" href="../25_algorithms/howto.html" type="text/html"
title="Algorithms" />
<link rel="Next" href="../27_io/howto.html" type="text/html"
title="Input/Output" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
<body>
<h1 class="centered"><a name="top">Chapter 26: Numerics</a></h1>
<p>Chapter 26 deals with building block abstractions to aid in
numerical computing:
</p>
<ul>
<li>Template data structures such as <code>valarray&lt;&gt;</code>
and <code>complex&lt;&gt;</code>.
</li>
<li>Template numerical functions such as <code>accumulate</code>,
<code>inner_product</code>, <code>partial_sum</code>, and
<code>adjacent_difference</code>.
</li>
</ul>
<p>All of the Standard C math functions are of course included in C++,
and overloaded versions for <code>long</code>, <code>float</code>, and
<code>long double</code> have been added for all of them.
</p>
<!-- ####################################################### -->
<hr />
<h1>Contents</h1>
<ul>
<li><a href="#1">Complex Number Processing</a></li>
<li><a href="#2">Array Processing</a></li>
<li><a href="#3">Numerical Functions</a></li>
<li><a href="#4">C99</a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="1">Complex Number Processing</a></h2>
<p>Using <code>complex&lt;&gt;</code> becomes even more comple- er, sorry,
<em>complicated</em>, with the not-quite-gratuitously-incompatible
addition of complex types to the C language. David Tribble has
compiled a list of C++98 and C99 conflict points; his description of
C's new type versus those of C++ and how to get them playing together
nicely is
<a href="http://david.tribble.com/text/cdiffs.htm#C99-complex">here</a>.
</p>
<p><code>complex&lt;&gt;</code> is intended to be instantiated with a
floating-point type. As long as you meet that and some other basic
requirements, then the resulting instantiation has all of the usual
math operators defined, as well as definitions of <code>op&lt;&lt;</code>
and <code>op&gt;&gt;</code> that work with iostreams: <code>op&lt;&lt;</code>
prints <code>(u,v)</code> and <code>op&gt;&gt;</code> can read <code>u</code>,
<code>(u)</code>, and <code>(u,v)</code>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="2">Array Processing</a></h2>
<p>One of the major reasons why FORTRAN can chew through numbers so well
is that it is defined to be free of pointer aliasing, an assumption
that C89 is not allowed to make, and neither is C++98. C99 adds a new
keyword, <code>restrict</code>, to apply to individual pointers. The
C++ solution is contained in the library rather than the language
(although many vendors can be expected to add this to their compilers
as an extension).
</p>
<p>That library solution is a set of two classes, five template classes,
and &quot;a whole bunch&quot; of functions. The classes are required
to be free of pointer aliasing, so compilers can optimize the
daylights out of them the same way that they have been for FORTRAN.
They are collectively called <code>valarray</code>, although strictly
speaking this is only one of the five template classes, and they are
designed to be familiar to people who have worked with the BLAS
libraries before.
</p>
<p>Some more stuff should go here once somebody has time to write it.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="3">Numerical Functions</a></h2>
<p>There are four generalized functions in the &lt;numeric&gt; header
that follow the same conventions as those in &lt;algorithm&gt;. Each
of them is overloaded: one signature for common default operations,
and a second for fully general operations. Their names are
self-explanatory to anyone who works with numerics on a regular basis:
</p>
<ul>
<li><code>accumulate</code></li>
<li><code>inner_product</code></li>
<li><code>partial_sum</code></li>
<li><code>adjacent_difference</code></li>
</ul>
<p>Here is a simple example of the two forms of <code>accumulate</code>.
</p>
<pre>
int ar[50];
int someval = somefunction();
// ...initialize members of ar to something...
int sum = std::accumulate(ar,ar+50,0);
int sum_stuff = std::accumulate(ar,ar+50,someval);
int product = std::accumulate(ar,ar+50,1,std::multiplies&lt;int&gt;());
</pre>
<p>The first call adds all the members of the array, using zero as an
initial value for <code>sum</code>. The second does the same, but uses
<code>someval</code> as the starting value (thus, <code>sum_stuff == sum +
someval</code>). The final call uses the second of the two signatures,
and multiplies all the members of the array; here we must obviously
use 1 as a starting value instead of 0.
</p>
<p>The other three functions have similar dual-signature forms.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<hr />
<h2><a name="4">C99</a></h2>
<p>In addition to the other topics on this page, we'll note here some
of the C99 features that appear in libstdc++.
</p>
<p>The C99 features depend on the <code>--enable-c99</code> configure flag.
This flag is already on by default, but it can be disabled by the
user. Also, the configuration machinery will disable it if the
necessary support for C99 (e.g., header files) cannot be found.
</p>
<p>As of GCC 3.0, C99 support includes classification functions
such as <code>isnormal</code>, <code>isgreater</code>,
<code>isnan</code>, etc.
The functions used for 'long long' support such as <code>strtoll</code>
are supported, as is the <code>lldiv_t</code> typedef. Also supported
are the wide character functions using 'long long', like
<code>wcstoll</code>.
</p>
<p>Return <a href="#top">to top of page</a> or
<a href="../faq/index.html">to the FAQ</a>.
</p>
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="../17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
From: James Kanze <kanze@gabi-soft.de>
Newsgroups: comp.lang.c++.moderated
Subject: Re: binary iostreams ?
Date: 3 Feb 2001 14:28:19 -0500
Message-ID: <86lmro86qp.fsf@alex.gabi-soft.de>
"Plinio Conti" <plinio.contiNO@SPAMMINGmclink.it> writes:
|> Why std c++ library stream classes are only text-oriented?
Because that is the only universally recognized format.
|> I mean, if I want to write an int, a float, etc. AS IT IS I can't
|> use streams, because they write and read a human readable text
|> format of numbers.
Correct.
|> Does anyone know how to solve the problem?
It depends on what you really want to do. If you are just dumping a
block of memory to disk, in order to free up memory, and will reread it
later in the same run of the same program, ostream::write and
istream::read are what you need. Note, however, that this ony works 1)
in the same run of the same program, and 2) for PODs without pointers.
If you are writing something that will be read by another program, or a
later run of the same program, you'll have to define a specific format
to use, and implement streams to input and output that. If you are
writing something that will be read by an existing program, or be
transmitted over a network to another machine, you will have to find out
what protocol is expected, and adher to it.
|> Any public library?
Not that I know of. I think that there is a library somewhere that
outputs in format RPC, or maybe some Internet format.
|> What do you think about this choice?
What other choice is possible? It's not reasonable to ask the standard
to support all binary formats, and it's not reasonable for it to favor
any one of them. Given that, what else can you do.
--
James Kanze mailto:kanze@gabi-soft.de
Conseils en informatique orientée objet/
Beratung in objektorientierter Datenverarbeitung
Ziegelhüttenweg 17a, 60598 Frankfurt, Germany Tel. +49(069)63198627
From: kuehl@ramsen.informatik.uni-konstanz.de (Dietmar Kuehl)
Newsgroups: comp.std.c++
Subject: Re: binary iostreams ?
Date: Sat, 3 Feb 2001 17:17:49 GMT
Message-ID: <95hctq$suu$2@news.BelWue.DE>
Hi,
Plinio Conti (plinio.contiNO@SPAMMINGmclink.it) wrote:
: Why std c++ library stream classes are only text-oriented?
There is only a text oriented front end to stream buffers because text
input and output does not vary between platforms. This is very
different for binary output. For example, binary output has to consider
- word sizes: Is an 'int' two, four, or eight bytes long? The same
questions arise for all other built-in types.
- what is the bit pattern of a value? I think that at least implicitly
in the standard a binary representation for integer types is required.
I don't think that it is required to use two's complement. In any
case, the floating point representations do differ, eg. in their
number of bytes used.
- what "endianess" is to be used?
Basically it is possible to decide a format for each of those. This,
however, implies inefficient implementations on platforms where the
format does not match the internal representation.
What many people asking for binary I/O forget is that binary I/O also
requires some form of formatting! Assuming that just writing data and
then reading it in will work is asking for problems, eg. when the
compiler version changes and they decided to use a 32 bit integer
rather than a 16 bit integer: It is not even necessary to switch
platforms to run into problems!
: I mean, if I want to write an int, a float, etc. AS IT IS I can't use
: streams, because they write and read a human readable text format of
: numbers.
Which is for most I/O a reasonable approach. If it is not for you, you
might want to consider a data base: File I/O is not really useful as a
persistance mechanism. It is fine eg. for user interaction (text I/O),
logging (text I/O), cross platfrom program interaction (formatted I/O),
and data exchange (formatted I/O). In all these cases, the I/O is
formatted, although possible using a binary format. For persistance,
data bases are used. Depending on your needs, a relational or an object
oriented one may be better suited.
That said, it is worth to mention that it is easy to create a hierarchy
similar to IOStreams built on top of stream buffers but doing binary
formatting. A somewhat aged example is found at
<ftp://ftp.fmi.uni-konstanz.de/pub/algo/personal/kuehl/binio.tar.gz>.
This uses XDR formatting of the binary data (well, if I remmeber
correctly, it is easy to plug in a different binary formatting).
: Does anyone know how to solve the problem?
Use a data base, text formatting, or binary formatting. With the
details you have given it is impossible to tell which of those is the
right approach because you haven't told *why* you want a binary format
and *what* you want to do. That basically means that you came up with
solution and you want us to confirm that it is the right one without
telling us what problem is solved! Until I have seen the problem I
doubt that binary I/O is the right approach...
... and, BTW, using 'std::istream::read()' and 'std::ostream::write()'
is almost certainly the *wrong* approach! These functions are an
historical mistake which should have been corrected in the standard:
It is my understanding that these methods were present in the IOStream
version predating the rework from Jerry Schwartz and were left in to
be compatible with the earlier stuff although they were not necessary:
You could get binary I/O from the stream buffer level. The original
IOStream library (maybe you remember using <stream.h>) did not have
stream buffers and thus basic support for binary I/O was also present
on the streams level.
: What do you think about this choice?
When I wrote the above paragraph about confirming your choice, I haven't
read this question! As I said above: You told us what solution you have
choosen without stating what problem is solved. We cannot determine
whether your choice is the right one. Actually, I'm pretty sure it is
the wrong one but without seen the details I can't be certain.
--
<mailto:dietmar_kuehl@yahoo.com> <http://www.dietmar-kuehl.de/>
Phaidros eaSE - Easy Software Engineering: <http://www.phaidros.com/>
The HTML documentation in this folder is generated from the XML sources.
To change or edit, please edit the XML sources in the ../xml directory.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
<meta name="KEYWORDS" content="C++, libstdc++, MT, thread, pthread, mutex, loc, atomic" />
<meta name="DESCRIPTION" content="Concurrency Support" />
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>Concurrency Support</title>
<link rel="StyleSheet" href="lib3styles.css" type="text/css" />
<link rel="Start" href="documentation.html" type="text/html"
title="GNU C++ Standard Library" />
<link rel="Copyright" href="17_intro/license.html" type="text/html" />
</head>
<body>
<h1 class="centered"><a name="top">Concurrency Support</a></h1>
<p class="fineprint"><em>
The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html">
http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html</a>.
</em></p>
<p><em>
To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
</em></p>
<!-- ####################################################### -->
<hr />
<p>The interface for concurrency support is divided into two files:
&lt;ext/atomicity.h&gt; which provides support for atomic operations,
and &lt;ext/concurrence.h&gt;, which provides mutex and lock objects
as well as compile-time data structures for querying thread
support.</p>
<p>It is expected that support for concurrence will evolve into what
is specified in the draft C++0x standard.</p>
<h3 class="left">
<a name="atomic_api">Atomics Interface</a>
</h3>
<p>
Two functions and one type form the base of atomic support.
</p>
<p>The type <code>_Atomic_word</code> is a signed integral type
supporting atomic operations.
</p>
<p>
The two functions functions are:
</p>
<pre>
_Atomic_word
__exchange_and_add_dispatch(volatile _Atomic_word*, int);
void
__atomic_add_dispatch(volatile _Atomic_word*, int);
</pre>
<p>Both of these functions are declared in the header file
&lt;ext/atomicity.h&gt;, and are in <code>namespace __gnu_cxx</code>.
</p>
<ul>
<li>
<code>
__exchange_and_add_dispatch
</code>
<p>Adds the second argument's value to the first argument. Returns the old value.
</p>
</li>
<li>
<code>
__atomic_add_dispatch
</code>
<p>Adds the second argument's value to the first argument. Has no return value.
</p>
</li>
</ul>
<p>
These functions forward to one of several specialized helper
functions, depending on the circumstances. For instance,
</p>
<p>
<code>
__exchange_and_add_dispatch
</code>
</p>
<p>
Calls through to either of:
</p>
<ul>
<li><code>__exchange_and_add</code>
<p>Multi-thread version. Inlined if compiler-generated builtin atomics
can be used, otherwise resolved at link time to a non-builtin code
sequence.
</p>
</li>
<li><code>__exchange_and_add_single</code>
<p>Single threaded version. Inlined.</p>
</li>
</ul>
<p>However, only <code>__exchange_and_add_dispatch</code>
and <code>__atomic_add_dispatch</code> should be used. These functions
can be used in a portable manner, regardless of the specific
environment. They are carefully designed to provide optimum efficiency
and speed, abstracting out atomic accesses when they are not required
(even on hosts that support compiler intrinsics for atomic
operations.)
</p>
<p>
In addition, there are two macros
</p>
<p>
<code>
_GLIBCXX_READ_MEM_BARRIER
</code>
</p>
<p>
<code>
_GLIBCXX_WRITE_MEM_BARRIER
</code>
</p>
<p>
Which expand to the appropriate write and read barrier required by the
host hardware and operating system.
</p>
<h3 class="left">
<a name="pthread_api">Pthread Interface</a>
</h3>
<p>A thin layer above IEEE 1003.1 (ie pthreads) is used to abstract
the thread interface for GCC. This layer is called "gthread," and is
comprised of one header file that wraps the host's default thread layer with
a POSIX-like interface.
</p>
<p> The file &lt;gthr-default.h&gt; points to the deduced wrapper for
the current host. In libstdc++ implementation files,
&lt;bits/gthr.h&gt; is used to select the proper gthreads file.
</p>
<p>Within libstdc++ sources, all calls to underlying thread functionality
use this layer. More detail as to the specific interface can be found in the source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</a>.
</p>
<p>By design, the gthread layer is interoperable with the types,
functions, and usage found in the usual &lt;pthread.h&gt; file,
including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>,
etc.
</p>
<h3 class="left">
<a name="concur_api">Concurrence Interface</a>
</h3>
<p>The file &lt;ext/concurrence.h&gt; contains all the higher-level
constructs for playing with threads. In contrast to the atomics layer,
the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>.
</p>
<p>
These types can be used in a portable manner, regardless of the
specific environment. They are carefully designed to provide optimum
efficiency and speed, abstracting out underlying thread calls and
accesses when compiling for single-threaded situations (even on hosts
that support multiple threads.)
</p>
<p>The enumerated type <code>_Lock_policy</code> details the set of
available locking
policies: <code>_S_single</code>, <code>_S_mutex</code>,
and <code>_S_atomic</code>.
</p>
<ul>
<li><code>_S_single</code>
<p>Indicates single-threaded code that does not need locking.
</p>
</li>
<li><code>_S_mutex</code>
<p>Indicates multi-threaded code using thread-layer abstractions.
</p>
</li>
<li><code>_S_atomic</code>
<p>Indicates multi-threaded code using atomic operations.
</p>
</li>
</ul>
<p>The compile-time constant <code>__default_lock_policy</code> is set
to one of the three values above, depending on characteristics of the
host environment and the current compilation flags.
</p>
<p>Two more datatypes make up the rest of the
interface: <code>__mutex</code>, and <code>__scoped_lock</code>.
</p>
<p>
</p>
<p>The scoped lock idiom is well-discussed within the C++
community. This version takes a <code>__mutex</code> reference, and
locks it during construction of <code>__scoped_locke</code> and
unlocks it during destruction. This is an efficient way of locking
critical sections, while retaining exception-safety.
</p>
<p>Typical usage of the last two constructs is demonstrated as follows:
</p>
<pre>
#include &lt;ext/concurrence.h&gt;
namespace
{
__gnu_cxx::__mutex safe_base_mutex;
} // anonymous namespace
namespace other
{
void
foo()
{
__gnu_cxx::__scoped_lock sentry(safe_base_mutex);
for (int i = 0; i &lt; max; ++i)
{
_Safe_iterator_base* __old = __iter;
__iter = __iter-&lt;_M_next;
__old-&lt;_M_detach_single();
}
}
</pre>
<p>In this sample code, an anonymous namespace is used to keep
the <code>__mutex</code> private to the compilation unit,
and <code>__scoped_lock</code> is used to guard access to the critical
section within the for loop, locking the mutex on creation and freeing
the mutex as control moves out of this block.
</p>
<p>Several exception classes are used to keep track of
concurrence-related errors. These classes
are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>,
and <code>__concurrence_broadcast_error</code>.
</p>
<h3 class="left">
<a name="atomic_impl">Details on builtin atomic support and library fallbacks</a>
</h3>
<p>The functions for atomic operations described above are either
implemented via compiler intrinsics (if the underlying host is
capable) or by library fallbacks.</p>
<p>Compiler intrinsics (builtins) are always preferred. However, as
the compiler builtins for atomics are not universally implemented,
using them directly is problematic, and can result in undefined
function calls. (An example of an undefined symbol from the use
of <code>__sync_fetch_and_add</code> on an unsupported host is a
missing reference to <code>__sync_fetch_and_add_4</code>.)
</p>
<p>In addition, on some hosts the compiler intrinsics are enabled
conditionally, via the <code>-march</code> command line flag. This makes
usage vary depending on the target hardware and the flags used during
compile.
</p>
<p> If builtins are possible, <code>_GLIBCXX_ATOMIC_BUILTINS</code>
will be defined.
</p>
<p>For the following hosts, intrinsics are enabled by default.
</p>
<ul>
<li>alpha</li>
<li>ia64</li>
<li>powerpc</li>
<li>s390</li>
</ul>
<p>For others, some form of <code>-march</code> may work. On
non-ancient x86 hardware, <code>-march=native</code> usually does the
trick.</p>
<p> For hosts without compiler intrinsics, but with capable
hardware, hand-crafted assembly is selected. This is the case for the following hosts:
</p>
<ul>
<li>cris</li>
<li>hppa</li>
<li>i386</li>
<li>i486</li>
<li>m48k</li>
<li>mips</li>
<li>sparc</li>
</ul>
<p>And for the rest, a simulated atomic lock via pthreads.
</p>
<p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</a>.
</p>
<p> More details on the library fallbacks from the porting <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</a>.
</p>
</body>
</html>
<html>
<head>
<title>The GNU C++ Library Documentation</title>
</head>
<body>
<!-- ==================================================================== -->
<div>
<h1>The GNU C++ Library Documentation</h1>
<p>Copyright 2008 FSF</p>
<p>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.2 or any later version published by the
Free Software Foundation; with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts.
</p>
<p>
This is the top level of the libstdc++ documentation tree.
The documentation is contained in three logically separate
documents, as listed in the following Table of Contents.
</p>
</div>
<div>
<p><b>Table of Contents</b></p>
<dl>
<dt><a href="manual/spine.html">Manual</a></dt>
<dt><a href="faq.html">Frequently Asked Questions</a></dt>
<dt><a href="api.html">API and Source Documentation</a></dt>
</dl>
</div>
</body>
</html>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" />
<meta name="KEYWORDS" content="libstdc++, libstdc++, GCC, g++" />
<meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." />
<meta name="GENERATOR" content="vi and eight fingers" />
<title>libstdc++ Installation Instructions</title>
<link rel="StyleSheet" href="lib3styles.css" type="text/css" />
<link rel="Copyright" href="17_intro/license.html" type="text/html" />
</head>
<body>
<h1 class="centered"><a name="top">Getting started: configure, build, install</a></h1>
<p class="fineprint"><em>
The latest version of this document is always available at
<a href="http://gcc.gnu.org/onlinedocs/libstdc++/install.html">
http://gcc.gnu.org/onlinedocs/libstdc++/install.html</a>.
</em></p>
<p><em>
To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>.
</em></p>
<!-- ####################################################### -->
<hr />
<h2>Contents</h2>
<p>Because libstdc++ is part of GCC, the primary source for
installation instructions is
<a href="http://gcc.gnu.org/install/">the GCC install page</a>.
Additional data is given here only where it applies to libstdc++.
</p>
<ul>
<li><a href="#prereqs">Tools you will need beforehand</a></li>
<li><a href="#config">Configuring</a></li>
<li><a href="#usage">Using the library</a></li>
</ul>
<hr />
<!-- ####################################################### -->
<h2><a name="prereqs">Tools you will need beforehand</a></h2>
<p>The list of software needed to build the library is kept with the
rest of the compiler, at
<a href="http://gcc.gnu.org/install/prerequisites.html">
http://gcc.gnu.org/install/prerequisites.html</a>. The same page
also lists the tools you will need if you wish to modify the source.
</p>
<p>As of GCC 4.0.1 the minimum version of binutils required to build
libstdc++ is <code>2.15.90.0.1.1</code>. You can get snapshots
(as well as releases) of binutils from
<a href="ftp://sources.redhat.com/pub/binutils">
ftp://sources.redhat.com/pub/binutils</a>.
Older releases of libstdc++ do not require such a recent version,
but to take full advantage of useful space-saving features and
bug-fixes you should use a recent binutils if possible.
The configure process will automatically detect and use these
features if the underlying support is present.
</p>
<p>Finally, a few system-specific requirements: </p>
<dl>
<dt> linux </dt>
<dd>If gcc 3.1.0 or later on is being used on linux, an attempt
will be made to use "C" library functionality necessary for C++
named locale support. For gcc 3.2.1 and later, this means that
glibc 2.2.5 or later is required and the "C" library de_DE locale
information must be installed.
<p>
Note however that the sanity checks involving the de_DE locale are
skipped when an explicit --enable-clocale=gnu configure option is
used: only the basic checks are carried out, defending against
misconfigurations.
</p>
<p>
If the 'gnu' locale model is being used, the following locales
are used and tested in the libstdc++ testsuites. The first column
is the name of the locale, the second is the character set it is
expected to use.
</p>
<pre>
de_DE ISO-8859-1
de_DE@euro ISO-8859-15
en_HK ISO-8859-1
en_PH ISO-8859-1
en_US ISO-8859-1
en_US.ISO-8859-1 ISO-8859-1
en_US.ISO-8859-15 ISO-8859-15
en_US.UTF-8 UTF-8
es_ES ISO-8859-1
es_MX ISO-8859-1
fr_FR ISO-8859-1
fr_FR@euro ISO-8859-15
is_IS UTF-8
it_IT ISO-8859-1
ja_JP.eucjp EUC-JP
se_NO.UTF-8 UTF-8
ta_IN UTF-8
zh_TW BIG5
</pre>
<p>Failure to have the underlying "C" library locale
information installed will mean that C++ named locales for the
above regions will not work: because of this, the libstdc++
testsuite will skip the named locale tests. If this isn't an
issue, don't worry about it. If named locales are needed, the
underlying locale information must be installed. Note that
rebuilding libstdc++ after the "C" locales are installed is not
necessary.
</p>
<p>To install support for locales, do only one of the following:
</p>
<ul>
<li> install all locales
<ul>
<li>with RedHat Linux:
<p> <code> export LC_ALL=C </code> </p>
<p> <code> rpm -e glibc-common --nodeps </code> </p>
<p> <code> rpm -i --define "_install_langs all"
glibc-common-2.2.5-34.i386.rpm </code> </p>
</li>
<li> (instructions for other operating systems solicited) </li>
</ul>
</li>
<li> install just the necessary locales
<ul>
<li>with Debian Linux:
<p> Add the above list, as shown, to the file
<code>/etc/locale.gen</code> </p>
<p> run <code>/usr/sbin/locale-gen</code> </p>
</li>
<li> on most Unix-like operating systems:
<p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p>
<p> (repeat for each entry in the above list) </p>
</li>
<li> (instructions for other operating systems solicited) </li>
</ul>
</li>
</ul>
</dd>
</dl>
<hr />
<h2><a name="config">Configuring</a></h2>
<p>If you have never done this before, you should read the basic
<a href="http://gcc.gnu.org/install/">GCC Installation
Instructions</a> first. Read <em>all of them</em>.
<strong>Twice.</strong>
</p>
<p>When building libstdc++ you'll have to configure
the entire <em>gccsrcdir</em> directory. The full list of libstdc++
specific configuration options, not dependent on the specific compiler
release being used, can be found <a href="configopts.html">here</a>.
</p>
<p>Consider possibly using --enable-languages=c++ to save time by only
building the C++ language parts.
</p>
<pre>
cd <em>gccbuilddir</em>
<em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre>
<hr />
<h2><a name="usage">Using the library</a></h2>
<h3>Find the new library at runtime (shared linking only)</h3>
<p>If you only built a static library (libstdc++.a), or if you
specified static linking, you don't have to worry about this.
But if you built a shared library (libstdc++.so) and linked
against it, then you will need to find that library when you
run the executable.
</p>
<p>Methods vary for different platforms and different styles, but
the usual ones are printed to the screen during installation.
They include:
</p>
<ul>
<li>At runtime set LD_LIBRARY_PATH in your environment correctly,
so that the shared library for libstdc++ can be found and
loaded. Be certain that you understand all of the other
implications and behavior of LD_LIBRARY_PATH first (few
people do, and they get into trouble).
</li>
<li>Compile the path to find the library at runtime into the
program. This can be done by passing certain options to g++,
which will in turn pass them on to the linker. The exact
format of the options is dependent on which linker you use:
<ul>
<li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li>
<li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li>
<li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li>
<li>More...? Let us know!</li>
</ul>
</li>
</ul>
<p>Use the <code>ldd(1)</code> utility to show which library the system
thinks it will get at runtime.
</p>
<p>A libstdc++.la file is also installed, for use with Libtool. If
you use Libtool to create your executables, these details are
taken care of for you.
</p>
<!--
<hr />
<h2><a name=""></a></h2>
<p>
</p>
-->
<!-- ####################################################### -->
<hr />
<p class="fineprint"><em>
See <a href="17_intro/license.html">license.html</a> for copying conditions.
Comments and suggestions are welcome, and may be sent to
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
</em></p>
</body>
</html>
.centered { text-align: center }
.tocheader { font-size: large }
.fineprint { font-size: x-small }
.larger { font-size: large }
BODY { background: #FFFFFF }
PRE { text-align: left ; margin-left: 1em }
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment