- Boost - lists.boost.org

[locale] Review of Boost.Locale library
by Edward Diener 18 Apr '11

18 Apr '11

This is my review of the Boost Locale library. It is divided into two parts, a review of the documentation and a review of the library itself. I will refer to Boost Locale as just Locale, with a capital L, for the remainder of this review. I will use the term C++ locale to refer to the C++ standard library locale implementation. 1. Documentation The layout of the main page is decent, but I would have expected a discussion there, or as a first topic, of what Locale brings that the C++ standard locale does not have. I was disappointed not to find such a discussion. The documentation topics are specified as Tutorials. I do not think they are Tutorials, which is fine with me since I much prefer topics rather than exmaples when trying to understand a library. a. Introduction to C++ Standard Library localization support The common critical problems of the C++ locale portion of the standard library seems spurious to me. The problems mentioned are really about implementations or programmer usage, not the C++ locale library itself. The only valid problem mentioned I find there is that the C++ standard library did not attempt to standardize any locale names. This makes using C++ locales based on locale names non-portable. Unfortunately the issues there make a very weak argument for the Locale library itself. b. Locale generation I would have liked it if the doc here specified where one finds valid lists of language, country, encoding, and variant which make up a locale name. Without this information, the one valid problem mentioned regarding C++ locale is also a problem with Locale. The note about wide strings and 8-bit encoding makes no sense to me at all. If I am using a wide string encoding, why would I not be using wide string iostreams ? c. Collation There is no explanation about what 'collation' is about. This is very disappointing, as it makes the rest of the discussion difficult to follow. The examples were worthless to me since the classes involved have not been mentioned or discussed. Also the examples are woefully incomplete even in what they represent. This is one reason why I dislike documentation which attempts to teach by example. It always seems to assume that if it throws examples at the reader before anything about the classes/templates in the examples have been mentioned, that this is somehow an effective way of learning a library. Instead it just creates confusion and serves unfortunately as a way by which a library implementer does not have to explain how the classes in his library actually work or relate to each other. d. Conversions "You may notice that there are existing functions to_upper and to_lower in the Boost.StringAlgo library. The difference is that these function operate over an entire string instead of performing incorrect character-by-character conversions." In he second sentence, "these function" gramatically refers to the functions in Boost.StringAlgo, but I doubt that is what is meant. I do not understand how these conversion functions use a locale. The example gives: boost::locale::to_upper(gruben) used in a stream. Is this function using the locale imbued in the iostream ? Again this is what happens when one creates examples without first explaining topics in a rational and orderly way. e. Numbers, Time and Currency formatting and parsing A bunch of ICU flags are mentioned but with no indication about how these are supposed to be used by iostreams. These flags look like they are supposed to be used by C-like format printf statements but since Locale uses iostreams I can not understand their purpose with Locale. f. Messages Formatting (Translation) Gnu gettext should be explained when it interfaces with Locale. Just telling someone to learn Gnu gettext is not adequate. Other than that the explanation is pretty thorough. g. Character Set Conversions An explanation of what character sets are, and what character set conversions entail, should be the beginning of this documentation. h. Localized Text Formatting "Each format specifier is enclosed within {} brackets.." These are not "brackets" but "braces". Brackets are '[]'. i. In general It is confusing to me how generated locales affect the functionality of the different sections presented under 'Using Boost.Locale'. In a number of situations I am looking at classes or functions and I have no idea how these pick up a locale. I do understand that when used with iostreams the locale is determined by the locale imbued in the iostream. But outside of iostreams I do not understand from the documentation what locale is being used. If it is the C++ global locale, the documentation should say so. This entire issue about how locales are actually being used in various parts of the library should be explained as part of an overall explanation of the library. I find this good overall explanation of the library the major flaw in the documentation. The documentation itself is well-ordered and the explanations generally decent. But I find it next to impossible to understand a library when the documentation does not take the time to explain concepts/topics and instead substititutes exmaples as a means of understaning a library. 2. Library itself I did not look at the code itself and have no interest in critiquing the source. Others do this much better than I ever can. The library offers a great deal of functionality and a great positive of the library is that it works with multiple backends and brings those backends into the C++ world. In general I think that using the global locale is a bad programming practice when one specifically intends to work with locales. Unfortunately it was hard for me to understand how individual locales are used with each of the parts of the library from the documentation. But I will assume for the time being, because it seems the only correct design, that each part of the library which is documented can work with some non-global locale which is created and passed around as necessary. The only design flaw which I could discover in the library was in message translation. The fact that translation always begin from English ( or perhaps some other narrow character language ) to something else is horrendous. I can understand that the Locale implementer wanted to use something popular and that already exists, but an idea so tremendously flawed in its conception either needs to be changed, if possible, or discarded for something better. I do understand that translation is just one part of this large library, but I hope that the implementer undestands how ridiculous it is to assume that non-English programmers are going to be willing to translate from English to language X rather than from their own language to language X. I am assuming that all other parts of the library support both narrow character encodings and wide character encodings fully, and that at least UTF-16 is always supported using wide characters. It was really hard for me to make out from the docs whether or not this was the case. I believe a great deal of work was put into the library, and that this work is invaluable in bringing locale usage into C++ in a better way than it is currently supported in C++ locale. But I would have to vote "No" that the library should be accepted into Boost at the current time, with some provisos which would most likely gain my own change to a "Yes" vote in the future. 1) The documentation should explain the differences and improvements of Locale over C++ locale in a good general way. 2) The documentation should explain the use of locales for each of the topics. 3) A number of topics should discuss what they are about in general, and more time should be given to discuss how the classes/templates relate to each other. 4) Message translation should be reconsidered. I don't mean to say that the way it is done is enough to have the library rejected, but I can not believe that it is not a flawed system no matter what the popularity of Gnu gettext might be. My major trouble with the library, which has led to my "No" vote, is that I can not really understand how to use the library from the documentation or what the library really offers over and above C++ locales. I realize the library programmer may not himself be a native English speaker, but if I can not really understand a library from its documentation in a way that makes sense to me I can not vote for its inclusion into Boost. I strongly suspect that if I were to understand the functionality of the library through a more rigorous explanation of its topics, and each topics relationship to a locale class and various encodings, I mught well vote for its inclusion into Boost. But for now, and in the state which the documentation resides for me, I can not do so. So I hope this review will be undersstood at least partially as a request to improve the docs as much as anything else.

