sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // sl@0: sl@0: #include sl@0: #include sl@0: sl@0: const TUint KDefaultExpandSize = 16; sl@0: sl@0: sl@0: /** sl@0: Aligns the supplied capacity to the nearest growth factor sl@0: sl@0: For performance reasons the growth factor, KDefaultExpandSizeShift, sl@0: is expressed as an exponent of 2 so shifting can be used to achieve the sl@0: alignment. sl@0: sl@0: a KDefaultExpandSizeShift value of 4 is equivalent to 16; sl@0: giving newCapacity = ((newCapacity / 16) + 1) * 16 sl@0: sl@0: @param aNewCapacity The size to be aligned sl@0: sl@0: @return The new, aligned capacity sl@0: */ sl@0: static inline TInt AlignCapacity(TInt aNewCapacity) sl@0: { sl@0: const TUint KDefaultExpandSizeShift = 4; sl@0: sl@0: return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift); sl@0: } sl@0: sl@0: /** sl@0: Guarantees that MaxLength() is greater than or equal to the supplied sl@0: capacity, reallocating the supplied capacity if necessary. sl@0: sl@0: The actual value of MaxLength() after a call may differ from the exact sl@0: value requested, but if it does differ it will always be greater. This sl@0: flexibility allows the implementation to manage heap buffers more sl@0: efficiently. sl@0: sl@0: The string descriptor's heap buffer may be reallocated in order to sl@0: accommodate the new size. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aMinRequiredCapacity The minimum value of MaxLength() required sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: void LString16::ReserveL(TInt aMinRequiredCapacity) sl@0: { sl@0: if (MaxLength() < aMinRequiredCapacity) sl@0: { sl@0: ReAllocL(AlignCapacity(aMinRequiredCapacity)); sl@0: } sl@0: } sl@0: sl@0: sl@0: /** sl@0: Guarantees that MaxLength() is greater than or equal to the supplied sl@0: integer parameter, growing the underlying heap buffer if necessary. sl@0: sl@0: The growth is exponential; maxLength *= 1.5 sl@0: This is reported to give an amortised complexity of O(n) when adding sl@0: n characters. sl@0: If the required capacity is larger than the expanded size then the sl@0: required capacity is used instead. sl@0: sl@0: The actual value of MaxLength() after a call may differ from the exact sl@0: value requested, but if it does differ it will always be greater. This sl@0: flexibility allows the implementation to manage heap buffers more sl@0: efficiently. sl@0: sl@0: @param aRequiredCapacity The minimum value of MaxLength() required sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: void LString16::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity) sl@0: { sl@0: //work in unsigned int for the appropriate shift operation sl@0: TUint max_length = MaxLength(); sl@0: TUint requiredCapacity = aRequiredCapacity; sl@0: sl@0: if (max_length < requiredCapacity) sl@0: { sl@0: // max_length *= 3/2; sl@0: max_length = (max_length + (max_length << 1)) >> 1; sl@0: sl@0: // take the bigger of the extended buffer or the required capactiy sl@0: ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity))); sl@0: } sl@0: } sl@0: sl@0: /** sl@0: Guarantees that free space in the buffer greater than or equal the sl@0: supplied integer parameter, growing the underlying heap buffer sl@0: if necessary. sl@0: sl@0: @param aRequiredEmptySpace The minimum value of free space required sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: void LString16::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace) sl@0: { sl@0: ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace); sl@0: } sl@0: sl@0: /** sl@0: Grows the underlying buffer using the exponential growth sl@0: function. Guarantees that MaxLength() is greater than or sl@0: equal to 1.5 * the current MaxLength. sl@0: sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: void LString16::ReserveCapacityGrowExponentialL() sl@0: { sl@0: ReserveCapacityGrowExponentialL(MaxLength() + 1); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Default constructor. sl@0: sl@0: Constructs a zero-length 16-bit resizable string descriptor. sl@0: sl@0: Note that the resulting object owns no allocated memory yet. This sl@0: default constructor never leaves. sl@0: */ sl@0: EXPORT_C LString16::LString16() sl@0: : iReserved(0) sl@0: { sl@0: } sl@0: sl@0: /** sl@0: Destructor. sl@0: sl@0: Frees any heap-allocated resources owned by this string descriptor. It sl@0: is safe to rely on this destructor to perform all necessary cleanup; sl@0: it is not necessary use the cleanup stack or to call Close() manually. sl@0: sl@0: @see RBuf16::Close sl@0: */ sl@0: EXPORT_C LString16::~LString16() sl@0: { sl@0: RBuf16::Close(); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor with an sl@0: initial capacity. sl@0: sl@0: The function allocates sufficient memory to contain descriptor data up to sl@0: the specified initial maximum length. sl@0: sl@0: The current length of the descriptor is set to zero. The maximum length of sl@0: the descriptor is set to the specified value. sl@0: sl@0: @param aMaxLength The maximum length of the descriptor. sl@0: sl@0: @leave KErrNoMemory If there is insufficient memory. sl@0: sl@0: @see RBuf16::CreateL sl@0: */ sl@0: EXPORT_C LString16::LString16(TInt aMaxLength) sl@0: : iReserved(0) sl@0: { sl@0: RBuf16::CreateL(aMaxLength); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor from a sl@0: pre-allocated heap descriptor. sl@0: sl@0: Transfers ownership of the specified heap descriptor to this object. sl@0: sl@0: @param aHBuf The heap descriptor to be transferred to this object. sl@0: This pointer can be NULL, which means that a zero length sl@0: 16-bit resizable string descriptor is created. sl@0: sl@0: @see RBuf16::RBuf16(HBufC16*) sl@0: */ sl@0: EXPORT_C LString16::LString16(HBufC16* aHBuf) sl@0: : iReserved(0) sl@0: { sl@0: if (aHBuf) sl@0: RBuf16::Assign (aHBuf); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor from a sl@0: pre-allocated raw heap buffer. sl@0: sl@0: The allocated memory forms the buffer for this string descriptor. The sl@0: current length of the descriptor is set to zero. sl@0: sl@0: @param aHeapCell The allocated memory to be assigned to this object. This sl@0: pointer can be NULL, which means that a zero length 16-bit sl@0: resizable buffer descriptor is created. sl@0: @param aMaxLength The maximum length of the constructed string descriptor. sl@0: sl@0: @panic USER 8 If the specified maximum length is greater then the size of sl@0: the allocated heap cell, or the specified maximum length sl@0: is NOT zero when the pointer to the heap cell is NULL. sl@0: sl@0: @see RBuf16::Assign() sl@0: */ sl@0: EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aMaxLength) sl@0: : iReserved(0) sl@0: { sl@0: RBuf16::Assign(aHeapCell, aMaxLength); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor from a sl@0: pre-allocated raw heap buffer. sl@0: sl@0: The allocated memory forms the buffer for this string descriptor. The sl@0: current length of the descriptor is set to the value of the second sl@0: parameter. sl@0: sl@0: @param aHeapCell The allocated memory to be assigned to this object. sl@0: @param aLength The length of the resulting string descriptor. sl@0: @param aMaxLength The maximum length of the resulting string descriptor. sl@0: sl@0: @panic USER 8 If the specified maximum length is greater then the size of sl@0: the allocated heap cell, or the specified length is greater then sl@0: the specified maximum length, or the specified maximum length sl@0: is NOT zero when the pointer to the heap cell is NULL. sl@0: sl@0: @see RBuf16::Assign() sl@0: */ sl@0: EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aLength,TInt aMaxLength) sl@0: : iReserved(0) sl@0: { sl@0: RBuf16::Assign(aHeapCell, aLength, aMaxLength); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor to contain sl@0: a copy of the specified (source) descriptor, or leave on failure. sl@0: sl@0: The constructor allocates sufficient memory so that this string sl@0: descriptor's maximum length is the same as the length of the source sl@0: descriptor. Both the current length and the maximum length of this sl@0: string descriptor are set to the length of the source descriptor. sl@0: sl@0: The data contained in the source descriptor is copied into this string sl@0: descriptor. sl@0: sl@0: @param aDes Source descriptor to be copied into this object. sl@0: sl@0: @leave KErrNoMemory If there is insufficient memory. sl@0: sl@0: @see RBuf16::CreateL() sl@0: */ sl@0: EXPORT_C LString16::LString16(const TDesC16& aDes) sl@0: : iReserved(0) sl@0: { sl@0: RBuf16::CreateL(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This operation may cause the target string descriptor's heap buffer to sl@0: be reallocated in order to accommodate the new data. As a result, sl@0: MaxLength() and Ptr() may return different values afterwards, and any sl@0: existing raw pointers to into the descriptor data may be invalidated. sl@0: sl@0: Note that the automatic resizing performed is a change to the sl@0: functionality of this operation compared to other descriptor sl@0: classes. This change is only active on objects directly declared sl@0: LString16; when LString16 instances are instead manipulated via sl@0: references to TDes16 or TDesC16, the standard (non-resizing, panicing) sl@0: variant is invoked. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor. sl@0: sl@0: @return A reference to this 16-bit string descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator=(const TDesC16& aDes) sl@0: { sl@0: CopyL(aDes); sl@0: return *this; sl@0: } sl@0: sl@0: sl@0: /** sl@0: Transfers ownership of the specified 16-bit resizable descriptor's this object. sl@0: sl@0: @param aBuf The source 16-bit resizable buffer. The ownership of this sl@0: object's buffer is to be transferred. sl@0: sl@0: @return A reference to this 16-bit string descriptor. sl@0: sl@0: @see Assign() sl@0: */ sl@0: EXPORT_C LString16& LString16::operator=(HBufC16* aBuf) sl@0: { sl@0: Assign(aBuf); sl@0: return *this; sl@0: } sl@0: sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::operator= sl@0: @see TDes16::Copy sl@0: */ sl@0: EXPORT_C void LString16::CopyL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::Copy(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copy constructor to create a 16-bit resizable string descriptor to sl@0: contain a copy of the specified (source) string descriptor's data, or sl@0: leave on failure. sl@0: sl@0: The constructor allocates sufficient memory so that this string sl@0: descriptor's maximum length is the same as the length of the source sl@0: string descriptor. Both the current length and the maximum length of sl@0: this string descriptor are set to the length of the source descriptor. sl@0: sl@0: The data contained in the source string descriptor is copied into this sl@0: string descriptor. sl@0: sl@0: @param aDes Source string descriptor to be copied into this object. sl@0: sl@0: @leave KErrNoMemory If there is insufficient memory. sl@0: sl@0: @see RBuf16::CreateL() sl@0: */ sl@0: EXPORT_C LString16::LString16(const LString16& aDes) sl@0: : iReserved(0) sl@0: { sl@0: RBuf16::CreateL(aDes); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This operation may cause the target string descriptor's heap buffer to sl@0: be reallocated in order to accommodate the new data. As a result, sl@0: MaxLength() and Ptr() may return different values afterwards, and any sl@0: existing raw pointers to into the descriptor data may be invalidated. sl@0: sl@0: Note that the automatic resizing performed is a change to the sl@0: functionality of this operation compared to other descriptor sl@0: classes. This change is only active on objects directly declared sl@0: LString16; when LString16 instances are instead manipulated via sl@0: references to TDes16 or TDesC16, the standard (non-resizing, panicing) sl@0: variant is invoked. sl@0: sl@0: @param aDes A 16-bit string descriptor. sl@0: sl@0: @return A reference to this 16-bit string descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator=(const LString16& aDes) sl@0: { sl@0: CopyL(aDes); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor containing sl@0: a copy of the specified (source) zero-terminated string data, or leave sl@0: on failure. sl@0: sl@0: The constructor allocates sufficient memory so that this string sl@0: descriptor's maximum length is the same as the length of the source sl@0: string. Both the current length and the maximum length of this string sl@0: descriptor are set to the length of the source string. sl@0: sl@0: The data contained in the source string is copied into this string sl@0: descriptor. The zero terminator is not copied. sl@0: sl@0: @param aZeroTerminatedString A pointer to a zero-terminated string sl@0: sl@0: @leave KErrNoMemory If there is insufficient memory. sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16::LString16(const TUint16* aZeroTerminatedString) sl@0: : iReserved(0) sl@0: { sl@0: CopyL(aZeroTerminatedString); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This operation may cause the target string descriptor's heap buffer to sl@0: be reallocated in order to accommodate the new data. As a result, sl@0: MaxLength() and Ptr() may return different values afterwards, and any sl@0: existing raw pointers to into the descriptor data may be invalidated. sl@0: sl@0: Note that the automatic resizing performed is a change to the sl@0: functionality of this operation compared to other descriptor sl@0: classes. This change is only active on objects directly declared sl@0: LString16; when LString16 instances are instead manipulated via sl@0: references to TDes16 or TDesC16, the standard (non-resizing, panicing) sl@0: variant is invoked. sl@0: sl@0: @param aZeroTerminatedString A pointer to a zero-terminated string sl@0: sl@0: @return A reference to this 16-bit string descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator=(const TUint16* aZeroTerminatedString) sl@0: { sl@0: CopyL(aZeroTerminatedString); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A pointer to a zero-terminated string sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::operator= sl@0: @see TDes16::Copy sl@0: */ sl@0: EXPORT_C void LString16::CopyL(const TUint16* aZeroTerminatedString) sl@0: { sl@0: ReserveL(User::StringLength(aZeroTerminatedString)); sl@0: RBuf16::Copy(aZeroTerminatedString); sl@0: } sl@0: sl@0: /** sl@0: Copies 8-bit descriptor data into this 16-bit string descriptor, sl@0: replacing any existing data, and expanding its heap buffer to sl@0: accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Each 8-bit character value is widened to a 16-bit character value as sl@0: part of the copying process. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes An 8 bit non modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::operator= sl@0: @see TDes16::Copy sl@0: */ sl@0: EXPORT_C void LString16::CopyL(const TDesC8& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::Copy(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set according to the second sl@0: parameter. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aBuf The start address of data to be copied. sl@0: @param aLength The length of data to be copied. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @panic USER 11 if aLength is negative. sl@0: sl@0: @see TDes16::Copy sl@0: */ sl@0: EXPORT_C void LString16::CopyL(const TUint16* aBuf,TInt aLength) sl@0: { sl@0: ReserveL(aLength); sl@0: RBuf16::Copy(aBuf, aLength); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Sets the length of the data represented by the string descriptor to sl@0: the specified value. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aLength The new length of the descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::SetLengthL(TInt aLength) sl@0: { sl@0: ReserveL(aLength); sl@0: RBuf16::SetLength(aLength); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Sets the storage space allocated to this descriptor to the specified sl@0: value by growing or compressing its buffer size. sl@0: sl@0: If the current length of the descriptor is greater than the specified sl@0: max length, length is truncated to max length. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aMaxLength The new maximum length of the descriptor. sl@0: sl@0: @leave KErrNoMemory if the the buffer needs to be sl@0: reallocated and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::SetMaxLengthL(TInt aMaxLength) sl@0: { sl@0: if (MaxLength() == aMaxLength) sl@0: { sl@0: return; sl@0: } sl@0: sl@0: if (Length() > aMaxLength) sl@0: { sl@0: // truncate the current length sl@0: RBuf16::SetLength(aMaxLength); sl@0: } sl@0: sl@0: ReAllocL(aMaxLength); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Ensures that the remaining unused space is more than the supplied value. sl@0: sl@0: May reallocate a larger storage space to meet the requirement. sl@0: As a result MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: Typically, you use this method to reserve a known amount of required space sl@0: in one go instead of relying on the automatic growth pattern. sl@0: sl@0: @param aExtraSpaceLength The extra space required. sl@0: sl@0: @leave KErrNoMemory if the the buffer needs to be sl@0: reallocated and there are insufficient resources to do so. sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::ReserveFreeCapacityL(TInt aExtraSpaceLength) sl@0: { sl@0: ReserveL(Length() + aExtraSpaceLength); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Re-initialises the descriptor destroying its payload sl@0: sl@0: */ sl@0: EXPORT_C void LString16::Reset() sl@0: { sl@0: RBuf16::Close(); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Re-allocates a smaller descriptor buffer space to the current sl@0: descriptor length sl@0: sl@0: This may cause the string descriptor's heap buffer to be reallocated sl@0: in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: If there is insufficient memory to re-allocate the buffer then the sl@0: descriptor left unchanged sl@0: */ sl@0: EXPORT_C void LString16::Compress() sl@0: { sl@0: TInt length = Length(); sl@0: if (MaxLength() > length) sl@0: { sl@0: ReAlloc(length); sl@0: } sl@0: } sl@0: sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aChar A single character to be appended. The length of the descriptor sl@0: is incremented by one. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see LString16::operator+= sl@0: */ sl@0: EXPORT_C void LString16::AppendL(TChar aChar) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(1); sl@0: RBuf16::Append(aChar); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aChar A single character to be appended. The length of the descriptor sl@0: is incremented by one. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see LString16::AppendL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator+=(TChar aChar) sl@0: { sl@0: AppendL(aChar); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non modifiable descriptor whose data is to be appended. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::AppendL(const TDesC16& aDes) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aDes.Length()); sl@0: RBuf16::Append(aDes); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non modifiable descriptor whose data is to be appended. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see LString16::AppendL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator+=(const TDesC16& aDes) sl@0: { sl@0: AppendL(aDes); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aBuf A pointer to the data to be copied. sl@0: @param aLength The length of data to be copied. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendL(const TUint16* aBuf,TInt aLength) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aLength); sl@0: RBuf16::Append(aBuf, aLength); sl@0: } sl@0: sl@0: /** sl@0: Fills the descriptor's data area with the specified character, replacing any sl@0: existing data. sl@0: sl@0: The descriptor is filled with the specified number of characters, sl@0: and its length is changed to reflect this. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aChar The fill character. sl@0: @param aLength The new length of the descriptor and the number of fill characters sl@0: to be copied into it. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::FillL(TChar aChar,TInt aLength) sl@0: { sl@0: ReserveL(aLength); sl@0: RBuf16::Fill(aChar, aLength); sl@0: } sl@0: sl@0: /** sl@0: Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any sl@0: existing data, and changes its length. sl@0: sl@0: The descriptor is filled with the specified number of binary zeroes. sl@0: The descriptor's length is changed to reflect this. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aLength The new length of the descriptor and the number of binary zeroes sl@0: to be copied into it. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::FillZL(TInt aLength) sl@0: { sl@0: ReserveL(aLength); sl@0: RBuf16::FillZ(aLength); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified unsigned integer into a fixed width character sl@0: representation based on the specified number system and copies the conversion sl@0: into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The function generates the exact number of specified characters, either padding sl@0: to the left with character zeroes or discarding low order characters as necessary. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: lower case. sl@0: sl@0: This function is equivalent to using Format() with parameters which specify: sl@0: sl@0: 1. a fixed length target field sl@0: sl@0: 2. padding with zero characters, for example "%08x". sl@0: sl@0: When this is the case, always use NumFixedWidth() in preference sl@0: to Format() as it is more efficient. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The unsigned integer value. sl@0: @param aRadix The number system representation for the unsigned integer. sl@0: @param aWidth The number of characters: to be used to contain the conversion, sl@0: to be copied into this descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth) sl@0: { sl@0: Zero(); sl@0: AppendNumFixedWidthL(aVal, aRadix, aWidth); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified unsigned integer into a fixed width character sl@0: representation based on the specified number system and appends the conversion sl@0: onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: The function generates the exact number of specified characters, either padding sl@0: to the left with character zeroes or discarding low order characters as sl@0: necessary. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: lower case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The unsigned integer value. sl@0: @param aRadix The number system representation for the unsigned integer. sl@0: @param aWidth The number of characters to be used to contain the conversion, sl@0: and to be appended to this descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aWidth); sl@0: RBuf16::AppendNumFixedWidth(aVal, aRadix, aWidth); sl@0: } sl@0: sl@0: /** sl@0: Appends a zero terminator onto the end of this descriptor's data and returns sl@0: a pointer to the data. sl@0: sl@0: The length of the descriptor is not changed, but the capacity of the sl@0: descriptor may need to be grown to accommodate the zero terminator. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @return A pointer to the descriptor's zero terminated data. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C const TUint16 *LString16::PtrZL() sl@0: { sl@0: ReserveFreeCapacityL(1); sl@0: return RBuf16::PtrZ(); sl@0: } sl@0: sl@0: /** sl@0: Copies and folds data from the specified descriptor into this descriptor replacing sl@0: any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new sl@0: data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used when dealing with strings in natural sl@0: language. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::CopyFL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::CopyF(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies and collates data from the specified descriptor sl@0: into this descriptor replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::CopyCL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::CopyC(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified descriptor and converts it to lower case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to lower case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::CopyLCL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::CopyLC(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified descriptor and converts it to upper case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to upper case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::CopyUCL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::CopyUC(aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified descriptor and capitalises it before putting sl@0: it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Capitalisation is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::CopyCPL(const TDesC16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: RBuf16::CopyCP(aDes); sl@0: } sl@0: sl@0: /** sl@0: Appends and fills this descriptor with the specified character. sl@0: sl@0: The descriptor is appended with the specified number of characters. sl@0: and its length is changed to reflect this. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aChar The fill character. sl@0: @param aLength The number of fill characters to be appended. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aLength is negative sl@0: */ sl@0: EXPORT_C void LString16::AppendFillL(TChar aChar,TInt aLength) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aLength); sl@0: RBuf16::AppendFill(aChar, aLength); sl@0: } sl@0: sl@0: /** sl@0: Appends a zero terminator onto the end of this descriptor's data. sl@0: sl@0: The length of the descriptor is not changed, but the capacity of the sl@0: descriptor may need to be grown to accommodate the zero terminator. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::ZeroTerminateL() sl@0: { sl@0: ReserveFreeCapacityL(1); sl@0: RBuf16::ZeroTerminate(); sl@0: } sl@0: sl@0: /** sl@0: Swaps the data represented by this descriptor with the data represented by sl@0: the specified descriptor. sl@0: sl@0: The lengths of both descriptors are also swapped to reflect the change. sl@0: sl@0: Note that each descriptor must be capable of accommodating the contents of sl@0: the other descriptor. sl@0: sl@0: Each descriptor must be capable of accommodating the contents of the sl@0: other descriptor. If the maximum length of the descriptor parameter is sl@0: smaller than the length of the target LString16, then the function sl@0: raises a USER 11 panic. The target LString16 will be grown if sl@0: necessary to accommodate the descriptor parameter's data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes The 16-bit modifiable descriptor whose data is to be swapped with sl@0: the data of this descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if the maximum length of the descriptor parameter is smaller than the sl@0: length of the target LString16 sl@0: */ sl@0: EXPORT_C void LString16::SwapL(TDes16& aDes) sl@0: { sl@0: ReserveL(aDes.Length()); sl@0: TDes16::Swap(aDes); sl@0: } sl@0: sl@0: /** sl@0: Swaps the data represented by this string descriptor with the data sl@0: represented by the specified string descriptor. sl@0: sl@0: The lengths of both string descriptors are also swapped to reflect the sl@0: change, and their buffers grown as necessary to accommodate the data sl@0: they receive. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes The 16-bit modifiable string descriptor whose data is to be swapped with sl@0: the data of this descriptor. sl@0: sl@0: @leave KErrNoMemory if one of the underlying buffers needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::SwapL(LString16& aDes) sl@0: { sl@0: this->ReserveL(aDes.Length()); sl@0: aDes.ReserveL(this->Length()); sl@0: TDes16::Swap(aDes); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Inserts data into this descriptor. sl@0: sl@0: The length of this descriptor is changed to reflect the extra data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where insertion is to start. This sl@0: is an offset value; a zero value refers to the leftmost data sl@0: position. sl@0: sl@0: @param aDes A 16-bit non modifiable descriptor whose data is to be inserted. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: */ sl@0: EXPORT_C void LString16::InsertL(TInt aPos,const TDesC16& aDes) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aDes.Length()); sl@0: RBuf16::Insert(aPos, aDes); sl@0: } sl@0: sl@0: /** sl@0: Replaces data in this descriptor. sl@0: sl@0: The specified length can be different to the length of the replacement data. sl@0: The length of this descriptor changes to reflect the change of data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where replacement is to start. sl@0: This is an offset value; a zero value refers to the leftmost sl@0: data position. sl@0: sl@0: @param aLength The length of data to be replaced. sl@0: sl@0: @param aDes The source 16-bit non modifiable descriptor whose data is to sl@0: replace the target descriptor's data at aPos. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 8 if aLength is negative sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: sl@0: @panic USER 16 if the length of the source descriptor aDes is negative sl@0: */ sl@0: EXPORT_C void LString16::ReplaceL(TInt aPos,TInt aLength,const TDesC16& aDes) sl@0: { sl@0: TInt delta = aDes.Length() - aLength; sl@0: if (delta > 0) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(delta); sl@0: } sl@0: RBuf16::Replace(aPos, aLength, aDes); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this descriptor and justifies it, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The target area is considered to be an area of specified width positioned at sl@0: the beginning of this descriptor's data area. Source data is copied into, and sl@0: aligned within this target area according to the specified alignment sl@0: instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, then sl@0: spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor containing the source data. sl@0: The length of the data to be copied is the smaller of: sl@0: the length of the source descriptor, and sl@0: the width of the target area (only if this is not the sl@0: explicit negative value KDefaultJustifyWidth). sl@0: sl@0: @param aWidth The width of the target area. If this has the specific sl@0: negative value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16::JustifyL(const TDesC16& aDes,TInt aWidth,TAlign aAlignment,TChar aFill) sl@0: { sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth); sl@0: ReserveL(width); sl@0: RBuf16::Justify(aDes, aWidth, aAlignment, aFill); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified unsigned integer into a fixed width character sl@0: representation based on the specified number system and copies the conversion sl@0: into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The function generates the exact number of specified characters, either padding sl@0: to the left with character zeroes or discarding low order characters as sl@0: necessary. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: upper case. sl@0: sl@0: This function is equivalent to using Format() with parameters which specify: sl@0: sl@0: 1. a fixed length target field sl@0: sl@0: 2. padding with zero characters, for example "%08x". sl@0: sl@0: When this is the case, always use NumFixedWidthUC() in sl@0: preference to Format() as it is more efficient. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The unsigned integer value. sl@0: @param aRadix The number system representation for the unsigned integer. sl@0: @param aWidth The number of characters: to be used to contain the conversion, sl@0: to be copied into this descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see TDes16::Format() sl@0: */ sl@0: EXPORT_C void LString16::NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth) sl@0: { sl@0: Zero(); sl@0: AppendNumFixedWidthUCL(aVal, aRadix, aWidth); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified 64 bit unsigned integer into a character representation sl@0: based on the specified number system and copies the conversion into this sl@0: descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: upper case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64 bit integer value. This is always treated as an unsigned sl@0: value for all builds. sl@0: @param aRadix The number system representation for the 64 bit integer. If no sl@0: explicit value is specified, then EDecimal is the default. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::NumUCL(TUint64 aVal, TRadix aRadix) sl@0: { sl@0: Zero(); sl@0: AppendNumUCL(aVal, aRadix); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified floating point number into a character representation sl@0: and copies the conversion into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The character representation of the real number is dictated by the specified sl@0: format. sl@0: sl@0: Note that the function leaves if the iType data member of the specified sl@0: TRealFormat object has both an invalid character representation format sl@0: (i.e. the format type) and invalid format flags. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The floating point number to be converted. sl@0: @param aFormat The format of the conversion. sl@0: sl@0: @return If the conversion is successful, the length of this descriptor. If sl@0: the conversion fails, a negative value indicating the cause of failure. sl@0: In addition, extra information on the cause of the failure may be sl@0: appended onto this descriptor. The possible values and their meaning sl@0: are: sl@0: sl@0: 1.KErrArgument - the supplied floating point number is not a valid sl@0: number. The three characters NaN are appended to this descriptor. sl@0: sl@0: 2.KErrOverflow - the number is too large to represent. sl@0: 2.1 For positive overflow, the three characters Inf are appended sl@0: to this descriptor. sl@0: 2.2 For negative overflow, the four characters -Inf are appended sl@0: to this descriptor. sl@0: sl@0: 3.KErrUnderflow - the number is too small to represent. sl@0: 3.1 For positive underflow, the three characters Inf are appended sl@0: to this descriptor. sl@0: 3.2 For negative underflow, the four characters -Inf are appended sl@0: to this descriptor. sl@0: sl@0: 4.KErrGeneral - the conversion cannot be completed. There are a sl@0: number of possible reasons for this, but the most common is: sl@0: 4.1 The character representation format (i.e. the format type), as sl@0: defined in the TRealFormat object is not recognised. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see TRealFormat::iType sl@0: */ sl@0: EXPORT_C TInt LString16::NumL(TReal aVal,const TRealFormat &aFormat) sl@0: { sl@0: Zero(); sl@0: return AppendNumL(aVal, aFormat); sl@0: } sl@0: sl@0: /** sl@0: Converts the 64-bit signed integer into a decimal character representation sl@0: and copies the conversion into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: If the integer is negative, the character representation is prefixed by a sl@0: minus sign. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64-bit signed integer value. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::NumL(TInt64 aVal) sl@0: { sl@0: Zero(); sl@0: AppendNumL(aVal); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified 64 bit unsigned integer into a character representation sl@0: based on the specified number system and copies the conversion into this sl@0: descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: lower case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64 bit integer value. This is treated as an unsigned sl@0: value for all builds. sl@0: @param aRadix The number system representation for the 64 bit integer. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::NumL(TUint64 aVal, TRadix aRadix) sl@0: { sl@0: Zero(); sl@0: AppendNumL(aVal, aRadix); sl@0: } sl@0: sl@0: /** sl@0: Formats and copies text into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The function takes a format string and a variable number of arguments. sl@0: The format string contains literal text embedded with directives for converting sl@0: the trailing list of arguments into text. sl@0: sl@0: The embedded directives are character sequences prefixed with the '%' character. sl@0: The literal text is simply copied into this descriptor unaltered while sl@0: the '%' directives are used to convert successive arguments from the sl@0: trailing list. sl@0: sl@0: The resulting stream of literal text and converted arguments is copied into sl@0: this descriptor. sl@0: sl@0: The syntax of the embedded directives follows one of four general patterns. sl@0: sl@0: Note that formatting of single numerical values can be achieved more sl@0: conveniently using the Num() and NumUC() member functions of this class. sl@0: sl@0: The full description of the syntax of a format string cannot be included here. sl@0: For full details, navigate to the Symbian OS guide, and follow the hierarchy of links: sl@0: sl@0: @code sl@0: Symbian OS Guide sl@0: Base sl@0: Using User Library (E32) sl@0: Buffers and Strings sl@0: Using Descriptors sl@0: How to Use Descriptors sl@0: Format string syntax sl@0: @endcode sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aFmt The descriptor containing the format string. sl@0: The TRefByValue class provides a constructor which takes a sl@0: TDesC8 type. sl@0: sl@0: @param ... A variable number of arguments to be converted to text as sl@0: dictated by the format string. sl@0: sl@0: @panic USER 12 if the format string has incorrect syntax. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see TDes16::Num() sl@0: @see TDes16::NumUC() sl@0: */ sl@0: EXPORT_C void LString16::FormatL(TRefByValue aFmt,...) sl@0: { sl@0: VA_LIST list; sl@0: VA_START(list,aFmt); sl@0: FormatListL(aFmt,list); sl@0: } sl@0: sl@0: /** sl@0: Formats and copies text into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The behaviour of this function is the same as FormatL(). In practice, it is sl@0: better and easier to use FormatL(), passing a variable number of arguments sl@0: as required by the format string. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aFmt The descriptor containing the format string. sl@0: @param aList A pointer to an argument list. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see TDes16::Format() sl@0: @see VA_LIST sl@0: */ sl@0: EXPORT_C void LString16::FormatListL(const TDesC16& aFmt,VA_LIST aList) sl@0: { sl@0: Zero(); sl@0: AppendFormatListL(aFmt, aList); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data and justifies it. sl@0: sl@0: The source of the appended data is an existing descriptor. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes A 16-bit non-modifiable descriptor containing the source sl@0: data. The length of the data to be copied is the smaller of: sl@0: the length of the source descriptor, and sl@0: the width of the target area (only if this is not the sl@0: explicit negative value KDefaultJustifyWidth). sl@0: sl@0: @param aWidth The width of the target area. If this has the specific sl@0: negative value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aWidth,TAlign aAlignment,TChar aFill) sl@0: { sl@0: sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? Des.Length() : aWidth); sl@0: ReserveFreeCapacityGrowExponentialL(width); sl@0: RBuf16::AppendJustify(Des, aWidth, aAlignment, aFill); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data and justifies it. sl@0: sl@0: The source of the appended data is an existing descriptor. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aDes An 8-bit non-modifiable descriptor containing the source data. sl@0: sl@0: @param aLength The length of data to be copied from the source descriptor. sl@0: If this is greater than the width of the target area, then sl@0: the length of data copied is limited to the width. sl@0: The length of data to be copied must not be greater than sl@0: the length of the source descriptor. Note that this sl@0: condition is not automatically tested. sl@0: sl@0: @param aWidth The width of the target area. If this has the specific negative sl@0: value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) sl@0: { sl@0: sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); sl@0: ReserveFreeCapacityGrowExponentialL(width); sl@0: sl@0: RBuf16::AppendJustify(Des, aLength, aWidth, aAlignment, aFill); sl@0: } sl@0: sl@0: /** sl@0: Appends a zero terminated string onto the end of this descriptor's data and sl@0: justifies it. sl@0: sl@0: The zero terminator is not copied. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within, this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A pointer to a zero terminated string The length of the data sl@0: to be copied is the smaller of: the length of the string (excluding the zero sl@0: terminator), the width of the target area (only if this is not the explicit sl@0: negative value KDefaultJustifyWidth). sl@0: sl@0: @param aWidth The width of the target area. If this has the specific negative sl@0: value KDefaultJustifyWidth, then the width is re-set to the length of the sl@0: zero terminated string (excluding the zero terminator). sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16::AppendJustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill) sl@0: { sl@0: sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth); sl@0: ReserveFreeCapacityGrowExponentialL(width); sl@0: sl@0: RBuf16::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill); sl@0: sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data and justifies it. sl@0: sl@0: The source of the appended data is a memory location. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within, this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aString A pointer to a source memory location. sl@0: sl@0: @param aLength The length of data to be copied. If this is greater than the sl@0: width of the target area, then the length of data copied is sl@0: limited to the width. sl@0: sl@0: @param aWidth The width of the target area. If this has the specific negative sl@0: value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendJustifyL(const TUint16* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) sl@0: { sl@0: sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); sl@0: ReserveFreeCapacityGrowExponentialL(width); sl@0: sl@0: RBuf16::AppendJustify(aString, aLength, aWidth, aAlignment, aFill); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified unsigned integer into a fixed width character sl@0: representation based on the specified number system and appends the conversion sl@0: onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: The function generates the exact number of specified characters, either sl@0: padding to the left with character zeroes or discarding low order characters sl@0: as necessary. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: upper case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The unsigned integer value. sl@0: @param aRadix The number system representation for the unsigned integer. sl@0: @param aWidth The number of characters: to be used to contain the conversion, sl@0: to be appended to this descriptor. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: */ sl@0: EXPORT_C void LString16::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aWidth); sl@0: RBuf16::AppendNumFixedWidthUC(aVal, aRadix, aWidth); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified 64 bit integer into a character representation sl@0: based on the specified number system and appends the conversion onto the end sl@0: of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: upper case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64 bit integer value. This is always treated as an unsigned sl@0: value. sl@0: @param aRadix The number system representation for the 64 bit integer. If no sl@0: explicit value is specified, then EDecimal is the default. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::AppendNumUCL(TUint64 aVal, TRadix aRadix) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); sl@0: RBuf16::AppendNumUC(aVal, aRadix); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified floating point number into a character representation sl@0: and appends the conversion onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: The character representation of the real number is dictated by the specified sl@0: format. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The floating point number to be converted. sl@0: @param aFormat The format of the conversion. sl@0: sl@0: @return If the conversion is successful, the length of this descriptor. If sl@0: the conversion fails, a negative value indicating the cause of failure. sl@0: In addition, extra information on the cause of the failure may be sl@0: appended onto this descriptor. The possible values and their meaning sl@0: are: sl@0: sl@0: 1.KErrArgument - the supplied floating point number is not a valid sl@0: number. The three characters NaN are appended to this descriptor. sl@0: sl@0: 2.KErrOverflow - the number is too large to represent. sl@0: 2.1 For positive overflow, the three characters Inf are appended sl@0: to this descriptor. sl@0: 2.2 For negative overflow, the four characters -Inf are appended sl@0: to this descriptor. sl@0: sl@0: 3.KErrUnderflow - the number is too small to represent. sl@0: 3.1 For positive underflow, the three characters Inf are appended sl@0: to this descriptor. sl@0: 3.2 For negative underflow, the four characters -Inf are appended sl@0: to this descriptor. sl@0: sl@0: 4.KErrGeneral - the conversion cannot be completed. There are a sl@0: number of possible reasons for this, but the most common is: sl@0: 4.1 The character representation format (i.e. the format type), as sl@0: defined in the TRealFormat object is not recognised. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C TInt LString16::AppendNumL(TReal aVal,const TRealFormat& aFormat) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize); sl@0: return RBuf16::AppendNum(aVal, aFormat); sl@0: } sl@0: sl@0: /** sl@0: Converts the 64-bit signed integer into a decimal character representation sl@0: and appends the conversion onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: If the integer is negative, the character representation is prefixed by a sl@0: minus sign. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64-bit signed integer value. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::AppendNumL(TInt64 aVal) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); sl@0: RBuf16::AppendNum(aVal); sl@0: } sl@0: sl@0: /** sl@0: Converts the specified 64 bit integer into a character representation sl@0: based on the specified number system and appends the conversion onto the end sl@0: of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: When a hexadecimal conversion is specified, hexadecimal characters are in sl@0: lower case. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aVal The 64 bit integer value. This is always treated as an unsigned sl@0: value. sl@0: @param aRadix The number system representation for the 64 bit integer. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16::AppendNumL(TUint64 aVal, TRadix aRadix) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); sl@0: RBuf16::AppendNum(aVal, aRadix); sl@0: } sl@0: sl@0: /** sl@0: Formats and appends text onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: The function takes a format string and a variable number of arguments. sl@0: The format string contains literal text, embedded with directives, sl@0: for converting the trailing list of arguments into text. sl@0: sl@0: The embedded directives are character sequences prefixed with the '%' character. sl@0: The literal text is simply copied into this descriptor unaltered while sl@0: the '%' directives are used to convert successive arguments from the sl@0: trailing list. See the description of the Format() function. sl@0: sl@0: Literal text is appended on a character by character basis, and the sl@0: underlying buffer is grown as necessary to accommodate it. sl@0: sl@0: Text converted from a trailing argument is appended as a complete sl@0: string, and the underlying buffer is grown as necessary to accommodate sl@0: it. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aFmt The 16-bit non-modifiable descriptor containing the sl@0: format string. The TRefByValue class provides a sl@0: constructor which takes a TDesC16 type. sl@0: sl@0: @param ... A variable number of arguments to be converted to text sl@0: as dictated by the format string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 12 if the format string has incorrect syntax. sl@0: sl@0: @see TDes16::Format() sl@0: @see TDes16Overflow::Overflow() sl@0: */ sl@0: EXPORT_C void LString16::AppendFormatL(TRefByValue aFmt,...) sl@0: { sl@0: VA_LIST list; sl@0: VA_START(list,aFmt); sl@0: AppendFormatListL(aFmt,list); sl@0: } sl@0: sl@0: class TRetryOverflow16 : public TDes16Overflow sl@0: { sl@0: public: sl@0: TRetryOverflow16() : iOverflow(EFalse) sl@0: { sl@0: } sl@0: sl@0: virtual void Overflow(TDes16& /*aDes*/) sl@0: { sl@0: iOverflow = ETrue; sl@0: } sl@0: sl@0: TBool iOverflow; sl@0: }; sl@0: sl@0: /** sl@0: Formats and appends text onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: The behaviour of this function is the same as sl@0: AppendFormatL(TRefByValue aFmt,TDes16Overflow *aOverflowHandler,...). sl@0: In practice, it is better and easier to use AppendFormat(), passing a variable number of sl@0: arguments as required by the format string. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aFmt The descriptor containing the format string. sl@0: @param aList A pointer to an argument list. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see TDes16::AppendFormat sl@0: @see VA_LIST sl@0: */ sl@0: EXPORT_C void LString16::AppendFormatListL(const TDesC16& aFmt,VA_LIST aList) sl@0: { sl@0: ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint sl@0: for (;;) sl@0: { sl@0: TInt before = Length(); sl@0: TRetryOverflow16 overflow; sl@0: RBuf16::AppendFormatList(aFmt, aList, &overflow); sl@0: if (overflow.iOverflow) sl@0: { sl@0: SetLengthL(before); // Can't leave sl@0: ReserveCapacityGrowExponentialL(); sl@0: } sl@0: else sl@0: { sl@0: break; sl@0: } sl@0: } sl@0: } sl@0: sl@0: sl@0: /** sl@0: Unlinks and transfers ownership of the specified 16-bit resizable descriptor's sl@0: buffer to this object. The source descriptor is detached from the buffer. sl@0: sl@0: @param aString The source 16-bit resizable buffer. The ownership of this sl@0: object's buffer is to be transferred. sl@0: sl@0: @see RBuf16::Close() sl@0: */ sl@0: EXPORT_C void LString16::Assign(const LString16& aString) sl@0: { sl@0: // free any previously owned resource sl@0: Reset(); sl@0: sl@0: RBuf16::Assign(aString); sl@0: // unlink buffer from original descriptor sl@0: new (const_cast(&aString)) LString16(); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Transfers ownership of the specified 16-bit resizable descriptor's sl@0: buffer to this object. The source descriptor is detached from the buffer. sl@0: sl@0: @param aRBuf The source 16-bit resizable buffer. The ownership of this sl@0: object's buffer is to be transferred. sl@0: sl@0: @see RBuf16::Assign() sl@0: */ sl@0: sl@0: EXPORT_C void LString16::Assign(const RBuf16& aRBuf) sl@0: { sl@0: // free any previously owned resource sl@0: Reset(); sl@0: sl@0: RBuf16::Assign(aRBuf); sl@0: sl@0: // reset the RBuf; sl@0: new (const_cast(&aRBuf)) RBuf16(); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Transfers ownership of the specified 16-bit resizable descriptor's this object. sl@0: sl@0: @param aHBuf The heap descriptor to be transferred to this object. sl@0: The ownership of this object's buffer is to be transferred. sl@0: sl@0: @see RBuf16::Assign() sl@0: */ sl@0: EXPORT_C void LString16::Assign(HBufC16* aHBuf) sl@0: { sl@0: // free any previously owned resource sl@0: Reset(); sl@0: sl@0: RBuf16::Assign(aHBuf); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Assigns ownership of the specified allocated memory to this object. sl@0: sl@0: @param aHeapCell The allocated memory to be assigned to this object. sl@0: This pointer can be NULL, which means that a zero length sl@0: 16-bit resizable buffer descriptor is created. sl@0: sl@0: @param aMaxLength The maximum length of the descriptor. sl@0: sl@0: @panic USER 8 If the specified maximum length is greater then the size of the sl@0: allocated heap cell, or the specified maximum length is NOT sl@0: zero when the pointer to the heap cell is NULL. sl@0: sl@0: @see RBuf16::Close() sl@0: @see RBuf16::Assign() sl@0: */ sl@0: EXPORT_C void LString16::Assign(TUint16* aHeapCell, TInt aMaxLength) sl@0: { sl@0: // free any previously owned resource sl@0: Reset(); sl@0: sl@0: RBuf16::Assign(aHeapCell, aMaxLength); sl@0: } sl@0: sl@0: sl@0: /** sl@0: Transfers ownership of the specified 16-bit resizable descriptor's this object. sl@0: sl@0: @param aHeapCell The allocated memory to be assigned to this object. sl@0: sl@0: @param aLength The length of the descriptor. sl@0: sl@0: @param aMaxLength The maximum length of the descriptor. sl@0: sl@0: @panic USER 8 If the specified maximum length is greater then the size of the sl@0: allocated heap cell, or the specified length is greater then sl@0: the specified maximum length, or the specified maximum length sl@0: is NOT zero when the pointer to the heap cell is NULL. sl@0: sl@0: @see RBuf16::Close() sl@0: @see RBuf16::Assign() sl@0: */ sl@0: EXPORT_C void LString16::Assign(TUint16* aHeapCell,TInt aLength,TInt aMaxLength) sl@0: { sl@0: // free any previously owned resource sl@0: Reset(); sl@0: sl@0: RBuf16::Assign(aHeapCell, aLength, aMaxLength); sl@0: } sl@0: sl@0: /** sl@0: Creates a 16-bit resizable buffer descriptor that has been initialised with sl@0: data from the specified read stream; leaves on failure. sl@0: sl@0: Data is assigned to the new descriptor from the specified stream. sl@0: This variant assumes that the stream contains the length of the data followed sl@0: by the data itself. sl@0: sl@0: The function is implemented by calling the HBufC16::NewL(RReadStream&,TInt) sl@0: variant and then assigning the resulting heap descriptor using sl@0: the RBuf16::Assign(HBufC16*) variant. The comments that describe sl@0: the HBufC16::NewL() variant also apply to this RBuf16::CreateL() function. sl@0: sl@0: The function may leave with one of the system-wide error codes, specifically sl@0: KErrOverflow, if the length of the data as read from the stream is greater than sl@0: the upper limit as specified by the aMaxLength parameter. sl@0: sl@0: @param aStream The stream from which the data length and the data to be sl@0: assigned to the new descriptor, are taken. sl@0: @param aMaxLength The upper limit on the length of data that the descriptor is sl@0: to represent. The value of this parameter must be non-negative sl@0: otherwise the underlying function will panic. sl@0: */ sl@0: EXPORT_C void LString16::CreateL(RReadStream &aStream,TInt aMaxLength) sl@0: { sl@0: Reset(); sl@0: Assign(HBufC16::NewL(aStream,aMaxLength)); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A pointer to a zero terminated string . sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see LString16::AppendL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator+=(const TUint16* aZeroTerminatedString) sl@0: { sl@0: AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); sl@0: return *this; sl@0: } sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A pointer to the data to be copied. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendL(const TUint16* aZeroTerminatedString) sl@0: { sl@0: AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); sl@0: } sl@0: sl@0: /** sl@0: Constructor to create a 16-bit resizable string descriptor containing sl@0: a copy of the specified (source) zero-terminated wide character string data, or leave sl@0: on failure. sl@0: sl@0: The constructor allocates sufficient memory so that this string sl@0: descriptor's maximum length is the same as the length of the source sl@0: string. Both the current length and the maximum length of this string sl@0: descriptor are set to the length of the source string. sl@0: sl@0: The data contained in the source string is copied into this string sl@0: descriptor. The zero terminator is not copied. sl@0: sl@0: @param aWideCharStr A pointer to a zero-terminated wide character string sl@0: sl@0: @leave KErrNoMemory If there is insufficient memory. sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16::LString16(const wchar_t* aWideCharStr) sl@0: : iReserved(0) sl@0: { sl@0: CopyL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: This operation may cause the target string descriptor's heap buffer to sl@0: be reallocated in order to accommodate the new data. As a result, sl@0: MaxLength() and Ptr() may return different values afterwards, and any sl@0: existing raw pointers to into the descriptor data may be invalidated. sl@0: sl@0: Note that the automatic resizing performed is a change to the sl@0: functionality of this operation compared to other descriptor sl@0: classes. This change is only active on objects directly declared sl@0: LString16; when LString16 instances are instead manipulated via sl@0: references to TDes16 or TDesC16, the standard (non-resizing, panicing) sl@0: variant is invoked. sl@0: sl@0: @param aWideCharStr A pointer to a wide character zero-terminated string sl@0: sl@0: @return A reference to this 16-bit string descriptor. sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @see LString16::CopyL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator=(const wchar_t* aWideCharStr) sl@0: { sl@0: CopyL(reinterpret_cast(aWideCharStr)); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A pointer to a wide character zero terminated string . sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @see LString16::AppendL sl@0: */ sl@0: EXPORT_C LString16& LString16::operator+=(const wchar_t* aWideCharStr) sl@0: { sl@0: AppendL(reinterpret_cast(aWideCharStr),User::StringLength(reinterpret_cast(aWideCharStr))); sl@0: return *this; sl@0: } sl@0: sl@0: /** sl@0: Copies data into this 16-bit string descriptor, replacing any existing sl@0: data, and expanding its heap buffer to accommodate if necessary. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A pointer to a wide character zero terminated string to be copied. sl@0: sl@0: sl@0: @leave KErrNoMemory If the heap buffer of the string descriptor being sl@0: assigned to needs to be expanded, but there is sl@0: insufficient memory to do so sl@0: sl@0: @panic USER 11 if aLength is negative. sl@0: sl@0: @see TDes16::Copy sl@0: */ sl@0: EXPORT_C void LString16::CopyL(const wchar_t* aWideCharStr) sl@0: { sl@0: CopyL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data and justifies it. sl@0: sl@0: The source of the appended data is a memory location. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within, this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A pointer to a source memory location. sl@0: sl@0: @param aLength The length of data to be copied. If this is greater than the sl@0: width of the target area, then the length of data copied is sl@0: limited to the width. sl@0: sl@0: @param aWidth The width of the target area. If this has the specific negative sl@0: value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) sl@0: { sl@0: AppendJustifyL(reinterpret_cast( aWideCharStr),aWidth,anAlignment,aFill); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A pointer to the data to be copied. sl@0: @param aLength The length of data to be copied. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr,TInt aLength) sl@0: { sl@0: AppendL(reinterpret_cast(aWideCharStr),aLength); sl@0: } sl@0: /** sl@0: Appends data onto the end of this descriptor's data. sl@0: sl@0: The length of this descriptor is incremented to reflect the new content. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A pointer to the data to be copied. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr) sl@0: { sl@0: AppendL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: /** sl@0: Determines whether this Descriptor's data is equal to the specified sl@0: string's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if equal, false otherwise. sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator==( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator==(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this Descriptor's data is equal to the specified sl@0: string's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if equal, false otherwise. sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator==( const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator==(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is less than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is less than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator<( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator<(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is less than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is less than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator<(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator<(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is less than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is less than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator<=( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator<=(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is less than/equal to the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is less than/equal to that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator<=(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator<=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is greater than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is greater than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator>( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator>(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is greater than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is greater than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator>(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator>(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is greater than/equal to the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is greater than/equal to that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator>=( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator>=(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is greater than the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is greater than that of the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator>=(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator>=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is not equal to the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is not equal to the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator!=( const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::operator!=(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Determines whether this descriptor's data is not equal to the specified sl@0: strings's data. sl@0: sl@0: The comparison is implemented internally using the TDesC::Compare() function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return True if this descriptor's data is not equal to the specified string's data sl@0: sl@0: @see TDesC::Compare sl@0: */ sl@0: EXPORT_C TBool LString16::operator!=(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::operator!=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Searches this descriptor's data for a match with the match pattern supplied sl@0: in the specified string. sl@0: sl@0: The match pattern can contain the wildcard characters "*" and "?", where "*" sl@0: matches zero or more consecutive occurrences of any character and "?" matches sl@0: a single occurrence of any character. sl@0: sl@0: Note that there is no 'escape character', which means that it is not possible sl@0: to match either the "*" character itself or the "?" character itself using sl@0: this function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be matched sl@0: with this Descriptor's data. sl@0: sl@0: @return If a match is found, the offset within this descriptor's data where sl@0: the match first occurs. KErrNotFound, if there is no match. sl@0: */ sl@0: EXPORT_C TInt LString16::Match(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::Match(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Searches this descriptor's data for a match with the match pattern supplied sl@0: in the specified string. sl@0: sl@0: The match pattern can contain the wildcard characters "*" and "?", where "*" sl@0: matches zero or more consecutive occurrences of any character and "?" matches sl@0: a single occurrence of any character. sl@0: sl@0: Note that there is no 'escape character', which means that it is not possible sl@0: to match either the "*" character itself or the "?" character itself using sl@0: this function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be matched with this Descriptor's data. sl@0: sl@0: @return If a match is found, the offset within this descriptor's data where sl@0: the match first occurs. KErrNotFound, if there is no match. sl@0: */ sl@0: EXPORT_C TInt LString16::Match(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::Match(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: /** sl@0: Searches this descriptor's folded data for a match with the folded match sl@0: pattern supplied in the specified string. sl@0: sl@0: The match pattern can contain the wildcard characters "*" and "?", where "*" sl@0: matches zero or more consecutive occurrences of any character and "?" matches sl@0: a single occurrence of any character. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for matching strings in natural language; sl@0: use MatchC() for this. sl@0: sl@0: Note that there is no 'escape character', which means that it is not possible sl@0: to match either the "*" character itself or the "?" character itself using sl@0: this function. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be matched sl@0: with this Descriptor's data. sl@0: sl@0: @return If a match is found, the offset within this descriptor's data where sl@0: the match first occurs. KErrNotFound, if there is no match. sl@0: sl@0: @see TDesC::MatchC() sl@0: */ sl@0: EXPORT_C TInt LString16::MatchF(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::MatchF(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: /** sl@0: Searches this descriptor's folded data for a match with the folded match sl@0: pattern supplied in the specified string. sl@0: sl@0: The match pattern can contain the wildcard characters "*" and "?", where "*" sl@0: matches zero or more consecutive occurrences of any character and "?" matches sl@0: a single occurrence of any character. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for matching strings in natural language; sl@0: use MatchC() for this. sl@0: sl@0: Note that there is no 'escape character', which means that it is not possible sl@0: to match either the "*" character itself or the "?" character itself using sl@0: this function. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be matched with this Descriptor's data. sl@0: sl@0: @return If a match is found, the offset within this descriptor's data where sl@0: the match first occurs. KErrNotFound, if there is no match. sl@0: sl@0: @see TDesC::MatchC() sl@0: */ sl@0: EXPORT_C TInt LString16::MatchF(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::MatchF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: /** sl@0: Compares this descriptor's data with the specified string's data. sl@0: sl@0: The comparison proceeds on a byte for byte basis. The result of the comparison sl@0: is based on the difference of the first bytes to disagree. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return Positive, if this descriptor is greater than the specified string. sl@0: Negative, if this descriptor is less than the specified string. sl@0: Zero, if both the descriptor and the string have the same length sl@0: and the their contents are the same. sl@0: */ sl@0: EXPORT_C TInt LString16::Compare(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::Compare(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Compares this descriptor's data with the specified string's data. sl@0: sl@0: The comparison proceeds on a byte for byte basis. The result of the comparison sl@0: is based on the difference of the first bytes to disagree. sl@0: sl@0: @param aZeroTerminatedString The wide Zero TerminatedString string whose data sl@0: is to be compared with this Descriptor's data. sl@0: sl@0: @return Positive, if this descriptor is greater than the specified string. sl@0: Negative, if this descriptor is less than the specified string. sl@0: Zero, if both the descriptor and the string have the same length sl@0: and the their contents are the same. sl@0: */ sl@0: EXPORT_C TInt LString16::Compare(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::Compare(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: /** sl@0: Compares this descriptor's folded data with the specified string's folded sl@0: data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for comparing strings in natural language; sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be compared sl@0: with this Descriptor's data. sl@0: sl@0: @return Positive, if this descriptor is greater than the specified string. sl@0: Negative, if this descriptor is less than the specified string. sl@0: Zero, if the descriptor and the specified string have the same length sl@0: and the their contents are the same. sl@0: sl@0: @see TDesC::Compare() sl@0: */ sl@0: EXPORT_C TInt LString16::CompareF(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::CompareF(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Compares this descriptor's folded data with the specified string's folded sl@0: data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for comparing strings in natural language; sl@0: sl@0: @param aZeroTerminatedString The wide Zero Terminated String whose data sl@0: is to be compared with this string's data. sl@0: sl@0: @return Positive, if this descriptor is greater than the specified string. sl@0: Negative, if this descriptor is less than the specified string. sl@0: Zero, if the descriptor and the specified string have the same length sl@0: and the their contents are the same. sl@0: sl@0: @see TDesC::Compare() sl@0: */ sl@0: EXPORT_C TInt LString16::CompareF(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::CompareF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Searches for the first occurrence of the specified data sequence within this sl@0: descriptor. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. sl@0: */ sl@0: EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::Find(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Searches for the first occurrence of the specified data sequence within this sl@0: descriptor. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. sl@0: */ sl@0: EXPORT_C TInt LString16::Find(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::Find(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Searches for the first occurrence of the specified data sequence within this sl@0: descriptor. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: @param aLenS The length of the data sequence to be searched for. This value sl@0: must not be negative, otherwise the function raises a panic. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. sl@0: sl@0: @panic USER 29 if aLenS is negative. sl@0: */ sl@0: EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr,TInt aLenS) const sl@0: { sl@0: return LString16::Find(reinterpret_cast(aWideCharStr), aLenS); sl@0: } sl@0: sl@0: /** sl@0: Searches for the first occurrence of the specified folded data sequence within sl@0: this descriptor's folded data. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for finding strings in natural language; sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. Zero, if the sl@0: length of the search data sequence is zero. sl@0: sl@0: */ sl@0: EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr) const sl@0: { sl@0: return LString16::FindF(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Searches for the first occurrence of the specified folded data sequence within sl@0: this descriptor's folded data. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for finding strings in natural language; sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. Zero, if the sl@0: length of the search data sequence is zero. sl@0: sl@0: */ sl@0: EXPORT_C TInt LString16::FindF(const TUint16* aZeroTerminatedString) const sl@0: { sl@0: return RBuf16::FindF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: /** sl@0: Searches for the first occurrence of the specified folded data sequence within sl@0: this descriptor's folded data. sl@0: sl@0: Searching always starts at the beginning of this descriptor's data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used for finding strings in natural language; sl@0: sl@0: @param aWideCharStr The wide character string whose data is to be searched for, sl@0: within this Descriptor's data. sl@0: @param aLenS The length of the data sequence to be searched for. This value sl@0: must not be negative, otherwise the function raises a panic. sl@0: sl@0: @return The offset of the data sequence from the beginning of this descriptor's sl@0: data. KErrNotFound, if the data sequence cannot be found. Zero, if the sl@0: length of the search data sequence is zero. sl@0: sl@0: @panic USER 29 if aLenS is negative sl@0: sl@0: */ sl@0: EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr, TInt aLen) const sl@0: { sl@0: return RBuf16::FindF(reinterpret_cast(aWideCharStr),aLen); sl@0: } sl@0: sl@0: /** sl@0: Copies and folds data from the specified string into this descriptor replacing sl@0: any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new sl@0: data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used when dealing with strings in natural sl@0: language. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyFL(const wchar_t* aWideCharStr ) sl@0: { sl@0: LString16::CopyFL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Copies and folds data from the specified string into this descriptor replacing sl@0: any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new sl@0: data. sl@0: sl@0: Note that folding is locale-independent behaviour. It is also important to sl@0: note that there can be no guarantee that folding is in any way culturally sl@0: appropriate, and should not be used when dealing with strings in natural sl@0: language. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A wide zero terminated string sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyFL(const TUint16* aZeroTerminatedString ) sl@0: { sl@0: LString16::CopyFL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and converts it to lower case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to lower case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyLCL(const wchar_t* aWideCharStr) sl@0: { sl@0: LString16::CopyLCL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and converts it to lower case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to lower case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A wide zero terminated string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyLCL(const TUint16* aZeroTerminatedString) sl@0: { sl@0: LString16::CopyLCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and converts it to upper case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to upper case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyUCL(const wchar_t* aWideCharStr) sl@0: { sl@0: LString16::CopyUCL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and converts it to upper case before sl@0: putting it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Conversion to upper case is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A wide zero terminated string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyUCL(const TUint16* aZeroTerminatedString) sl@0: { sl@0: LString16::CopyUCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and capitalises it before putting sl@0: it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Capitalisation is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyCPL(const wchar_t* aWideCharStr) sl@0: { sl@0: LString16::CopyCPL(reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Copies text from the specified string and capitalises it before putting sl@0: it into this descriptor, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: Capitalisation is implemented as appropriate to the current locale. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aZeroTerminatedString A wide zero terminated string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: */ sl@0: EXPORT_C void LString16:: CopyCPL(const TUint16* aZeroTerminatedString) sl@0: { sl@0: LString16::CopyCPL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: /** sl@0: Inserts data into this descriptor. sl@0: sl@0: The length of this descriptor is changed to reflect the extra data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where insertion is to start. This sl@0: is an offset value; a zero value refers to the leftmost data sl@0: position. sl@0: sl@0: @param aWideCharStr A wide character string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: */ sl@0: EXPORT_C void LString16:: InsertL(TInt aPos,const wchar_t* aWideCharStr) sl@0: { sl@0: LString16::InsertL(aPos, reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Inserts data into this descriptor. sl@0: sl@0: The length of this descriptor is changed to reflect the extra data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where insertion is to start. This sl@0: is an offset value; a zero value refers to the leftmost data sl@0: position. sl@0: sl@0: @param aZeroTerminatedString A wide null terminated string. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: */ sl@0: EXPORT_C void LString16:: InsertL(TInt aPos,const TUint16* aZeroTerminatedString) sl@0: { sl@0: LString16::InsertL(aPos,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Replaces data in this descriptor. sl@0: sl@0: The specified length can be different to the length of the replacement data. sl@0: The length of this descriptor changes to reflect the change of data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where replacement is to start. sl@0: This is an offset value; a zero value refers to the leftmost sl@0: data position. sl@0: sl@0: @param aLength The length of data to be replaced. sl@0: sl@0: @param aWideCharStr The source wide character string sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 8 if aLength is negative sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: sl@0: @panic USER 16 if the length of the source descriptor aDes is negative sl@0: */ sl@0: EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr) sl@0: { sl@0: LString16::ReplaceL(aPos,aLength,reinterpret_cast(aWideCharStr)); sl@0: } sl@0: sl@0: /** sl@0: Replaces data in this descriptor. sl@0: sl@0: The specified length can be different to the length of the replacement data. sl@0: The length of this descriptor changes to reflect the change of data. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aPos The position within the data where replacement is to start. sl@0: This is an offset value; a zero value refers to the leftmost sl@0: data position. sl@0: sl@0: @param aLength The length of data to be replaced. sl@0: sl@0: @param aZeroTerminatedString The source wide null terminated character string sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 8 if aLength is negative sl@0: sl@0: @panic USER 10 if aPos is negative or is greater than the length of this sl@0: descriptor. sl@0: sl@0: @panic USER 16 if the length of the source descriptor aDes is negative sl@0: */ sl@0: EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString) sl@0: { sl@0: LString16::ReplaceL(aPos,aLength,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this descriptor and justifies it, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The target area is considered to be an area of specified width positioned at sl@0: the beginning of this descriptor's data area. Source data is copied into, and sl@0: aligned within this target area according to the specified alignment sl@0: instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, then sl@0: spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string containing the source data. sl@0: The length of the data to be copied is the smaller of: sl@0: the length of the source descriptor, and sl@0: the width of the target area (only if this is not the sl@0: explicit negative value KDefaultJustifyWidth). sl@0: sl@0: @param aWidth The width of the target area. If this has the specific sl@0: negative value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16:: JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) sl@0: { sl@0: LString16::JustifyL(reinterpret_cast(aWideCharStr),aWidth,anAlignment,aFill); sl@0: } sl@0: sl@0: /** sl@0: Copies data into this descriptor and justifies it, replacing any existing data. sl@0: sl@0: The length of this descriptor is set to reflect the new data. sl@0: sl@0: The target area is considered to be an area of specified width positioned at sl@0: the beginning of this descriptor's data area. Source data is copied into, and sl@0: aligned within this target area according to the specified alignment sl@0: instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, then sl@0: spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aWideCharStr A wide character string containing the source data. sl@0: The length of the data to be copied is the smaller of: sl@0: the length of the source descriptor, and sl@0: the width of the target area (only if this is not the sl@0: explicit negative value KDefaultJustifyWidth). sl@0: sl@0: @param aWidth The width of the target area. If this has the specific sl@0: negative value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: */ sl@0: EXPORT_C void LString16:: JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill) sl@0: { sl@0: LString16::JustifyL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill); sl@0: } sl@0: sl@0: /** sl@0: Appends data onto the end of this descriptor's data and justifies it. sl@0: sl@0: The source of the appended data is a memory location. sl@0: sl@0: The target area is considered to be an area of specified width, immediately sl@0: following this descriptor's existing data. Source data is copied into, and sl@0: aligned within, this target area according to the specified alignment instruction. sl@0: sl@0: If the length of the target area is larger than the length of the source, sl@0: then spare space within the target area is padded with the fill character. sl@0: sl@0: This leaving variant of the standard, non-leaving descriptor method sl@0: differs in that this operation may cause the string descriptor's heap sl@0: buffer to be reallocated in order to accommodate the new data. As a sl@0: result, MaxLength() and Ptr() may return different values afterwards, sl@0: and any existing raw pointers to into the descriptor data may be sl@0: invalidated. sl@0: sl@0: @param aString A pointer to a source memory location. sl@0: sl@0: @param aLength The length of data to be copied. If this is greater than the sl@0: width of the target area, then the length of data copied is sl@0: limited to the width. sl@0: sl@0: @param aWidth The width of the target area. If this has the specific negative sl@0: value KDefaultJustifyWidth, then the width is sl@0: re-set to the length of the data source. sl@0: sl@0: @param aAlignment The alignment of the data within the target area. sl@0: sl@0: @param aFill The fill character used to pad the target area. sl@0: sl@0: @leave KErrNoMemory if the underlying buffer needs to be sl@0: grown and there are insufficient resources to do so sl@0: sl@0: @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. sl@0: sl@0: @panic USER 17 if aLength is negative. sl@0: */ sl@0: EXPORT_C void LString16:: AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill) sl@0: { sl@0: LString16::AppendJustifyL(reinterpret_cast(aWideCharStr),aLength, aWidth,anAlignment,aFill); sl@0: } sl@0: //eof