LString8 Class Reference

#include <estring.h>

Link against: euserhl.lib

class LString8 : public RBuf8

Inherits from

Public Member Functions
LString8()
LString8(TInt)
LString8(const TDesC8 &)
LString8(const TUint8 *)
LString8(const LString8 &)
LString8(HBufC8 *)
LString8(TUint8 *, TInt)
LString8(TUint8 *, TInt, TInt)
LString8(const char *)
~LString8()
IMPORT_C voidAppendFillL(TChar, TInt)
IMPORT_C voidAppendFormatL(TRefByValue< const TDesC8 >, ...)
IMPORT_C voidAppendFormatListL(const TDesC8 &, VA_LIST)
IMPORT_C voidAppendJustifyL(const TDesC8 &, TInt, TAlign, TChar)
IMPORT_C voidAppendJustifyL(const TDesC8 &, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustifyL(const TUint8 *, TInt, TAlign, TChar)
IMPORT_C voidAppendJustifyL(const TUint8 *, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustifyL(const char *, TInt, TInt, TAlign, TChar)
IMPORT_C voidAppendJustifyL(const char *, TInt, TAlign, TChar)
IMPORT_C voidAppendL(TChar)
IMPORT_C voidAppendL(const TDesC8 &)
IMPORT_C voidAppendL(const TUint8 *, TInt)
IMPORT_C voidAppendL(const TUint8 *)
IMPORT_C voidAppendL(const char *, TInt)
IMPORT_C voidAppendL(const char *)
IMPORT_C voidAppendNumFixedWidthL(TUint, TRadix, TInt)
IMPORT_C voidAppendNumFixedWidthUCL(TUint, TRadix, TInt)
IMPORT_C TIntAppendNumL(TReal, const TRealFormat &)
IMPORT_C voidAppendNumL(TInt64)
IMPORT_C voidAppendNumL(TUint64, TRadix)
IMPORT_C voidAppendNumUCL(TUint64, TRadix)
IMPORT_C voidAssign(const LString8 &)
IMPORT_C voidAssign(const RBuf8 &)
IMPORT_C voidAssign(HBufC8 *)
IMPORT_C voidAssign(TUint8 *, TInt)
IMPORT_C voidAssign(TUint8 *, TInt, TInt)
IMPORT_C TIntCompare(const TUint8 *)
IMPORT_C TIntCompare(const char *)
IMPORT_C TIntCompareF(const TUint8 *)
IMPORT_C TIntCompareF(const char *)
IMPORT_C voidCompress()
IMPORT_C voidCopyCL(const TDesC8 &)
IMPORT_C voidCopyCPL(const TDesC8 &)
IMPORT_C voidCopyCPL(const TUint8 *)
IMPORT_C voidCopyCPL(const char *)
IMPORT_C voidCopyFL(const TDesC8 &)
IMPORT_C voidCopyFL(const TUint8 *)
IMPORT_C voidCopyFL(const char *)
IMPORT_C voidCopyL(const TDesC8 &)
IMPORT_C voidCopyL(const TDesC16 &)
IMPORT_C voidCopyL(const TUint8 *)
IMPORT_C voidCopyL(const TUint8 *, TInt)
IMPORT_C voidCopyL(const char *)
IMPORT_C voidCopyLCL(const TDesC8 &)
IMPORT_C voidCopyLCL(const TUint8 *)
IMPORT_C voidCopyLCL(const char *)
IMPORT_C voidCopyUCL(const TDesC8 &)
IMPORT_C voidCopyUCL(const TUint8 *)
IMPORT_C voidCopyUCL(const char *)
IMPORT_C voidCreateL(RReadStream &, TInt)
IMPORT_C voidFillL(TChar, TInt)
IMPORT_C voidFillZL(TInt)
IMPORT_C TIntFind(const TUint8 *)
IMPORT_C TIntFind(const char *)
IMPORT_C TIntFind(const char *, TInt)
IMPORT_C TIntFindF(const TUint8 *)
IMPORT_C TIntFindF(const char *)
IMPORT_C TIntFindF(const char *, TInt)
IMPORT_C voidFormatL(TRefByValue< const TDesC8 >, ...)
IMPORT_C voidFormatListL(const TDesC8 &, VA_LIST)
IMPORT_C voidInsertL(TInt, const TDesC8 &)
IMPORT_C voidInsertL(TInt, const TUint8 *)
IMPORT_C voidInsertL(TInt, const char *)
IMPORT_C voidJustifyL(const TDesC8 &, TInt, TAlign, TChar)
IMPORT_C voidJustifyL(const TUint8 *, TInt, TAlign, TChar)
IMPORT_C voidJustifyL(const char *, TInt, TAlign, TChar)
IMPORT_C TIntMatch(const TUint8 *)
IMPORT_C TIntMatch(const char *)
IMPORT_C TIntMatchF(const TUint8 *)
IMPORT_C TIntMatchF(const char *)
IMPORT_C voidNumFixedWidthL(TUint, TRadix, TInt)
IMPORT_C voidNumFixedWidthUCL(TUint, TRadix, TInt)
IMPORT_C TIntNumL(TReal, const TRealFormat &)
IMPORT_C voidNumL(TInt64)
IMPORT_C voidNumL(TUint64, TRadix)
IMPORT_C voidNumUCL(TUint64, TRadix)
IMPORT_C const TUint8 *PtrZL()
IMPORT_C voidReplaceL(TInt, TInt, const TDesC8 &)
IMPORT_C voidReplaceL(TInt, TInt, const TUint8 *)
IMPORT_C voidReplaceL(TInt, TInt, const char *)
IMPORT_C voidReserveFreeCapacityL(TInt)
IMPORT_C voidReset()
IMPORT_C voidSetLengthL(TInt)
IMPORT_C voidSetMaxLengthL(TInt)
IMPORT_C voidSwapL(TDes8 &)
IMPORT_C voidSwapL(LString8 &)
IMPORT_C voidZeroTerminateL()
voidoperator delete(TAny *)
voidoperator delete(TAny *, TLeave)
voidoperator delete(TAny *, TAny *)
IMPORT_C TBooloperator!=(const TUint8 *)
IMPORT_C TBooloperator!=(const char *)
IMPORT_C LString8 &operator+=(TChar)
IMPORT_C LString8 &operator+=(const TDesC8 &)
IMPORT_C LString8 &operator+=(const TUint8 *)
IMPORT_C LString8 &operator+=(const char *)
IMPORT_C TBooloperator<(const TUint8 *)
IMPORT_C TBooloperator<(const char *)
IMPORT_C TBooloperator<=(const TUint8 *)
IMPORT_C TBooloperator<=(const char *)
IMPORT_C LString8 &operator=(const TDesC8 &)
IMPORT_C LString8 &operator=(const LString8 &)
IMPORT_C LString8 &operator=(const TUint8 *)
IMPORT_C LString8 &operator=(HBufC8 *)
IMPORT_C LString8 &operator=(const char *)
IMPORT_C TBooloperator==(const TUint8 *)
IMPORT_C TBooloperator==(const char *)
IMPORT_C TBooloperator>(const TUint8 *)
IMPORT_C TBooloperator>(const char *)
IMPORT_C TBooloperator>=(const TUint8 *)
IMPORT_C TBooloperator>=(const char *)
Inherited Attributes
RBuf8::@20
RBuf8::__DECLARE_TEST
RBuf8::iEBufCPtrType
RBuf8::iEPtrType
TDes8::iMaxLength
Inherited Functions
RBuf8::RBuf8()
RBuf8::RBuf8(HBufC8 *)
RBuf8::RBuf8(TInt,TInt,TInt)
RBuf8::RBuf8(const RBuf8 &)
RBuf8::ReAlloc(TInt)
RBuf8::ReAllocL(TInt)
RBuf8::operator=(const RBuf8 &)
TDes8::Append(const TDesC16 &)
TDes8::Capitalize()
TDes8::Collapse()
TDes8::Collate()
TDes8::Delete(TInt,TInt)
TDes8::DoAppendNum(TUint64,TRadix,TUint,TInt)
TDes8::DoPadAppendNum(TInt,TInt,const TUint8 *)
TDes8::Expand()
TDes8::Fill(TChar)
TDes8::FillZ()
TDes8::Fold()
TDes8::LeftTPtr(TInt)const
TDes8::LowerCase()
TDes8::MaxLength()const
TDes8::MaxSize()const
TDes8::MidTPtr(TInt)const
TDes8::MidTPtr(TInt,TInt)const
TDes8::Repeat(const TDesC8 &)
TDes8::Repeat(const TUint8 *,TInt)
TDes8::RightTPtr(TInt)const
TDes8::TDes8()
TDes8::TDes8(TInt,TInt,TInt)
TDes8::Trim()
TDes8::TrimAll()
TDes8::TrimLeft()
TDes8::TrimRight()
TDes8::UpperCase()
TDes8::WPtr()const
TDes8::Zero()
TDes8::operator=(const TDes8 &)
TDes8::operator[](TInt)
TDes8::operator[](TInt)const
TDesC8::Alloc()const
TDesC8::AllocL()const
TDesC8::AllocLC()const
TDesC8::AtC(TInt)const
TDesC8::Compare(const TDesC8 &)const
TDesC8::CompareC(const TDesC8 &)const
TDesC8::CompareF(const TDesC8 &)const
TDesC8::DoSetLength(TInt)
TDesC8::Find(const TDesC8 &)const
TDesC8::Find(const TUint8 *,TInt)const
TDesC8::FindC(const TDesC8 &)const
TDesC8::FindC(const TUint8 *,TInt)const
TDesC8::FindF(const TDesC8 &)const
TDesC8::FindF(const TUint8 *,TInt)const
TDesC8::Left(TInt)const
TDesC8::Length()const
TDesC8::Locate(TChar)const
TDesC8::LocateF(TChar)const
TDesC8::LocateReverse(TChar)const
TDesC8::LocateReverseF(TChar)const
TDesC8::Match(const TDesC8 &)const
TDesC8::MatchC(const TDesC8 &)const
TDesC8::MatchF(const TDesC8 &)const
TDesC8::Mid(TInt)const
TDesC8::Mid(TInt,TInt)const
TDesC8::Ptr()const
TDesC8::Right(TInt)const
TDesC8::Size()const
TDesC8::TDesC8()
TDesC8::TDesC8(TInt,TInt)
TDesC8::Type()const
TDesC8::operator!=(const TDesC8 &)const
TDesC8::operator<(const TDesC8 &)const
TDesC8::operator<=(const TDesC8 &)const
TDesC8::operator==(const TDesC8 &)const
TDesC8::operator>(const TDesC8 &)const
TDesC8::operator>=(const TDesC8 &)const

Detailed Description

LString8 is a convenient, general-purpose 8 bit string class derived from RBuf8. LString8 adds automatic cleanup and on-demand buffer resize facilities.

L-Classes
Note: The L prefix denotes that construction, copying, passing and returning by value, assignment, and manipulation via operators should all be considered potentially leaving operations unless otherwise explicitly documented. Code that uses LString8 should be written accordingly, in leave-safe style.
Descriptor Relationships
Like an RBuf8, an LString8 can be passed to any function that is prototyped to take a TDes8 or a TDesC8 reference. Again like an RBuf8, an LString8 maintains its string data in a heap buffer.
Value-Type Behaviour
Unlike RBuf8, an LString8 may be used much like a simple T class; LString8 typed variables will automatically clean up after themselves when they go out of scope, and LString8 typed fields will similarly automatically release all owned resources when their containing object is destroyed.

For example, where:

RBuf8 buf;
buf.CleanupClosePushL();
...
CleanupStack::PopAndDestroy();

would be required, with LString8:

LString8 buf;
...

will suffice. Pushing an LString8 onto the cleanup stack is not necessary or recommended, but the effects of doing so are benign. LString8 instances can also be passed and returned by value, but note that doing so may trigger implicit heap allocation and cause a leave with KErrNoMemory.

void TakeString(LString8 aString)
	{
	// ...
	}

LString8 ReturnString(LString8 aString)
	{
	TakeString(aString); // Statement may leave with KErrNoMemory
	return aString; // Statement may leave with KErrNoMemory
	}

As with other descriptors, passing by reference when possible is more efficient.

On-Demand Growth
In addition to the value-type semantics described above, LString8 also supports automatic in-place resizing. All standard descriptor methods are available, but for any non-leaving descriptor method that may panic due to buffer overflow, LString8 adds a corresponding leaving method that automatically expands the underlying buffer on-demand. For example, Append() will panic if the new data overflows available buffer space, while AppendL() will attempt to realloc the buffer as necessary. The new leaving variants may therefore leave with KErrNoMemory, may invalidate any existing raw pointers into the data buffer (e.g. those previously returned by Ptr()), and may change the value returned by MaxLength().
LString8 message; // Zero length
message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer
User::InfoPrint(message);

It is important to note that LString8 only supports automatic growth when being manipulated directly as an LString8. When an LString8 is passed to a function accepting a TDes8, that function will operate on it as if it is a fixed-max-length descriptor. In that case, adequate capacity must be reserved within the LString8 prior to calling the function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL().

extern void GetLastQuery(TDes8& aQuery);
extern void GetLastAuxQuery(TDes8& aQuery);

LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize
GetLastQuery(query);

// ...

previousQueryMaxLength = query.MaxLength(); 

query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength;
GetLastAuxQuery(query);
Relationship with TDes and RBuf
LString8 derives from RBuf8 in order to achieve maximum interoperability with existing descriptor-accepting APIs. This derivation forces some unusual API compromises, however, due to the unique characteristics of LString8 compared to other descriptors.

Some of the mutating methods on the base classes, TDes8 and RBuf8, panic when called with insufficient buffer space. Sufficient space is a precondition of these base classes which LString8 relaxes with its capability to start with zero length. LString8 defines new leaving variants of these methods with auto-growth behaviour (e.g. AppendL), but at the same time inherits the original methods (e.g. Append). This makes it too easy for developers to call the wrong method inadvertently. In order to address this, the original non-leaving methods have been made private in LString8. Developers should use the leaving LString8 versions.

Note that, if required for any reason, the non-leaving method variants may be accessed by explicitly qualifying the method name to the appropriate parent type. For example: aString.TDes::Append(...). When working with an LString8 but doing so via a TDes& typed variable, all TDes8 APIs are directly available.

Hiding these methods does not remove the problem entirely. The same problem can happen if an LString object of insufficient size in passed into a any API accepting a TDes. The advice is that developers always ensure there is sufficient space before passing LString as a TDes.

Performance Concerns
While being simpler to use than existing descriptors in many cases, LString8's use of heap allocation and its resizing variant methods clearly come with associated costs. Their use in performance-critical code should be carefully considered. On the other hand, LString8's small stack footprint and ability to better-handle inputs of unpredictable size may make them a better choice when the alternative is a large, fixed-max-size TBuf or HBufC.
Buffer Ownership
Typically an LString8 will automatically allocate its own buffer, but like RBuf8 it can also take ownership of a pre-existing raw memory buffer or heap descriptor.

The class is intended for instantiation.

See also: RBuf8 TBuf8 TPtr8 HBufC8 TDesC8 TDes8 LString

Constructor & Destructor Documentation

LString8 ( )

IMPORT_CLString8()

Default constructor.

Constructs a zero-length 8-bit resizable string descriptor.

Note that the resulting object owns no allocated memory yet. This default constructor never leaves.

LString8 ( TInt )

IMPORT_CLString8(TIntaInitialCapacity)[explicit]

Constructor to create a 8-bit resizable string descriptor with an initial capacity.

The function allocates sufficient memory to contain descriptor data up to the specified initial maximum length.

The current length of the descriptor is set to zero. The maximum length of the descriptor is set to the specified value.

See also: RBuf8::CreateL

Parameters
aInitialCapacityThe maximum length of the descriptor.
Leave Codes
KErrNoMemoryIf there is insufficient memory.

LString8 ( const TDesC8 & )

IMPORT_CLString8(const TDesC8 &aDes)

Constructor to create a 8-bit resizable string descriptor to contain a copy of the specified (source) descriptor, or leave on failure.

The constructor allocates sufficient memory so that this string descriptor's maximum length is the same as the length of the source descriptor. Both the current length and the maximum length of this string descriptor are set to the length of the source descriptor.

The data contained in the source descriptor is copied into this string descriptor.

See also: RBuf8::CreateL()

Parameters
aDesSource descriptor to be copied into this object.
Leave Codes
KErrNoMemoryIf there is insufficient memory.

LString8 ( const TUint8 * )

IMPORT_CLString8(const TUint8 *aZeroTerminatedString)

Constructor to create a 8-bit resizable string descriptor containing a copy of the specified (source) zero-terminated string data, or leave on failure.

The constructor allocates sufficient memory so that this string descriptor's maximum length is the same as the length of the source string. Both the current length and the maximum length of this string descriptor are set to the length of the source string.

The data contained in the source string is copied into this string descriptor. The zero terminator is not copied.

See also: LString8::CopyL

Parameters
aZeroTerminatedStringA pointer to a zero-terminated string
Leave Codes
KErrNoMemoryIf there is insufficient memory.

LString8 ( const LString8 & )

IMPORT_CLString8(const LString8 &aDes)

Copy constructor to create a 8-bit resizable string descriptor to contain a copy of the specified (source) string descriptor's data, or leave on failure.

The constructor allocates sufficient memory so that this string descriptor's maximum length is the same as the length of the source string descriptor. Both the current length and the maximum length of this string descriptor are set to the length of the source descriptor.

The data contained in the source string descriptor is copied into this string descriptor.

See also: RBuf8::CreateL()

Parameters
aDesSource string descriptor to be copied into this object.
Leave Codes
KErrNoMemoryIf there is insufficient memory.

LString8 ( HBufC8 * )

IMPORT_CLString8(HBufC8 *aHBuf)[explicit]

Constructor to create a 8-bit resizable string descriptor from a pre-allocated heap descriptor.

Transfers ownership of the specified heap descriptor to this object.

See also: RBuf8::RBuf8(HBufC8*)

Parameters
aHBufThe heap descriptor to be transferred to this object. This pointer can be NULL, which means that a zero length 8-bit resizable string descriptor is created.

LString8 ( TUint8 *, TInt )

IMPORT_CLString8(TUint8 *aHeapCell,
TIntaMaxLength
)[explicit]

Constructor to create a 8-bit resizable string descriptor from a pre-allocated raw heap buffer.

The allocated memory forms the buffer for this string descriptor. The current length of the descriptor is set to zero.

See also: RBuf8::Assign()

Parameters
aHeapCellThe allocated memory to be assigned to this object. This pointer can be NULL, which means that a zero length 8-bit resizable buffer descriptor is created.
aMaxLengthThe maximum length of the constructed string descriptor.
Panic Codes
USER8 If the specified maximum length is greater then the size of the allocated heap cell, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

LString8 ( TUint8 *, TInt, TInt )

IMPORT_CLString8(TUint8 *aHeapCell,
TIntaLength,
TIntaMaxLength
)[explicit]

Constructor to create a 8-bit resizable string descriptor from a pre-allocated raw heap buffer.

The allocated memory forms the buffer for this string descriptor. The current length of the descriptor is set to the value of the second parameter.

See also: RBuf8::Assign()

Parameters
aHeapCellThe allocated memory to be assigned to this object.
aLengthThe length of the resulting string descriptor.
aMaxLengthThe maximum length of the resulting string descriptor.
Panic Codes
USER8 If the specified maximum length is greater then the size of the allocated heap cell, or the specified length is greater then the specified maximum length, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

LString8 ( const char * )

IMPORT_CLString8(const char *aCharStr)

Constructor to create a 8-bit resizable string descriptor containing a copy of the specified (source) zero-terminated character string data, or leave on failure.

The constructor allocates sufficient memory so that this string descriptor's maximum length is the same as the length of the source string. Both the current length and the maximum length of this string descriptor are set to the length of the source string.

The data contained in the source string is copied into this string descriptor. The zero terminator is not copied.

See also: LString8::CopyL

Parameters
aCharStrA pointer to a zero-terminated wide character string
Leave Codes
KErrNoMemoryIf there is insufficient memory.

~LString8 ( )

IMPORT_C~LString8()

Destructor.

Frees any heap-allocated resources owned by this string descriptor. It is safe to rely on this destructor to perform all necessary cleanup; it is not necessary use the cleanup stack or to call Close() manually.

See also: RBuf8::Close

Member Function Documentation

AppendFillL ( TChar, TInt )

IMPORT_C voidAppendFillL(TCharaChar,
TIntaLength
)

Appends and fills this descriptor with the specified character.

The descriptor is appended with the specified number of characters. and its length is changed to reflect this.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharThe fill character.
aLengthThe number of fill characters to be appended.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aLength is negative

AppendFormatL ( TRefByValue< const TDesC8 >, ... )

IMPORT_C voidAppendFormatL(TRefByValue< const TDesC8 >aFmt,
...
)

Formats and appends text onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The function takes a format string and a variable number of arguments. The format string contains literal text, embedded with directives, for converting the trailing list of arguments into text.

The embedded directives are character sequences prefixed with the '' character. The literal text is simply copied into this descriptor unaltered while the '' directives are used to convert successive arguments from the trailing list. See the description of the Format() function.

Literal text is appended on a character by character basis, and the underlying buffer is grown as necessary to accommodate it.

Text converted from a trailing argument is appended as a complete string, and the underlying buffer is grown as necessary to accommodate it.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Format() TDes8Overflow::Overflow()

Parameters
aFmtThe 8-bit non-modifiable descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER12 if the format string has incorrect syntax.

AppendFormatListL ( const TDesC8 &, VA_LIST )

IMPORT_C voidAppendFormatListL(const TDesC8 &aFmt,
VA_LISTaList
)

Formats and appends text onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The behaviour of this function is the same as AppendFormatL(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...). In practice, it is better and easier to use AppendFormat(), passing a variable number of arguments as required by the format string.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::AppendFormat VA_LIST

Parameters
aFmtThe descriptor containing the format string.
aListA pointer to an argument list.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendJustifyL ( const TDesC8 &, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const TDesC8 &Des,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is an existing descriptor.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

AppendJustifyL ( const TDesC8 &, TInt, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const TDesC8 &Des,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is an existing descriptor.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aLengthThe length of data to be copied from the source descriptor. If this is greater than the width of the target area, then the length of data copied is limited to the width. The length of data to be copied must not be greater than the length of the source descriptor. Note that this condition is not automatically tested.
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

AppendJustifyL ( const TUint8 *, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const TUint8 *aZeroTerminatedString,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends a zero terminated string onto the end of this descriptor's data and justifies it.

The zero terminator is not copied.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA pointer to a zero terminated string The length of the data to be copied is the smaller of: the length of the string (excluding the zero terminator), the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth).
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the zero terminated string (excluding the zero terminator).
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

AppendJustifyL ( const TUint8 *, TInt, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const TUint8 *aString,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is a memory location.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aStringA pointer to a source memory location.
aLengthThe length of data to be copied. If this is greater than the width of the target area, then the length of data copied is limited to the width.
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
anAlignmentThe alignment of the data within the target area.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.
USER17 if aLength is negative.

AppendJustifyL ( const char *, TInt, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const char *aCharStr,
TIntaLength,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is a memory location.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aLengthThe length of data to be copied. If this is greater than the width of the target area, then the length of data copied is limited to the width.
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.
USER17 if aLength is negative.

AppendJustifyL ( const char *, TInt, TAlign, TChar )

IMPORT_C voidAppendJustifyL(const char *aCharStr,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Appends data onto the end of this descriptor's data and justifies it.

The source of the appended data is a memory location.

The target area is considered to be an area of specified width, immediately following this descriptor's existing data. Source data is copied into, and aligned within, this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA pointer to a source memory location.
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.
USER17 if aLength is negative.

AppendL ( TChar )

IMPORT_C voidAppendL(TCharaChar)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::operator+=

Parameters
aCharA single character to be appended. The length of the descriptor is incremented by one.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendL ( const TDesC8 & )

IMPORT_C voidAppendL(const TDesC8 &aDes)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non modifiable descriptor whose data is to be appended.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendL ( const TUint8 *, TInt )

IMPORT_C voidAppendL(const TUint8 *aBuf,
TIntaLength
)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aBufA pointer to the data to be copied.
aLengthThe length of data to be copied.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER17 if aLength is negative.

AppendL ( const TUint8 * )

IMPORT_C voidAppendL(const TUint8 *aZeroTerminatedString)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA pointer to the data to be copied.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER17 if aLength is negative.

AppendL ( const char *, TInt )

IMPORT_C voidAppendL(const char *aCharStr,
TIntaLength
)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA pointer to the data to be copied.
aLengthThe length of data to be copied.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER17 if aLength is negative.

AppendL ( const char * )

IMPORT_C voidAppendL(const char *aCharStr)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA pointer to the data to be copied.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER17 if aLength is negative.

AppendNumFixedWidthL ( TUint, TRadix, TInt )

IMPORT_C voidAppendNumFixedWidthL(TUintaVal,
TRadixaRadix,
TIntaWidth
)

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters to be used to contain the conversion, and to be appended to this descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendNumFixedWidthUCL ( TUint, TRadix, TInt )

IMPORT_C voidAppendNumFixedWidthUCL(TUintaVal,
TRadixaRadix,
TIntaWidth
)

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be appended to this descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendNumL ( TReal, const TRealFormat & )

IMPORT_C TIntAppendNumL(TRealaVal,
const TRealFormat &aFormat
)

Converts the specified floating point number into a character representation and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

The character representation of the real number is dictated by the specified format.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

1.KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.

2.KErrOverflow - the number is too large to represent. 2.1 For positive overflow, the three characters Inf are appended to this descriptor. 2.2 For negative overflow, the four characters -Inf are appended to this descriptor.

3.KErrUnderflow - the number is too small to represent. 3.1 For positive underflow, the three characters Inf are appended to this descriptor. 3.2 For negative underflow, the four characters -Inf are appended to this descriptor.

4.KErrGeneral - the conversion cannot be completed. There are a number of possible reasons for this, but the most common is: 4.1 The character representation format (i.e. the format type), as defined in the TRealFormat object is not recognised.

Parameters
aValThe floating point number to be converted.
aFormatThe format of the conversion.
Return Value
If the conversion is successful, the length of this descriptor. If the conversion fails, a negative value indicating the cause of failure. In addition, extra information on the cause of the failure may be appended onto this descriptor. The possible values and their meaning are:
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendNumL ( TInt64 )

IMPORT_C voidAppendNumL(TInt64aVal)

Converts the 64-bit signed integer into a decimal character representation and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

If the integer is negative, the character representation is prefixed by a minus sign.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64-bit signed integer value.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendNumL ( TUint64, TRadix )

IMPORT_C voidAppendNumL(TUint64aVal,
TRadixaRadix
)

Converts the specified 64 bit integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64 bit integer value. This is always treated as an unsigned value.
aRadixThe number system representation for the 64 bit integer.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

AppendNumUCL ( TUint64, TRadix )

IMPORT_C voidAppendNumUCL(TUint64aVal,
TRadixaRadix = EDecimal
)

Converts the specified 64 bit integer into a character representation based on the specified number system and appends the conversion onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64 bit integer value. This is always treated as an unsigned value.
aRadixThe number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

Assign ( const LString8 & )

IMPORT_C voidAssign(const LString8 &aString)

Unlinks and transfers ownership of the specified 8-bit resizable descriptor's buffer to this object. The source descriptor is detached from the buffer.

Parameters
aStringThe source 8-bit resizable buffer. The ownership of this object's buffer is to be transferred.

Assign ( const RBuf8 & )

IMPORT_C voidAssign(const RBuf8 &aRBuf)

Reimplemented from RBuf8::Assign(const RBuf8 &)

Transfers ownership of the specified 8-bit resizable descriptor's buffer to this object. The source descriptor is detached from the buffer.

See also: RBuf8::Assign()

Parameters
aRBufThe source 8-bit resizable buffer. The ownership of this object's buffer is to be transferred.

Assign ( HBufC8 * )

IMPORT_C voidAssign(HBufC8 *aHBuf)

Reimplemented from RBuf8::Assign(HBufC8 *)

Transfers ownership of the specified 8-bit resizable descriptor's this object.

See also: RBuf8::Assign()

Parameters
aHBufThe heap descriptor to be transferred to this object. The ownership of this object's buffer is to be transferred.

Assign ( TUint8 *, TInt )

IMPORT_C voidAssign(TUint8 *aHeapCell,
TIntaMaxLength
)

Reimplemented from RBuf8::Assign(TUint8 *,TInt)

Assigns ownership of the specified allocated memory to this object.

See also: RBuf8::Assign()

Parameters
aHeapCellThe allocated memory to be assigned to this object. This pointer can be NULL, which means that a zero length 8-bit resizable buffer descriptor is created.
aMaxLengthThe maximum length of the descriptor.
Panic Codes
USER8 If the specified maximum length is greater then the size of the allocated heap cell, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

Assign ( TUint8 *, TInt, TInt )

IMPORT_C voidAssign(TUint8 *aHeapCell,
TIntaLength,
TIntaMaxLength
)

Reimplemented from RBuf8::Assign(TUint8 *,TInt,TInt)

Transfers ownership of the specified 16-bit resizable descriptor's this object.

See also: RBuf8::Assign()

Parameters
aHeapCellThe allocated memory to be assigned to this object.
aLengthThe length of the descriptor.
aMaxLengthThe maximum length of the descriptor.
Panic Codes
USER8 If the specified maximum length is greater then the size of the allocated heap cell, or the specified length is greater then the specified maximum length, or the specified maximum length is NOT zero when the pointer to the heap cell is NULL.

Compare ( const TUint8 * )

IMPORT_C TIntCompare(const TUint8 *aZeroTerminatedString)const

Compares this descriptor's data with the specified string's data.

The comparison proceeds on a byte for byte basis. The result of the comparison is based on the difference of the first bytes to disagree.

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
Positive, if this descriptor is greater than the specified string. Negative, if this descriptor is less than the specified string. Zero, if both the descriptor and the string have the same length and the their contents are the same.

Compare ( const char * )

IMPORT_C TIntCompare(const char *aCharStr)const

Compares this descriptor's data with the specified string's data.

The comparison proceeds on a byte for byte basis. The result of the comparison is based on the difference of the first bytes to disagree.

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
Positive, if this descriptor is greater than the specified string. Negative, if this descriptor is less than the specified string. Zero, if both the descriptor and the string have the same length and the their contents are the same.

CompareF ( const TUint8 * )

IMPORT_C TIntCompareF(const TUint8 *aZeroTerminatedString)const

Compares this descriptor's folded data with the specified string's folded data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for comparing strings in natural language;

See also: TDesC8::Compare()

Parameters
aZeroTerminatedStringThe 8-bit Zero Terminated String whose data is to be compared with this string's data.
Return Value
Positive, if this descriptor is greater than the specified string. Negative, if this descriptor is less than the specified string. Zero, if the descriptor and the specified string have the same length and the their contents are the same.

CompareF ( const char * )

IMPORT_C TIntCompareF(const char *aCharStr)const

Compares this descriptor's folded data with the specified string's folded data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for comparing strings in natural language;

See also: TDesC8::Compare()

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
Positive, if this descriptor is greater than the specified string. Negative, if this descriptor is less than the specified string. Zero, if the descriptor and the specified string have the same length and the their contents are the same.

Compress ( )

IMPORT_C voidCompress()

Re-allocates a smaller descriptor buffer space to the current descriptor length

This may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

If there is insufficient memory to re-allocate the buffer then the descriptor left unchanged

CopyCL ( const TDesC8 & )

IMPORT_C voidCopyCL(const TDesC8 &aDes)

Copies and collates data from the specified descriptor into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non-modifiable descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyCPL ( const TDesC8 & )

IMPORT_C voidCopyCPL(const TDesC8 &aDes)

Copies text from the specified descriptor and capitalises it before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Capitalisation is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non-modifiable descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyCPL ( const TUint8 * )

IMPORT_C voidCopyCPL(const TUint8 *aZeroTerminatedString)

Copies text from the specified string and capitalises it before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Capitalisation is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA 8-bit zero terminated string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyCPL ( const char * )

IMPORT_C voidCopyCPL(const char *aCharStr)

Copies text from the specified string and capitalises it before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Capitalisation is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA 8-bit character string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyFL ( const TDesC8 & )

IMPORT_C voidCopyFL(const TDesC8 &aDes)

Copies and folds data from the specified descriptor into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used when dealing with strings in natural language.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non-modifiable descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyFL ( const TUint8 * )

IMPORT_C voidCopyFL(const TUint8 *aZeroTerminatedString)

Copies and folds data from the specified string into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used when dealing with strings in natural language.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA 8-bit zero terminated string
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyFL ( const char * )

IMPORT_C voidCopyFL(const char *aCharStr)

Copies and folds data from the specified string into this descriptor replacing any existing data.

The length of this descriptor is set to reflect the new data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used when dealing with strings in natural language.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA 8-bit character string
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyL ( const TDesC8 & )

IMPORT_C voidCopyL(const TDesC8 &aDes)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::operator= TDes8::Copy

Parameters
aDesA 8-bit non-modifiable descriptor.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

CopyL ( const TDesC16 & )

IMPORT_C voidCopyL(const TDesC16 &aDes)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Copy

Parameters
aDesA 16-bit non-modifiable descriptor.A 16-bit non-modifiable descriptor. Each double-byte value can only be copied into the corresponding single byte when the double-byte value is less than decimal 256. A double-byte value of 256 or greater cannot be copied and the corresponding single byte is set to a value of decimal 1.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

CopyL ( const TUint8 * )

IMPORT_C voidCopyL(const TUint8 *aZeroTerminatedString)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::operator= TDes8::Copy

Parameters
aZeroTerminatedStringA pointer to a zero-terminated string
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

CopyL ( const TUint8 *, TInt )

IMPORT_C voidCopyL(const TUint8 *aBuf,
TIntaLength
)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set according to the second parameter.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Copy

Parameters
aBufThe start address of data to be copied.
aLengthThe length of data to be copied.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so
Panic Codes
USER11 if aLength is negative.

CopyL ( const char * )

IMPORT_C voidCopyL(const char *aCharStr)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set according to the new parameter.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Copy

Parameters
aCharStrA pointer to a character zero terminated string to be copied.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so
Panic Codes
USER11 if aLength is negative.

CopyLCL ( const TDesC8 & )

IMPORT_C voidCopyLCL(const TDesC8 &aDes)

Copies text from the specified descriptor and converts it to lower case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to lower case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non modifiable descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyLCL ( const TUint8 * )

IMPORT_C voidCopyLCL(const TUint8 *aZeroTerminatedString)

Copies text from the specified string and converts it to lower case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to lower case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA 8-bit zero terminated string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyLCL ( const char * )

IMPORT_C voidCopyLCL(const char *aCharStr)

Copies text from the specified string and converts it to lower case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to lower case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA 8-bit character string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyUCL ( const TDesC8 & )

IMPORT_C voidCopyUCL(const TDesC8 &aDes)

Copies text from the specified descriptor and converts it to upper case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to upper case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non modifiable descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyUCL ( const TUint8 * )

IMPORT_C voidCopyUCL(const TUint8 *aZeroTerminatedString)

Copies text from the specified string and converts it to upper case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to upper case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aZeroTerminatedStringA 8-bit zero terminated string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CopyUCL ( const char * )

IMPORT_C voidCopyUCL(const char *aCharStr)

Copies text from the specified string and converts it to upper case before putting it into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

Conversion to upper case is implemented as appropriate to the current locale.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA 8-bit character string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

CreateL ( RReadStream &, TInt )

IMPORT_C voidCreateL(RReadStream &aStream,
TIntaMaxLength
)

Reimplemented from RBuf8::CreateL(RReadStream &,TInt)

Creates an 8-bit resizable buffer descriptor that has been initialised with data from the specified read stream; leaves on failure.

Data is assigned to the new descriptor from the specified stream. This variant assumes that the stream contains the length of the data followed by the data itself.

The function is implemented by calling the HBufC8::NewL(RReadStream&,TInt) variant and then assigning the resulting heap descriptor using the RBuf8::Assign(HBufC8*) variant. The comments that describe the HBufC8::NewL() variant also apply to this RBuf8::CreateL() function.

The function may leave with one of the system-wide error codes, specifically KErrOverflow, if the length of the data as read from the stream is greater than the upper limit as specified by the aMaxLength parameter.

Parameters
aStreamThe stream from which the data length and the data to be assigned to the new descriptor, are taken.
aMaxLengthThe upper limit on the length of data that the descriptor is to represent. The value of this parameter must be non-negative otherwise the underlying function will panic.

FillL ( TChar, TInt )

IMPORT_C voidFillL(TCharaChar,
TIntaLength
)

Fills the descriptor's data area with the specified character, replacing any existing data.

The descriptor is filled with the specified number of characters, and its length is changed to reflect this.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharThe fill character.
aLengthThe new length of the descriptor and the number of fill characters to be copied into it.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aLength is negative

FillZL ( TInt )

IMPORT_C voidFillZL(TIntaLength)

Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any existing data, and changes its length.

The descriptor is filled with the specified number of binary zeroes. The descriptor's length is changed to reflect this.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aLengthThe new length of the descriptor and the number of binary zeroes to be copied into it.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aLength is negative

Find ( const TUint8 * )

IMPORT_C TIntFind(const TUint8 *aZeroTerminatedString)const

Searches for the first occurrence of the specified data sequence within this descriptor.

Searching always starts at the beginning of this descriptor's data.

Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.

Find ( const char * )

IMPORT_C TIntFind(const char *aCharStr)const

Searches for the first occurrence of the specified data sequence within this descriptor.

Searching always starts at the beginning of this descriptor's data.

Parameters
aCharStrThe 8-bit character string whose data is to be searched for, within this Descriptor's data.
Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.

Find ( const char *, TInt )

IMPORT_C TIntFind(const char *aCharStr,
TIntaLenS
)const

Searches for the first occurrence of the specified data sequence within this descriptor.

Searching always starts at the beginning of this descriptor's data.

Parameters
aCharStrThe 8-bit character string whose data is to be searched for, within this Descriptor's data.
aLenSThe length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a panic.
Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found.
Panic Codes
USER29 if aLenS is negative.

FindF ( const TUint8 * )

IMPORT_C TIntFindF(const TUint8 *aZeroTerminatedString)const

Searches for the first occurrence of the specified folded data sequence within this descriptor's folded data.

Searching always starts at the beginning of this descriptor's data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for finding strings in natural language;

Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found. Zero, if the length of the search data sequence is zero.

FindF ( const char * )

IMPORT_C TIntFindF(const char *aCharStr)const

Searches for the first occurrence of the specified folded data sequence within this descriptor's folded data.

Searching always starts at the beginning of this descriptor's data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for finding strings in natural language;

Parameters
aCharStrThe 8-bit character string whose data is to be searched for, within this Descriptor's data.
Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found. Zero, if the length of the search data sequence is zero.

FindF ( const char *, TInt )

IMPORT_C TIntFindF(const char *aCharStr,
TIntaLenS
)const

Searches for the first occurrence of the specified folded data sequence within this descriptor's folded data.

Searching always starts at the beginning of this descriptor's data.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for finding strings in natural language;

Parameters
aCharStrThe 8-bit character string whose data is to be searched for, within this Descriptor's data.
aLenSThe length of the data sequence to be searched for. This value must not be negative, otherwise the function raises a panic.
Return Value
The offset of the data sequence from the beginning of this descriptor's data. KErrNotFound, if the data sequence cannot be found. Zero, if the length of the search data sequence is zero.
Panic Codes
USER29 if aLenS is negative

FormatL ( TRefByValue< const TDesC8 >, ... )

IMPORT_C voidFormatL(TRefByValue< const TDesC8 >aFmt,
...
)

Formats and copies text into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The function takes a format string and a variable number of arguments. The format string contains literal text embedded with directives for converting the trailing list of arguments into text.

The embedded directives are character sequences prefixed with the '' character. The literal text is simply copied into this descriptor unaltered while the '' directives are used to convert successive arguments from the trailing list.

The resulting stream of literal text and converted arguments is copied into this descriptor.

The syntax of the embedded directives follows one of four general patterns.

Note that formatting of single numerical values can be achieved more conveniently using the Num() and NumUC() member functions of this class.

The full description of the syntax of a format string cannot be included here. For full details, navigate to the Symbian OS guide, and follow the hierarchy of links:

Symbian OS Guide
	Base
		Using  User Library (E32)
			Buffers and Strings
				Using Descriptors
					How to Use Descriptors
						Format string syntax

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Num() TDes8::NumUC()

Parameters
aFmtThe descriptor containing the format string. The TRefByValue class provides a constructor which takes a TDesC8 type.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER12 if the format string has incorrect syntax.

FormatListL ( const TDesC8 &, VA_LIST )

IMPORT_C voidFormatListL(const TDesC8 &aFmt,
VA_LISTaList
)

Formats and copies text into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The behaviour of this function is the same as FormatL(). In practice, it is better and easier to use FormatL(), passing a variable number of arguments as required by the format string.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Format() VA_LIST

Parameters
aFmtThe descriptor containing the format string.
aListA pointer to an argument list.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

InsertL ( TInt, const TDesC8 & )

IMPORT_C voidInsertL(TIntaPos,
const TDesC8 &aDes
)

Inserts data into this descriptor.

The length of this descriptor is changed to reflect the extra data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where insertion is to start. This is an offset value; a zero value refers to the leftmost data position.
aDesA 8-bit non modifiable descriptor whose data is to be inserted.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER10 if aPos is negative or is greater than the length of this descriptor.

InsertL ( TInt, const TUint8 * )

IMPORT_C voidInsertL(TIntaPos,
const TUint8 *aZeroTerminatedString
)

Inserts data into this descriptor.

The length of this descriptor is changed to reflect the extra data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where insertion is to start. This is an offset value; a zero value refers to the leftmost data position.
aZeroTerminatedStringA 8-bit null terminated string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER10 if aPos is negative or is greater than the length of this descriptor.

InsertL ( TInt, const char * )

IMPORT_C voidInsertL(TIntaPos,
const char *aCharStr
)

Inserts data into this descriptor.

The length of this descriptor is changed to reflect the extra data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where insertion is to start. This is an offset value; a zero value refers to the leftmost data position.
aCharStrA 8-bit character string.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER10 if aPos is negative or is greater than the length of this descriptor.

JustifyL ( const TDesC8 &, TInt, TAlign, TChar )

IMPORT_C voidJustifyL(const TDesC8 &aDes,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Copies data into this descriptor and justifies it, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The target area is considered to be an area of specified width positioned at the beginning of this descriptor's data area. Source data is copied into, and aligned within this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesA 8-bit non-modifiable descriptor containing the source data. The length of the data to be copied is the smaller of: the length of the source descriptor, and the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth).
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
anAlignmentThe alignment of the data within the target area
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

JustifyL ( const TUint8 *, TInt, TAlign, TChar )

IMPORT_C voidJustifyL(const TUint8 *aZeroTerminatedString,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Copies data into this descriptor and justifies it, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The target area is considered to be an area of specified width positioned at the beginning of this descriptor's data area. Source data is copied into, and aligned within this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

JustifyL ( const char *, TInt, TAlign, TChar )

IMPORT_C voidJustifyL(const char *aCharStr,
TIntaWidth,
TAlignanAlignment,
TCharaFill
)

Copies data into this descriptor and justifies it, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The target area is considered to be an area of specified width positioned at the beginning of this descriptor's data area. Source data is copied into, and aligned within this target area according to the specified alignment instruction.

If the length of the target area is larger than the length of the source, then spare space within the target area is padded with the fill character.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aCharStrA 8-bit character string containing the source data. The length of the data to be copied is the smaller of: the length of the source descriptor, and the width of the target area (only if this is not the explicit negative value KDefaultJustifyWidth).
aWidthThe width of the target area. If this has the specific negative value KDefaultJustifyWidth, then the width is re-set to the length of the data source.
aFillThe fill character used to pad the target area.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aWidth has a negative value other than KDefaultJustifyWidth.

Match ( const TUint8 * )

IMPORT_C TIntMatch(const TUint8 *aZeroTerminatedString)const

Searches this descriptor's data for a match with the match pattern supplied in the specified string.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be matched with this Descriptor's data.
Return Value
If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

Match ( const char * )

IMPORT_C TIntMatch(const char *aCharStr)const

Searches this descriptor's data for a match with the match pattern supplied in the specified string.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

Parameters
aCharStrThe 8-bit character string whose data is to be matched with this Descriptor's data.
Return Value
If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

MatchF ( const TUint8 * )

IMPORT_C TIntMatchF(const TUint8 *aZeroTerminatedString)const

Searches this descriptor's folded data for a match with the folded match pattern supplied in the specified string.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for matching strings in natural language; use MatchC() for this.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

See also: TDesC8::MatchC()

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be matched with this Descriptor's data.
Return Value
If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

MatchF ( const char * )

IMPORT_C TIntMatchF(const char *aCharStr)const

Searches this descriptor's folded data for a match with the folded match pattern supplied in the specified string.

The match pattern can contain the wildcard characters "*" and "?", where "*" matches zero or more consecutive occurrences of any character and "?" matches a single occurrence of any character.

Note that folding is locale-independent behaviour. It is also important to note that there can be no guarantee that folding is in any way culturally appropriate, and should not be used for matching strings in natural language; use MatchC() for this.

Note that there is no 'escape character', which means that it is not possible to match either the "*" character itself or the "?" character itself using this function.

See also: TDesC8::MatchC()

Parameters
aCharStrThe 8-bit character string whose data is to be matched with this Descriptor's data.
Return Value
If a match is found, the offset within this descriptor's data where the match first occurs. KErrNotFound, if there is no match.

NumFixedWidthL ( TUint, TRadix, TInt )

IMPORT_C voidNumFixedWidthL(TUintaVal,
TRadixaRadix,
TIntaWidth
)

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

This function is equivalent to using Format() with parameters which specify:

1. a fixed length target field

2. padding with zero characters, for example "%08x".

When this is the case, always use NumFixedWidth() in preference to Format() as it is more efficient.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be copied into this descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

NumFixedWidthUCL ( TUint, TRadix, TInt )

IMPORT_C voidNumFixedWidthUCL(TUintaVal,
TRadixaRadix,
TIntaWidth
)

Converts the specified unsigned integer into a fixed width character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The function generates the exact number of specified characters, either padding to the left with character zeroes or discarding low order characters as necessary.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

This function is equivalent to using Format() with parameters which specify:

1. a fixed length target field

2. padding with zero characters, for example "%08x".

When this is the case, always use NumFixedWidthUC() in preference to Format() as it is more efficient.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: TDes8::Format()

Parameters
aValThe unsigned integer value.
aRadixThe number system representation for the unsigned integer.
aWidthThe number of characters: to be used to contain the conversion, to be copied into this descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

NumL ( TReal, const TRealFormat & )

IMPORT_C TIntNumL(TRealaVal,
const TRealFormat &aFormat
)

Converts the specified floating point number into a character representation and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

The character representation of the real number is dictated by the specified format.

Note that the function leaves if the iType data member of the specified TRealFormat object has both an invalid character representation format (i.e. the format type) and invalid format flags.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

1.KErrArgument - the supplied floating point number is not a valid number. The three characters NaN are appended to this descriptor.

2.KErrOverflow - the number is too large to represent. 2.1 For positive overflow, the three characters Inf are appended to this descriptor. 2.2 For negative overflow, the four characters -Inf are appended to this descriptor.

3.KErrUnderflow - the number is too small to represent. 3.1 For positive underflow, the three characters Inf are appended to this descriptor. 3.2 For negative underflow, the four characters -Inf are appended to this descriptor.

4.KErrGeneral - the conversion cannot be completed. There are a number of possible reasons for this, but the most common is: 4.1 The character representation format (i.e. the format type), as defined in the TRealFormat object is not recognised.

See also: TRealFormat::iType

Parameters
aValThe floating point number to be converted.
aFormatThe format of the conversion.
Return Value
If the conversion is successful, the length of this descriptor. If the conversion fails, a negative value indicating the cause of failure. In addition, extra information on the cause of the failure may be appended onto this descriptor. The possible values and their meaning are:
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

NumL ( TInt64 )

IMPORT_C voidNumL(TInt64aVal)

Converts the 64-bit signed integer into a decimal character representation and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

If the integer is negative, the character representation is prefixed by a minus sign.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64-bit signed integer value.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

NumL ( TUint64, TRadix )

IMPORT_C voidNumL(TUint64aVal,
TRadixaRadix
)

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in lower case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64 bit integer value. This is treated as an unsigned value for all builds.
aRadixThe number system representation for the 64 bit integer.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

NumUCL ( TUint64, TRadix )

IMPORT_C voidNumUCL(TUint64aVal,
TRadixaRadix = EDecimal
)

Converts the specified 64 bit unsigned integer into a character representation based on the specified number system and copies the conversion into this descriptor, replacing any existing data.

The length of this descriptor is set to reflect the new data.

When a hexadecimal conversion is specified, hexadecimal characters are in upper case.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aValThe 64 bit integer value. This is always treated as an unsigned value for all builds.
aRadixThe number system representation for the 64 bit integer. If no explicit value is specified, then EDecimal is the default.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

PtrZL ( )

IMPORT_C const TUint8 *PtrZL()

Appends a zero terminator onto the end of this descriptor's data and returns a pointer to the data.

The length of the descriptor is not changed, but the capacity of the descriptor may need to be grown to accommodate the zero terminator.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Return Value
A pointer to the descriptor's zero terminated data.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

ReplaceL ( TInt, TInt, const TDesC8 & )

IMPORT_C voidReplaceL(TIntaPos,
TIntaLength,
const TDesC8 &aDes
)

Replaces data in this descriptor.

The specified length can be different to the length of the replacement data. The length of this descriptor changes to reflect the change of data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where replacement is to start. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe length of data to be replaced.
aDesThe source 8-bit non modifiable descriptor whose data is to replace the target descriptor's data at aPos.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER8 if aLength is negative
USER10 if aPos is negative or is greater than the length of this descriptor.
USER16 if the length of the source descriptor aDes is negative

ReplaceL ( TInt, TInt, const TUint8 * )

IMPORT_C voidReplaceL(TIntaPos,
TIntaLength,
const TUint8 *aZeroTerminatedString
)

Replaces data in this descriptor.

The specified length can be different to the length of the replacement data. The length of this descriptor changes to reflect the change of data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where replacement is to start. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe length of data to be replaced.
aZeroTerminatedStringThe source 8-bit null terminated character string
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER8 if aLength is negative
USER10 if aPos is negative or is greater than the length of this descriptor.
USER16 if the length of the source descriptor aDes is negative

ReplaceL ( TInt, TInt, const char * )

IMPORT_C voidReplaceL(TIntaPos,
TIntaLength,
const char *aCharStr
)

Replaces data in this descriptor.

The specified length can be different to the length of the replacement data. The length of this descriptor changes to reflect the change of data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aPosThe position within the data where replacement is to start. This is an offset value; a zero value refers to the leftmost data position.
aLengthThe length of data to be replaced.
aCharStrThe source 8-bit character string
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER8 if aLength is negative
USER10 if aPos is negative or is greater than the length of this descriptor.
USER16 if the length of the source descriptor aDes is negative

ReserveFreeCapacityL ( TInt )

IMPORT_C voidReserveFreeCapacityL(TIntaExtraSpaceLength)

Ensures that the remaining unused space is more than the supplied value.

May reallocate a larger storage space to meet the requirement. As a result MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Typically, you use this method to reserve a known amount of required space in one go instead of relying on the automatic growth pattern.

Parameters
aExtraSpaceLengthThe extra space required.
Leave Codes
KErrNoMemoryif the the buffer needs to be reallocated and there are insufficient resources to do so.
Panic Codes
USER11 if aLength is negative

Reset ( )

IMPORT_C voidReset()

Re-initialises the descriptor destroying its payload

SetLengthL ( TInt )

IMPORT_C voidSetLengthL(TIntaLength)

Sets the length of the data represented by the string descriptor to the specified value.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aLengthThe new length of the descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if aLength is negative

SetMaxLengthL ( TInt )

IMPORT_C voidSetMaxLengthL(TIntaMaxLength)

Sets the storage space allocated to this descriptor to the specified value by growing or compressing its buffer size.

If the current length of the descriptor is greater than the specified max length, length is truncated to max length.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aMaxLengthThe new maximum length of the descriptor.
Leave Codes
KErrNoMemoryif the the buffer needs to be reallocated and there are insufficient resources to do so
Panic Codes
USER11 if aLength is negative

SwapL ( TDes8 & )

IMPORT_C voidSwapL(TDes8 &aDes)

Swaps the data represented by this descriptor with the data represented by the specified descriptor.

The lengths of both descriptors are also swapped to reflect the change.

Note that each descriptor must be capable of accommodating the contents of the other descriptor.

Each descriptor must be capable of accommodating the contents of the other descriptor. If the maximum length of the descriptor parameter is smaller than the length of the target LString8, then the function raises a USER 11 panic. The target LString8 will be grown if necessary to accommodate the descriptor parameter's data.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesThe 8-bit modifiable descriptor whose data is to be swapped with the data of this descriptor.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so
Panic Codes
USER11 if the maximum length of the descriptor parameter is smaller than the length of the target

SwapL ( LString8 & )

IMPORT_C voidSwapL(LString8 &aDes)

Swaps the data represented by this string descriptor with the data represented by the specified string descriptor.

The lengths of both string descriptors are also swapped to reflect the change, and their buffers grown as necessary to accommodate the data they receive.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Parameters
aDesThe 8-bit modifiable string descriptor whose data is to be swapped with the data of this descriptor.
Leave Codes
KErrNoMemoryif one of the underlying buffers needs to be grown and there are insufficient resources to do so

ZeroTerminateL ( )

IMPORT_C voidZeroTerminateL()

Appends a zero terminator onto the end of this descriptor's data.

The length of the descriptor is not changed, but the capacity of the descriptor may need to be grown to accommodate the zero terminator.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

operator delete ( TAny * )

voidoperator delete(TAny *aPtr)[static, inline]

operator delete ( TAny *, TLeave )

voidoperator delete(TAny *aPtr,
TLeave
)[static, inline]

operator delete ( TAny *, TAny * )

voidoperator delete(TAny *,
TAny *
)[static, inline]

operator!= ( const TUint8 * )

IMPORT_C TBooloperator!=(const TUint8 *aZeroTerminatedString)const

Determines whether this descriptor's data is not equal to the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is not equal to the specified string's data

operator!= ( const char * )

IMPORT_C TBooloperator!=(const char *aCharStr)const

Determines whether this descriptor's data is not equal to the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is not equal to the specified string's data

operator+= ( TChar )

IMPORT_C LString8 &operator+=(TCharaChar)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::AppendL

Parameters
aCharA single character to be appended. The length of the descriptor is incremented by one.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

operator+= ( const TDesC8 & )

IMPORT_C LString8 &operator+=(const TDesC8 &aDes)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::AppendL

Parameters
aDesA 8-bit non modifiable descriptor whose data is to be appended.
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

operator+= ( const TUint8 * )

IMPORT_C LString8 &operator+=(const TUint8 *aZeroTerminatedString)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::AppendL

Parameters
aZeroTerminatedStringA pointer to a zero terminated string .
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

operator+= ( const char * )

IMPORT_C LString8 &operator+=(const char *aCharStr)

Appends data onto the end of this descriptor's data.

The length of this descriptor is incremented to reflect the new content.

This leaving variant of the standard, non-leaving descriptor method differs in that this operation may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

See also: LString8::AppendL

Parameters
aCharStrA pointer to a character zero terminated string .
Leave Codes
KErrNoMemoryif the underlying buffer needs to be grown and there are insufficient resources to do so

operator< ( const TUint8 * )

IMPORT_C TBooloperator<(const TUint8 *aZeroTerminatedString)const

Determines whether this descriptor's data is less than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is less than that of the specified string's data

operator< ( const char * )

IMPORT_C TBooloperator<(const char *aCharStr)const

Determines whether this descriptor's data is less than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is less than that of the specified string's data

operator<= ( const TUint8 * )

IMPORT_C TBooloperator<=(const TUint8 *aZeroTerminatedString)const

Determines whether this descriptor's data is less than/equal to the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is less than/equal to that of the specified string's data

operator<= ( const char * )

IMPORT_C TBooloperator<=(const char *aCharStr)const

Determines whether this descriptor's data is less than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is less than that of the specified string's data

operator= ( const TDesC8 & )

IMPORT_C LString8 &operator=(const TDesC8 &aDes)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This operation may cause the target string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Note that the automatic resizing performed is a change to the functionality of this operation compared to other descriptor classes. This change is only active on objects directly declared LString8; when LString8 instances are instead manipulated via references to TDes8 or TDesC8, the standard (non-resizing, panicing) variant is invoked.

@leave KErrNoMemory If the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

See also: LString8::CopyL

Parameters
aDesA 8-bit non-modifiable descriptor.
Return Value
A reference to this 8-bit string descriptor.

operator= ( const LString8 & )

IMPORT_C LString8 &operator=(const LString8 &aDes)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This operation may cause the target string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Note that the automatic resizing performed is a change to the functionality of this operation compared to other descriptor classes. This change is only active on objects directly declared LString8; when LString8 instances are instead manipulated via references to TDes8 or TDesC8, the standard (non-resizing, panicing) variant is invoked.

See also: LString8::CopyL

Parameters
aDesA 8-bit string descriptor.
Return Value
A reference to this 8-bit string descriptor.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

operator= ( const TUint8 * )

IMPORT_C LString8 &operator=(const TUint8 *aZeroTerminatedString)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This operation may cause the target string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Note that the automatic resizing performed is a change to the functionality of this operation compared to other descriptor classes. This change is only active on objects directly declared LString8; when LString8 instances are instead manipulated via references to TDes8 or TDesC8, the standard (non-resizing, panicing) variant is invoked.

See also: LString8::CopyL

Parameters
aZeroTerminatedStringA pointer to a zero-terminated string
Return Value
A reference to this 8-bit string descriptor.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

operator= ( HBufC8 * )

IMPORT_C LString8 &operator=(HBufC8 *aHBuf)

Transfers ownership of the specified 8-bit descriptor to this object.

See also: Assign()

Parameters
aHBufThe source 8-bit buffer. The ownership of this object's buffer is to be transferred.

operator= ( const char * )

IMPORT_C LString8 &operator=(const char *aCharStr)

Copies data into this 8-bit string descriptor, replacing any existing data, and expanding its heap buffer to accommodate if necessary.

The length of this descriptor is set to reflect the new data.

This operation may cause the target string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated.

Note that the automatic resizing performed is a change to the functionality of this operation compared to other descriptor classes. This change is only active on objects directly declared LString8; when LString8 instances are instead manipulated via references to TDes8 or TDesC8, the standard (non-resizing, panicing) variant is invoked.

See also: LString8::CopyL

Parameters
aCharStrA pointer to a character zero-terminated string
Return Value
A reference to this 8-bit string descriptor.
Leave Codes
KErrNoMemoryIf the heap buffer of the string descriptor being assigned to needs to be expanded, but there is insufficient memory to do so

operator== ( const TUint8 * )

IMPORT_C TBooloperator==(const TUint8 *aZeroTerminatedString)const

Determines whether this Descriptor's data is equal to the specified string's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if equal, false otherwise.

operator== ( const char * )

IMPORT_C TBooloperator==(const char *aCharStr)const

Determines whether this Descriptor's data is equal to the specified string's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if equal, false otherwise.

operator> ( const TUint8 * )

IMPORT_C TBooloperator>(const TUint8 *aZeroTerminatedString)const

Determines whether this descriptor's data is greater than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is greater than that of the specified string's data

operator> ( const char * )

IMPORT_C TBooloperator>(const char *aCharStr)const

Determines whether this descriptor's data is greater than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is greater than that of the specified string's data

operator>= ( const TUint8 * )

IMPORT_C TBooloperator>=(const TUint8 *aZeroTerminatedString)const

Determines whether this descriptor's data is greater than the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aZeroTerminatedStringThe 8-bit Zero TerminatedString string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is greater than that of the specified string's data

operator>= ( const char * )

IMPORT_C TBooloperator>=(const char *aCharStr)const

Determines whether this descriptor's data is greater than/equal to the specified strings's data.

The comparison is implemented internally using the TDesC8::Compare() function.

See also: TDesC8::Compare

Parameters
aCharStrThe 8-bit character string whose data is to be compared with this Descriptor's data.
Return Value
True if this descriptor's data is greater than/equal to that of the specified string's data