6 10

[locale] Review. Internationalization library?
by Vicente BOTET 18 Apr '11

18 Apr '11

Hi, from the name of the library Boost.Locale and the section "What is Boost.Locale?" I didn't get enough information about the motivation and the scope of the library. I think that maybe be this is due to the fact that the dependency to ICU hides a lot of features the library provides. I think that a direct link to what ICU is is a must, but I would expect a little bit more than "On the other hand, there is a great, well debugged, high quality, widely used ICU library that gives all of the goodies" in this section. >From my side if the library was named Boost.Internationalization I'm sure I would had take a look long time ago. Do you think that this renaming (or a shorter one) will cover the whole library or there are parts of the library that don't fall in the internationalization domain? As the review period has been extended, I will try to review at least the documentation. Best, Vicente

3 17

Would a construct_cast<T>(u..) be useful?
by Johannes Schaub (litb) 17 Apr '11

17 Apr '11

I was wondering whether it makes sense to have another kind of cast in boost, which behaves like the following: template<typename T, typename ...U> T construct_cast(U &&... u) { T t(std::forward<U>(u)...); return t; } This cast works if std::is_constructible<T, U...>::value is true, and fails if it is false. It presents a slightly more explicit form of boost::implicit_cast<T> in that explicit constructors of T are allowed, and for the case of a single- elemented parameter pack, explicit conversion functions of U converting to "T" are allowed. It does not allow non-implicit conversions like void* -> nonvoid*, Base* -> Derived*. Advantages over not having construct_cast: - Converting expressions to "bool" by use of "contextually converted to bool", without using things like "!!x" or "x ? true : false" (the first may trigger user defined opeators for "operator!", which may not be desired). - No need for introducing a temporary named variable like the above "t". - If all you want is to consider contexual conversions, explicit constructors and conversion functions, this can be used. All these conversion seem "safe", compared to the set of conversions allowed by T(u) and even static_cast<T>(u). What do you think about it?

2 1

BGL
by Sultana Rashid 17 Apr '11

17 Apr '11

