PageRenderTime 112ms CodeModel.GetById 9ms RepoModel.GetById 1ms app.codeStats 0ms

/gecko_api/include/nsXPCOMStrings.h

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