> -----Ursprüngliche Nachricht----- > Von: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Im Auftrag von > Chase Douglas > Gesendet: Montag, 11. Februar 2008 22:47 > An: [email protected] > Betreff: [xml] xmlwriter function naming convention > > Hello, > > After a lengthy discussion today on the #irc with DV (thanks again, even > though it was frustrating at points), I realized that I was > misunderstanding what the xmlFreeTextWriter function did. > xmlFreeTextWriter currently flushes out the writer buffer to the > associated stream and then deallocates resources associated with the > writer. My assumption was that data was being written directly to the > associated output stream without any buffering inside the writer.
Well, the writer uses a xmlOutputBuffer as an output stream and this one is doing all the buffering. With xmlTextWriterFlush you can flush the buffer at any point in your code. > > I propose that xmlFreeTextWriter be renamed to xmlCloseTextWriter. This > follows the convention of file I/O through stdio. After fopen(), one > uses the fclose() function to flush out the buffers and deallocate > resources. One cannot use free() on the file pointer without potentially > disasterous results. This is the distinction between a "close" function > and a "free" function. A "close" function flushes data from buffers > before freeing resources, whereas a "free" function only frees > resources. Since xmlFreeTextWriter behaves more like a destructor it could as well be called xmlDeleteTextWriter. From another point of view, maybe xmlTextWriterEndDocument should call xmlTextWriterFlush, so there would be no need for xmlOutputBufferClose to flush the buffer itself and the behaviour of xmlFreeTextWriter would match the behaviour you expect from it. > > Further, I feel that the naming convention is more important for libxml2 > than other libraries as there is currently no documentation outside of > the writer.c example given on xmlsoft.org (which does not point out the > buffer flushing aspect of xmlFreeTextWriter), and the xmlwriter API > (which only notes that xmlFreeTextWriter deallocates resources > associated with the writer). > > My thoughts are that this name clarification will lead to a better > understanding of the use of the xmlwriter library, especially given the > current documentation available to the end user. It may also help to add > the flushing aspect to the API documentation for the function as well. > Anyway, you can rename the function as you like if you make shure, there will be no ABI problem. Servus -- Alfred -- Alfred Mickautsch Schuler Business Solutions AG Karl-Berner-Str. 4 D-72285 Pfalzgrafenweiler tel: +49 (0)74 45 830-184 fax: +49 (0)74 45 830-349 e-mail: [EMAIL PROTECTED] _______________________________________________ xml mailing list, project page http://xmlsoft.org/ [email protected] http://mail.gnome.org/mailman/listinfo/xml