Hi all, I have submitted two proposals to Boost.I am very interested in C++ works and algorithms,so I submitted only for Boost projects.I met an accident after proposal submission so that I could not refine my project ideas.Now I am well and have enough free time to interact with mentors and do the necessary works.My proposals can be found here: http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/monowara… http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/monowara… Now I am writing something about one of my algorithms' prospective design. *Dinitz blocking max flow algorithm:* *Input:* Graph& g .A directed graph. The graph's type will be a model of VertexListGraph and IncidenceGraph. *Input:* *source node* which is a vertex. Its type will be graph's vertex descriptor type. *Input:* *sink node* ,its type will be same as source node. *Input:* capacity map(CapacityEdgeMap cap),the edge capacity property map. The type must be a model of a constant Lvalue Property Map. The key type of the map must be the graph's edge descriptor type. Default: get(edge_capacity, g) *Input:* reverse edge map(ReverseEdgeMap rev) An edge property map that maps every edge (u,v) in the graph to the reverse edge (v,u). The map must be a model of constant Lvalue Property Map. The key type of the map must be the graph's edge descriptor type. Default: get(edge_reverse, g) *Input:*residual capacity map(ResidualCapacityEdgeMap res) ,This maps edges to their residual capacity. The type must be a model of a mutable Lvalue Property Map. The key type of the map must be the graph's edge descriptor type. Default: get(edge_residual_capacity, g) At first the whole capacity will be the residual capacity,then after every phase of calculation it will act as output. *Input:* vertex index(VertexIndexMap index_map) Maps each vertex of the graph to a unique integer in the range [0, num_vertices(g)). The map must be a model of constant LvaluePropertyMap. The key type of the map must be the graph's vertex descriptor type. Default: get(vertex_index, g) *Output:*The total flow of the network,flow in every iteration and min cut. *** User will be able to use the algorithm in two ways, named parameter version and non-named parameter version.* *** In named parameter version,explicit inputs will be the graph,source and sink node.Other will be default params. * *** In non-named parameter version,all will be explicitly input. * * * I studied already implemented flow algorithms and took help.But I am in confusion about UTIL parameters.* * If I get help or advice ,I'll try my best to refine my ideas about implementation and design.I studied all the relevant algorithms and wish to write all after getting feedback.I am not sure what to write about algorithm design.Would I write details how input and output will work as how min cut will be got or how flow will be determined? Please give me some hints.Hope to get some help.If I am not suitable for GSoC,however I want to know and implement. Mariya

2 1

Proposal Complete
by Sitesh Shrivastava 17 Apr '11

17 Apr '11

Dear Andrew, First of all, I'd like to thanks for letting me complete the timeline and other missing details in the proposal. I have almost completed my proposal. Please have a review of it and do let me know in case modification is required. Proposal URL: http://socghop.appspot.com/gsoc/proposal/review/google/gsoc2011/sitz/3001 --Thanks & Regards, *Sitesh Shrivastava* Junior Undergraduate, BIT Mesra Phone: *+91-9470521313 *E-Mail: *siteshshrivastava(a)gmail.com *Home-Page: *https://sites.google.com/site/siteshshrivastava** *

1 0

[locale] Off-list review of Boost.Locale library
by Chad Nelson 17 Apr '11

17 Apr '11

Date: Sat, 16 Apr 2011 15:40:53 +0400 From: <steve.bush(a)neosys.com> --- What is your evaluation of the design? Very good to start with since leveraging locale for i18n/l10n is a great rallying point for developers. Translate GETTEXT might be better in a separate library to increase degrees of freedom and reduce coupling. --- What is your evaluation of the implementation? The wrapper/backend strategy provides immediate benefit while leaving the door open to progressive reimplementation. Since it is a wrapper, could PARTS of it be implemented as a header only? --- What is your evaluation of the documentation? The documentation is more than good enough to start with considering this library's potential usefulness. --- What is your evaluation of the potential usefulness of the library? This library is potentially *extremely* useful because it LEVERAGES an important chunk of standard C++ that is sadly underutilised merely due to a few design and implementation flaws. This library has potential something of the order of Boost.FileSystem. This is a VERY strategic library and any shortcomings will be resolved with time. --- Did you try to use the library? With what compiler? Did you have any problems? Didn't try. --- How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? I meticulously read all documentation several times. --- Are you knowledgeable about the problem domain? Yes, we have used similar technique for Exodus http://devwiki.neosys.com and will replace those with Boost.Locale if and when it becomes available. --- Do you think the library should be accepted as a Boost library? YES - It is relatively small but has a massive effect. It has a very low cost/benefit ratio since it leverages long standing classic C++ locale design/skills.

3 2

doxygen limitations
by Vicente BOTET 17 Apr '11

