| 1 | /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|---|
| 2 | /* vim:set ts=2 sw=2 sts=2 et cindent: */
|
|---|
| 3 | /* ***** BEGIN LICENSE BLOCK *****
|
|---|
| 4 | * Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|---|
| 5 | *
|
|---|
| 6 | * The contents of this file are subject to the Mozilla Public License Version
|
|---|
| 7 | * 1.1 (the "License"); you may not use this file except in compliance with
|
|---|
| 8 | * the License. You may obtain a copy of the License at
|
|---|
| 9 | * http://www.mozilla.org/MPL/
|
|---|
| 10 | *
|
|---|
| 11 | * Software distributed under the License is distributed on an "AS IS" basis,
|
|---|
| 12 | * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|---|
| 13 | * for the specific language governing rights and limitations under the
|
|---|
| 14 | * License.
|
|---|
| 15 | *
|
|---|
| 16 | * The Original Code is Mozilla.
|
|---|
| 17 | *
|
|---|
| 18 | * The Initial Developer of the Original Code is IBM Corporation.
|
|---|
| 19 | * Portions created by IBM Corporation are Copyright (C) 2003
|
|---|
| 20 | * IBM Corporation. All Rights Reserved.
|
|---|
| 21 | *
|
|---|
| 22 | * Contributor(s):
|
|---|
| 23 | * Darin Fisher <darin@meer.net>
|
|---|
| 24 | *
|
|---|
| 25 | * Alternatively, the contents of this file may be used under the terms of
|
|---|
| 26 | * either the GNU General Public License Version 2 or later (the "GPL"), or
|
|---|
| 27 | * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|---|
| 28 | * in which case the provisions of the GPL or the LGPL are applicable instead
|
|---|
| 29 | * of those above. If you wish to allow use of your version of this file only
|
|---|
| 30 | * under the terms of either the GPL or the LGPL, and not to allow others to
|
|---|
| 31 | * use your version of this file under the terms of the MPL, indicate your
|
|---|
| 32 | * decision by deleting the provisions above and replace them with the notice
|
|---|
| 33 | * and other provisions required by the GPL or the LGPL. If you do not delete
|
|---|
| 34 | * the provisions above, a recipient may use your version of this file under
|
|---|
| 35 | * the terms of any one of the MPL, the GPL or the LGPL.
|
|---|
| 36 | *
|
|---|
| 37 | * ***** END LICENSE BLOCK ***** */
|
|---|
| 38 |
|
|---|
| 39 | #ifndef nsObsoleteAString_h___
|
|---|
| 40 | #define nsObsoleteAString_h___
|
|---|
| 41 |
|
|---|
| 42 | /*
|
|---|
| 43 | STRING INTERNALS
|
|---|
| 44 |
|
|---|
| 45 | This file defines nsObsoleteAString and nsObsoleteACString. These are
|
|---|
| 46 | abstract classes (interfaces), containing only virtual functions
|
|---|
| 47 | corresponding to the FROZEN nsA[C]String classes. They exist to provide
|
|---|
| 48 | the new non-abstract nsA[C]String classes with a mechanism to maintain
|
|---|
| 49 | backwards binary compatability.
|
|---|
| 50 |
|
|---|
| 51 | From a binary point-of-view, the new nsA[C]String classes appear to have a
|
|---|
| 52 | vtable pointer to the vtable of nsObsoleteA[C]StringThunk.
|
|---|
| 53 | nsObsoleteA[C]StringThunk is a subclass of nsObsoleteA[C]String that serves
|
|---|
| 54 | as a simple bridge between the virtual functions that make up the FROZEN
|
|---|
| 55 | nsA[C]String contract and the new ns[C]Substring, which is now our only
|
|---|
| 56 | subclass of nsA[C]String.
|
|---|
| 57 |
|
|---|
| 58 | The methods on the new nsA[C]String are now all non-virtual. This reduces
|
|---|
| 59 | codesize at the callsite, and reduces the number of memory dereferences and
|
|---|
| 60 | jumps required to invoke a method on nsA[C]String. The result is improved
|
|---|
| 61 | performance and reduced codesize. However, to maintain binary
|
|---|
| 62 | compatibility, each method on nsA[C]String must check the value of its
|
|---|
| 63 | vtable to determine if it corresponds to the built-in implementation of
|
|---|
| 64 | nsObsoleteA[C]String (i.e., the address of the canonical vtable). If it
|
|---|
| 65 | does, then the vtable can be ignored, and the nsA[C]String object (i.e.,
|
|---|
| 66 | |this|) can be cast to ns[C]Substring directly. In which case, the
|
|---|
| 67 | nsA[C]String methods can be satisfied by invoking the corresponding methods
|
|---|
| 68 | directly on ns[C]Substring. If the vtable address does not correspond to
|
|---|
| 69 | the built-in implementation, then the virtual functions on
|
|---|
| 70 | nsObsoleteA[C]String must be invoked instead.
|
|---|
| 71 |
|
|---|
| 72 | So, if a nsA[C]String reference corresponds to an external implementation
|
|---|
| 73 | (such as the old nsEmbed[C]String that shipped with previous versions of
|
|---|
| 74 | Mozilla), then methods invoked on that nsA[C]String will still act like
|
|---|
| 75 | virtual function calls. This ensures binary compatibility while avoiding
|
|---|
| 76 | virtual function calls in most cases.
|
|---|
| 77 |
|
|---|
| 78 | Finally, nsObsoleteA[C]String (i.e., the FROZEN nsA[C]String vtable) is
|
|---|
| 79 | now a DEPRECATED interface. See nsStringAPI.h and nsEmbedString.h for
|
|---|
| 80 | the new preferred way to access nsA[C]String references in an external
|
|---|
| 81 | component or Gecko embedding application.
|
|---|
| 82 | */
|
|---|
| 83 |
|
|---|
| 84 | #ifndef nsStringFwd_h___
|
|---|
| 85 | #include "nsStringFwd.h"
|
|---|
| 86 | #endif
|
|---|
| 87 |
|
|---|
| 88 | #ifndef nscore_h___
|
|---|
| 89 | #include "nscore.h"
|
|---|
| 90 | #endif
|
|---|
| 91 |
|
|---|
| 92 | // declare nsObsoleteAString
|
|---|
| 93 | #include "string-template-def-unichar.h"
|
|---|
| 94 | #include "nsTObsoleteAString.h"
|
|---|
| 95 | #include "string-template-undef.h"
|
|---|
| 96 |
|
|---|
| 97 | // declare nsObsoleteACString
|
|---|
| 98 | #include "string-template-def-char.h"
|
|---|
| 99 | #include "nsTObsoleteAString.h"
|
|---|
| 100 | #include "string-template-undef.h"
|
|---|
| 101 |
|
|---|
| 102 | #endif // !defined(nsObsoleteAString_h___)
|
|---|
