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 <e32base.h>
sl@0: #include <estring.h>
sl@0:
sl@0: const TUint KDefaultExpandSize = 16;
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 LString8::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 LString8::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 LString8::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 LString8::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 8-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 LString8::LString8()
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 RBuf8::Close
sl@0: */
sl@0: EXPORT_C LString8::~LString8()
sl@0: {
sl@0: RBuf8::Close();
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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 RBuf8::CreateL
sl@0: */
sl@0: EXPORT_C LString8::LString8(TInt aMaxLength)
sl@0: : iReserved(0)
sl@0: {
sl@0: RBuf8::CreateL(aMaxLength);
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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: 8-bit resizable string descriptor is created.
sl@0:
sl@0: @see RBuf8::RBuf8(HBufC8*)
sl@0: */
sl@0: EXPORT_C LString8::LString8(HBufC8* aHBuf)
sl@0: : iReserved(0)
sl@0: {
sl@0: if (aHBuf)
sl@0: RBuf8::Assign (aHBuf);
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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 8-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 RBuf8::Assign()
sl@0: */
sl@0: EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aMaxLength)
sl@0: : iReserved(0)
sl@0: {
sl@0: RBuf8::Assign(aHeapCell, aMaxLength);
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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 RBuf8::Assign()
sl@0: */
sl@0: EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0: : iReserved(0)
sl@0: {
sl@0: RBuf8::Assign(aHeapCell, aLength, aMaxLength);
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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 RBuf8::CreateL()
sl@0: */
sl@0: EXPORT_C LString8::LString8(const TDesC8& aDes)
sl@0: : iReserved(0)
sl@0: {
sl@0: RBuf8::CreateL(aDes);
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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: LString8; when LString8 instances are instead manipulated via
sl@0: references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0: variant is invoked.
sl@0:
sl@0: @param aDes A 8-bit non-modifiable descriptor.
sl@0:
sl@0: @return A reference to this 8-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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator=(const TDesC8& 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 8-bit descriptor to this object.
sl@0:
sl@0: @param aBuf The source 8-bit buffer. The ownership of this
sl@0: object's buffer is to be transferred.
sl@0:
sl@0: @see Assign()
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator=(HBufC8* 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 8-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 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 LString8::operator=
sl@0: @see TDes8::Copy
sl@0: */
sl@0: EXPORT_C void LString8::CopyL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::Copy(aDes);
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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.A 16-bit non-modifiable descriptor.
sl@0: Each double-byte value can
sl@0: only be copied into the corresponding single byte when the
sl@0: double-byte value is less than decimal 256. A double-byte value of
sl@0: 256 or greater cannot be copied and the corresponding single byte
sl@0: is set to a value of decimal 1.
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 TDes8::Copy
sl@0: */
sl@0: EXPORT_C void LString8::CopyL(const TDesC16& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::Copy(aDes);
sl@0: }
sl@0:
sl@0: /**
sl@0: Copy constructor to create a 8-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 RBuf8::CreateL()
sl@0: */
sl@0: EXPORT_C LString8::LString8(const LString8& aDes)
sl@0: : iReserved(0)
sl@0: {
sl@0: RBuf8::CreateL(aDes);
sl@0: }
sl@0:
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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: LString8; when LString8 instances are instead manipulated via
sl@0: references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0: variant is invoked.
sl@0:
sl@0: @param aDes A 8-bit string descriptor.
sl@0:
sl@0: @return A reference to this 8-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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator=(const LString8& aDes)
sl@0: {
sl@0: CopyL(aDes);
sl@0: return *this;
sl@0: }
sl@0:
sl@0: /**
sl@0: Constructor to create a 8-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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8::LString8(const TUint8* aZeroTerminatedString)
sl@0: : iReserved(0)
sl@0: {
sl@0: CopyL(aZeroTerminatedString);
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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: LString8; when LString8 instances are instead manipulated via
sl@0: references to TDes8 or TDesC8, 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 8-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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator=(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: CopyL(aZeroTerminatedString);
sl@0: return *this;
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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 LString8::operator=
sl@0: @see TDes8::Copy
sl@0: */
sl@0: EXPORT_C void LString8::CopyL(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: ReserveL(User::StringLength(aZeroTerminatedString));
sl@0: RBuf8::Copy(aZeroTerminatedString);
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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 TDes8::Copy
sl@0: */
sl@0: EXPORT_C void LString8::CopyL(const TUint8* aBuf,TInt aLength)
sl@0: {
sl@0: ReserveL(aLength);
sl@0: RBuf8::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 LString8::SetLengthL(TInt aLength)
sl@0: {
sl@0: ReserveL(aLength);
sl@0: RBuf8::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 LString8::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: RBuf8::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 LString8::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 LString8::Reset()
sl@0: {
sl@0: RBuf8::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 LString8::Compress()
sl@0: {
sl@0: TInt length = Length();
sl@0: if (MaxLength() > length)
sl@0: {
sl@0: //coverity[checked_return]
sl@0: /*Check for return value from realloc is not needed because neither can
sl@0: * maxlength be negative or length be less than the existing data length
sl@0: */
sl@0: ReAlloc(length);
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 LString8::operator+=
sl@0: */
sl@0: EXPORT_C void LString8::AppendL(TChar aChar)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(1);
sl@0: RBuf8::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 LString8::AppendL
sl@0: */
sl@0: EXPORT_C LString8& LString8::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 8-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 LString8::AppendL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::AppendL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator+=(const TDesC8& 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 LString8::AppendL(const TUint8* aBuf,TInt aLength)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aLength);
sl@0: RBuf8::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 LString8::FillL(TChar aChar,TInt aLength)
sl@0: {
sl@0: ReserveL(aLength);
sl@0: RBuf8::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 LString8::FillZL(TInt aLength)
sl@0: {
sl@0: ReserveL(aLength);
sl@0: RBuf8::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 LString8::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 LString8::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0: RBuf8::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 TUint8 *LString8::PtrZL()
sl@0: {
sl@0: ReserveFreeCapacityL(1);
sl@0: return RBuf8::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 8-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 LString8::CopyFL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::CopyCL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::CopyLCL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::CopyUCL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::CopyCPL(const TDesC8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: RBuf8::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 LString8::AppendFillL(TChar aChar,TInt aLength)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aLength);
sl@0: RBuf8::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 LString8::ZeroTerminateL()
sl@0: {
sl@0: ReserveFreeCapacityL(1);
sl@0: RBuf8::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 LString8, then the function
sl@0: raises a USER 11 panic. The target LString8 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 8-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 LString8
sl@0: */
sl@0: EXPORT_C void LString8::SwapL(TDes8& aDes)
sl@0: {
sl@0: ReserveL(aDes.Length());
sl@0: TDes8::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 8-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 LString8::SwapL(LString8& aDes)
sl@0: {
sl@0: this->ReserveL(aDes.Length());
sl@0: aDes.ReserveL(this->Length());
sl@0: TDes8::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 8-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 LString8::InsertL(TInt aPos,const TDesC8& aDes)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0: RBuf8::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 8-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 LString8::ReplaceL(TInt aPos,TInt aLength,const TDesC8& 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: RBuf8::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 8-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 LString8::JustifyL(const TDesC8& aDes,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0: {
sl@0: TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth);
sl@0: ReserveL(width);
sl@0: RBuf8::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 TDes8::Format()
sl@0: */
sl@0: EXPORT_C void LString8::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 LString8::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 LString8::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 LString8::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 LString8::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 TDes8::Num()
sl@0: @see TDes8::NumUC()
sl@0: */
sl@0: EXPORT_C void LString8::FormatL(TRefByValue<const TDesC8> 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 TDes8::Format()
sl@0: @see VA_LIST
sl@0: */
sl@0: EXPORT_C void LString8::FormatListL(const TDesC8& 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 8-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 LString8::AppendJustifyL(const TDesC8& 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: RBuf8::AppendJustify(Des, 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 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 LString8::AppendJustifyL(const TDesC8& 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: RBuf8::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 LString8::AppendJustifyL(const TUint8* 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: RBuf8::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 LString8::AppendJustifyL(const TUint8* 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: RBuf8::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 LString8::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0: RBuf8::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 LString8::AppendNumUCL(TUint64 aVal, TRadix aRadix)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0: RBuf8::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 LString8::AppendNumL(TReal aVal,const TRealFormat& aFormat)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize);
sl@0: return RBuf8::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 LString8::AppendNumL(TInt64 aVal)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0: RBuf8::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 LString8::AppendNumL(TUint64 aVal, TRadix aRadix)
sl@0: {
sl@0: ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0: RBuf8::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 8-bit non-modifiable descriptor containing the
sl@0: format string. The TRefByValue class provides a
sl@0: constructor which takes a TDesC8 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 TDes8::Format()
sl@0: @see TDes8Overflow::Overflow()
sl@0: */
sl@0: EXPORT_C void LString8::AppendFormatL(TRefByValue<const TDesC8> 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 TRetryOverflow8 : public TDes8Overflow
sl@0: {
sl@0: public:
sl@0: TRetryOverflow8() : iOverflow(EFalse)
sl@0: {
sl@0: }
sl@0:
sl@0: virtual void Overflow(TDes8& /*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<const TDesC8> aFmt,TDes8Overflow *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 TDes8::AppendFormat
sl@0: @see VA_LIST
sl@0: */
sl@0: EXPORT_C void LString8::AppendFormatListL(const TDesC8& 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: TRetryOverflow8 overflow;
sl@0: RBuf8::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 8-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 8-bit resizable buffer. The ownership of this
sl@0: object's buffer is to be transferred.
sl@0:
sl@0: */
sl@0: EXPORT_C void LString8::Assign(const LString8& aString)
sl@0: {
sl@0: // free any previously owned resource
sl@0: Reset();
sl@0:
sl@0: RBuf8::Assign(aString);
sl@0: // unlink buffer from original descriptor
sl@0: new (const_cast<LString8*>(&aString)) LString8();
sl@0: }
sl@0:
sl@0:
sl@0: /**
sl@0: Transfers ownership of the specified 8-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 8-bit resizable buffer. The ownership of this
sl@0: object's buffer is to be transferred.
sl@0:
sl@0: @see RBuf8::Assign()
sl@0: */
sl@0:
sl@0: EXPORT_C void LString8::Assign(const RBuf8& aRBuf)
sl@0: {
sl@0: // free any previously owned resource
sl@0: Reset();
sl@0:
sl@0: RBuf8::Assign(aRBuf);
sl@0:
sl@0: // reset the RBuf;
sl@0: new (const_cast<RBuf8*>(&aRBuf)) RBuf8();
sl@0: }
sl@0:
sl@0:
sl@0: /**
sl@0: Transfers ownership of the specified 8-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 RBuf8::Assign()
sl@0: */
sl@0: EXPORT_C void LString8::Assign(HBufC8* aHBuf)
sl@0: {
sl@0: // free any previously owned resource
sl@0: Reset();
sl@0:
sl@0: RBuf8::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: 8-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 RBuf8::Assign()
sl@0: */
sl@0: EXPORT_C void LString8::Assign(TUint8 *aHeapCell, TInt aMaxLength)
sl@0: {
sl@0: // free any previously owned resource
sl@0: Reset();
sl@0:
sl@0: RBuf8::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 RBuf8::Assign()
sl@0: */
sl@0: EXPORT_C void LString8::Assign(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0: {
sl@0: // free any previously owned resource
sl@0: Reset();
sl@0:
sl@0: RBuf8::Assign(aHeapCell, aLength, aMaxLength);
sl@0: }
sl@0:
sl@0: /**
sl@0: Creates an 8-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 HBufC8::NewL(RReadStream&,TInt)
sl@0: variant and then assigning the resulting heap descriptor using
sl@0: the RBuf8::Assign(HBufC8*) variant. The comments that describe
sl@0: the HBufC8::NewL() variant also apply to this RBuf8::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 LString8::CreateL(RReadStream &aStream,TInt aMaxLength)
sl@0: {
sl@0: Reset();
sl@0: Assign(HBufC8::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 LString8::AppendL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator+=(const TUint8* 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 LString8::AppendL(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
sl@0: }
sl@0: /**
sl@0: Constructor to create a 8-bit resizable string descriptor containing
sl@0: a copy of the specified (source) zero-terminated 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 aCharStr 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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8::LString8(const char* aCharStr)
sl@0: : iReserved(0)
sl@0: {
sl@0: CopyL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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: LString8; when LString8 instances are instead manipulated via
sl@0: references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0: variant is invoked.
sl@0:
sl@0: @param aCharStr A pointer to a character zero-terminated string
sl@0:
sl@0: @return A reference to this 8-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 LString8::CopyL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator=(const char* aCharStr)
sl@0: {
sl@0: CopyL(reinterpret_cast<const TUint8*>(aCharStr));
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 aCharStr A pointer to a 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 LString8::AppendL
sl@0: */
sl@0: EXPORT_C LString8& LString8::operator+=(const char* aCharStr)
sl@0: {
sl@0: AppendL(reinterpret_cast<const TUint8*>(aCharStr),User::StringLength(reinterpret_cast<const TUint8*>(aCharStr)));
sl@0: return *this;
sl@0: }
sl@0:
sl@0: /**
sl@0: Copies data into this 8-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 new
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 aCharStr A pointer to a 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 TDes8::Copy
sl@0: */
sl@0: EXPORT_C void LString8::CopyL(const char* aCharStr)
sl@0: {
sl@0: CopyL(reinterpret_cast<const TUint8*>(aCharStr));
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 aCharStr 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 LString8::AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0: {
sl@0: AppendJustifyL(reinterpret_cast<const TUint8*>( aCharStr),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 aCharStr 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 LString8::AppendL(const char* aCharStr,TInt aLength)
sl@0: {
sl@0: AppendL(reinterpret_cast<const TUint8*>(aCharStr),aLength);
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 aCharStr 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 LString8::AppendL(const char* aCharStr)
sl@0: {
sl@0: AppendL(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator==( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator==(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator==( const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator==(TPtrC8((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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator<( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator<(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator<(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator<(TPtrC8((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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator<=( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator<=(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator<=(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator<=(TPtrC8((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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator>( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator>(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator>(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator>(TPtrC8((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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator>=( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator>=(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator>=(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator>=(TPtrC8((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 TDesC8::Compare() function.
sl@0:
sl@0: @param aCharStr The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator!=( const char* aCharStr) const
sl@0: {
sl@0: return LString8::operator!=(reinterpret_cast<const TUint8*>(aCharStr));
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 TDesC8::Compare() function.
sl@0:
sl@0: @param aZeroTerminatedString The 8-bit 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 TDesC8::Compare
sl@0: */
sl@0: EXPORT_C TBool LString8::operator!=(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::operator!=(TPtrC8((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 aCharStr The 8-bit 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 LString8::Match(const char* aCharStr) const
sl@0: {
sl@0: return LString8::Match(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8::Match(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::Match(TPtrC8((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 aCharStr The 8-bit 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 TDesC8::MatchC()
sl@0: */
sl@0: EXPORT_C TInt LString8::MatchF(const char* aCharStr) const
sl@0: {
sl@0: return LString8::MatchF(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 TDesC8::MatchC()
sl@0: */
sl@0: EXPORT_C TInt LString8::MatchF(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::MatchF(TPtrC8((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 aCharStr The 8-bit 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 LString8::Compare(const char* aCharStr) const
sl@0: {
sl@0: return LString8::Compare(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8::Compare(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::Compare(TPtrC8((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 aCharStr The 8-bit 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 TDesC8::Compare()
sl@0: */
sl@0: EXPORT_C TInt LString8::CompareF(const char* aCharStr) const
sl@0: {
sl@0: return LString8::CompareF(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 TDesC8::Compare()
sl@0: */
sl@0: EXPORT_C TInt LString8::CompareF(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::CompareF(TPtrC8((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 aCharStr The 8-bit 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 LString8::Find(const char* aCharStr) const
sl@0: {
sl@0: return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr));
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 aCharStr The 8-bit 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 LString8::Find(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::Find(TPtrC8((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 aCharStr The 8-bit 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 LString8::Find(const char* aCharStr,TInt aLenS) const
sl@0: {
sl@0: return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr), 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 aCharStr The 8-bit 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 LString8::FindF(const char* aCharStr) const
sl@0: {
sl@0: return LString8::FindF(reinterpret_cast<const TUint8*>(aCharStr));
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 aCharStr The 8-bit 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 LString8::FindF(const TUint8* aZeroTerminatedString) const
sl@0: {
sl@0: return RBuf8::FindF(TPtrC8((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 aCharStr The 8-bit 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 LString8::FindF(const char* aCharStr, TInt aLen) const
sl@0: {
sl@0: return RBuf8::FindF(reinterpret_cast<const TUint8*>(aCharStr),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 aCharStr A 8-bit 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 LString8:: CopyFL(const char* aCharStr )
sl@0: {
sl@0: LString8::CopyFL(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: CopyFL(const TUint8* aZeroTerminatedString )
sl@0: {
sl@0: LString8::CopyFL(TPtrC8((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 aCharStr A 8-bit 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 LString8:: CopyLCL(const char* aCharStr)
sl@0: {
sl@0: LString8::CopyLCL(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: CopyLCL(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: LString8::CopyLCL(TPtrC8((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 aCharStr A 8-bit 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 LString8:: CopyUCL(const char* aCharStr)
sl@0: {
sl@0: LString8::CopyUCL(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: CopyUCL(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: LString8::CopyUCL(TPtrC8((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 aCharStr A 8-bit 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 LString8:: CopyCPL(const char* aCharStr)
sl@0: {
sl@0: LString8::CopyCPL(reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: CopyCPL(const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: LString8::CopyCPL(TPtrC8((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 aCharStr A 8-bit 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 LString8:: InsertL(TInt aPos,const char* aCharStr)
sl@0: {
sl@0: LString8::InsertL(aPos, reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: InsertL(TInt aPos,const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: LString8::InsertL(aPos,TPtrC8((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 aCharStr The source 8-bit 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 LString8:: ReplaceL(TInt aPos,TInt aLength,const char* aCharStr)
sl@0: {
sl@0: LString8::ReplaceL(aPos,aLength,reinterpret_cast<const TUint8*>(aCharStr));
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 8-bit 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 LString8:: ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString)
sl@0: {
sl@0: LString8::ReplaceL(aPos,aLength,TPtrC8((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 aCharStr A 8-bit 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 LString8:: JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0: {
sl@0: LString8::JustifyL(reinterpret_cast<const TUint8*>(aCharStr),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 aCharStr A 8-bit 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 LString8:: JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0: {
sl@0: LString8::JustifyL(TPtrC8((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 LString8:: AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0: {
sl@0: LString8::AppendJustifyL(reinterpret_cast<const TUint8*>(aCharStr),aLength, aWidth,anAlignment,aFill);
sl@0: }
sl@0:
sl@0: // eof