Writing textual data to streams
When writing textual data to an output stream or to a file, you need to pick a character set.
Some character sets can represent "all" characters (the UTF-* character sets and UCS-4), others can only represent some characters.
When the file is to be read only by the application/extension itself, using UTF-8 is often the best choice - it can represent all characters, and ASCII characters are represented efficiently.
Writing to a stream
In Gecko 1.8 (SeaMonkey 1.0, Firefox 1.1), you can use nsIConverterOutputStream:
var charset = "UTF-8"; // Can be any charset name that Mozilla supports var os = Components.classes["@mozilla.org/intl/converter-output-stream;1"] .createInstance(Components.interfaces.nsIConverterOutputStream); // This assumes that fos is the nsIOutputStream you want to write to os.init(fos, charset); os.write("Umlaute: \u00FC \u00E4\n"); os.write("Hebrew: \u05D0 \u05D1\n"); // etc. os.close();
You can also write single characters using the
writeChar function, although using
By default, trying to write characters that are not supported by the selected character set throws an exception (with an error code of NS_ERROR_LOSS_OF_SIGNIFICANT_DATA), and no data will be written.
To instead write an replacement character in such cases, you can use the setReplacementChar function:
Note: If the replacement character is not a supported character in the chosen character set, attempts to write unsupported characters will fail with NS_ERROR_LOSS_OF_SIGNIFICANT_DATA.
Versions before Gecko 1.8
Firefox 1.0.x, Mozilla 1.7.x and older versions do not support
Here's an example:
// First, get and initialize the converter var converter = Components.classes["@mozilla.org/intl/scriptableunicodeconverter"] .createInstance(Components.interfaces.nsIScriptableUnicodeConverter); converter.charset = /* The charset you want, using UTF-8 for this example */ "UTF-8";
Now you can convert and write to the stream:
// This code assumes that os is your nsIOutputStream // your_string here is the string you want to write. var chunk = converter.ConvertFromUnicode(your_string); os.write(chunk, chunk.length); // Repeat as needed for further strings
At the end, you need to call
Finish and write its data to the stream.
Note that not many character sets need it, but for those that do calling this is important
for proper output.
var fin = converter.Finish(); os.write(fin, fin.length); os.close();
Converting a string into a stream
Sometimes, it is useful to convert a string into a stream, for example for uploading it using
The example here requires Gecko 1.8 (Firefox 1.1, SeaMonkey 1.0).
nsIScriptableUnicodeConverter has a simple method to do that:
// First, get and initialize the converter var converter = Components.classes["@mozilla.org/intl/scriptableunicodeconverter"] .createInstance(Components.interfaces.nsIScriptableUnicodeConverter); converter.charset = /* The charset you want to use. Using UTF-8 in this example */ "UTF-8";
// Now, convert a string to an nsIInputStream var stream = converter.convertToInputStream("A string with non-ASCII characters: \u00FC \u05D0\n"); // stream can now be used as an nsIInputStream