/gecko_api/include/nsXPCOMStrings.h
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__