1 martin 1.6 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.7 //

  3 martin 1.6 // Licensed to The Open Group (TOG) under one or more contributor license
  4            // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5            // this work for additional information regarding copyright ownership.
  6            // Each contributor licenses this file to you under the OpenPegasus Open
  7            // Source License; you may not use this file except in compliance with the
  8            // License.

  9 martin 1.7 //

 10 martin 1.6 // Permission is hereby granted, free of charge, to any person obtaining a
 11            // copy of this software and associated documentation files (the "Software"),
 12            // to deal in the Software without restriction, including without limitation
 13            // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14            // and/or sell copies of the Software, and to permit persons to whom the
 15            // Software is furnished to do so, subject to the following conditions:

 16 martin 1.7 //

 17 martin 1.6 // The above copyright notice and this permission notice shall be included
 18            // in all copies or substantial portions of the Software.

 19 martin 1.7 //

 20 martin 1.6 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.7 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.6 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23            // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24            // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25            // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26            // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 27 martin 1.7 //

 28 martin 1.6 //////////////////////////////////////////////////////////////////////////

 29 mike   1.1 //
 30            //%/////////////////////////////////////////////////////////////////////////////
 31            
 32            #ifndef Pegasus_StrLit_h
 33            #define Pegasus_StrLit_h
 34            
 35            #include <Pegasus/Common/Config.h>
 36            #include <Pegasus/Common/Buffer.h>
 37            
 38            #define STRLIT_ARGS(STR) STR, (sizeof(STR)-1)
 39            #define STRLIT(STR) StrLit(STRLIT_ARGS(STR))
 40            
 41            PEGASUS_NAMESPACE_BEGIN
 42            
 43            /*  The StrLit class and associated macros provide a mechanism for retaining the
 44                length C string literals at compile time. This is preferrable to repeated
 45                recalculation of the length, usually with strlen(). For example, this:

 46 kumpf  1.4 
 47                    String s("hello world");

 48 mike   1.1 
 49                Is less efficient than this:
 50            

 51 kumpf  1.4         String s("hello world", 11);

 52 mike   1.1 
 53                The first form, forces the String constructor to call strlen(), an O(N)

 54 kumpf  1.4     operation. This is unfortunate for C string literals since the length can

 55 mike   1.1     be obtained at compile time with the sizeof operator. For example:
 56            

 57 kumpf  1.4         String s("hello world", sizeof("hello world") - 1);

 58 mike   1.1 
 59                But repeating the literal twice is error prone, so instead we use the
 60                STRLIT_ARGS() macro.
 61            

 62 kumpf  1.4         String s(STRLIT_ARGS("hello world"));

 63 mike   1.1 
 64                This macro can also be used to define StrLit objects at compile time.
 65                For example:
 66            

 67 kumpf  1.4         const StrLit DEFAULT_HOSTNAME(STRLIT_ARGS("localhost"));

 68 mike   1.1 

 69 kumpf  1.4     You can implement functions that take StrLit objects. For example, we

 70 mike   1.1     define this function:
 71            

 72 kumpf  1.4         operator<<(const Buffer&, const StrLit&);

 73 mike   1.1 
 74                This function can be used in two ways. You can pass predefined StrLit
 75                object to it like this:
 76            

 77 kumpf  1.4         Buffer out;
 78                    out << DEFAULT_HOSTNAME;

 79 mike   1.1 
 80                Or you can use the STRLIT() macro to construct on on the fly:
 81            

 82 kumpf  1.4         Buffer out;
 83                    out << STRLIT("localhost");

 84 mike   1.1 
 85                Note that the latter form would be faster than this, since somebody
 86                is going to have to call strlen() eventually.
 87            

 88 kumpf  1.4         Buffer out;
 89                    out << "localhost";

 90 mike   1.1 

 91 kumpf  1.4     At first glance, this may seem like a small optimization, but this
 92                technique alone was used to decrease the Pegasus CIM server latency
 93                by ten percent (with only moderate application to the XML marshalling

 94 mike   1.1     routines).
 95            */
 96            struct StrLit
 97            {

 98 kumpf  1.5     StrLit(const char* s, size_t n) : str(s), size((Uint32)n) { }

 99 mike   1.1     const char* str;

100 kumpf  1.5     const Uint32 size;

101 mike   1.1 };
102            
103            inline Buffer& operator<<(Buffer& out, const StrLit& x)
104            {

105 mike   1.2     out.append(x.str, x.size);

106 mike   1.1     return out;
107            }
108            
109            PEGASUS_NAMESPACE_END
110            
111            #endif /* Pegasus_StrLit_h */