17 Apr '11

Hi, I would like to comment some limitations I have found while trying to generate the reference manual from the code comments using doxygen. 1. C++0x explicit operators are not documented as explicit with a warning explicit operator underlying_type const&() const ^^^^ gives operator underlying_type const &() const; 2. ::type misplaced when inheriting from a metafunction template < typename Final, typename UT, typename MetaMixinSeq=boost::mpl::vector0<>, typename Base=base_opaque_type > class new_class : public linear_hierarchy::type { gives template, typename Base = base_opaque_type> class new_class : public linear_hierarchy::type< MetaMixinSeq, Final, Base > { // ^^^^ 3. The base type is missing if the class is not documented elsewhere. This applies to other classes defined in other libraries in Boost or the Stl, but also when we use parameterized inheritance. template struct inherited_from_underlying { template struct type : Base { // Parameterized inheritance }; }; gives template struct inherited_from_underlying { // member classes/structs/unions template struct type { }; }; 4. When the brief comment takes only one line the comment is included on the Synopsis and nothing on the description section //! the underlying type typedef UT underlying_type; generates typedef UT underlying_type; // the underlying type 5. The classes are sometimes implicitly prefixed with his namespace template < typename UT, typename Tag=void, typename Bool=bool, typename MetaMixinSeq=boost::mpl::vector0<>, typename Base=base_private_opaque_type > class private_opaque_type : public private_opaque_class< private_opaque_type, UT, Bool, MetaMixinSeq, Base> gives template, typename Base = base_private_opaque_type> class private_opaque_type : public boost::opaque::private_opaque_class< private_opaque_type< UT, Tag, Bool, MetaMixinSeq, Base >, UT, Bool, MetaMixinSeq, Base > Do you have a workaround to some of these issues? What about creating a specific doxygen limitations and workarounds wiki page? Is there a possibility that the generated html goes to a single reference html file? Best, Vicente P.S. You can see directly some real examples on the documentation of Boost.Opaque https://svn.boost.org/svn/boost/sandbox/opaque/libs/opaque/doc/html/index.h….

3 5

[locale] Review of the proposed Boost.Locale library
by Volker Lukas 17 Apr '11

17 Apr '11

Hello, this is my review of the Locale library proposed for inclusion in Boost. I vote to accept the proposed Boost.Locale as a Boost library. - What is your evaluation of the design? The library is nicely structured into individual components, as far as I can infer from the documentation and having a glance at some of the source files. I like that it is possible to use different backends, utilizing the large ICU library when available. - What is your evaluation of the implementation? I was having only a superficial look at some of the source files, so I can not comment much. What I have seen looks clean to me. While reading the source code I think I could benefit from even more code comments. There are a lot already, but on the other hand there exists for example a source file libs/locale/src/shared/mo_lambda.cpp apparently containing a whole state machine or something without any word how it is used. I also stumbled over an odd comment in file libs/locale/src/std/numeric.cpp in line 163: "// workaround common bug - substitute NBSP with ordinary space". As a reader who did not already write the code I can not infer much from comments such as this one - I mean "What is the common bug then?" If this comment refers to the situation that e.g. the locale implementation of GCCs standard library implementation generates invalid UTF-8 when using NBSP as thousands seperator, then the comment should say that. Well, my point about comments is a minor issue of course. I do not suggest that the author goes over all the code again just to add or change comments. I am a bit worried over the size of the libraries binary. On GNU/Linux x86_64 the built libboost_locale.so is almost 10MB large and codesize according to the "size" utility is almost 1MB. This comes in addition to the underlying ICU library. Is there any potential for reducing codesize? Due to the same concern about codesize I have also one concrete suggestion relating to the comparator template of the collation component. I suggest to not make the default comparision level a template parameter, instead to store it as a member. This way, when instantiating container templates the number of instantiations can be kept down. Or am I mistaken in thinking this would lead to more compact code? - What is your evaluation of the documentation? It is nicely structured. I could easily find the documentation for any specific component I was using and the documentation is also very helpful if you have a task at hand and want to find out which component to use (and whether such a component is available in the proposed Boost.Locale). There are some issues I have: Phrasing is sometime odd. For example right in the beginning, under the headline "What is Boost.Locale" there is a sentence which reads "C++ offers a very good base for localization via the existing C++ locale facets std::num_put, std::ctype, std::collate etc. But these are very limited and sometimes buggy by design." I can only guess what that means. Superficially it seems like a contradiction to me, something which is excellent can not be buggy by design, not even sometimes. Okay, minor issue again, it just stands out because it is only the fourth or fifth sentence or so. There are some typos (I guess) where it is important to be correct: Under "Messages Formatting (Translation)", subheading "Indirect Message Translation" all functions are documented as "The source text is not copied.". From the emphasis in the original document I think I can conclude that some of these functions copy and some do not. The reference section of the documentation should document the requirements on the CharType which many functions/classes are parameterized upon (can it be char/wchar_t only?). The reference documentation for token_iterator and break_iterator should not have individual entries for operator++, operator--, operator== and other operators which are always required for iterators, unless the documentation adds information. Instead, it should just be stated to which iterator concepts these templates conform. Documentation for the dereferening operators (operator*) of these templates states that the underlying sequences iterated over can not be modified with these operators. As this is the case, could a usage hint be incorporated stating that users should always use const_iterators as arguments to these templates? If a user sometimes employs for example std::string::iterator and sometimes std::string::const_iterator this would lead to unnecessary code bloat. Also, operator-> is missing from these templates. - What is your evaluation of the potential usefulness of the library? It is potentially very useful. The only objection I could conceive of is that ICU already provides much of the functionality of Boost.Locale. This library also duplicates functionality of Matthew Wilsons excellent Fastformat library (http://fastformat.sourceforge.net/) though the latter does not feature localization support as complete as that of the proposed Boost.Locale. - Did you try to use the library? With what compiler? Did you have any problems? I used the CMake way to build this library on an Opensuse system on x86_64. Compiler is GCC 4.5.1 (or a Svn snapshot roughly corresponding). The Boost version built against is 1.46.1, as delivered by Opensuse. I did not encounter any problems building the library. I played around with some of the components of the library and ran the supplied test cases. There is one inconsistency I noted, the following program generates output "Currency: $100.11" when the environment variable LANG is set to "en_US.UTF-8" and variable LC_MONETARY is set to "de_DE.UTF-8". Shouldn't the library honor LC_MONETARY? If LANG is set to "de_DE.UTF-8" "Currency: 100,11 €" is put out. Program: ------------------------------------------------- #include <ios> #include <iostream> #include <ostream> #include <locale> #include "boost/locale.hpp" int main() { namespace loc = boost::locale; using std::cout; loc::generator gen; cout.imbue(gen("")); cout << "Currency: " << loc::as::currency << 100.11 << '\n'; } ------------------------------------------------- - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? Reading the tuturial section of the Documentation. Glancing over the reference section. I also had a look at some of the source files, but only superficially. - Are you knowledgeable about the problem domain? Only marginally. With best regards, Volker Lukas

2 1

[locale] Review: Build
by Gevorg Voskanyan 17 Apr '11

17 Apr '11

build/Jamfile.v2: line 18: s/Feaures/Features line 130: There should be a space between '!' and '<target-os>cygwin', otherwise the whole condition will never evaluate to true line 132: s/need/needs/ . Also it can be equivalently replaced with just: EXIT "error: Boost.Locale needs either iconv or ICU library to be built." ; line 200: doesn't posix backend work for BSDs other than darwin? line 283: <link>shared:<define>BOOST_LOCALE_DYN_LINK=1 should be present in usage requirements too. The same applies to <threading>multi as well. lines 275, 282: what's the reason for commenting build_options and having <conditional>@configure instead? line 288: Being a vim user myself I appreciate this, but in general tabs are not allowed in code per Boost's development policy. Users of other editors would not be happy with tabs here :) General remarks: As a Boost.Build user I would see it very beneficial when using Boost.Locale to be able to have ICU build from source with BB just like the other 3rd party libraries commonly are. For it to work Boost.Locale Jamfile can check if a project /icu is available, and if so use /icu//icu as source and skip ICU configuration checking together with options for linking to prebuilt ICU. I can prepare and propose a patch for this if that scheme is OK with you. Examples and performance benchmarks should have Jamfiles too. Gevorg

2 6

SFINAE yes_type and no_type
by Jeroen Habraken 16 Apr '11

16 Apr '11

Hi, Is there a specific yes_type and no_type inside boost that I should be using when writing a SFINAE test? There seem to be quite a few defined already and reinventing the wheel (albeit it being trivial) again doesn't make sense. Regards, Jeroen

6 9