The Tor Browser / file comparison

comparison: xpcom/string/public/nsXPCOMStrings.h

xpcom/string/public/nsXPCOMStrings.h

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial