GdomeDOMString

The implementation of DOMString deserves a section on its own, since it is the only one which differs in some aspects from the DOM specification. In fact, the specification requires a DOMString to be a sequence of 16-bit units, while Gdome2 uses invariably a UTF-8 encoding [3]. This is because Gdome2 acts like a wrapper for libxml2 which already adopts internally the UTF-8 encoding. Some of the rationales for this choice are the following (see [9] for a more exhaustive treatment of this subject in the context of libxml2):

• UTF-8, while a bit more complex to convert from/to with respect to UTF-16, it is also far more compact for a majority of the documents.
• UTF-8 is being used as the de-facto internal standard encoding in the upcoming Gnome text widget [10,11], and a lot of other Unix/Linux code.

In practice, the GdomeDOMString is a simple structure made of a field str which is a pointer to a sequence of bytes assembled as a UTF-8 valid string. So Gdome2 users only need to make sure that characters outside the plain ASCII set are properly converted to UTF-8. To manage GdomeDOMString object allocation, Gdome2 has 3 different constructors, depending on the storage allocation class of the source string used as initializer:

GdomeDOMString *gdome_str_mkref(const gchar* str)
GdomeDOMString *gdome_str_mkref_own(gchar* str)
GdomeDOMString *gdome_str_mkref_dup(const gchar* str)

gdome_str_mkref creates a GdomeDOMString from a statically allocated string. gdome_str_mkref_own must be used when the user want to make a GdomeDOMString from a dynamically allocated gchar buffer. The buffer will be freed automatically upon destruction of the object. Finally, gdome_str_mkref_dup is similar to the previous one, but a copy of the initializing string is done before construction. In order to release a GdomeDOMString, just use its destructor gdome_str_unref.