PageRenderTime 268ms CodeModel.GetById 141ms app.highlight 17ms RepoModel.GetById 66ms app.codeStats 38ms

/gecko_api/include/nsXPCOMStrings.h

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