1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4  * License, v. 2.0. If a copy of the MPL was not distributed with this
5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 
7 #ifndef nsXPCOMStrings_h__
8 #define nsXPCOMStrings_h__
9 
10 #include <string.h>
11 #include "nscore.h"
12 #include <limits>
13 
14 /**
15  * nsXPCOMStrings.h
16  *
17  * This file describes a minimal API for working with XPCOM's abstract
18  * string classes.  It divorces the consumer from having any run-time
19  * dependency on the implementation details of the abstract string types.
20  */
21 
22 #include "nscore.h"
23 
24 /* The base string types */
25 class nsAString;
26 class nsACString;
27 
28 /* ------------------------------------------------------------------------- */
29 
30 /**
31  * nsStringContainer
32  *
33  * This is an opaque data type that is large enough to hold the canonical
34  * implementation of nsAString.  The binary structure of this class is an
35  * implementation detail.
36  *
37  * The string data stored in a string container is always single fragment
38  * and may be null-terminated depending on how it is initialized.
39  *
40  * Typically, string containers are allocated on the stack for temporary
41  * use.  However, they can also be malloc'd if necessary.  In either case,
42  * a string container is not useful until it has been initialized with a
43  * call to NS_StringContainerInit.  The following example shows how to use
44  * a string container to call a function that takes a |nsAString &| out-param.
45  *
46  *   nsresult GetBlah(nsAString &aBlah);
47  *
48  *   nsresult MyCode()
49  *   {
50  *     nsresult rv;
51  *
52  *     nsStringContainer sc;
53  *     rv = NS_StringContainerInit(sc);
54  *     if (NS_FAILED(rv))
55  *       return rv;
56  *
57  *     rv = GetBlah(sc);
58  *     if (NS_SUCCEEDED(rv))
59  *     {
60  *       const char16_t *data;
61  *       NS_StringGetData(sc, &data);
62  *       //
63  *       // |data| now points to the result of the GetBlah function
64  *       //
65  *     }
66  *
67  *     NS_StringContainerFinish(sc);
68  *     return rv;
69  *   }
70  *
71  * The following example show how to use a string container to pass a string
72  * parameter to a function taking a |const nsAString &| in-param.
73  *
74  *   nsresult SetBlah(const nsAString &aBlah);
75  *
76  *   nsresult MyCode()
77  *   {
78  *     nsresult rv;
79  *
80  *     nsStringContainer sc;
81  *     rv = NS_StringContainerInit(sc);
82  *     if (NS_FAILED(rv))
83  *       return rv;
84  *
85  *     const char16_t kData[] = {'x','y','z','\0'};
86  *     rv = NS_StringSetData(sc, kData, sizeof(kData)/2 - 1);
87  *     if (NS_SUCCEEDED(rv))
88  *       rv = SetBlah(sc);
89  *
90  *     NS_StringContainerFinish(sc);
91  *     return rv;
92  *   }
93  */
94 class nsStringContainer;
95 
96 
97 /**
98  * This struct is never used directly. It is designed to have the same
99  * size as nsString. It can be stack and heap allocated and the internal
100  * functions cast it to nsString.
101  * While this practice is a strict aliasing violation, it doesn't seem to
102  * cause problems since the the struct is only accessed via the casts to
103  * nsString.
104  * We use protected instead of private to avoid compiler warnings about
105  * the members being unused.
106  */
107 struct nsStringContainer_base
108 {
109 protected:
110   void* d1;
111   uint32_t d2;
112   uint32_t d3;
113 };
114 
115 /**
116  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
117  */
118 enum
119 {
120   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
121    * string references the passed in data pointer directly.  The caller must
122    * ensure that the data is valid for the lifetime of the string container.
123    * This flag should not be combined with NS_STRING_CONTAINER_INIT_ADOPT. */
124   NS_STRING_CONTAINER_INIT_DEPEND    = (1 << 1),
125 
126   /* Data passed into NS_StringContainerInit2 is not copied; instead, the
127    * string takes ownership over the data pointer.  The caller must have
128    * allocated the data array using the XPCOM memory allocator (nsMemory).
129    * This flag should not be combined with NS_STRING_CONTAINER_INIT_DEPEND. */
130   NS_STRING_CONTAINER_INIT_ADOPT     = (1 << 2),
131 
132   /* Data passed into NS_StringContainerInit2 is a substring that is not
133    * null-terminated. */
134   NS_STRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
135 };
136 
137 /**
138  * NS_StringContainerInit
139  *
140  * @param aContainer    string container reference
141  * @return              NS_OK if string container successfully initialized
142  *
143  * This function may allocate additional memory for aContainer.  When
144  * aContainer is no longer needed, NS_StringContainerFinish should be called.
145  */
146 XPCOM_API(nsresult) NS_StringContainerInit(nsStringContainer& aContainer);
147 
148 /**
149  * NS_StringContainerInit2
150  *
151  * @param aContainer    string container reference
152  * @param aData         character buffer (may be null)
153  * @param aDataLength   number of characters stored at aData (may pass
154  *                      UINT32_MAX if aData is null-terminated)
155  * @param aFlags        flags affecting how the string container is
156  *                      initialized.  this parameter is ignored when aData
157  *                      is null.  otherwise, if this parameter is 0, then
158  *                      aData is copied into the string.
159  *
160  * This function resembles NS_StringContainerInit but provides further
161  * options that permit more efficient memory usage.  When aContainer is
162  * no longer needed, NS_StringContainerFinish should be called.
163  *
164  * NOTE: NS_StringContainerInit2(container, nullptr, 0, 0) is equivalent to
165  * NS_StringContainerInit(container).
166  */
167 XPCOM_API(nsresult) NS_StringContainerInit2(nsStringContainer& aContainer,
168                                             const char16_t* aData = nullptr,
169                                             uint32_t aDataLength = UINT32_MAX,
170                                             uint32_t aFlags = 0);
171 
172 /**
173  * NS_StringContainerFinish
174  *
175  * @param aContainer    string container reference
176  *
177  * This function frees any memory owned by aContainer.
178  */
179 XPCOM_API(void) NS_StringContainerFinish(nsStringContainer& aContainer);
180 
181 /* ------------------------------------------------------------------------- */
182 
183 /**
184  * NS_StringGetData
185  *
186  * This function returns a const character pointer to the string's internal
187  * buffer, the length of the string, and a boolean value indicating whether
188  * or not the buffer is null-terminated.
189  *
190  * @param aStr          abstract string reference
191  * @param aData         out param that will hold the address of aStr's
192  *                      internal buffer
193  * @param aTerminated   if non-null, this out param will be set to indicate
194  *                      whether or not aStr's internal buffer is null-
195  *                      terminated
196  * @return              length of aStr's internal buffer
197  */
198 XPCOM_API(uint32_t) NS_StringGetData(const nsAString& aStr,
199                                      const char16_t** aData,
200                                      bool* aTerminated = nullptr);
201 
202 /**
203  * NS_StringGetMutableData
204  *
205  * This function provides mutable access to a string's internal buffer.  It
206  * returns a pointer to an array of characters that may be modified.  The
207  * returned pointer remains valid until the string object is passed to some
208  * other string function.
209  *
210  * Optionally, this function may be used to resize the string's internal
211  * buffer.  The aDataLength parameter specifies the requested length of the
212  * string's internal buffer.  By passing some value other than UINT32_MAX,
213  * the caller can request that the buffer be resized to the specified number of
214  * characters before returning.  The caller is not responsible for writing a
215  * null-terminator.
216  *
217  * @param aStr          abstract string reference
218  * @param aDataLength   number of characters to resize the string's internal
219  *                      buffer to or UINT32_MAX if no resizing is needed
220  * @param aData         out param that upon return holds the address of aStr's
221  *                      internal buffer or null if the function failed
222  * @return              number of characters or zero if the function failed
223  *
224  * This function does not necessarily null-terminate aStr after resizing its
225  * internal buffer.  The behavior depends on the implementation of the abstract
226  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
227  * will be null-terminated by this function.
228  */
229 XPCOM_API(uint32_t) NS_StringGetMutableData(nsAString& aStr,
230                                             uint32_t aDataLength,
231                                             char16_t** aData);
232 
233 /**
234  * NS_StringCloneData
235  *
236  * This function returns a null-terminated copy of the string's
237  * internal buffer.
238  *
239  * @param aStr          abstract string reference
240  * @return              null-terminated copy of the string's internal buffer
241  *                      (it must be free'd using using free)
242  */
243 XPCOM_API(char16_t*) NS_StringCloneData(const nsAString& aStr);
244 
245 /**
246  * NS_StringSetData
247  *
248  * This function copies aData into aStr.
249  *
250  * @param aStr          abstract string reference
251  * @param aData         character buffer
252  * @param aDataLength   number of characters to copy from source string (pass
253  *                      UINT32_MAX to copy until end of aData, designated by
254  *                      a null character)
255  * @return              NS_OK if function succeeded
256  *
257  * This function does not necessarily null-terminate aStr after copying data
258  * from aData.  The behavior depends on the implementation of the abstract
259  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
260  * will be null-terminated by this function.
261  */
262 XPCOM_API(nsresult) NS_StringSetData(nsAString& aStr, const char16_t* aData,
263                                      uint32_t aDataLength = UINT32_MAX);
264 
265 /**
266  * NS_StringSetDataRange
267  *
268  * This function copies aData into a section of aStr.  As a result it can be
269  * used to insert new characters into the string.
270  *
271  * @param aStr          abstract string reference
272  * @param aCutOffset    starting index where the string's existing data
273  *                      is to be overwritten (pass UINT32_MAX to cause
274  *                      aData to be appended to the end of aStr, in which
275  *                      case the value of aCutLength is ignored).
276  * @param aCutLength    number of characters to overwrite starting at
277  *                      aCutOffset (pass UINT32_MAX to overwrite until the
278  *                      end of aStr).
279  * @param aData         character buffer (pass null to cause this function
280  *                      to simply remove the "cut" range)
281  * @param aDataLength   number of characters to copy from source string (pass
282  *                      UINT32_MAX to copy until end of aData, designated by
283  *                      a null character)
284  * @return              NS_OK if function succeeded
285  *
286  * This function does not necessarily null-terminate aStr after copying data
287  * from aData.  The behavior depends on the implementation of the abstract
288  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
289  * will be null-terminated by this function.
290  */
291 XPCOM_API(nsresult) NS_StringSetDataRange(nsAString& aStr,
292                                           uint32_t aCutOffset, uint32_t aCutLength,
293                                           const char16_t* aData,
294                                           uint32_t aDataLength = UINT32_MAX);
295 
296 /**
297  * NS_StringCopy
298  *
299  * This function makes aDestStr have the same value as aSrcStr.  It is
300  * provided as an optimization.
301  *
302  * @param aDestStr      abstract string reference to be modified
303  * @param aSrcStr       abstract string reference containing source string
304  * @return              NS_OK if function succeeded
305  *
306  * This function does not necessarily null-terminate aDestStr after copying
307  * data from aSrcStr.  The behavior depends on the implementation of the
308  * abstract string, aDestStr.  If aDestStr is a reference to a
309  * nsStringContainer, then its data will be null-terminated by this function.
310  */
311 XPCOM_API(nsresult) NS_StringCopy(nsAString& aDestStr,
312                                   const nsAString& aSrcStr);
313 
314 /**
315  * NS_StringAppendData
316  *
317  * This function appends data to the existing value of aStr.
318  *
319  * @param aStr          abstract string reference to be modified
320  * @param aData         character buffer
321  * @param aDataLength   number of characters to append (pass UINT32_MAX to
322  *                      append until a null-character is encountered)
323  * @return              NS_OK if function succeeded
324  *
325  * This function does not necessarily null-terminate aStr upon completion.
326  * The behavior depends on the implementation of the abstract string, aStr.
327  * If aStr is a reference to a nsStringContainer, then its data will be null-
328  * terminated by this function.
329  */
330 inline NS_HIDDEN_(nsresult)
331 NS_StringAppendData(nsAString& aStr, const char16_t* aData,
332                     uint32_t aDataLength = UINT32_MAX)
333 {
334   return NS_StringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength);
335 }
336 
337 /**
338  * NS_StringInsertData
339  *
340  * This function inserts data into the existing value of aStr at the specified
341  * offset.
342  *
343  * @param aStr          abstract string reference to be modified
344  * @param aOffset       specifies where in the string to insert aData
345  * @param aData         character buffer
346  * @param aDataLength   number of characters to append (pass UINT32_MAX to
347  *                      append until a null-character is encountered)
348  * @return              NS_OK if function succeeded
349  *
350  * This function does not necessarily null-terminate aStr upon completion.
351  * The behavior depends on the implementation of the abstract string, aStr.
352  * If aStr is a reference to a nsStringContainer, then its data will be null-
353  * terminated by this function.
354  */
355 inline NS_HIDDEN_(nsresult)
356 NS_StringInsertData(nsAString& aStr, uint32_t aOffset, const char16_t* aData,
357                     uint32_t aDataLength = UINT32_MAX)
358 {
359   return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
360 }
361 
362 /**
363  * NS_StringCutData
364  *
365  * This function shortens the existing value of aStr, by removing characters
366  * at the specified offset.
367  *
368  * @param aStr          abstract string reference to be modified
369  * @param aCutOffset    specifies where in the string to insert aData
370  * @param aCutLength    number of characters to remove
371  * @return              NS_OK if function succeeded
372  */
373 inline NS_HIDDEN_(nsresult)
NS_StringCutData(nsAString & aStr,uint32_t aCutOffset,uint32_t aCutLength)374 NS_StringCutData(nsAString& aStr, uint32_t aCutOffset, uint32_t aCutLength)
375 {
376   return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0);
377 }
378 
379 /**
380  * NS_StringSetIsVoid
381  *
382  * This function marks a string as being a "void string".  Any data in the
383  * string will be lost.
384  */
385 XPCOM_API(void) NS_StringSetIsVoid(nsAString& aStr, const bool aIsVoid);
386 
387 /**
388  * NS_StringGetIsVoid
389  *
390  * This function provides a way to test if a string is a "void string", as
391  * marked by NS_StringSetIsVoid.
392  */
393 XPCOM_API(bool) NS_StringGetIsVoid(const nsAString& aStr);
394 
395 /* ------------------------------------------------------------------------- */
396 
397 /**
398  * nsCStringContainer
399  *
400  * This is an opaque data type that is large enough to hold the canonical
401  * implementation of nsACString.  The binary structure of this class is an
402  * implementation detail.
403  *
404  * The string data stored in a string container is always single fragment
405  * and may be null-terminated depending on how it is initialized.
406  *
407  * @see nsStringContainer for use cases and further documentation.
408  */
409 class nsCStringContainer;
410 
411 /**
412  * Flags that may be OR'd together to pass to NS_StringContainerInit2:
413  */
414 enum
415 {
416   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
417    * string references the passed in data pointer directly.  The caller must
418    * ensure that the data is valid for the lifetime of the string container.
419    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
420   NS_CSTRING_CONTAINER_INIT_DEPEND    = (1 << 1),
421 
422   /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
423    * string takes ownership over the data pointer.  The caller must have
424    * allocated the data array using the XPCOM memory allocator (nsMemory).
425    * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
426   NS_CSTRING_CONTAINER_INIT_ADOPT     = (1 << 2),
427 
428   /* Data passed into NS_CStringContainerInit2 is a substring that is not
429    * null-terminated. */
430   NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
431 };
432 
433 /**
434  * NS_CStringContainerInit
435  *
436  * @param aContainer    string container reference
437  * @return              NS_OK if string container successfully initialized
438  *
439  * This function may allocate additional memory for aContainer.  When
440  * aContainer is no longer needed, NS_CStringContainerFinish should be called.
441  */
442 XPCOM_API(nsresult) NS_CStringContainerInit(nsCStringContainer& aContainer);
443 
444 /**
445  * NS_CStringContainerInit2
446  *
447  * @param aContainer    string container reference
448  * @param aData         character buffer (may be null)
449  * @param aDataLength   number of characters stored at aData (may pass
450  *                      UINT32_MAX if aData is null-terminated)
451  * @param aFlags        flags affecting how the string container is
452  *                      initialized.  this parameter is ignored when aData
453  *                      is null.  otherwise, if this parameter is 0, then
454  *                      aData is copied into the string.
455  *
456  * This function resembles NS_CStringContainerInit but provides further
457  * options that permit more efficient memory usage.  When aContainer is
458  * no longer needed, NS_CStringContainerFinish should be called.
459  *
460  * NOTE: NS_CStringContainerInit2(container, nullptr, 0, 0) is equivalent to
461  * NS_CStringContainerInit(container).
462  */
463 XPCOM_API(nsresult) NS_CStringContainerInit2(nsCStringContainer& aContainer,
464                                              const char* aData = nullptr,
465                                              uint32_t aDataLength = UINT32_MAX,
466                                              uint32_t aFlags = 0);
467 
468 /**
469  * NS_CStringContainerFinish
470  *
471  * @param aContainer    string container reference
472  *
473  * This function frees any memory owned by aContainer.
474  */
475 XPCOM_API(void) NS_CStringContainerFinish(nsCStringContainer& aContainer);
476 
477 /* ------------------------------------------------------------------------- */
478 
479 /**
480  * NS_CStringGetData
481  *
482  * This function returns a const character pointer to the string's internal
483  * buffer, the length of the string, and a boolean value indicating whether
484  * or not the buffer is null-terminated.
485  *
486  * @param aStr          abstract string reference
487  * @param aData         out param that will hold the address of aStr's
488  *                      internal buffer
489  * @param aTerminated   if non-null, this out param will be set to indicate
490  *                      whether or not aStr's internal buffer is null-
491  *                      terminated
492  * @return              length of aStr's internal buffer
493  */
494 XPCOM_API(uint32_t) NS_CStringGetData(const nsACString& aStr,
495                                       const char** aData,
496                                       bool* aTerminated = nullptr);
497 
498 /**
499  * NS_CStringGetMutableData
500  *
501  * This function provides mutable access to a string's internal buffer.  It
502  * returns a pointer to an array of characters that may be modified.  The
503  * returned pointer remains valid until the string object is passed to some
504  * other string function.
505  *
506  * Optionally, this function may be used to resize the string's internal
507  * buffer.  The aDataLength parameter specifies the requested length of the
508  * string's internal buffer.  By passing some value other than UINT32_MAX,
509  * the caller can request that the buffer be resized to the specified number of
510  * characters before returning.  The caller is not responsible for writing a
511  * null-terminator.
512  *
513  * @param aStr          abstract string reference
514  * @param aDataLength   number of characters to resize the string's internal
515  *                      buffer to or UINT32_MAX if no resizing is needed
516  * @param aData         out param that upon return holds the address of aStr's
517  *                      internal buffer or null if the function failed
518  * @return              number of characters or zero if the function failed
519  *
520  * This function does not necessarily null-terminate aStr after resizing its
521  * internal buffer.  The behavior depends on the implementation of the abstract
522  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
523  * will be null-terminated by this function.
524  */
525 XPCOM_API(uint32_t) NS_CStringGetMutableData(nsACString& aStr,
526                                              uint32_t aDataLength,
527                                              char** aData);
528 
529 /**
530  * NS_CStringCloneData
531  *
532  * This function returns a null-terminated copy of the string's
533  * internal buffer.
534  *
535  * @param aStr          abstract string reference
536  * @return              null-terminated copy of the string's internal buffer
537  *                      (it must be free'd using using free)
538  */
539 XPCOM_API(char*) NS_CStringCloneData(const nsACString& aStr);
540 
541 /**
542  * NS_CStringSetData
543  *
544  * This function copies aData into aStr.
545  *
546  * @param aStr          abstract string reference
547  * @param aData         character buffer
548  * @param aDataLength   number of characters to copy from source string (pass
549  *                      UINT32_MAX to copy until end of aData, designated by
550  *                      a null character)
551  * @return              NS_OK if function succeeded
552  *
553  * This function does not necessarily null-terminate aStr after copying data
554  * from aData.  The behavior depends on the implementation of the abstract
555  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
556  * will be null-terminated by this function.
557  */
558 XPCOM_API(nsresult) NS_CStringSetData(nsACString& aStr, const char* aData,
559                                       uint32_t aDataLength = UINT32_MAX);
560 
561 /**
562  * NS_CStringSetDataRange
563  *
564  * This function copies aData into a section of aStr.  As a result it can be
565  * used to insert new characters into the string.
566  *
567  * @param aStr          abstract string reference
568  * @param aCutOffset    starting index where the string's existing data
569  *                      is to be overwritten (pass UINT32_MAX to cause
570  *                      aData to be appended to the end of aStr, in which
571  *                      case the value of aCutLength is ignored).
572  * @param aCutLength    number of characters to overwrite starting at
573  *                      aCutOffset (pass UINT32_MAX to overwrite until the
574  *                      end of aStr).
575  * @param aData         character buffer (pass null to cause this function
576  *                      to simply remove the "cut" range)
577  * @param aDataLength   number of characters to copy from source string (pass
578  *                      UINT32_MAX to copy until end of aData, designated by
579  *                      a null character)
580  * @return              NS_OK if function succeeded
581  *
582  * This function does not necessarily null-terminate aStr after copying data
583  * from aData.  The behavior depends on the implementation of the abstract
584  * string, aStr.  If aStr is a reference to a nsStringContainer, then its data
585  * will be null-terminated by this function.
586  */
587 XPCOM_API(nsresult) NS_CStringSetDataRange(nsACString& aStr,
588                                            uint32_t aCutOffset,
589                                            uint32_t aCutLength,
590                                            const char* aData,
591                                            uint32_t aDataLength = UINT32_MAX);
592 
593 /**
594  * NS_CStringCopy
595  *
596  * This function makes aDestStr have the same value as aSrcStr.  It is
597  * provided as an optimization.
598  *
599  * @param aDestStr      abstract string reference to be modified
600  * @param aSrcStr       abstract string reference containing source string
601  * @return              NS_OK if function succeeded
602  *
603  * This function does not necessarily null-terminate aDestStr after copying
604  * data from aSrcStr.  The behavior depends on the implementation of the
605  * abstract string, aDestStr.  If aDestStr is a reference to a
606  * nsStringContainer, then its data will be null-terminated by this function.
607  */
608 XPCOM_API(nsresult) NS_CStringCopy(nsACString& aDestStr,
609                                    const nsACString& aSrcStr);
610 
611 /**
612  * NS_CStringAppendData
613  *
614  * This function appends data to the existing value of aStr.
615  *
616  * @param aStr          abstract string reference to be modified
617  * @param aData         character buffer
618  * @param aDataLength   number of characters to append (pass UINT32_MAX to
619  *                      append until a null-character is encountered)
620  * @return              NS_OK if function succeeded
621  *
622  * This function does not necessarily null-terminate aStr upon completion.
623  * The behavior depends on the implementation of the abstract string, aStr.
624  * If aStr is a reference to a nsStringContainer, then its data will be null-
625  * terminated by this function.
626  */
627 inline NS_HIDDEN_(nsresult)
628 NS_CStringAppendData(nsACString& aStr, const char* aData,
629                      uint32_t aDataLength = UINT32_MAX)
630 {
631   return NS_CStringSetDataRange(aStr, UINT32_MAX, 0, aData, aDataLength);
632 }
633 
634 /**
635  * NS_CStringInsertData
636  *
637  * This function inserts data into the existing value of aStr at the specified
638  * offset.
639  *
640  * @param aStr          abstract string reference to be modified
641  * @param aOffset       specifies where in the string to insert aData
642  * @param aData         character buffer
643  * @param aDataLength   number of characters to append (pass UINT32_MAX to
644  *                      append until a null-character is encountered)
645  * @return              NS_OK if function succeeded
646  *
647  * This function does not necessarily null-terminate aStr upon completion.
648  * The behavior depends on the implementation of the abstract string, aStr.
649  * If aStr is a reference to a nsStringContainer, then its data will be null-
650  * terminated by this function.
651  */
652 inline NS_HIDDEN_(nsresult)
653 NS_CStringInsertData(nsACString& aStr, uint32_t aOffset, const char* aData,
654                      uint32_t aDataLength = UINT32_MAX)
655 {
656   return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
657 }
658 
659 /**
660  * NS_CStringCutData
661  *
662  * This function shortens the existing value of aStr, by removing characters
663  * at the specified offset.
664  *
665  * @param aStr          abstract string reference to be modified
666  * @param aCutOffset    specifies where in the string to insert aData
667  * @param aCutLength    number of characters to remove
668  * @return              NS_OK if function succeeded
669  */
670 inline NS_HIDDEN_(nsresult)
NS_CStringCutData(nsACString & aStr,uint32_t aCutOffset,uint32_t aCutLength)671 NS_CStringCutData(nsACString& aStr, uint32_t aCutOffset, uint32_t aCutLength)
672 {
673   return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nullptr, 0);
674 }
675 
676 /**
677  * NS_CStringSetIsVoid
678  *
679  * This function marks a string as being a "void string".  Any data in the
680  * string will be lost.
681  */
682 XPCOM_API(void) NS_CStringSetIsVoid(nsACString& aStr, const bool aIsVoid);
683 
684 /**
685  * NS_CStringGetIsVoid
686  *
687  * This function provides a way to test if a string is a "void string", as
688  * marked by NS_CStringSetIsVoid.
689  */
690 XPCOM_API(bool) NS_CStringGetIsVoid(const nsACString& aStr);
691 
692 /* ------------------------------------------------------------------------- */
693 
694 /**
695  * Encodings that can be used with the following conversion routines.
696  */
697 enum nsCStringEncoding
698 {
699   /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
700    * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
701    * bytes.  Reverse conversion is done by truncating every other byte.  The
702    * conversion may result in loss and/or corruption of information if the
703    * strings do not strictly contain ASCII data. */
704   NS_CSTRING_ENCODING_ASCII = 0,
705 
706   /* Conversion between UTF-8 and UTF-16 is non-lossy. */
707   NS_CSTRING_ENCODING_UTF8 = 1,
708 
709   /* Conversion from UTF-16 to the native filesystem charset may result in a
710    * loss of information.  No attempt is made to protect against data loss in
711    * this case.  The native filesystem charset applies to strings passed to
712    * the "Native" method variants on nsIFile. */
713   NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
714 };
715 
716 /**
717  * NS_CStringToUTF16
718  *
719  * This function converts the characters in a nsACString to an array of UTF-16
720  * characters, in the platform endianness.  The result is stored in a nsAString
721  * object.
722  *
723  * @param aSource       abstract string reference containing source string
724  * @param aSrcEncoding  character encoding of the source string
725  * @param aDest         abstract string reference to hold the result
726  */
727 XPCOM_API(nsresult) NS_CStringToUTF16(const nsACString& aSource,
728                                       nsCStringEncoding aSrcEncoding,
729                                       nsAString& aDest);
730 
731 /**
732  * NS_UTF16ToCString
733  *
734  * This function converts the UTF-16 characters in a nsAString to a single-byte
735  * encoding.  The result is stored in a nsACString object.  In some cases this
736  * conversion may be lossy.  In such cases, the conversion may succeed with a
737  * return code indicating loss of information.  The exact behavior is not
738  * specified at this time.
739  *
740  * @param aSource       abstract string reference containing source string
741  * @param aDestEncoding character encoding of the resulting string
742  * @param aDest         abstract string reference to hold the result
743  */
744 XPCOM_API(nsresult) NS_UTF16ToCString(const nsAString& aSource,
745                                       nsCStringEncoding aDestEncoding,
746                                       nsACString& aDest);
747 
748 #endif // nsXPCOMStrings_h__
749