Line data    Source code

       1             : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
       2             : /* vim: set ts=8 sts=2 et sw=2 tw=80: */
       3             : /* This Source Code Form is subject to the terms of the Mozilla Public
       4             :  * License, v. 2.0. If a copy of the MPL was not distributed with this
       5             :  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
       6             : 
       7             : 
       8             : /**
       9             :  * NOTE:
      10             :  *
      11             :  * Try to avoid flat strings.  |PromiseFlat[C]String| will help you as a last
      12             :  * resort, and this may be necessary when dealing with legacy or OS calls,
      13             :  * but in general, requiring a null-terminated array of characters kills many
      14             :  * of the performance wins the string classes offer.  Write your own code to
      15             :  * use |nsA[C]String&|s for parameters.  Write your string proccessing
      16             :  * algorithms to exploit iterators.  If you do this, you will benefit from
      17             :  * being able to chain operations without copying or allocating and your code
      18             :  * will be significantly more efficient.  Remember, a function that takes an
      19             :  * |const nsA[C]String&| can always be passed a raw character pointer by
      20             :  * wrapping it (for free) in a |nsDependent[C]String|.  But a function that
      21             :  * takes a character pointer always has the potential to force allocation and
      22             :  * copying.
      23             :  *
      24             :  *
      25             :  * How to use it:
      26             :  *
      27             :  * A |nsPromiseFlat[C]String| doesn't necessarily own the characters it
      28             :  * promises.  You must never use it to promise characters out of a string
      29             :  * with a shorter lifespan.  The typical use will be something like this:
      30             :  *
      31             :  *   SomeOSFunction( PromiseFlatCString(aCSubstring).get() ); // GOOD
      32             :  *
      33             :  * Here's a BAD use:
      34             :  *
      35             :  *  const char* buffer = PromiseFlatCString(aCSubstring).get();
      36             :  *  SomeOSFunction(buffer); // BAD!! |buffer| is a dangling pointer
      37             :  *
      38             :  * The only way to make one is with the function |PromiseFlat[C]String|,
      39             :  * which produce a |const| instance.  ``What if I need to keep a promise
      40             :  * around for a little while?'' you might ask.  In that case, you can keep a
      41             :  * reference, like so:
      42             :  *
      43             :  *   const nsCString& flat = PromiseFlatString(aCSubstring);
      44             :  *     // Temporaries usually die after the full expression containing the
      45             :  *     // expression that created the temporary is evaluated.  But when a
      46             :  *     // temporary is assigned to a local reference, the temporary's lifetime
      47             :  *     // is extended to the reference's lifetime (C++11 [class.temporary]p5).
      48             :  *     //
      49             :  *     // This reference holds the anonymous temporary alive.  But remember: it
      50             :  *     // must _still_ have a lifetime shorter than that of |aCSubstring|, and
      51             :  *     // |aCSubstring| must not be changed while the PromiseFlatString lives.
      52             :  *
      53             :  *  SomeOSFunction(flat.get());
      54             :  *  SomeOtherOSFunction(flat.get());
      55             :  *
      56             :  *
      57             :  * How does it work?
      58             :  *
      59             :  * A |nsPromiseFlat[C]String| is just a wrapper for another string.  If you
      60             :  * apply it to a string that happens to be flat, your promise is just a
      61             :  * dependent reference to the string's data.  If you apply it to a non-flat
      62             :  * string, then a temporary flat string is created for you, by allocating and
      63             :  * copying.  In the event that you end up assigning the result into a sharing
      64             :  * string (e.g., |nsTString|), the right thing happens.
      65             :  */
      66             : 
      67       27921 : class nsTPromiseFlatString_CharT : public nsTString_CharT
      68             : {
      69             : public:
      70             : 
      71             :   typedef nsTPromiseFlatString_CharT self_type;
      72             : 
      73             : private:
      74             : 
      75             :   void Init(const substring_type&);
      76             : 
      77             :   // NOT TO BE IMPLEMENTED
      78             :   void operator=(const self_type&) = delete;
      79             : 
      80             :   // NOT TO BE IMPLEMENTED
      81             :   nsTPromiseFlatString_CharT() = delete;
      82             : 
      83             :   // NOT TO BE IMPLEMENTED
      84             :   nsTPromiseFlatString_CharT(const string_type& aStr) = delete;
      85             : 
      86             : public:
      87             : 
      88             :   explicit
      89       27921 :   nsTPromiseFlatString_CharT(const substring_type& aStr)
      90       27921 :     : string_type()
      91             :   {
      92       27921 :     Init(aStr);
      93       27921 :   }
      94             : 
      95             :   explicit
      96           0 :   nsTPromiseFlatString_CharT(const substring_tuple_type& aTuple)
      97           0 :     : string_type()
      98             :   {
      99             :     // nothing else to do here except assign the value of the tuple
     100             :     // into ourselves.
     101           0 :     Assign(aTuple);
     102           0 :   }
     103             : };
     104             : 
     105             : // We template this so that the constructor is chosen based on the type of the
     106             : // parameter. This allows us to reject attempts to promise a flat flat string.
     107             : template<class T>
     108             : const nsTPromiseFlatString_CharT
     109       27905 : TPromiseFlatString_CharT(const T& aString)
     110             : {
     111       27905 :   return nsTPromiseFlatString_CharT(aString);
     112             : }