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 */
83 : class nsAString;
84 : class 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 : */
152 : class nsStringContainer;
153 :
154 : struct nsStringContainer_base
155 22346 : {
156 : private:
157 : void *d1;
158 : PRUint32 d2;
159 : PRUint32 d3;
160 : };
161 :
162 : /**
163 : * Flags that may be OR'd together to pass to NS_StringContainerInit2:
164 : */
165 : enum {
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 : XPCOM_API(nsresult)
193 : NS_StringContainerInit(nsStringContainer &aContainer);
194 :
195 : /**
196 : * NS_StringContainerInit2
197 : *
198 : * @param aContainer string container reference
199 : * @param aData character buffer (may be null)
200 : * @param aDataLength number of characters stored at aData (may pass
201 : * PR_UINT32_MAX if aData is null-terminated)
202 : * @param aFlags flags affecting how the string container is
203 : * initialized. this parameter is ignored when aData
204 : * is null. otherwise, if this parameter is 0, then
205 : * aData is copied into the string.
206 : *
207 : * This function resembles NS_StringContainerInit but provides further
208 : * options that permit more efficient memory usage. When aContainer is
209 : * no longer needed, NS_StringContainerFinish should be called.
210 : *
211 : * NOTE: NS_StringContainerInit2(container, nsnull, 0, 0) is equivalent to
212 : * NS_StringContainerInit(container).
213 : */
214 : XPCOM_API(nsresult)
215 : NS_StringContainerInit2
216 : (nsStringContainer &aContainer, const PRUnichar *aData = nsnull,
217 : PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
218 :
219 : /**
220 : * NS_StringContainerFinish
221 : *
222 : * @param aContainer string container reference
223 : *
224 : * This function frees any memory owned by aContainer.
225 : */
226 : XPCOM_API(void)
227 : NS_StringContainerFinish(nsStringContainer &aContainer);
228 :
229 : /* ------------------------------------------------------------------------- */
230 :
231 : /**
232 : * NS_StringGetData
233 : *
234 : * This function returns a const character pointer to the string's internal
235 : * buffer, the length of the string, and a boolean value indicating whether
236 : * or not the buffer is null-terminated.
237 : *
238 : * @param aStr abstract string reference
239 : * @param aData out param that will hold the address of aStr's
240 : * internal buffer
241 : * @param aTerminated if non-null, this out param will be set to indicate
242 : * whether or not aStr's internal buffer is null-
243 : * terminated
244 : * @return length of aStr's internal buffer
245 : */
246 : XPCOM_API(PRUint32)
247 : NS_StringGetData
248 : (const nsAString &aStr, const PRUnichar **aData,
249 : bool *aTerminated = nsnull);
250 :
251 : /**
252 : * NS_StringGetMutableData
253 : *
254 : * This function provides mutable access to a string's internal buffer. It
255 : * returns a pointer to an array of characters that may be modified. The
256 : * returned pointer remains valid until the string object is passed to some
257 : * other string function.
258 : *
259 : * Optionally, this function may be used to resize the string's internal
260 : * buffer. The aDataLength parameter specifies the requested length of the
261 : * string's internal buffer. By passing some value other than PR_UINT32_MAX,
262 : * the caller can request that the buffer be resized to the specified number of
263 : * characters before returning. The caller is not responsible for writing a
264 : * null-terminator.
265 : *
266 : * @param aStr abstract string reference
267 : * @param aDataLength number of characters to resize the string's internal
268 : * buffer to or PR_UINT32_MAX if no resizing is needed
269 : * @param aData out param that upon return holds the address of aStr's
270 : * internal buffer or null if the function failed
271 : * @return number of characters or zero if the function failed
272 : *
273 : * This function does not necessarily null-terminate aStr after resizing its
274 : * internal buffer. The behavior depends on the implementation of the abstract
275 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
276 : * will be null-terminated by this function.
277 : */
278 : XPCOM_API(PRUint32)
279 : NS_StringGetMutableData
280 : (nsAString &aStr, PRUint32 aDataLength, PRUnichar **aData);
281 :
282 : /**
283 : * NS_StringCloneData
284 : *
285 : * This function returns a null-terminated copy of the string's
286 : * internal buffer.
287 : *
288 : * @param aStr abstract string reference
289 : * @return null-terminated copy of the string's internal buffer
290 : * (it must be free'd using using nsMemory::Free)
291 : */
292 : XPCOM_API(PRUnichar *)
293 : NS_StringCloneData
294 : (const nsAString &aStr);
295 :
296 : /**
297 : * NS_StringSetData
298 : *
299 : * This function copies aData into aStr.
300 : *
301 : * @param aStr abstract string reference
302 : * @param aData character buffer
303 : * @param aDataLength number of characters to copy from source string (pass
304 : * PR_UINT32_MAX to copy until end of aData, designated by
305 : * a null character)
306 : * @return NS_OK if function succeeded
307 : *
308 : * This function does not necessarily null-terminate aStr after copying data
309 : * from aData. The behavior depends on the implementation of the abstract
310 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
311 : * will be null-terminated by this function.
312 : */
313 : XPCOM_API(nsresult)
314 : NS_StringSetData
315 : (nsAString &aStr, const PRUnichar *aData,
316 : PRUint32 aDataLength = PR_UINT32_MAX);
317 :
318 : /**
319 : * NS_StringSetDataRange
320 : *
321 : * This function copies aData into a section of aStr. As a result it can be
322 : * used to insert new characters into the string.
323 : *
324 : * @param aStr abstract string reference
325 : * @param aCutOffset starting index where the string's existing data
326 : * is to be overwritten (pass PR_UINT32_MAX to cause
327 : * aData to be appended to the end of aStr, in which
328 : * case the value of aCutLength is ignored).
329 : * @param aCutLength number of characters to overwrite starting at
330 : * aCutOffset (pass PR_UINT32_MAX to overwrite until the
331 : * end of aStr).
332 : * @param aData character buffer (pass null to cause this function
333 : * to simply remove the "cut" range)
334 : * @param aDataLength number of characters to copy from source string (pass
335 : * PR_UINT32_MAX to copy until end of aData, designated by
336 : * a null character)
337 : * @return NS_OK if function succeeded
338 : *
339 : * This function does not necessarily null-terminate aStr after copying data
340 : * from aData. The behavior depends on the implementation of the abstract
341 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
342 : * will be null-terminated by this function.
343 : */
344 : XPCOM_API(nsresult)
345 : NS_StringSetDataRange
346 : (nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
347 : const PRUnichar *aData, PRUint32 aDataLength = PR_UINT32_MAX);
348 :
349 : /**
350 : * NS_StringCopy
351 : *
352 : * This function makes aDestStr have the same value as aSrcStr. It is
353 : * provided as an optimization.
354 : *
355 : * @param aDestStr abstract string reference to be modified
356 : * @param aSrcStr abstract string reference containing source string
357 : * @return NS_OK if function succeeded
358 : *
359 : * This function does not necessarily null-terminate aDestStr after copying
360 : * data from aSrcStr. The behavior depends on the implementation of the
361 : * abstract string, aDestStr. If aDestStr is a reference to a
362 : * nsStringContainer, then its data will be null-terminated by this function.
363 : */
364 : XPCOM_API(nsresult)
365 : NS_StringCopy
366 : (nsAString &aDestStr, const nsAString &aSrcStr);
367 :
368 : /**
369 : * NS_StringAppendData
370 : *
371 : * This function appends data to the existing value of aStr.
372 : *
373 : * @param aStr abstract string reference to be modified
374 : * @param aData character buffer
375 : * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
376 : * append until a null-character is encountered)
377 : * @return NS_OK if function succeeded
378 : *
379 : * This function does not necessarily null-terminate aStr upon completion.
380 : * The behavior depends on the implementation of the abstract string, aStr.
381 : * If aStr is a reference to a nsStringContainer, then its data will be null-
382 : * terminated by this function.
383 : */
384 : inline NS_HIDDEN_(nsresult)
385 : NS_StringAppendData(nsAString &aStr, const PRUnichar *aData,
386 : PRUint32 aDataLength = PR_UINT32_MAX)
387 : {
388 : return NS_StringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
389 : }
390 :
391 : /**
392 : * NS_StringInsertData
393 : *
394 : * This function inserts data into the existing value of aStr at the specified
395 : * offset.
396 : *
397 : * @param aStr abstract string reference to be modified
398 : * @param aOffset specifies where in the string to insert aData
399 : * @param aData character buffer
400 : * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
401 : * append until a null-character is encountered)
402 : * @return NS_OK if function succeeded
403 : *
404 : * This function does not necessarily null-terminate aStr upon completion.
405 : * The behavior depends on the implementation of the abstract string, aStr.
406 : * If aStr is a reference to a nsStringContainer, then its data will be null-
407 : * terminated by this function.
408 : */
409 : inline NS_HIDDEN_(nsresult)
410 : NS_StringInsertData(nsAString &aStr, PRUint32 aOffset, const PRUnichar *aData,
411 : PRUint32 aDataLength = PR_UINT32_MAX)
412 : {
413 : return NS_StringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
414 : }
415 :
416 : /**
417 : * NS_StringCutData
418 : *
419 : * This function shortens the existing value of aStr, by removing characters
420 : * at the specified offset.
421 : *
422 : * @param aStr abstract string reference to be modified
423 : * @param aCutOffset specifies where in the string to insert aData
424 : * @param aCutLength number of characters to remove
425 : * @return NS_OK if function succeeded
426 : */
427 : inline NS_HIDDEN_(nsresult)
428 0 : NS_StringCutData(nsAString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
429 : {
430 0 : return NS_StringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
431 : }
432 :
433 : /**
434 : * NS_StringSetIsVoid
435 : *
436 : * This function marks a string as being a "void string". Any data in the
437 : * string will be lost.
438 : */
439 : XPCOM_API(void)
440 : NS_StringSetIsVoid(nsAString& aStr, const bool aIsVoid);
441 :
442 : /**
443 : * NS_StringGetIsVoid
444 : *
445 : * This function provides a way to test if a string is a "void string", as
446 : * marked by NS_StringSetIsVoid.
447 : */
448 : XPCOM_API(bool)
449 : NS_StringGetIsVoid(const nsAString& aStr);
450 :
451 : /* ------------------------------------------------------------------------- */
452 :
453 : /**
454 : * nsCStringContainer
455 : *
456 : * This is an opaque data type that is large enough to hold the canonical
457 : * implementation of nsACString. The binary structure of this class is an
458 : * implementation detail.
459 : *
460 : * The string data stored in a string container is always single fragment
461 : * and may be null-terminated depending on how it is initialized.
462 : *
463 : * @see nsStringContainer for use cases and further documentation.
464 : */
465 : class nsCStringContainer;
466 :
467 : /**
468 : * Flags that may be OR'd together to pass to NS_StringContainerInit2:
469 : */
470 : enum {
471 : /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
472 : * string references the passed in data pointer directly. The caller must
473 : * ensure that the data is valid for the lifetime of the string container.
474 : * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_ADOPT. */
475 : NS_CSTRING_CONTAINER_INIT_DEPEND = (1 << 1),
476 :
477 : /* Data passed into NS_CStringContainerInit2 is not copied; instead, the
478 : * string takes ownership over the data pointer. The caller must have
479 : * allocated the data array using the XPCOM memory allocator (nsMemory).
480 : * This flag should not be combined with NS_CSTRING_CONTAINER_INIT_DEPEND. */
481 : NS_CSTRING_CONTAINER_INIT_ADOPT = (1 << 2),
482 :
483 : /* Data passed into NS_CStringContainerInit2 is a substring that is not
484 : * null-terminated. */
485 : NS_CSTRING_CONTAINER_INIT_SUBSTRING = (1 << 3)
486 : };
487 :
488 : /**
489 : * NS_CStringContainerInit
490 : *
491 : * @param aContainer string container reference
492 : * @return NS_OK if string container successfully initialized
493 : *
494 : * This function may allocate additional memory for aContainer. When
495 : * aContainer is no longer needed, NS_CStringContainerFinish should be called.
496 : */
497 : XPCOM_API(nsresult)
498 : NS_CStringContainerInit(nsCStringContainer &aContainer);
499 :
500 : /**
501 : * NS_CStringContainerInit2
502 : *
503 : * @param aContainer string container reference
504 : * @param aData character buffer (may be null)
505 : * @param aDataLength number of characters stored at aData (may pass
506 : * PR_UINT32_MAX if aData is null-terminated)
507 : * @param aFlags flags affecting how the string container is
508 : * initialized. this parameter is ignored when aData
509 : * is null. otherwise, if this parameter is 0, then
510 : * aData is copied into the string.
511 : *
512 : * This function resembles NS_CStringContainerInit but provides further
513 : * options that permit more efficient memory usage. When aContainer is
514 : * no longer needed, NS_CStringContainerFinish should be called.
515 : *
516 : * NOTE: NS_CStringContainerInit2(container, nsnull, 0, 0) is equivalent to
517 : * NS_CStringContainerInit(container).
518 : */
519 : XPCOM_API(nsresult)
520 : NS_CStringContainerInit2
521 : (nsCStringContainer &aContainer, const char *aData = nsnull,
522 : PRUint32 aDataLength = PR_UINT32_MAX, PRUint32 aFlags = 0);
523 :
524 : /**
525 : * NS_CStringContainerFinish
526 : *
527 : * @param aContainer string container reference
528 : *
529 : * This function frees any memory owned by aContainer.
530 : */
531 : XPCOM_API(void)
532 : NS_CStringContainerFinish(nsCStringContainer &aContainer);
533 :
534 : /* ------------------------------------------------------------------------- */
535 :
536 : /**
537 : * NS_CStringGetData
538 : *
539 : * This function returns a const character pointer to the string's internal
540 : * buffer, the length of the string, and a boolean value indicating whether
541 : * or not the buffer is null-terminated.
542 : *
543 : * @param aStr abstract string reference
544 : * @param aData out param that will hold the address of aStr's
545 : * internal buffer
546 : * @param aTerminated if non-null, this out param will be set to indicate
547 : * whether or not aStr's internal buffer is null-
548 : * terminated
549 : * @return length of aStr's internal buffer
550 : */
551 : XPCOM_API(PRUint32)
552 : NS_CStringGetData
553 : (const nsACString &aStr, const char **aData,
554 : bool *aTerminated = nsnull);
555 :
556 : /**
557 : * NS_CStringGetMutableData
558 : *
559 : * This function provides mutable access to a string's internal buffer. It
560 : * returns a pointer to an array of characters that may be modified. The
561 : * returned pointer remains valid until the string object is passed to some
562 : * other string function.
563 : *
564 : * Optionally, this function may be used to resize the string's internal
565 : * buffer. The aDataLength parameter specifies the requested length of the
566 : * string's internal buffer. By passing some value other than PR_UINT32_MAX,
567 : * the caller can request that the buffer be resized to the specified number of
568 : * characters before returning. The caller is not responsible for writing a
569 : * null-terminator.
570 : *
571 : * @param aStr abstract string reference
572 : * @param aDataLength number of characters to resize the string's internal
573 : * buffer to or PR_UINT32_MAX if no resizing is needed
574 : * @param aData out param that upon return holds the address of aStr's
575 : * internal buffer or null if the function failed
576 : * @return number of characters or zero if the function failed
577 : *
578 : * This function does not necessarily null-terminate aStr after resizing its
579 : * internal buffer. The behavior depends on the implementation of the abstract
580 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
581 : * will be null-terminated by this function.
582 : */
583 : XPCOM_API(PRUint32)
584 : NS_CStringGetMutableData
585 : (nsACString &aStr, PRUint32 aDataLength, char **aData);
586 :
587 : /**
588 : * NS_CStringCloneData
589 : *
590 : * This function returns a null-terminated copy of the string's
591 : * internal buffer.
592 : *
593 : * @param aStr abstract string reference
594 : * @return null-terminated copy of the string's internal buffer
595 : * (it must be free'd using using nsMemory::Free)
596 : */
597 : XPCOM_API(char *)
598 : NS_CStringCloneData
599 : (const nsACString &aStr);
600 :
601 : /**
602 : * NS_CStringSetData
603 : *
604 : * This function copies aData into aStr.
605 : *
606 : * @param aStr abstract string reference
607 : * @param aData character buffer
608 : * @param aDataLength number of characters to copy from source string (pass
609 : * PR_UINT32_MAX to copy until end of aData, designated by
610 : * a null character)
611 : * @return NS_OK if function succeeded
612 : *
613 : * This function does not necessarily null-terminate aStr after copying data
614 : * from aData. The behavior depends on the implementation of the abstract
615 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
616 : * will be null-terminated by this function.
617 : */
618 : XPCOM_API(nsresult)
619 : NS_CStringSetData
620 : (nsACString &aStr, const char *aData,
621 : PRUint32 aDataLength = PR_UINT32_MAX);
622 :
623 : /**
624 : * NS_CStringSetDataRange
625 : *
626 : * This function copies aData into a section of aStr. As a result it can be
627 : * used to insert new characters into the string.
628 : *
629 : * @param aStr abstract string reference
630 : * @param aCutOffset starting index where the string's existing data
631 : * is to be overwritten (pass PR_UINT32_MAX to cause
632 : * aData to be appended to the end of aStr, in which
633 : * case the value of aCutLength is ignored).
634 : * @param aCutLength number of characters to overwrite starting at
635 : * aCutOffset (pass PR_UINT32_MAX to overwrite until the
636 : * end of aStr).
637 : * @param aData character buffer (pass null to cause this function
638 : * to simply remove the "cut" range)
639 : * @param aDataLength number of characters to copy from source string (pass
640 : * PR_UINT32_MAX to copy until end of aData, designated by
641 : * a null character)
642 : * @return NS_OK if function succeeded
643 : *
644 : * This function does not necessarily null-terminate aStr after copying data
645 : * from aData. The behavior depends on the implementation of the abstract
646 : * string, aStr. If aStr is a reference to a nsStringContainer, then its data
647 : * will be null-terminated by this function.
648 : */
649 : XPCOM_API(nsresult)
650 : NS_CStringSetDataRange
651 : (nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength,
652 : const char *aData, PRUint32 aDataLength = PR_UINT32_MAX);
653 :
654 : /**
655 : * NS_CStringCopy
656 : *
657 : * This function makes aDestStr have the same value as aSrcStr. It is
658 : * provided as an optimization.
659 : *
660 : * @param aDestStr abstract string reference to be modified
661 : * @param aSrcStr abstract string reference containing source string
662 : * @return NS_OK if function succeeded
663 : *
664 : * This function does not necessarily null-terminate aDestStr after copying
665 : * data from aSrcStr. The behavior depends on the implementation of the
666 : * abstract string, aDestStr. If aDestStr is a reference to a
667 : * nsStringContainer, then its data will be null-terminated by this function.
668 : */
669 : XPCOM_API(nsresult)
670 : NS_CStringCopy
671 : (nsACString &aDestStr, const nsACString &aSrcStr);
672 :
673 : /**
674 : * NS_CStringAppendData
675 : *
676 : * This function appends data to the existing value of aStr.
677 : *
678 : * @param aStr abstract string reference to be modified
679 : * @param aData character buffer
680 : * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
681 : * append until a null-character is encountered)
682 : * @return NS_OK if function succeeded
683 : *
684 : * This function does not necessarily null-terminate aStr upon completion.
685 : * The behavior depends on the implementation of the abstract string, aStr.
686 : * If aStr is a reference to a nsStringContainer, then its data will be null-
687 : * terminated by this function.
688 : */
689 : inline NS_HIDDEN_(nsresult)
690 : NS_CStringAppendData(nsACString &aStr, const char *aData,
691 : PRUint32 aDataLength = PR_UINT32_MAX)
692 : {
693 : return NS_CStringSetDataRange(aStr, PR_UINT32_MAX, 0, aData, aDataLength);
694 : }
695 :
696 : /**
697 : * NS_CStringInsertData
698 : *
699 : * This function inserts data into the existing value of aStr at the specified
700 : * offset.
701 : *
702 : * @param aStr abstract string reference to be modified
703 : * @param aOffset specifies where in the string to insert aData
704 : * @param aData character buffer
705 : * @param aDataLength number of characters to append (pass PR_UINT32_MAX to
706 : * append until a null-character is encountered)
707 : * @return NS_OK if function succeeded
708 : *
709 : * This function does not necessarily null-terminate aStr upon completion.
710 : * The behavior depends on the implementation of the abstract string, aStr.
711 : * If aStr is a reference to a nsStringContainer, then its data will be null-
712 : * terminated by this function.
713 : */
714 : inline NS_HIDDEN_(nsresult)
715 : NS_CStringInsertData(nsACString &aStr, PRUint32 aOffset, const char *aData,
716 : PRUint32 aDataLength = PR_UINT32_MAX)
717 : {
718 : return NS_CStringSetDataRange(aStr, aOffset, 0, aData, aDataLength);
719 : }
720 :
721 : /**
722 : * NS_CStringCutData
723 : *
724 : * This function shortens the existing value of aStr, by removing characters
725 : * at the specified offset.
726 : *
727 : * @param aStr abstract string reference to be modified
728 : * @param aCutOffset specifies where in the string to insert aData
729 : * @param aCutLength number of characters to remove
730 : * @return NS_OK if function succeeded
731 : */
732 : inline NS_HIDDEN_(nsresult)
733 0 : NS_CStringCutData(nsACString &aStr, PRUint32 aCutOffset, PRUint32 aCutLength)
734 : {
735 0 : return NS_CStringSetDataRange(aStr, aCutOffset, aCutLength, nsnull, 0);
736 : }
737 :
738 : /**
739 : * NS_CStringSetIsVoid
740 : *
741 : * This function marks a string as being a "void string". Any data in the
742 : * string will be lost.
743 : */
744 : XPCOM_API(void)
745 : NS_CStringSetIsVoid(nsACString& aStr, const bool aIsVoid);
746 :
747 : /**
748 : * NS_CStringGetIsVoid
749 : *
750 : * This function provides a way to test if a string is a "void string", as
751 : * marked by NS_CStringSetIsVoid.
752 : */
753 : XPCOM_API(bool)
754 : NS_CStringGetIsVoid(const nsACString& aStr);
755 :
756 : /* ------------------------------------------------------------------------- */
757 :
758 : /**
759 : * Encodings that can be used with the following conversion routines.
760 : */
761 : enum nsCStringEncoding {
762 : /* Conversion between ASCII and UTF-16 assumes that all bytes in the source
763 : * string are 7-bit ASCII and can be inflated to UTF-16 by inserting null
764 : * bytes. Reverse conversion is done by truncating every other byte. The
765 : * conversion may result in loss and/or corruption of information if the
766 : * strings do not strictly contain ASCII data. */
767 : NS_CSTRING_ENCODING_ASCII = 0,
768 :
769 : /* Conversion between UTF-8 and UTF-16 is non-lossy. */
770 : NS_CSTRING_ENCODING_UTF8 = 1,
771 :
772 : /* Conversion from UTF-16 to the native filesystem charset may result in a
773 : * loss of information. No attempt is made to protect against data loss in
774 : * this case. The native filesystem charset applies to strings passed to
775 : * the "Native" method variants on nsIFile and nsILocalFile. */
776 : NS_CSTRING_ENCODING_NATIVE_FILESYSTEM = 2
777 : };
778 :
779 : /**
780 : * NS_CStringToUTF16
781 : *
782 : * This function converts the characters in a nsACString to an array of UTF-16
783 : * characters, in the platform endianness. The result is stored in a nsAString
784 : * object.
785 : *
786 : * @param aSource abstract string reference containing source string
787 : * @param aSrcEncoding character encoding of the source string
788 : * @param aDest abstract string reference to hold the result
789 : */
790 : XPCOM_API(nsresult)
791 : NS_CStringToUTF16(const nsACString &aSource, nsCStringEncoding aSrcEncoding,
792 : nsAString &aDest);
793 :
794 : /**
795 : * NS_UTF16ToCString
796 : *
797 : * This function converts the UTF-16 characters in a nsAString to a single-byte
798 : * encoding. The result is stored in a nsACString object. In some cases this
799 : * conversion may be lossy. In such cases, the conversion may succeed with a
800 : * return code indicating loss of information. The exact behavior is not
801 : * specified at this time.
802 : *
803 : * @param aSource abstract string reference containing source string
804 : * @param aDestEncoding character encoding of the resulting string
805 : * @param aDest abstract string reference to hold the result
806 : */
807 : XPCOM_API(nsresult)
808 : NS_UTF16ToCString(const nsAString &aSource, nsCStringEncoding aDestEncoding,
809 : nsACString &aDest);
810 :
811 : #endif // nsXPCOMStrings_h__
|