diff -r 000000000000 -r e35f40988205 xml/libxml2libs/inc/xmlengineutils/xmlengxestrings.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/libxml2libs/inc/xmlengineutils/xmlengxestrings.h Thu Dec 17 09:29:21 2009 +0200 @@ -0,0 +1,339 @@ +// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// This file contains definitions of string used by +// XmlEngine's modules. +// + + + +/** + @file + @publishedPartner + @released +*/ + +#ifndef XESTRINGS_H +#define XESTRINGS_H + +#include + +/** +Defines a constant string to be used as an argument value for arguments of type +TDOMString and TDOMStringArg. + +No '\0' character can appear in the string. + +Usage: +@code + _XMLLIT(KLitName, ""); + obj.SomeMethod(KLitName); // argument type is TXmlEngConstString or TDOMStringArg +@endcode +*/ +#define _XMLLIT(LitName, utf8String) const TUint8* const LitName = (const TUint8*) utf8String; + +/** +Implements a constant string used within libxml2-based API's. + +TXmlEngConstString contains a pointer to a zero-terminated UTF-8 string. The +contents of the string is not supposed to be changed. From this point of view +TXmlEngConstString instances are close to the concept of immutable strings. + +Ownership of the string is not defined for TXmlEngConstString. Thus, in +different contexts (APIs), different string-handling policies may be applied. +For instance, in XML Engine SAX API all reported via callbacks strings of +TXmlEngConstString type are assumed owned by the parser. + +TXmlEngConstString is a base class for other specialized string classes in XML +Engine APIs. +*/ +class TXmlEngConstString + { + friend class Libxml2_XmlAttributes; + +public: + /** Default constructor */ + inline TXmlEngConstString(); + + /** + Constructor + @param aString The string for initialization. Ownership is not transferred + and the string must stay in scope for the lifetime of this object. + */ + inline TXmlEngConstString(const char* aString); + + /** + Check if the string is not NULL + @return ETrue if the string is not null, EFalse otherwise + */ + inline TBool NotNull() const; + + /** + Check if the string is NULL + @return ETrue if the string is null, EFalse otherwise + */ + inline TBool IsNull() const; + + /** + Gets a c string + @return The string as a C string or NULL if null + */ + inline const char* Cstring() const; + + /** + Gets a c string or if NULL, return a default value. + @param aDefaultValue default value + @return If not NULL, the c string, otherwise aDefaultValue + */ + inline const char* CstringDef(const char* aDefaultValue) const; + + /** + Compares with another string. NULL and "" are considered equal. + + @param aString The string to compare + @return ETrue if equal, EFalse otherwise + */ + inline TBool Equals(TXmlEngConstString aString) const; + + /** + Compares with another string. NULL and "" are considered equal. + + @param aString The string to compare + @return 0 if equal, -1 otherwise + */ + IMPORT_C TInt Compare(TXmlEngConstString aString) const; + + /** + Allocates a HBufC from the string contents. Ownership is transferred to + the caller. + + Typical use: + @code + ... + HBufC* attrValue = attr.Value().AllocL(); + ... + @endcode + + @see AllocLC() + @leave KErrNoMemory Memory allocation failure + @leave KUriUtilsCannotConvert String cannot be converted + */ + IMPORT_C HBufC* AllocL() const; + + /** + Allocates a HBufC from the string contents and pushes the descriptor to + cleanup stack. Ownership is transferred to the caller. + + Typical use: + @code + ... + HBufC* attrValue = attr.Value().AllocLC(); + ... + @endcode + + @see AllocL() + @leave KErrNoMemory Memory allocation failure + @leave KUriUtilsCannotConvert String cannot be converted + */ + IMPORT_C HBufC* AllocLC() const; + + /** + Get a TPtrC8 that contains the string + @return A point descriptor that holds the string + */ + inline TPtrC8 PtrC8() const; + + /** + Creates a new copy of the string contents. Ownership for the new string is + transferred to the caller. + + @return A c string copy of the string contents + @leave KErrNoMemory Memory allocation failure + */ + IMPORT_C char* CopyL() const; + + /** + Returns the size of the string in bytes + @return The size + */ + IMPORT_C TUint Size() const; + + /** + Get the length of the string. For non-ASCII strings, Size() != Length() due + to the UTF-8 encoding used for non-ASCII characters. + @return The number of characters in the string + */ + IMPORT_C TUint Length() const; + +protected: + /** + Set a new string value. The old string is not freed. Ownership is not + transferred. + @param aString The new value + */ + inline void Set(char* aString); + +protected: + /** String value */ + char* iString; +}; + +/** +General-purpose string used in libxml2-based API's. + +This class holds a zero-terminated sequence of bytes (c-style string). It is +commonly used to represent a sequence of UTF-8 characters. + +TXmlEngString objects should be treated as if they were pointers. The +destructor for TXmlEngString does nothing. This means that the developer needs +to free the memory allocated by TXmlEngString by calling Free() or Close() +(Close() is an alias for Free()) and to do so only once. + +The reason for this design is that the goal is to have a string class that is +as small as a one-pointer sized object that is mostly stored on the stack, not +on the heap (and therefore no additional memory allocation is required). It is +also as flexible as possible to allow developers to create their own derived +classes which may provide auto_ptr-like or reference counting solutions. + +The contents of this class can be replaced, destroyed, copied and converted to +c strings and Symbian descriptor types. + +The contents of TXmlEngString may also be modified with AppendL(). + +When TXmlEngString is the return type in libxml2 based API's, this usually +indicates that a string has been newly allocated, which should be freed by the +method caller. +*/ +class TXmlEngString: public TXmlEngConstString +{ +public: + /** Default constructor */ + inline TXmlEngString(); + + /** + Constructs a new string from a given c string. Ownership is transferred + and the string must be freed with Free() or Close(). + + @param aString A heap-based c string + */ + inline TXmlEngString(char* aString); + + /** Frees the string */ + IMPORT_C void Free(); + + /** + Sets a new value. The old string is freed. Ownership is transferred and + the string must be freed with Free() or Close(). + + @param aStr The new string + */ + inline void Set(char* aStr); + + /** + Transfers a string and its ownership from another TXmlEngString object. If + this object currently stores a string it is freed. + + @param aSrc The source string + */ + IMPORT_C void Set(TXmlEngString& aSrc); + + /** Frees the string */ + inline void Close(); + + /** + Pushes this string to the cleanup stack. This must be matched with a + corresponding call to CleanupStack::Pop() or CleanupStack::PopAndDestroy(). + @return This object + @leave KErrNoMemory Memory allocation failure + */ + inline TXmlEngString PushL(); + + /** + Initializes the string, converting from a UTF-16 descriptor to + a UTF-8 zero-terminated string. + @param aDes The new value + @leave - One of the system-wide error codes + */ + IMPORT_C void SetL(const TDesC& aDes); + + /** + Initializes the string from a descriptor + @param aDes The new value + @leave - One of the system-wide error codes + */ + IMPORT_C void SetL(const TDesC8& aDes); + + /** + Creates a new UTF-16 HBufC from the UTF-8 string contents and transfers + ownership of the string. The string held by this object is freed. + + Typical use: + @code + ... + HBufC* attrValue = attr.WholeValueCopyL().AllocAndFreeL(); + ... + @endcode + + @see AllocAndFreeLC() + @return The copied string + @leave KErrNoMemory Memory allocation failure + @leave KUriUtilsCannotConvert String cannot be converted + */ + IMPORT_C HBufC* AllocAndFreeL(); + + /** + Creates a new UTF-16 HBufC from the UTF-8 string contents and transfers + ownership of the string. The result is placed on the cleanup stack. The + string held by this object is freed. + + Typical use: + @code + ... + HBufC* attrValue = attr.WholeValueCopyL().AllocAndFreeL(); + ... + @endcode + + @see AllocAndFreeL() + @return The copied string + @leave KErrNoMemory Memory allocation failure + @leave KUriUtilsCannotConvert String cannot be converted + */ + IMPORT_C HBufC* AllocAndFreeLC(); + + /** + Appends new text to the string + @param aStr The string to add + @leave KErrNoMemory Memory allocation failure + */ + IMPORT_C void AppendL(TXmlEngString aStr); + + /** + Appends new text to the string. + @param aStr1 The first string to append + @param aStr2 The second string to append + @leave KErrNoMemory Memory allocation failure + */ + IMPORT_C void AppendL(TXmlEngString aStr1, TXmlEngString aStr2); + +protected: + /** + Constructs the object from a TXmlEngConstString + @param aStr The string to initialize from + */ + inline TXmlEngString(const TXmlEngConstString& aStr): TXmlEngConstString(aStr.Cstring()) {} +}; + +#include + +#endif // XESTRINGS_H +