xpcom/ds/nsStringEnumerator.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   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 #include "nsIStringEnumerator.h"
   7 #include "nsStringFwd.h"
   8 #include "nsTArrayForwardDeclare.h"
   9
  10 // nsIStringEnumerator/nsIUTF8StringEnumerator implementations
  11 //
  12 // Currently all implementations support both interfaces. The
  13 // constructors below provide the most common interface for the given
  14 // type (i.e. nsIStringEnumerator for char16_t* strings, and so
  15 // forth) but any resulting enumerators can be queried to the other
  16 // type. Internally, the enumerators will hold onto the type that was
  17 // passed in and do conversion if GetNext() for the other type of
  18 // string is called.
  19
  20 // There are a few different types of enumerators:
  21
  22 //
  23 // These enumerators hold a pointer to the array. Be careful
  24 // because modifying the array may confuse the iterator, especially if
  25 // you insert or remove elements in the middle of the array.
  26 //
  27
  28 // The non-adopting enumerator requires that the array sticks around
  29 // at least as long as the enumerator does. These are for constant
  30 // string arrays that the enumerator does not own, this could be used
  31 // in VERY specialized cases such as when the provider KNOWS that the
  32 // string enumerator will be consumed immediately, or will at least
  33 // outlast the array.
  34 // For example:
  35 //
  36 // nsTArray<nsCString> array;
  37 // array.AppendCString("abc");
  38 // array.AppendCString("def");
  39 // NS_NewStringEnumerator(&enumerator, &array, true);
  40 //
  41 // // call some internal method which iterates the enumerator
  42 // InternalMethod(enumerator);
  43 // NS_RELEASE(enumerator);
  44 //
  45 nsresult
  46 NS_NewStringEnumerator(nsIStringEnumerator** aResult,
  47                        const nsTArray<nsString>* aArray,
  48                        nsISupports* aOwner);
  49 nsresult
  50 NS_NewUTF8StringEnumerator(nsIUTF8StringEnumerator** aResult,
  51                            const nsTArray<nsCString>* aArray);
  52
  53 nsresult
  54 NS_NewStringEnumerator(nsIStringEnumerator** aResult,
  55                        const nsTArray<nsString>* aArray);
  56
  57 // Adopting string enumerators assume ownership of the array and will
  58 // call |operator delete| on the array when the enumerator is destroyed
  59 // this is useful when the provider creates an array solely for the
  60 // purpose of creating the enumerator.
  61 // For example:
  62 //
  63 // nsTArray<nsCString>* array = new nsTArray<nsCString>;
  64 // array->AppendString("abcd");
  65 // NS_NewAdoptingStringEnumerator(&result, array);
  66 nsresult
  67 NS_NewAdoptingStringEnumerator(nsIStringEnumerator** aResult,
  68                                nsTArray<nsString>* aArray);
  69
  70 nsresult
  71 NS_NewAdoptingUTF8StringEnumerator(nsIUTF8StringEnumerator** aResult,
  72                                    nsTArray<nsCString>* aArray);
  73
  74
  75 // these versions take a refcounted "owner" which will be addreffed
  76 // when the enumerator is created, and destroyed when the enumerator
  77 // is released. This allows providers to give non-owning pointers to
  78 // ns*StringArray member variables without worrying about lifetime
  79 // issues
  80 // For example:
  81 //
  82 // nsresult MyClass::Enumerate(nsIUTF8StringEnumerator** aResult) {
  83 //     mCategoryList->AppendString("abcd");
  84 //     return NS_NewStringEnumerator(aResult, mCategoryList, this);
  85 // }
  86 //
  87 nsresult
  88 NS_NewUTF8StringEnumerator(nsIUTF8StringEnumerator** aResult,
  89                            const nsTArray<nsCString>* aArray,
  90                            nsISupports* aOwner);