Symaptic: os/ossrv/lowlevellibsandfws/genericusabilitylib/src/lstring8.cpp@260cb5ec6c19 (annotated)

sl@0	1	// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0	2	// All rights reserved.
sl@0	3	// This component and the accompanying materials are made available
sl@0	4	// under the terms of "Eclipse Public License v1.0"
sl@0	5	// which accompanies this distribution, and is available
sl@0	6	// at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0	7	//
sl@0	8	// Initial Contributors:
sl@0	9	// Nokia Corporation - initial contribution.
sl@0	10	//
sl@0	11	// Contributors:
sl@0	12	//
sl@0	13	// Description:
sl@0	14	//
sl@0	15
sl@0	16	#include <e32base.h>
sl@0	17	#include <estring.h>
sl@0	18
sl@0	19	const TUint KDefaultExpandSize = 16;
sl@0	20
sl@0	21	/**
sl@0	22	Aligns the supplied capacity to the nearest growth factor
sl@0	23
sl@0	24	For performance reasons the growth factor, KDefaultExpandSizeShift,
sl@0	25	is expressed as an exponent of 2 so shifting can be used to achieve the
sl@0	26	alignment.
sl@0	27
sl@0	28	a KDefaultExpandSizeShift value of 4 is equivalent to 16;
sl@0	29	giving newCapacity = ((newCapacity / 16) + 1) * 16
sl@0	30
sl@0	31	@param aNewCapacity The size to be aligned
sl@0	32
sl@0	33	@return The new, aligned capacity
sl@0	34	*/
sl@0	35	static inline TInt AlignCapacity(TInt aNewCapacity)
sl@0	36	{
sl@0	37	const TUint KDefaultExpandSizeShift = 4;
sl@0	38
sl@0	39	return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift);
sl@0	40	}
sl@0	41
sl@0	42	/**
sl@0	43	Guarantees that MaxLength() is greater than or equal to the supplied
sl@0	44	capacity, reallocating the supplied capacity if necessary.
sl@0	45
sl@0	46	The actual value of MaxLength() after a call may differ from the exact
sl@0	47	value requested, but if it does differ it will always be greater. This
sl@0	48	flexibility allows the implementation to manage heap buffers more
sl@0	49	efficiently.
sl@0	50
sl@0	51	The string descriptor's heap buffer may be reallocated in order to
sl@0	52	accommodate the new size. As a
sl@0	53	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	54	and any existing raw pointers to into the descriptor data may be
sl@0	55	invalidated.
sl@0	56
sl@0	57	@param aMinRequiredCapacity The minimum value of MaxLength() required
sl@0	58
sl@0	59	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	60	grown and there are insufficient resources to do so
sl@0	61	*/
sl@0	62	void LString8::ReserveL(TInt aMinRequiredCapacity)
sl@0	63	{
sl@0	64	if (MaxLength() < aMinRequiredCapacity)
sl@0	65	{
sl@0	66	ReAllocL(AlignCapacity(aMinRequiredCapacity));
sl@0	67	}
sl@0	68	}
sl@0	69
sl@0	70
sl@0	71	/**
sl@0	72	Guarantees that MaxLength() is greater than or equal to the supplied
sl@0	73	integer parameter, growing the underlying heap buffer if necessary.
sl@0	74
sl@0	75	The growth is exponential; maxLength *= 1.5
sl@0	76	This is reported to give an amortised complexity of O(n) when adding
sl@0	77	n characters.
sl@0	78	If the required capacity is larger than the expanded size then the
sl@0	79	required capacity is used instead.
sl@0	80
sl@0	81	The actual value of MaxLength() after a call may differ from the exact
sl@0	82	value requested, but if it does differ it will always be greater. This
sl@0	83	flexibility allows the implementation to manage heap buffers more
sl@0	84	efficiently.
sl@0	85
sl@0	86	@param aRequiredCapacity The minimum value of MaxLength() required
sl@0	87
sl@0	88	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	89	grown and there are insufficient resources to do so
sl@0	90	*/
sl@0	91	void LString8::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity)
sl@0	92	{
sl@0	93	//work in unsigned int for the appropriate shift operation
sl@0	94	TUint max_length = MaxLength();
sl@0	95	TUint requiredCapacity = aRequiredCapacity;
sl@0	96
sl@0	97	if (max_length < requiredCapacity)
sl@0	98	{
sl@0	99	// max_length *= 3/2;
sl@0	100	max_length = (max_length + (max_length << 1)) >> 1;
sl@0	101
sl@0	102	// take the bigger of the extended buffer or the required capactiy
sl@0	103	ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity)));
sl@0	104	}
sl@0	105	}
sl@0	106
sl@0	107	/**
sl@0	108	Guarantees that free space in the buffer greater than or equal the
sl@0	109	supplied integer parameter, growing the underlying heap buffer
sl@0	110	if necessary.
sl@0	111
sl@0	112	@param aRequiredEmptySpace The minimum value of free space required
sl@0	113
sl@0	114	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	115	grown and there are insufficient resources to do so
sl@0	116	*/
sl@0	117	void LString8::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace)
sl@0	118	{
sl@0	119	ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace);
sl@0	120	}
sl@0	121
sl@0	122	/**
sl@0	123	Grows the underlying buffer using the exponential growth
sl@0	124	function. Guarantees that MaxLength() is greater than or
sl@0	125	equal to 1.5 * the current MaxLength.
sl@0	126
sl@0	127
sl@0	128	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	129	grown and there are insufficient resources to do so
sl@0	130	*/
sl@0	131	void LString8::ReserveCapacityGrowExponentialL()
sl@0	132	{
sl@0	133	ReserveCapacityGrowExponentialL(MaxLength() + 1);
sl@0	134	}
sl@0	135
sl@0	136
sl@0	137	/**
sl@0	138	Default constructor.
sl@0	139
sl@0	140	Constructs a zero-length 8-bit resizable string descriptor.
sl@0	141
sl@0	142	Note that the resulting object owns no allocated memory yet. This
sl@0	143	default constructor never leaves.
sl@0	144	*/
sl@0	145	EXPORT_C LString8::LString8()
sl@0	146	: iReserved(0)
sl@0	147	{
sl@0	148	}
sl@0	149
sl@0	150	/**
sl@0	151	Destructor.
sl@0	152
sl@0	153	Frees any heap-allocated resources owned by this string descriptor. It
sl@0	154	is safe to rely on this destructor to perform all necessary cleanup;
sl@0	155	it is not necessary use the cleanup stack or to call Close() manually.
sl@0	156
sl@0	157	@see RBuf8::Close
sl@0	158	*/
sl@0	159	EXPORT_C LString8::~LString8()
sl@0	160	{
sl@0	161	RBuf8::Close();
sl@0	162	}
sl@0	163
sl@0	164	/**
sl@0	165	Constructor to create a 8-bit resizable string descriptor with an
sl@0	166	initial capacity.
sl@0	167
sl@0	168	The function allocates sufficient memory to contain descriptor data up to
sl@0	169	the specified initial maximum length.
sl@0	170
sl@0	171	The current length of the descriptor is set to zero. The maximum length of
sl@0	172	the descriptor is set to the specified value.
sl@0	173
sl@0	174	@param aMaxLength The maximum length of the descriptor.
sl@0	175
sl@0	176	@leave KErrNoMemory If there is insufficient memory.
sl@0	177
sl@0	178	@see RBuf8::CreateL
sl@0	179	*/
sl@0	180	EXPORT_C LString8::LString8(TInt aMaxLength)
sl@0	181	: iReserved(0)
sl@0	182	{
sl@0	183	RBuf8::CreateL(aMaxLength);
sl@0	184	}
sl@0	185
sl@0	186	/**
sl@0	187	Constructor to create a 8-bit resizable string descriptor from a
sl@0	188	pre-allocated heap descriptor.
sl@0	189
sl@0	190	Transfers ownership of the specified heap descriptor to this object.
sl@0	191
sl@0	192	@param aHBuf The heap descriptor to be transferred to this object.
sl@0	193	This pointer can be NULL, which means that a zero length
sl@0	194	8-bit resizable string descriptor is created.
sl@0	195
sl@0	196	@see RBuf8::RBuf8(HBufC8*)
sl@0	197	*/
sl@0	198	EXPORT_C LString8::LString8(HBufC8* aHBuf)
sl@0	199	: iReserved(0)
sl@0	200	{
sl@0	201	if (aHBuf)
sl@0	202	RBuf8::Assign (aHBuf);
sl@0	203	}
sl@0	204
sl@0	205	/**
sl@0	206	Constructor to create a 8-bit resizable string descriptor from a
sl@0	207	pre-allocated raw heap buffer.
sl@0	208
sl@0	209	The allocated memory forms the buffer for this string descriptor. The
sl@0	210	current length of the descriptor is set to zero.
sl@0	211
sl@0	212	@param aHeapCell The allocated memory to be assigned to this object. This
sl@0	213	pointer can be NULL, which means that a zero length 8-bit
sl@0	214	resizable buffer descriptor is created.
sl@0	215	@param aMaxLength The maximum length of the constructed string descriptor.
sl@0	216
sl@0	217	@panic USER 8 If the specified maximum length is greater then the size of
sl@0	218	the allocated heap cell, or the specified maximum length
sl@0	219	is NOT zero when the pointer to the heap cell is NULL.
sl@0	220
sl@0	221	@see RBuf8::Assign()
sl@0	222	*/
sl@0	223	EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aMaxLength)
sl@0	224	: iReserved(0)
sl@0	225	{
sl@0	226	RBuf8::Assign(aHeapCell, aMaxLength);
sl@0	227	}
sl@0	228
sl@0	229	/**
sl@0	230	Constructor to create a 8-bit resizable string descriptor from a
sl@0	231	pre-allocated raw heap buffer.
sl@0	232
sl@0	233	The allocated memory forms the buffer for this string descriptor. The
sl@0	234	current length of the descriptor is set to the value of the second
sl@0	235	parameter.
sl@0	236
sl@0	237	@param aHeapCell The allocated memory to be assigned to this object.
sl@0	238	@param aLength The length of the resulting string descriptor.
sl@0	239	@param aMaxLength The maximum length of the resulting string descriptor.
sl@0	240
sl@0	241	@panic USER 8 If the specified maximum length is greater then the size of
sl@0	242	the allocated heap cell, or the specified length is greater then
sl@0	243	the specified maximum length, or the specified maximum length
sl@0	244	is NOT zero when the pointer to the heap cell is NULL.
sl@0	245
sl@0	246	@see RBuf8::Assign()
sl@0	247	*/
sl@0	248	EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0	249	: iReserved(0)
sl@0	250	{
sl@0	251	RBuf8::Assign(aHeapCell, aLength, aMaxLength);
sl@0	252	}
sl@0	253
sl@0	254	/**
sl@0	255	Constructor to create a 8-bit resizable string descriptor to contain
sl@0	256	a copy of the specified (source) descriptor, or leave on failure.
sl@0	257
sl@0	258	The constructor allocates sufficient memory so that this string
sl@0	259	descriptor's maximum length is the same as the length of the source
sl@0	260	descriptor. Both the current length and the maximum length of this
sl@0	261	string descriptor are set to the length of the source descriptor.
sl@0	262
sl@0	263	The data contained in the source descriptor is copied into this string
sl@0	264	descriptor.
sl@0	265
sl@0	266	@param aDes Source descriptor to be copied into this object.
sl@0	267
sl@0	268	@leave KErrNoMemory If there is insufficient memory.
sl@0	269
sl@0	270	@see RBuf8::CreateL()
sl@0	271	*/
sl@0	272	EXPORT_C LString8::LString8(const TDesC8& aDes)
sl@0	273	: iReserved(0)
sl@0	274	{
sl@0	275	RBuf8::CreateL(aDes);
sl@0	276	}
sl@0	277
sl@0	278	/**
sl@0	279	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	280	data, and expanding its heap buffer to accommodate if necessary.
sl@0	281
sl@0	282	The length of this descriptor is set to reflect the new data.
sl@0	283
sl@0	284	This operation may cause the target string descriptor's heap buffer to
sl@0	285	be reallocated in order to accommodate the new data. As a result,
sl@0	286	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	287	existing raw pointers to into the descriptor data may be invalidated.
sl@0	288
sl@0	289	Note that the automatic resizing performed is a change to the
sl@0	290	functionality of this operation compared to other descriptor
sl@0	291	classes. This change is only active on objects directly declared
sl@0	292	LString8; when LString8 instances are instead manipulated via
sl@0	293	references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0	294	variant is invoked.
sl@0	295
sl@0	296	@param aDes A 8-bit non-modifiable descriptor.
sl@0	297
sl@0	298	@return A reference to this 8-bit string descriptor.
sl@0	299
sl@0	300	@@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	301	assigned to needs to be expanded, but there is
sl@0	302	insufficient memory to do so
sl@0	303
sl@0	304	@see LString8::CopyL
sl@0	305	*/
sl@0	306	EXPORT_C LString8& LString8::operator=(const TDesC8& aDes)
sl@0	307	{
sl@0	308	CopyL(aDes);
sl@0	309	return *this;
sl@0	310	}
sl@0	311
sl@0	312
sl@0	313	/**
sl@0	314	Transfers ownership of the specified 8-bit descriptor to this object.
sl@0	315
sl@0	316	@param aBuf The source 8-bit buffer. The ownership of this
sl@0	317	object's buffer is to be transferred.
sl@0	318
sl@0	319	@see Assign()
sl@0	320	*/
sl@0	321	EXPORT_C LString8& LString8::operator=(HBufC8* aBuf)
sl@0	322	{
sl@0	323	Assign(aBuf);
sl@0	324	return *this;
sl@0	325	}
sl@0	326
sl@0	327
sl@0	328	/**
sl@0	329	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	330	data, and expanding its heap buffer to accommodate if necessary.
sl@0	331
sl@0	332	The length of this descriptor is set to reflect the new data.
sl@0	333
sl@0	334	This leaving variant of the standard, non-leaving descriptor method
sl@0	335	differs in that this operation may cause the string descriptor's heap
sl@0	336	buffer to be reallocated in order to accommodate the new data. As a
sl@0	337	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	338	and any existing raw pointers to into the descriptor data may be
sl@0	339	invalidated.
sl@0	340
sl@0	341	@param aDes A 8-bit non-modifiable descriptor.
sl@0	342
sl@0	343	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	344	assigned to needs to be expanded, but there is
sl@0	345	insufficient memory to do so
sl@0	346
sl@0	347	@see LString8::operator=
sl@0	348	@see TDes8::Copy
sl@0	349	*/
sl@0	350	EXPORT_C void LString8::CopyL(const TDesC8& aDes)
sl@0	351	{
sl@0	352	ReserveL(aDes.Length());
sl@0	353	RBuf8::Copy(aDes);
sl@0	354	}
sl@0	355
sl@0	356	/**
sl@0	357	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	358	data, and expanding its heap buffer to accommodate if necessary.
sl@0	359
sl@0	360	The length of this descriptor is set to reflect the new data.
sl@0	361
sl@0	362	This leaving variant of the standard, non-leaving descriptor method
sl@0	363	differs in that this operation may cause the string descriptor's heap
sl@0	364	buffer to be reallocated in order to accommodate the new data. As a
sl@0	365	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	366	and any existing raw pointers to into the descriptor data may be
sl@0	367	invalidated.
sl@0	368
sl@0	369	@param aDes A 16-bit non-modifiable descriptor.A 16-bit non-modifiable descriptor.
sl@0	370	Each double-byte value can
sl@0	371	only be copied into the corresponding single byte when the
sl@0	372	double-byte value is less than decimal 256. A double-byte value of
sl@0	373	256 or greater cannot be copied and the corresponding single byte
sl@0	374	is set to a value of decimal 1.
sl@0	375
sl@0	376	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	377	assigned to needs to be expanded, but there is
sl@0	378	insufficient memory to do so
sl@0	379
sl@0	380	@see TDes8::Copy
sl@0	381	*/
sl@0	382	EXPORT_C void LString8::CopyL(const TDesC16& aDes)
sl@0	383	{
sl@0	384	ReserveL(aDes.Length());
sl@0	385	RBuf8::Copy(aDes);
sl@0	386	}
sl@0	387
sl@0	388	/**
sl@0	389	Copy constructor to create a 8-bit resizable string descriptor to
sl@0	390	contain a copy of the specified (source) string descriptor's data, or
sl@0	391	leave on failure.
sl@0	392
sl@0	393	The constructor allocates sufficient memory so that this string
sl@0	394	descriptor's maximum length is the same as the length of the source
sl@0	395	string descriptor. Both the current length and the maximum length of
sl@0	396	this string descriptor are set to the length of the source descriptor.
sl@0	397
sl@0	398	The data contained in the source string descriptor is copied into this
sl@0	399	string descriptor.
sl@0	400
sl@0	401	@param aDes Source string descriptor to be copied into this object.
sl@0	402
sl@0	403	@leave KErrNoMemory If there is insufficient memory.
sl@0	404
sl@0	405	@see RBuf8::CreateL()
sl@0	406	*/
sl@0	407	EXPORT_C LString8::LString8(const LString8& aDes)
sl@0	408	: iReserved(0)
sl@0	409	{
sl@0	410	RBuf8::CreateL(aDes);
sl@0	411	}
sl@0	412
sl@0	413
sl@0	414	/**
sl@0	415	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	416	data, and expanding its heap buffer to accommodate if necessary.
sl@0	417
sl@0	418	The length of this descriptor is set to reflect the new data.
sl@0	419
sl@0	420	This operation may cause the target string descriptor's heap buffer to
sl@0	421	be reallocated in order to accommodate the new data. As a result,
sl@0	422	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	423	existing raw pointers to into the descriptor data may be invalidated.
sl@0	424
sl@0	425	Note that the automatic resizing performed is a change to the
sl@0	426	functionality of this operation compared to other descriptor
sl@0	427	classes. This change is only active on objects directly declared
sl@0	428	LString8; when LString8 instances are instead manipulated via
sl@0	429	references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0	430	variant is invoked.
sl@0	431
sl@0	432	@param aDes A 8-bit string descriptor.
sl@0	433
sl@0	434	@return A reference to this 8-bit string descriptor.
sl@0	435
sl@0	436	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	437	assigned to needs to be expanded, but there is
sl@0	438	insufficient memory to do so
sl@0	439
sl@0	440	@see LString8::CopyL
sl@0	441	*/
sl@0	442	EXPORT_C LString8& LString8::operator=(const LString8& aDes)
sl@0	443	{
sl@0	444	CopyL(aDes);
sl@0	445	return *this;
sl@0	446	}
sl@0	447
sl@0	448	/**
sl@0	449	Constructor to create a 8-bit resizable string descriptor containing
sl@0	450	a copy of the specified (source) zero-terminated string data, or leave
sl@0	451	on failure.
sl@0	452
sl@0	453	The constructor allocates sufficient memory so that this string
sl@0	454	descriptor's maximum length is the same as the length of the source
sl@0	455	string. Both the current length and the maximum length of this string
sl@0	456	descriptor are set to the length of the source string.
sl@0	457
sl@0	458	The data contained in the source string is copied into this string
sl@0	459	descriptor. The zero terminator is not copied.
sl@0	460
sl@0	461	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	462
sl@0	463	@leave KErrNoMemory If there is insufficient memory.
sl@0	464
sl@0	465	@see LString8::CopyL
sl@0	466	*/
sl@0	467	EXPORT_C LString8::LString8(const TUint8* aZeroTerminatedString)
sl@0	468	: iReserved(0)
sl@0	469	{
sl@0	470	CopyL(aZeroTerminatedString);
sl@0	471	}
sl@0	472
sl@0	473	/**
sl@0	474	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	475	data, and expanding its heap buffer to accommodate if necessary.
sl@0	476
sl@0	477	The length of this descriptor is set to reflect the new data.
sl@0	478
sl@0	479	This operation may cause the target string descriptor's heap buffer to
sl@0	480	be reallocated in order to accommodate the new data. As a result,
sl@0	481	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	482	existing raw pointers to into the descriptor data may be invalidated.
sl@0	483
sl@0	484	Note that the automatic resizing performed is a change to the
sl@0	485	functionality of this operation compared to other descriptor
sl@0	486	classes. This change is only active on objects directly declared
sl@0	487	LString8; when LString8 instances are instead manipulated via
sl@0	488	references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0	489	variant is invoked.
sl@0	490
sl@0	491	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	492
sl@0	493	@return A reference to this 8-bit string descriptor.
sl@0	494
sl@0	495	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	496	assigned to needs to be expanded, but there is
sl@0	497	insufficient memory to do so
sl@0	498
sl@0	499	@see LString8::CopyL
sl@0	500	*/
sl@0	501	EXPORT_C LString8& LString8::operator=(const TUint8* aZeroTerminatedString)
sl@0	502	{
sl@0	503	CopyL(aZeroTerminatedString);
sl@0	504	return *this;
sl@0	505	}
sl@0	506
sl@0	507	/**
sl@0	508	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	509	data, and expanding its heap buffer to accommodate if necessary.
sl@0	510
sl@0	511	The length of this descriptor is set to reflect the new data.
sl@0	512
sl@0	513	This leaving variant of the standard, non-leaving descriptor method
sl@0	514	differs in that this operation may cause the string descriptor's heap
sl@0	515	buffer to be reallocated in order to accommodate the new data. As a
sl@0	516	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	517	and any existing raw pointers to into the descriptor data may be
sl@0	518	invalidated.
sl@0	519
sl@0	520	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	521
sl@0	522	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	523	assigned to needs to be expanded, but there is
sl@0	524	insufficient memory to do so
sl@0	525
sl@0	526	@see LString8::operator=
sl@0	527	@see TDes8::Copy
sl@0	528	*/
sl@0	529	EXPORT_C void LString8::CopyL(const TUint8* aZeroTerminatedString)
sl@0	530	{
sl@0	531	ReserveL(User::StringLength(aZeroTerminatedString));
sl@0	532	RBuf8::Copy(aZeroTerminatedString);
sl@0	533	}
sl@0	534
sl@0	535	/**
sl@0	536	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	537	data, and expanding its heap buffer to accommodate if necessary.
sl@0	538
sl@0	539	The length of this descriptor is set according to the second
sl@0	540	parameter.
sl@0	541
sl@0	542	This leaving variant of the standard, non-leaving descriptor method
sl@0	543	differs in that this operation may cause the string descriptor's heap
sl@0	544	buffer to be reallocated in order to accommodate the new data. As a
sl@0	545	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	546	and any existing raw pointers to into the descriptor data may be
sl@0	547	invalidated.
sl@0	548
sl@0	549	@param aBuf The start address of data to be copied.
sl@0	550	@param aLength The length of data to be copied.
sl@0	551
sl@0	552	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	553	assigned to needs to be expanded, but there is
sl@0	554	insufficient memory to do so
sl@0	555
sl@0	556	@panic USER 11 if aLength is negative.
sl@0	557
sl@0	558	@see TDes8::Copy
sl@0	559	*/
sl@0	560	EXPORT_C void LString8::CopyL(const TUint8* aBuf,TInt aLength)
sl@0	561	{
sl@0	562	ReserveL(aLength);
sl@0	563	RBuf8::Copy(aBuf, aLength);
sl@0	564	}
sl@0	565
sl@0	566
sl@0	567	/**
sl@0	568	Sets the length of the data represented by the string descriptor to
sl@0	569	the specified value.
sl@0	570
sl@0	571	This leaving variant of the standard, non-leaving descriptor method
sl@0	572	differs in that this operation may cause the string descriptor's heap
sl@0	573	buffer to be reallocated in order to accommodate the new data. As a
sl@0	574	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	575	and any existing raw pointers to into the descriptor data may be
sl@0	576	invalidated.
sl@0	577
sl@0	578	@param aLength The new length of the descriptor.
sl@0	579
sl@0	580	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	581	grown and there are insufficient resources to do so
sl@0	582
sl@0	583	@panic USER 11 if aLength is negative
sl@0	584	*/
sl@0	585	EXPORT_C void LString8::SetLengthL(TInt aLength)
sl@0	586	{
sl@0	587	ReserveL(aLength);
sl@0	588	RBuf8::SetLength(aLength);
sl@0	589	}
sl@0	590
sl@0	591
sl@0	592	/**
sl@0	593	Sets the storage space allocated to this descriptor to the specified
sl@0	594	value by growing or compressing its buffer size.
sl@0	595
sl@0	596	If the current length of the descriptor is greater than the specified
sl@0	597	max length, length is truncated to max length.
sl@0	598
sl@0	599	This leaving variant of the standard, non-leaving descriptor method
sl@0	600	differs in that this operation may cause the string descriptor's heap
sl@0	601	buffer to be reallocated in order to accommodate the new data. As a
sl@0	602	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	603	and any existing raw pointers to into the descriptor data may be
sl@0	604	invalidated.
sl@0	605
sl@0	606	@param aMaxLength The new maximum length of the descriptor.
sl@0	607
sl@0	608	@leave KErrNoMemory if the the buffer needs to be
sl@0	609	reallocated and there are insufficient resources to do so
sl@0	610
sl@0	611	@panic USER 11 if aLength is negative
sl@0	612	*/
sl@0	613	EXPORT_C void LString8::SetMaxLengthL(TInt aMaxLength)
sl@0	614	{
sl@0	615	if (MaxLength() == aMaxLength)
sl@0	616	{
sl@0	617	return;
sl@0	618	}
sl@0	619
sl@0	620	if (Length() > aMaxLength)
sl@0	621	{
sl@0	622	// truncate the current length
sl@0	623	RBuf8::SetLength(aMaxLength);
sl@0	624	}
sl@0	625
sl@0	626	ReAllocL(aMaxLength);
sl@0	627	}
sl@0	628
sl@0	629
sl@0	630	/**
sl@0	631	Ensures that the remaining unused space is more than the supplied value.
sl@0	632
sl@0	633	May reallocate a larger storage space to meet the requirement.
sl@0	634	As a result MaxLength() and Ptr() may return different values afterwards,
sl@0	635	and any existing raw pointers to into the descriptor data may be
sl@0	636	invalidated.
sl@0	637
sl@0	638	Typically, you use this method to reserve a known amount of required space
sl@0	639	in one go instead of relying on the automatic growth pattern.
sl@0	640
sl@0	641	@param aExtraSpaceLength The extra space required.
sl@0	642
sl@0	643	@leave KErrNoMemory if the the buffer needs to be
sl@0	644	reallocated and there are insufficient resources to do so.
sl@0	645
sl@0	646	@panic USER 11 if aLength is negative
sl@0	647	*/
sl@0	648	EXPORT_C void LString8::ReserveFreeCapacityL(TInt aExtraSpaceLength)
sl@0	649	{
sl@0	650	ReserveL(Length() + aExtraSpaceLength);
sl@0	651	}
sl@0	652
sl@0	653
sl@0	654	/**
sl@0	655	Re-initialises the descriptor destroying its payload
sl@0	656
sl@0	657	*/
sl@0	658	EXPORT_C void LString8::Reset()
sl@0	659	{
sl@0	660	RBuf8::Close();
sl@0	661	}
sl@0	662
sl@0	663
sl@0	664	/**
sl@0	665	Re-allocates a smaller descriptor buffer space to the current
sl@0	666	descriptor length
sl@0	667
sl@0	668	This may cause the string descriptor's heap buffer to be reallocated
sl@0	669	in order to accommodate the new data. As a
sl@0	670	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	671	and any existing raw pointers to into the descriptor data may be
sl@0	672	invalidated.
sl@0	673
sl@0	674	If there is insufficient memory to re-allocate the buffer then the
sl@0	675	descriptor left unchanged
sl@0	676	*/
sl@0	677	EXPORT_C void LString8::Compress()
sl@0	678	{
sl@0	679	TInt length = Length();
sl@0	680	if (MaxLength() > length)
sl@0	681	{
sl@0	682	//coverity[checked_return]
sl@0	683	/*Check for return value from realloc is not needed because neither can
sl@0	684	* maxlength be negative or length be less than the existing data length
sl@0	685	*/
sl@0	686	ReAlloc(length);
sl@0	687	}
sl@0	688	}
sl@0	689
sl@0	690	/**
sl@0	691	Appends data onto the end of this descriptor's data.
sl@0	692
sl@0	693	The length of this descriptor is incremented to reflect the new content.
sl@0	694
sl@0	695	This leaving variant of the standard, non-leaving descriptor method
sl@0	696	differs in that this operation may cause the string descriptor's heap
sl@0	697	buffer to be reallocated in order to accommodate the new data. As a
sl@0	698	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	699	and any existing raw pointers to into the descriptor data may be
sl@0	700	invalidated.
sl@0	701
sl@0	702	@param aChar A single character to be appended. The length of the descriptor
sl@0	703	is incremented by one.
sl@0	704
sl@0	705	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	706	grown and there are insufficient resources to do so
sl@0	707
sl@0	708	@see LString8::operator+=
sl@0	709	*/
sl@0	710	EXPORT_C void LString8::AppendL(TChar aChar)
sl@0	711	{
sl@0	712	ReserveFreeCapacityGrowExponentialL(1);
sl@0	713	RBuf8::Append(aChar);
sl@0	714	}
sl@0	715
sl@0	716	/**
sl@0	717	Appends data onto the end of this descriptor's data.
sl@0	718
sl@0	719	The length of this descriptor is incremented to reflect the new content.
sl@0	720
sl@0	721	This leaving variant of the standard, non-leaving descriptor method
sl@0	722	differs in that this operation may cause the string descriptor's heap
sl@0	723	buffer to be reallocated in order to accommodate the new data. As a
sl@0	724	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	725	and any existing raw pointers to into the descriptor data may be
sl@0	726	invalidated.
sl@0	727
sl@0	728	@param aChar A single character to be appended. The length of the descriptor
sl@0	729	is incremented by one.
sl@0	730
sl@0	731	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	732	grown and there are insufficient resources to do so
sl@0	733
sl@0	734	@see LString8::AppendL
sl@0	735	*/
sl@0	736	EXPORT_C LString8& LString8::operator+=(TChar aChar)
sl@0	737	{
sl@0	738	AppendL(aChar);
sl@0	739	return *this;
sl@0	740	}
sl@0	741
sl@0	742	/**
sl@0	743	Appends data onto the end of this descriptor's data.
sl@0	744
sl@0	745	The length of this descriptor is incremented to reflect the new content.
sl@0	746
sl@0	747	This leaving variant of the standard, non-leaving descriptor method
sl@0	748	differs in that this operation may cause the string descriptor's heap
sl@0	749	buffer to be reallocated in order to accommodate the new data. As a
sl@0	750	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	751	and any existing raw pointers to into the descriptor data may be
sl@0	752	invalidated.
sl@0	753
sl@0	754	@param aDes A 8-bit non modifiable descriptor whose data is to be appended.
sl@0	755
sl@0	756	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	757	grown and there are insufficient resources to do so
sl@0	758	*/
sl@0	759	EXPORT_C void LString8::AppendL(const TDesC8& aDes)
sl@0	760	{
sl@0	761	ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0	762	RBuf8::Append(aDes);
sl@0	763	}
sl@0	764
sl@0	765	/**
sl@0	766	Appends data onto the end of this descriptor's data.
sl@0	767
sl@0	768	The length of this descriptor is incremented to reflect the new content.
sl@0	769
sl@0	770	This leaving variant of the standard, non-leaving descriptor method
sl@0	771	differs in that this operation may cause the string descriptor's heap
sl@0	772	buffer to be reallocated in order to accommodate the new data. As a
sl@0	773	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	774	and any existing raw pointers to into the descriptor data may be
sl@0	775	invalidated.
sl@0	776
sl@0	777	@param aDes A 8-bit non modifiable descriptor whose data is to be appended.
sl@0	778
sl@0	779	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	780	grown and there are insufficient resources to do so
sl@0	781
sl@0	782	@see LString8::AppendL
sl@0	783	*/
sl@0	784	EXPORT_C LString8& LString8::operator+=(const TDesC8& aDes)
sl@0	785	{
sl@0	786	AppendL(aDes);
sl@0	787	return *this;
sl@0	788	}
sl@0	789
sl@0	790	/**
sl@0	791	Appends data onto the end of this descriptor's data.
sl@0	792
sl@0	793	The length of this descriptor is incremented to reflect the new content.
sl@0	794
sl@0	795	This leaving variant of the standard, non-leaving descriptor method
sl@0	796	differs in that this operation may cause the string descriptor's heap
sl@0	797	buffer to be reallocated in order to accommodate the new data. As a
sl@0	798	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	799	and any existing raw pointers to into the descriptor data may be
sl@0	800	invalidated.
sl@0	801
sl@0	802	@param aBuf A pointer to the data to be copied.
sl@0	803	@param aLength The length of data to be copied.
sl@0	804
sl@0	805	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	806	grown and there are insufficient resources to do so
sl@0	807
sl@0	808	@panic USER 17 if aLength is negative.
sl@0	809	*/
sl@0	810	EXPORT_C void LString8::AppendL(const TUint8* aBuf,TInt aLength)
sl@0	811	{
sl@0	812	ReserveFreeCapacityGrowExponentialL(aLength);
sl@0	813	RBuf8::Append(aBuf, aLength);
sl@0	814	}
sl@0	815
sl@0	816	/**
sl@0	817	Fills the descriptor's data area with the specified character, replacing any
sl@0	818	existing data.
sl@0	819
sl@0	820	The descriptor is filled with the specified number of characters,
sl@0	821	and its length is changed to reflect this.
sl@0	822
sl@0	823	This leaving variant of the standard, non-leaving descriptor method
sl@0	824	differs in that this operation may cause the string descriptor's heap
sl@0	825	buffer to be reallocated in order to accommodate the new data. As a
sl@0	826	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	827	and any existing raw pointers to into the descriptor data may be
sl@0	828	invalidated.
sl@0	829
sl@0	830	@param aChar The fill character.
sl@0	831	@param aLength The new length of the descriptor and the number of fill characters
sl@0	832	to be copied into it.
sl@0	833
sl@0	834	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	835	grown and there are insufficient resources to do so
sl@0	836
sl@0	837	@panic USER 11 if aLength is negative
sl@0	838	*/
sl@0	839	EXPORT_C void LString8::FillL(TChar aChar,TInt aLength)
sl@0	840	{
sl@0	841	ReserveL(aLength);
sl@0	842	RBuf8::Fill(aChar, aLength);
sl@0	843	}
sl@0	844
sl@0	845	/**
sl@0	846	Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any
sl@0	847	existing data, and changes its length.
sl@0	848
sl@0	849	The descriptor is filled with the specified number of binary zeroes.
sl@0	850	The descriptor's length is changed to reflect this.
sl@0	851
sl@0	852	This leaving variant of the standard, non-leaving descriptor method
sl@0	853	differs in that this operation may cause the string descriptor's heap
sl@0	854	buffer to be reallocated in order to accommodate the new data. As a
sl@0	855	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	856	and any existing raw pointers to into the descriptor data may be
sl@0	857	invalidated.
sl@0	858
sl@0	859	@param aLength The new length of the descriptor and the number of binary zeroes
sl@0	860	to be copied into it.
sl@0	861
sl@0	862	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	863	grown and there are insufficient resources to do so
sl@0	864
sl@0	865	@panic USER 11 if aLength is negative
sl@0	866	*/
sl@0	867	EXPORT_C void LString8::FillZL(TInt aLength)
sl@0	868	{
sl@0	869	ReserveL(aLength);
sl@0	870	RBuf8::FillZ(aLength);
sl@0	871	}
sl@0	872
sl@0	873	/**
sl@0	874	Converts the specified unsigned integer into a fixed width character
sl@0	875	representation based on the specified number system and copies the conversion
sl@0	876	into this descriptor, replacing any existing data.
sl@0	877
sl@0	878	The length of this descriptor is set to reflect the new data.
sl@0	879
sl@0	880	The function generates the exact number of specified characters, either padding
sl@0	881	to the left with character zeroes or discarding low order characters as necessary.
sl@0	882
sl@0	883	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	884	lower case.
sl@0	885
sl@0	886	This function is equivalent to using Format() with parameters which specify:
sl@0	887
sl@0	888	1. a fixed length target field
sl@0	889
sl@0	890	2. padding with zero characters, for example "%08x".
sl@0	891
sl@0	892	When this is the case, always use NumFixedWidth() in preference
sl@0	893	to Format() as it is more efficient.
sl@0	894
sl@0	895	This leaving variant of the standard, non-leaving descriptor method
sl@0	896	differs in that this operation may cause the string descriptor's heap
sl@0	897	buffer to be reallocated in order to accommodate the new data. As a
sl@0	898	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	899	and any existing raw pointers to into the descriptor data may be
sl@0	900	invalidated.
sl@0	901
sl@0	902	@param aVal The unsigned integer value.
sl@0	903	@param aRadix The number system representation for the unsigned integer.
sl@0	904	@param aWidth The number of characters: to be used to contain the conversion,
sl@0	905	to be copied into this descriptor.
sl@0	906
sl@0	907	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	908	grown and there are insufficient resources to do so
sl@0	909	*/
sl@0	910	EXPORT_C void LString8::NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	911	{
sl@0	912	Zero();
sl@0	913	AppendNumFixedWidthL(aVal, aRadix, aWidth);
sl@0	914	}
sl@0	915
sl@0	916	/**
sl@0	917	Converts the specified unsigned integer into a fixed width character
sl@0	918	representation based on the specified number system and appends the conversion
sl@0	919	onto the end of this descriptor's data.
sl@0	920
sl@0	921	The length of this descriptor is incremented to reflect the new content.
sl@0	922
sl@0	923	The function generates the exact number of specified characters, either padding
sl@0	924	to the left with character zeroes or discarding low order characters as
sl@0	925	necessary.
sl@0	926
sl@0	927	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	928	lower case.
sl@0	929
sl@0	930	This leaving variant of the standard, non-leaving descriptor method
sl@0	931	differs in that this operation may cause the string descriptor's heap
sl@0	932	buffer to be reallocated in order to accommodate the new data. As a
sl@0	933	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	934	and any existing raw pointers to into the descriptor data may be
sl@0	935	invalidated.
sl@0	936
sl@0	937	@param aVal The unsigned integer value.
sl@0	938	@param aRadix The number system representation for the unsigned integer.
sl@0	939	@param aWidth The number of characters to be used to contain the conversion,
sl@0	940	and to be appended to this descriptor.
sl@0	941
sl@0	942	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	943	grown and there are insufficient resources to do so
sl@0	944	*/
sl@0	945	EXPORT_C void LString8::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	946	{
sl@0	947	ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0	948	RBuf8::AppendNumFixedWidth(aVal, aRadix, aWidth);
sl@0	949	}
sl@0	950
sl@0	951	/**
sl@0	952	Appends a zero terminator onto the end of this descriptor's data and returns
sl@0	953	a pointer to the data.
sl@0	954
sl@0	955	The length of the descriptor is not changed, but the capacity of the
sl@0	956	descriptor may need to be grown to accommodate the zero terminator.
sl@0	957
sl@0	958	This leaving variant of the standard, non-leaving descriptor method
sl@0	959	differs in that this operation may cause the string descriptor's heap
sl@0	960	buffer to be reallocated in order to accommodate the new data. As a
sl@0	961	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	962	and any existing raw pointers to into the descriptor data may be
sl@0	963	invalidated.
sl@0	964
sl@0	965	@return A pointer to the descriptor's zero terminated data.
sl@0	966
sl@0	967	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	968	grown and there are insufficient resources to do so
sl@0	969	*/
sl@0	970	EXPORT_C const TUint8 *LString8::PtrZL()
sl@0	971	{
sl@0	972	ReserveFreeCapacityL(1);
sl@0	973	return RBuf8::PtrZ();
sl@0	974	}
sl@0	975
sl@0	976	/**
sl@0	977	Copies and folds data from the specified descriptor into this descriptor replacing
sl@0	978	any existing data.
sl@0	979
sl@0	980	The length of this descriptor is set to reflect the new
sl@0	981	data.
sl@0	982
sl@0	983	Note that folding is locale-independent behaviour. It is also important to
sl@0	984	note that there can be no guarantee that folding is in any way culturally
sl@0	985	appropriate, and should not be used when dealing with strings in natural
sl@0	986	language.
sl@0	987
sl@0	988	This leaving variant of the standard, non-leaving descriptor method
sl@0	989	differs in that this operation may cause the string descriptor's heap
sl@0	990	buffer to be reallocated in order to accommodate the new data. As a
sl@0	991	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	992	and any existing raw pointers to into the descriptor data may be
sl@0	993	invalidated.
sl@0	994
sl@0	995	@param aDes A 8-bit non-modifiable descriptor.
sl@0	996
sl@0	997	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	998	grown and there are insufficient resources to do so
sl@0	999	*/
sl@0	1000	EXPORT_C void LString8::CopyFL(const TDesC8& aDes)
sl@0	1001	{
sl@0	1002	ReserveL(aDes.Length());
sl@0	1003	RBuf8::CopyF(aDes);
sl@0	1004	}
sl@0	1005
sl@0	1006	/**
sl@0	1007	Copies and collates data from the specified descriptor
sl@0	1008	into this descriptor replacing any existing data.
sl@0	1009
sl@0	1010	The length of this descriptor is set to reflect the new data.
sl@0	1011
sl@0	1012	This leaving variant of the standard, non-leaving descriptor method
sl@0	1013	differs in that this operation may cause the string descriptor's heap
sl@0	1014	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1015	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1016	and any existing raw pointers to into the descriptor data may be
sl@0	1017	invalidated.
sl@0	1018
sl@0	1019	@param aDes A 8-bit non-modifiable descriptor.
sl@0	1020
sl@0	1021	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1022	grown and there are insufficient resources to do so
sl@0	1023	*/
sl@0	1024	EXPORT_C void LString8::CopyCL(const TDesC8& aDes)
sl@0	1025	{
sl@0	1026	ReserveL(aDes.Length());
sl@0	1027	RBuf8::CopyC(aDes);
sl@0	1028	}
sl@0	1029
sl@0	1030	/**
sl@0	1031	Copies text from the specified descriptor and converts it to lower case before
sl@0	1032	putting it into this descriptor, replacing any existing data.
sl@0	1033
sl@0	1034	The length of this descriptor is set to reflect the new data.
sl@0	1035
sl@0	1036	Conversion to lower case is implemented as appropriate to the current locale.
sl@0	1037
sl@0	1038	This leaving variant of the standard, non-leaving descriptor method
sl@0	1039	differs in that this operation may cause the string descriptor's heap
sl@0	1040	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1041	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1042	and any existing raw pointers to into the descriptor data may be
sl@0	1043	invalidated.
sl@0	1044
sl@0	1045	@param aDes A 8-bit non modifiable descriptor.
sl@0	1046
sl@0	1047	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1048	grown and there are insufficient resources to do so
sl@0	1049	*/
sl@0	1050	EXPORT_C void LString8::CopyLCL(const TDesC8& aDes)
sl@0	1051	{
sl@0	1052	ReserveL(aDes.Length());
sl@0	1053	RBuf8::CopyLC(aDes);
sl@0	1054	}
sl@0	1055
sl@0	1056	/**
sl@0	1057	Copies text from the specified descriptor and converts it to upper case before
sl@0	1058	putting it into this descriptor, replacing any existing data.
sl@0	1059
sl@0	1060	The length of this descriptor is set to reflect the new data.
sl@0	1061
sl@0	1062	Conversion to upper case is implemented as appropriate to the current locale.
sl@0	1063
sl@0	1064	This leaving variant of the standard, non-leaving descriptor method
sl@0	1065	differs in that this operation may cause the string descriptor's heap
sl@0	1066	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1067	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1068	and any existing raw pointers to into the descriptor data may be
sl@0	1069	invalidated.
sl@0	1070
sl@0	1071	@param aDes A 8-bit non modifiable descriptor.
sl@0	1072
sl@0	1073	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1074	grown and there are insufficient resources to do so
sl@0	1075	*/
sl@0	1076	EXPORT_C void LString8::CopyUCL(const TDesC8& aDes)
sl@0	1077	{
sl@0	1078	ReserveL(aDes.Length());
sl@0	1079	RBuf8::CopyUC(aDes);
sl@0	1080	}
sl@0	1081
sl@0	1082	/**
sl@0	1083	Copies text from the specified descriptor and capitalises it before putting
sl@0	1084	it into this descriptor, replacing any existing data.
sl@0	1085
sl@0	1086	The length of this descriptor is set to reflect the new data.
sl@0	1087
sl@0	1088	Capitalisation is implemented as appropriate to the current locale.
sl@0	1089
sl@0	1090	This leaving variant of the standard, non-leaving descriptor method
sl@0	1091	differs in that this operation may cause the string descriptor's heap
sl@0	1092	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1093	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1094	and any existing raw pointers to into the descriptor data may be
sl@0	1095	invalidated.
sl@0	1096
sl@0	1097	@param aDes A 8-bit non-modifiable descriptor.
sl@0	1098
sl@0	1099	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1100	grown and there are insufficient resources to do so
sl@0	1101	*/
sl@0	1102	EXPORT_C void LString8::CopyCPL(const TDesC8& aDes)
sl@0	1103	{
sl@0	1104	ReserveL(aDes.Length());
sl@0	1105	RBuf8::CopyCP(aDes);
sl@0	1106	}
sl@0	1107
sl@0	1108	/**
sl@0	1109	Appends and fills this descriptor with the specified character.
sl@0	1110
sl@0	1111	The descriptor is appended with the specified number of characters.
sl@0	1112	and its length is changed to reflect this.
sl@0	1113
sl@0	1114	This leaving variant of the standard, non-leaving descriptor method
sl@0	1115	differs in that this operation may cause the string descriptor's heap
sl@0	1116	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1117	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1118	and any existing raw pointers to into the descriptor data may be
sl@0	1119	invalidated.
sl@0	1120
sl@0	1121	@param aChar The fill character.
sl@0	1122	@param aLength The number of fill characters to be appended.
sl@0	1123
sl@0	1124	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1125	grown and there are insufficient resources to do so
sl@0	1126
sl@0	1127	@panic USER 11 if aLength is negative
sl@0	1128	*/
sl@0	1129	EXPORT_C void LString8::AppendFillL(TChar aChar,TInt aLength)
sl@0	1130	{
sl@0	1131	ReserveFreeCapacityGrowExponentialL(aLength);
sl@0	1132	RBuf8::AppendFill(aChar, aLength);
sl@0	1133	}
sl@0	1134
sl@0	1135	/**
sl@0	1136	Appends a zero terminator onto the end of this descriptor's data.
sl@0	1137
sl@0	1138	The length of the descriptor is not changed, but the capacity of the
sl@0	1139	descriptor may need to be grown to accommodate the zero terminator.
sl@0	1140
sl@0	1141	This leaving variant of the standard, non-leaving descriptor method
sl@0	1142	differs in that this operation may cause the string descriptor's heap
sl@0	1143	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1144	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1145	and any existing raw pointers to into the descriptor data may be
sl@0	1146	invalidated.
sl@0	1147
sl@0	1148	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1149	grown and there are insufficient resources to do so
sl@0	1150	*/
sl@0	1151	EXPORT_C void LString8::ZeroTerminateL()
sl@0	1152	{
sl@0	1153	ReserveFreeCapacityL(1);
sl@0	1154	RBuf8::ZeroTerminate();
sl@0	1155	}
sl@0	1156
sl@0	1157	/**
sl@0	1158	Swaps the data represented by this descriptor with the data represented by
sl@0	1159	the specified descriptor.
sl@0	1160
sl@0	1161	The lengths of both descriptors are also swapped to reflect the change.
sl@0	1162
sl@0	1163	Note that each descriptor must be capable of accommodating the contents of
sl@0	1164	the other descriptor.
sl@0	1165
sl@0	1166	Each descriptor must be capable of accommodating the contents of the
sl@0	1167	other descriptor. If the maximum length of the descriptor parameter is
sl@0	1168	smaller than the length of the target LString8, then the function
sl@0	1169	raises a USER 11 panic. The target LString8 will be grown if
sl@0	1170	necessary to accommodate the descriptor parameter's data.
sl@0	1171
sl@0	1172	This leaving variant of the standard, non-leaving descriptor method
sl@0	1173	differs in that this operation may cause the string descriptor's heap
sl@0	1174	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1175	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1176	and any existing raw pointers to into the descriptor data may be
sl@0	1177	invalidated.
sl@0	1178
sl@0	1179	@param aDes The 8-bit modifiable descriptor whose data is to be swapped with
sl@0	1180	the data of this descriptor.
sl@0	1181
sl@0	1182	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1183	grown and there are insufficient resources to do so
sl@0	1184
sl@0	1185	@panic USER 11 if the maximum length of the descriptor parameter is smaller than the
sl@0	1186	length of the target LString8
sl@0	1187	*/
sl@0	1188	EXPORT_C void LString8::SwapL(TDes8& aDes)
sl@0	1189	{
sl@0	1190	ReserveL(aDes.Length());
sl@0	1191	TDes8::Swap(aDes);
sl@0	1192	}
sl@0	1193
sl@0	1194	/**
sl@0	1195	Swaps the data represented by this string descriptor with the data
sl@0	1196	represented by the specified string descriptor.
sl@0	1197
sl@0	1198	The lengths of both string descriptors are also swapped to reflect the
sl@0	1199	change, and their buffers grown as necessary to accommodate the data
sl@0	1200	they receive.
sl@0	1201
sl@0	1202	This leaving variant of the standard, non-leaving descriptor method
sl@0	1203	differs in that this operation may cause the string descriptor's heap
sl@0	1204	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1205	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1206	and any existing raw pointers to into the descriptor data may be
sl@0	1207	invalidated.
sl@0	1208
sl@0	1209	@param aDes The 8-bit modifiable string descriptor whose data is to be swapped with
sl@0	1210	the data of this descriptor.
sl@0	1211
sl@0	1212	@leave KErrNoMemory if one of the underlying buffers needs to be
sl@0	1213	grown and there are insufficient resources to do so
sl@0	1214	*/
sl@0	1215	EXPORT_C void LString8::SwapL(LString8& aDes)
sl@0	1216	{
sl@0	1217	this->ReserveL(aDes.Length());
sl@0	1218	aDes.ReserveL(this->Length());
sl@0	1219	TDes8::Swap(aDes);
sl@0	1220	}
sl@0	1221
sl@0	1222
sl@0	1223	/**
sl@0	1224	Inserts data into this descriptor.
sl@0	1225
sl@0	1226	The length of this descriptor is changed to reflect the extra data.
sl@0	1227
sl@0	1228	This leaving variant of the standard, non-leaving descriptor method
sl@0	1229	differs in that this operation may cause the string descriptor's heap
sl@0	1230	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1231	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1232	and any existing raw pointers to into the descriptor data may be
sl@0	1233	invalidated.
sl@0	1234
sl@0	1235	@param aPos The position within the data where insertion is to start. This
sl@0	1236	is an offset value; a zero value refers to the leftmost data
sl@0	1237	position.
sl@0	1238
sl@0	1239	@param aDes A 8-bit non modifiable descriptor whose data is to be inserted.
sl@0	1240
sl@0	1241	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1242	grown and there are insufficient resources to do so
sl@0	1243
sl@0	1244	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	1245	descriptor.
sl@0	1246	*/
sl@0	1247	EXPORT_C void LString8::InsertL(TInt aPos,const TDesC8& aDes)
sl@0	1248	{
sl@0	1249	ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0	1250	RBuf8::Insert(aPos, aDes);
sl@0	1251	}
sl@0	1252
sl@0	1253	/**
sl@0	1254	Replaces data in this descriptor.
sl@0	1255
sl@0	1256	The specified length can be different to the length of the replacement data.
sl@0	1257	The length of this descriptor changes to reflect the change of data.
sl@0	1258
sl@0	1259	This leaving variant of the standard, non-leaving descriptor method
sl@0	1260	differs in that this operation may cause the string descriptor's heap
sl@0	1261	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1262	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1263	and any existing raw pointers to into the descriptor data may be
sl@0	1264	invalidated.
sl@0	1265
sl@0	1266	@param aPos The position within the data where replacement is to start.
sl@0	1267	This is an offset value; a zero value refers to the leftmost
sl@0	1268	data position.
sl@0	1269
sl@0	1270	@param aLength The length of data to be replaced.
sl@0	1271
sl@0	1272	@param aDes The source 8-bit non modifiable descriptor whose data is to
sl@0	1273	replace the target descriptor's data at aPos.
sl@0	1274
sl@0	1275	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1276	grown and there are insufficient resources to do so
sl@0	1277
sl@0	1278	@panic USER 8 if aLength is negative
sl@0	1279
sl@0	1280	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	1281	descriptor.
sl@0	1282
sl@0	1283	@panic USER 16 if the length of the source descriptor aDes is negative
sl@0	1284	*/
sl@0	1285	EXPORT_C void LString8::ReplaceL(TInt aPos,TInt aLength,const TDesC8& aDes)
sl@0	1286	{
sl@0	1287	TInt delta = aDes.Length() - aLength;
sl@0	1288	if (delta > 0)
sl@0	1289	{
sl@0	1290	ReserveFreeCapacityGrowExponentialL(delta);
sl@0	1291	}
sl@0	1292	RBuf8::Replace(aPos, aLength, aDes);
sl@0	1293	}
sl@0	1294
sl@0	1295	/**
sl@0	1296	Copies data into this descriptor and justifies it, replacing any existing data.
sl@0	1297
sl@0	1298	The length of this descriptor is set to reflect the new data.
sl@0	1299
sl@0	1300	The target area is considered to be an area of specified width positioned at
sl@0	1301	the beginning of this descriptor's data area. Source data is copied into, and
sl@0	1302	aligned within this target area according to the specified alignment
sl@0	1303	instruction.
sl@0	1304
sl@0	1305	If the length of the target area is larger than the length of the source, then
sl@0	1306	spare space within the target area is padded with the fill character.
sl@0	1307
sl@0	1308	This leaving variant of the standard, non-leaving descriptor method
sl@0	1309	differs in that this operation may cause the string descriptor's heap
sl@0	1310	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1311	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1312	and any existing raw pointers to into the descriptor data may be
sl@0	1313	invalidated.
sl@0	1314
sl@0	1315	@param aDes A 8-bit non-modifiable descriptor containing the source data.
sl@0	1316	The length of the data to be copied is the smaller of:
sl@0	1317	the length of the source descriptor, and
sl@0	1318	the width of the target area (only if this is not the
sl@0	1319	explicit negative value KDefaultJustifyWidth).
sl@0	1320
sl@0	1321	@param aWidth The width of the target area. If this has the specific
sl@0	1322	negative value KDefaultJustifyWidth, then the width is
sl@0	1323	re-set to the length of the data source.
sl@0	1324
sl@0	1325	@param aAlignment The alignment of the data within the target area
sl@0	1326
sl@0	1327	@param aFill The fill character used to pad the target area.
sl@0	1328
sl@0	1329	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1330	grown and there are insufficient resources to do so
sl@0	1331
sl@0	1332	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1333	*/
sl@0	1334	EXPORT_C void LString8::JustifyL(const TDesC8& aDes,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1335	{
sl@0	1336	TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth);
sl@0	1337	ReserveL(width);
sl@0	1338	RBuf8::Justify(aDes, aWidth, aAlignment, aFill);
sl@0	1339	}
sl@0	1340
sl@0	1341	/**
sl@0	1342	Converts the specified unsigned integer into a fixed width character
sl@0	1343	representation based on the specified number system and copies the conversion
sl@0	1344	into this descriptor, replacing any existing data.
sl@0	1345
sl@0	1346	The length of this descriptor is set to reflect the new data.
sl@0	1347
sl@0	1348	The function generates the exact number of specified characters, either padding
sl@0	1349	to the left with character zeroes or discarding low order characters as
sl@0	1350	necessary.
sl@0	1351
sl@0	1352	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1353	upper case.
sl@0	1354
sl@0	1355	This function is equivalent to using Format() with parameters which specify:
sl@0	1356
sl@0	1357	1. a fixed length target field
sl@0	1358
sl@0	1359	2. padding with zero characters, for example "%08x".
sl@0	1360
sl@0	1361	When this is the case, always use NumFixedWidthUC() in
sl@0	1362	preference to Format() as it is more efficient.
sl@0	1363
sl@0	1364	This leaving variant of the standard, non-leaving descriptor method
sl@0	1365	differs in that this operation may cause the string descriptor's heap
sl@0	1366	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1367	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1368	and any existing raw pointers to into the descriptor data may be
sl@0	1369	invalidated.
sl@0	1370
sl@0	1371	@param aVal The unsigned integer value.
sl@0	1372	@param aRadix The number system representation for the unsigned integer.
sl@0	1373	@param aWidth The number of characters: to be used to contain the conversion,
sl@0	1374	to be copied into this descriptor.
sl@0	1375
sl@0	1376	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1377	grown and there are insufficient resources to do so
sl@0	1378
sl@0	1379	@see TDes8::Format()
sl@0	1380	*/
sl@0	1381	EXPORT_C void LString8::NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	1382	{
sl@0	1383	Zero();
sl@0	1384	AppendNumFixedWidthUCL(aVal, aRadix, aWidth);
sl@0	1385	}
sl@0	1386
sl@0	1387	/**
sl@0	1388	Converts the specified 64 bit unsigned integer into a character representation
sl@0	1389	based on the specified number system and copies the conversion into this
sl@0	1390	descriptor, replacing any existing data.
sl@0	1391
sl@0	1392	The length of this descriptor is set to reflect the new data.
sl@0	1393
sl@0	1394	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1395	upper case.
sl@0	1396
sl@0	1397	This leaving variant of the standard, non-leaving descriptor method
sl@0	1398	differs in that this operation may cause the string descriptor's heap
sl@0	1399	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1400	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1401	and any existing raw pointers to into the descriptor data may be
sl@0	1402	invalidated.
sl@0	1403
sl@0	1404	@param aVal The 64 bit integer value. This is always treated as an unsigned
sl@0	1405	value for all builds.
sl@0	1406	@param aRadix The number system representation for the 64 bit integer. If no
sl@0	1407	explicit value is specified, then EDecimal is the default.
sl@0	1408
sl@0	1409	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1410	grown and there are insufficient resources to do so
sl@0	1411	*/
sl@0	1412	EXPORT_C void LString8::NumUCL(TUint64 aVal, TRadix aRadix)
sl@0	1413	{
sl@0	1414	Zero();
sl@0	1415	AppendNumUCL(aVal, aRadix);
sl@0	1416	}
sl@0	1417
sl@0	1418	/**
sl@0	1419	Converts the specified floating point number into a character representation
sl@0	1420	and copies the conversion into this descriptor, replacing any existing data.
sl@0	1421
sl@0	1422	The length of this descriptor is set to reflect the new data.
sl@0	1423
sl@0	1424	The character representation of the real number is dictated by the specified
sl@0	1425	format.
sl@0	1426
sl@0	1427	Note that the function leaves if the iType data member of the specified
sl@0	1428	TRealFormat object has both an invalid character representation format
sl@0	1429	(i.e. the format type) and invalid format flags.
sl@0	1430
sl@0	1431	This leaving variant of the standard, non-leaving descriptor method
sl@0	1432	differs in that this operation may cause the string descriptor's heap
sl@0	1433	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1434	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1435	and any existing raw pointers to into the descriptor data may be
sl@0	1436	invalidated.
sl@0	1437
sl@0	1438	@param aVal The floating point number to be converted.
sl@0	1439	@param aFormat The format of the conversion.
sl@0	1440
sl@0	1441	@return If the conversion is successful, the length of this descriptor. If
sl@0	1442	the conversion fails, a negative value indicating the cause of failure.
sl@0	1443	In addition, extra information on the cause of the failure may be
sl@0	1444	appended onto this descriptor. The possible values and their meaning
sl@0	1445	are:
sl@0	1446
sl@0	1447	1.KErrArgument - the supplied floating point number is not a valid
sl@0	1448	number. The three characters NaN are appended to this descriptor.
sl@0	1449
sl@0	1450	2.KErrOverflow - the number is too large to represent.
sl@0	1451	2.1 For positive overflow, the three characters Inf are appended
sl@0	1452	to this descriptor.
sl@0	1453	2.2 For negative overflow, the four characters -Inf are appended
sl@0	1454	to this descriptor.
sl@0	1455
sl@0	1456	3.KErrUnderflow - the number is too small to represent.
sl@0	1457	3.1 For positive underflow, the three characters Inf are appended
sl@0	1458	to this descriptor.
sl@0	1459	3.2 For negative underflow, the four characters -Inf are appended
sl@0	1460	to this descriptor.
sl@0	1461
sl@0	1462	4.KErrGeneral - the conversion cannot be completed. There are a
sl@0	1463	number of possible reasons for this, but the most common is:
sl@0	1464	4.1 The character representation format (i.e. the format type), as
sl@0	1465	defined in the TRealFormat object is not recognised.
sl@0	1466
sl@0	1467	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1468	grown and there are insufficient resources to do so
sl@0	1469
sl@0	1470	@see TRealFormat::iType
sl@0	1471	*/
sl@0	1472	EXPORT_C TInt LString8::NumL(TReal aVal,const TRealFormat& aFormat)
sl@0	1473	{
sl@0	1474	Zero();
sl@0	1475	return AppendNumL(aVal, aFormat);
sl@0	1476	}
sl@0	1477
sl@0	1478	/**
sl@0	1479	Converts the 64-bit signed integer into a decimal character representation
sl@0	1480	and copies the conversion into this descriptor, replacing any existing data.
sl@0	1481
sl@0	1482	The length of this descriptor is set to reflect the new data.
sl@0	1483
sl@0	1484	If the integer is negative, the character representation is prefixed by a
sl@0	1485	minus sign.
sl@0	1486
sl@0	1487	This leaving variant of the standard, non-leaving descriptor method
sl@0	1488	differs in that this operation may cause the string descriptor's heap
sl@0	1489	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1490	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1491	and any existing raw pointers to into the descriptor data may be
sl@0	1492	invalidated.
sl@0	1493
sl@0	1494	@param aVal The 64-bit signed integer value.
sl@0	1495
sl@0	1496	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1497	grown and there are insufficient resources to do so
sl@0	1498	*/
sl@0	1499	EXPORT_C void LString8::NumL(TInt64 aVal)
sl@0	1500	{
sl@0	1501	Zero();
sl@0	1502	AppendNumL(aVal);
sl@0	1503	}
sl@0	1504
sl@0	1505	/**
sl@0	1506	Converts the specified 64 bit unsigned integer into a character representation
sl@0	1507	based on the specified number system and copies the conversion into this
sl@0	1508	descriptor, replacing any existing data.
sl@0	1509
sl@0	1510	The length of this descriptor is set to reflect the new data.
sl@0	1511
sl@0	1512	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1513	lower case.
sl@0	1514
sl@0	1515	This leaving variant of the standard, non-leaving descriptor method
sl@0	1516	differs in that this operation may cause the string descriptor's heap
sl@0	1517	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1518	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1519	and any existing raw pointers to into the descriptor data may be
sl@0	1520	invalidated.
sl@0	1521
sl@0	1522	@param aVal The 64 bit integer value. This is treated as an unsigned
sl@0	1523	value for all builds.
sl@0	1524	@param aRadix The number system representation for the 64 bit integer.
sl@0	1525
sl@0	1526	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1527	grown and there are insufficient resources to do so
sl@0	1528	*/
sl@0	1529	EXPORT_C void LString8::NumL(TUint64 aVal, TRadix aRadix)
sl@0	1530	{
sl@0	1531	Zero();
sl@0	1532	AppendNumL(aVal, aRadix);
sl@0	1533	}
sl@0	1534
sl@0	1535	/**
sl@0	1536	Formats and copies text into this descriptor, replacing any existing data.
sl@0	1537
sl@0	1538	The length of this descriptor is set to reflect the new data.
sl@0	1539
sl@0	1540	The function takes a format string and a variable number of arguments.
sl@0	1541	The format string contains literal text embedded with directives for converting
sl@0	1542	the trailing list of arguments into text.
sl@0	1543
sl@0	1544	The embedded directives are character sequences prefixed with the '%' character.
sl@0	1545	The literal text is simply copied into this descriptor unaltered while
sl@0	1546	the '%' directives are used to convert successive arguments from the
sl@0	1547	trailing list.
sl@0	1548
sl@0	1549	The resulting stream of literal text and converted arguments is copied into
sl@0	1550	this descriptor.
sl@0	1551
sl@0	1552	The syntax of the embedded directives follows one of four general patterns.
sl@0	1553
sl@0	1554	Note that formatting of single numerical values can be achieved more
sl@0	1555	conveniently using the Num() and NumUC() member functions of this class.
sl@0	1556
sl@0	1557	The full description of the syntax of a format string cannot be included here.
sl@0	1558	For full details, navigate to the Symbian OS guide, and follow the hierarchy of links:
sl@0	1559
sl@0	1560	@code
sl@0	1561	Symbian OS Guide
sl@0	1562	Base
sl@0	1563	Using User Library (E32)
sl@0	1564	Buffers and Strings
sl@0	1565	Using Descriptors
sl@0	1566	How to Use Descriptors
sl@0	1567	Format string syntax
sl@0	1568	@endcode
sl@0	1569
sl@0	1570	This leaving variant of the standard, non-leaving descriptor method
sl@0	1571	differs in that this operation may cause the string descriptor's heap
sl@0	1572	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1573	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1574	and any existing raw pointers to into the descriptor data may be
sl@0	1575	invalidated.
sl@0	1576
sl@0	1577	@param aFmt The descriptor containing the format string.
sl@0	1578	The TRefByValue class provides a constructor which takes a
sl@0	1579	TDesC8 type.
sl@0	1580
sl@0	1581	@param ... A variable number of arguments to be converted to text as
sl@0	1582	dictated by the format string.
sl@0	1583
sl@0	1584	@panic USER 12 if the format string has incorrect syntax.
sl@0	1585
sl@0	1586	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1587	grown and there are insufficient resources to do so
sl@0	1588
sl@0	1589	@see TDes8::Num()
sl@0	1590	@see TDes8::NumUC()
sl@0	1591	*/
sl@0	1592	EXPORT_C void LString8::FormatL(TRefByValue<const TDesC8> aFmt,...)
sl@0	1593	{
sl@0	1594	VA_LIST list;
sl@0	1595	VA_START(list,aFmt);
sl@0	1596	FormatListL(aFmt,list);
sl@0	1597	}
sl@0	1598
sl@0	1599	/**
sl@0	1600	Formats and copies text into this descriptor, replacing any existing data.
sl@0	1601
sl@0	1602	The length of this descriptor is set to reflect the new data.
sl@0	1603
sl@0	1604	The behaviour of this function is the same as FormatL(). In practice, it is
sl@0	1605	better and easier to use FormatL(), passing a variable number of arguments
sl@0	1606	as required by the format string.
sl@0	1607
sl@0	1608	This leaving variant of the standard, non-leaving descriptor method
sl@0	1609	differs in that this operation may cause the string descriptor's heap
sl@0	1610	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1611	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1612	and any existing raw pointers to into the descriptor data may be
sl@0	1613	invalidated.
sl@0	1614
sl@0	1615	@param aFmt The descriptor containing the format string.
sl@0	1616	@param aList A pointer to an argument list.
sl@0	1617
sl@0	1618	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1619	grown and there are insufficient resources to do so
sl@0	1620
sl@0	1621	@see TDes8::Format()
sl@0	1622	@see VA_LIST
sl@0	1623	*/
sl@0	1624	EXPORT_C void LString8::FormatListL(const TDesC8& aFmt,VA_LIST aList)
sl@0	1625	{
sl@0	1626	Zero();
sl@0	1627	AppendFormatListL(aFmt, aList);
sl@0	1628	}
sl@0	1629
sl@0	1630	/**
sl@0	1631	Appends data onto the end of this descriptor's data and justifies it.
sl@0	1632
sl@0	1633	The source of the appended data is an existing descriptor.
sl@0	1634
sl@0	1635	The target area is considered to be an area of specified width, immediately
sl@0	1636	following this descriptor's existing data. Source data is copied into, and
sl@0	1637	aligned within this target area according to the specified alignment instruction.
sl@0	1638
sl@0	1639	If the length of the target area is larger than the length of the source,
sl@0	1640	then spare space within the target area is padded with the fill character.
sl@0	1641
sl@0	1642	This leaving variant of the standard, non-leaving descriptor method
sl@0	1643	differs in that this operation may cause the string descriptor's heap
sl@0	1644	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1645	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1646	and any existing raw pointers to into the descriptor data may be
sl@0	1647	invalidated.
sl@0	1648
sl@0	1649	@param aDes A 8-bit non-modifiable descriptor containing the source
sl@0	1650	data. The length of the data to be copied is the smaller of:
sl@0	1651	the length of the source descriptor, and
sl@0	1652	the width of the target area (only if this is not the
sl@0	1653	explicit negative value KDefaultJustifyWidth).
sl@0	1654
sl@0	1655	@param aWidth The width of the target area. If this has the specific
sl@0	1656	negative value KDefaultJustifyWidth, then the width is
sl@0	1657	re-set to the length of the data source.
sl@0	1658
sl@0	1659	@param aAlignment The alignment of the data within the target area.
sl@0	1660
sl@0	1661	@param aFill The fill character used to pad the target area.
sl@0	1662
sl@0	1663	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1664	grown and there are insufficient resources to do so
sl@0	1665
sl@0	1666	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1667	*/
sl@0	1668	EXPORT_C void LString8::AppendJustifyL(const TDesC8& Des,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1669	{
sl@0	1670
sl@0	1671	TInt width = (aWidth == KDefaultJustifyWidth ? Des.Length() : aWidth);
sl@0	1672	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1673	RBuf8::AppendJustify(Des, aWidth, aAlignment, aFill);
sl@0	1674
sl@0	1675	}
sl@0	1676
sl@0	1677	/**
sl@0	1678	Appends data onto the end of this descriptor's data and justifies it.
sl@0	1679
sl@0	1680	The source of the appended data is an existing descriptor.
sl@0	1681
sl@0	1682	The target area is considered to be an area of specified width, immediately
sl@0	1683	following this descriptor's existing data. Source data is copied into, and
sl@0	1684	aligned within this target area according to the specified alignment instruction.
sl@0	1685
sl@0	1686	If the length of the target area is larger than the length of the source,
sl@0	1687	then spare space within the target area is padded with the fill character.
sl@0	1688
sl@0	1689	This leaving variant of the standard, non-leaving descriptor method
sl@0	1690	differs in that this operation may cause the string descriptor's heap
sl@0	1691	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1692	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1693	and any existing raw pointers to into the descriptor data may be
sl@0	1694	invalidated.
sl@0	1695
sl@0	1696	@param aDes An 8-bit non-modifiable descriptor containing the source data.
sl@0	1697
sl@0	1698	@param aLength The length of data to be copied from the source descriptor.
sl@0	1699	If this is greater than the width of the target area, then
sl@0	1700	the length of data copied is limited to the width.
sl@0	1701	The length of data to be copied must not be greater than
sl@0	1702	the length of the source descriptor. Note that this
sl@0	1703	condition is not automatically tested.
sl@0	1704
sl@0	1705	@param aWidth The width of the target area. If this has the specific negative
sl@0	1706	value KDefaultJustifyWidth, then the width is
sl@0	1707	re-set to the length of the data source.
sl@0	1708
sl@0	1709	@param aAlignment The alignment of the data within the target area.
sl@0	1710
sl@0	1711	@param aFill The fill character used to pad the target area.
sl@0	1712
sl@0	1713	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1714	grown and there are insufficient resources to do so
sl@0	1715
sl@0	1716	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1717	*/
sl@0	1718	EXPORT_C void LString8::AppendJustifyL(const TDesC8& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1719	{
sl@0	1720
sl@0	1721	TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
sl@0	1722	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1723
sl@0	1724	RBuf8::AppendJustify(Des, aLength, aWidth, aAlignment, aFill);
sl@0	1725	}
sl@0	1726
sl@0	1727	/**
sl@0	1728	Appends a zero terminated string onto the end of this descriptor's data and
sl@0	1729	justifies it.
sl@0	1730
sl@0	1731	The zero terminator is not copied.
sl@0	1732
sl@0	1733	The target area is considered to be an area of specified width, immediately
sl@0	1734	following this descriptor's existing data. Source data is copied into, and
sl@0	1735	aligned within, this target area according to the specified alignment instruction.
sl@0	1736
sl@0	1737	If the length of the target area is larger than the length of the source,
sl@0	1738	then spare space within the target area is padded with the fill character.
sl@0	1739
sl@0	1740	This leaving variant of the standard, non-leaving descriptor method
sl@0	1741	differs in that this operation may cause the string descriptor's heap
sl@0	1742	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1743	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1744	and any existing raw pointers to into the descriptor data may be
sl@0	1745	invalidated.
sl@0	1746
sl@0	1747	@param aZeroTerminatedString A pointer to a zero terminated string The length of the data
sl@0	1748	to be copied is the smaller of: the length of the string (excluding the zero
sl@0	1749	terminator), the width of the target area (only if this is not the explicit
sl@0	1750	negative value KDefaultJustifyWidth).
sl@0	1751
sl@0	1752	@param aWidth The width of the target area. If this has the specific negative
sl@0	1753	value KDefaultJustifyWidth, then the width is re-set to the length of the
sl@0	1754	zero terminated string (excluding the zero terminator).
sl@0	1755
sl@0	1756	@param aAlignment The alignment of the data within the target area.
sl@0	1757
sl@0	1758	@param aFill The fill character used to pad the target area.
sl@0	1759
sl@0	1760	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1761	grown and there are insufficient resources to do so
sl@0	1762
sl@0	1763	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1764	*/
sl@0	1765	EXPORT_C void LString8::AppendJustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1766	{
sl@0	1767
sl@0	1768	TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth);
sl@0	1769	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1770
sl@0	1771	RBuf8::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill);
sl@0	1772
sl@0	1773	}
sl@0	1774
sl@0	1775	/**
sl@0	1776	Appends data onto the end of this descriptor's data and justifies it.
sl@0	1777
sl@0	1778	The source of the appended data is a memory location.
sl@0	1779
sl@0	1780	The target area is considered to be an area of specified width, immediately
sl@0	1781	following this descriptor's existing data. Source data is copied into, and
sl@0	1782	aligned within, this target area according to the specified alignment instruction.
sl@0	1783
sl@0	1784	If the length of the target area is larger than the length of the source,
sl@0	1785	then spare space within the target area is padded with the fill character.
sl@0	1786
sl@0	1787	This leaving variant of the standard, non-leaving descriptor method
sl@0	1788	differs in that this operation may cause the string descriptor's heap
sl@0	1789	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1790	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1791	and any existing raw pointers to into the descriptor data may be
sl@0	1792	invalidated.
sl@0	1793
sl@0	1794	@param aString A pointer to a source memory location.
sl@0	1795
sl@0	1796	@param aLength The length of data to be copied. If this is greater than the
sl@0	1797	width of the target area, then the length of data copied is
sl@0	1798	limited to the width.
sl@0	1799
sl@0	1800	@param aWidth The width of the target area. If this has the specific negative
sl@0	1801	value KDefaultJustifyWidth, then the width is
sl@0	1802	re-set to the length of the data source.
sl@0	1803
sl@0	1804	@param aAlignment The alignment of the data within the target area.
sl@0	1805
sl@0	1806	@param aFill The fill character used to pad the target area.
sl@0	1807
sl@0	1808	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1809	grown and there are insufficient resources to do so
sl@0	1810
sl@0	1811	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1812
sl@0	1813	@panic USER 17 if aLength is negative.
sl@0	1814	*/
sl@0	1815	EXPORT_C void LString8::AppendJustifyL(const TUint8* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1816	{
sl@0	1817
sl@0	1818	TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
sl@0	1819	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1820
sl@0	1821	RBuf8::AppendJustify(aString, aLength, aWidth, aAlignment, aFill);
sl@0	1822	}
sl@0	1823
sl@0	1824	/**
sl@0	1825	Converts the specified unsigned integer into a fixed width character
sl@0	1826	representation based on the specified number system and appends the conversion
sl@0	1827	onto the end of this descriptor's data.
sl@0	1828
sl@0	1829	The length of this descriptor is incremented to reflect the new content.
sl@0	1830
sl@0	1831	The function generates the exact number of specified characters, either
sl@0	1832	padding to the left with character zeroes or discarding low order characters
sl@0	1833	as necessary.
sl@0	1834
sl@0	1835	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1836	upper case.
sl@0	1837
sl@0	1838	This leaving variant of the standard, non-leaving descriptor method
sl@0	1839	differs in that this operation may cause the string descriptor's heap
sl@0	1840	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1841	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1842	and any existing raw pointers to into the descriptor data may be
sl@0	1843	invalidated.
sl@0	1844
sl@0	1845	@param aVal The unsigned integer value.
sl@0	1846	@param aRadix The number system representation for the unsigned integer.
sl@0	1847	@param aWidth The number of characters: to be used to contain the conversion,
sl@0	1848	to be appended to this descriptor.
sl@0	1849
sl@0	1850	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1851	grown and there are insufficient resources to do so
sl@0	1852
sl@0	1853	*/
sl@0	1854	EXPORT_C void LString8::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	1855	{
sl@0	1856	ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0	1857	RBuf8::AppendNumFixedWidthUC(aVal, aRadix, aWidth);
sl@0	1858	}
sl@0	1859
sl@0	1860	/**
sl@0	1861	Converts the specified 64 bit integer into a character representation
sl@0	1862	based on the specified number system and appends the conversion onto the end
sl@0	1863	of this descriptor's data.
sl@0	1864
sl@0	1865	The length of this descriptor is incremented to reflect the new content.
sl@0	1866
sl@0	1867	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1868	upper case.
sl@0	1869
sl@0	1870	This leaving variant of the standard, non-leaving descriptor method
sl@0	1871	differs in that this operation may cause the string descriptor's heap
sl@0	1872	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1873	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1874	and any existing raw pointers to into the descriptor data may be
sl@0	1875	invalidated.
sl@0	1876
sl@0	1877	@param aVal The 64 bit integer value. This is always treated as an unsigned
sl@0	1878	value.
sl@0	1879	@param aRadix The number system representation for the 64 bit integer. If no
sl@0	1880	explicit value is specified, then EDecimal is the default.
sl@0	1881
sl@0	1882	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1883	grown and there are insufficient resources to do so
sl@0	1884	*/
sl@0	1885	EXPORT_C void LString8::AppendNumUCL(TUint64 aVal, TRadix aRadix)
sl@0	1886	{
sl@0	1887	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1888	RBuf8::AppendNumUC(aVal, aRadix);
sl@0	1889	}
sl@0	1890
sl@0	1891	/**
sl@0	1892	Converts the specified floating point number into a character representation
sl@0	1893	and appends the conversion onto the end of this descriptor's data.
sl@0	1894
sl@0	1895	The length of this descriptor is incremented to reflect the new content.
sl@0	1896
sl@0	1897	The character representation of the real number is dictated by the specified
sl@0	1898	format.
sl@0	1899
sl@0	1900	This leaving variant of the standard, non-leaving descriptor method
sl@0	1901	differs in that this operation may cause the string descriptor's heap
sl@0	1902	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1903	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1904	and any existing raw pointers to into the descriptor data may be
sl@0	1905	invalidated.
sl@0	1906
sl@0	1907	@param aVal The floating point number to be converted.
sl@0	1908	@param aFormat The format of the conversion.
sl@0	1909
sl@0	1910	@return If the conversion is successful, the length of this descriptor. If
sl@0	1911	the conversion fails, a negative value indicating the cause of failure.
sl@0	1912	In addition, extra information on the cause of the failure may be
sl@0	1913	appended onto this descriptor. The possible values and their meaning
sl@0	1914	are:
sl@0	1915
sl@0	1916	1.KErrArgument - the supplied floating point number is not a valid
sl@0	1917	number. The three characters NaN are appended to this descriptor.
sl@0	1918
sl@0	1919	2.KErrOverflow - the number is too large to represent.
sl@0	1920	2.1 For positive overflow, the three characters Inf are appended
sl@0	1921	to this descriptor.
sl@0	1922	2.2 For negative overflow, the four characters -Inf are appended
sl@0	1923	to this descriptor.
sl@0	1924
sl@0	1925	3.KErrUnderflow - the number is too small to represent.
sl@0	1926	3.1 For positive underflow, the three characters Inf are appended
sl@0	1927	to this descriptor.
sl@0	1928	3.2 For negative underflow, the four characters -Inf are appended
sl@0	1929	to this descriptor.
sl@0	1930
sl@0	1931	4.KErrGeneral - the conversion cannot be completed. There are a
sl@0	1932	number of possible reasons for this, but the most common is:
sl@0	1933	4.1 The character representation format (i.e. the format type), as
sl@0	1934	defined in the TRealFormat object is not recognised.
sl@0	1935
sl@0	1936	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1937	grown and there are insufficient resources to do so
sl@0	1938	*/
sl@0	1939	EXPORT_C TInt LString8::AppendNumL(TReal aVal,const TRealFormat& aFormat)
sl@0	1940	{
sl@0	1941	ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize);
sl@0	1942	return RBuf8::AppendNum(aVal, aFormat);
sl@0	1943	}
sl@0	1944
sl@0	1945	/**
sl@0	1946	Converts the 64-bit signed integer into a decimal character representation
sl@0	1947	and appends the conversion onto the end of this descriptor's data.
sl@0	1948
sl@0	1949	The length of this descriptor is incremented to reflect the new content.
sl@0	1950
sl@0	1951	If the integer is negative, the character representation is prefixed by a
sl@0	1952	minus sign.
sl@0	1953
sl@0	1954	This leaving variant of the standard, non-leaving descriptor method
sl@0	1955	differs in that this operation may cause the string descriptor's heap
sl@0	1956	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1957	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1958	and any existing raw pointers to into the descriptor data may be
sl@0	1959	invalidated.
sl@0	1960
sl@0	1961	@param aVal The 64-bit signed integer value.
sl@0	1962
sl@0	1963	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1964	grown and there are insufficient resources to do so
sl@0	1965	*/
sl@0	1966	EXPORT_C void LString8::AppendNumL(TInt64 aVal)
sl@0	1967	{
sl@0	1968	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1969	RBuf8::AppendNum(aVal);
sl@0	1970	}
sl@0	1971
sl@0	1972	/**
sl@0	1973	Converts the specified 64 bit integer into a character representation
sl@0	1974	based on the specified number system and appends the conversion onto the end
sl@0	1975	of this descriptor's data.
sl@0	1976
sl@0	1977	The length of this descriptor is incremented to reflect the new content.
sl@0	1978
sl@0	1979	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1980	lower case.
sl@0	1981
sl@0	1982	This leaving variant of the standard, non-leaving descriptor method
sl@0	1983	differs in that this operation may cause the string descriptor's heap
sl@0	1984	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1985	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1986	and any existing raw pointers to into the descriptor data may be
sl@0	1987	invalidated.
sl@0	1988
sl@0	1989	@param aVal The 64 bit integer value. This is always treated as an unsigned
sl@0	1990	value.
sl@0	1991	@param aRadix The number system representation for the 64 bit integer.
sl@0	1992
sl@0	1993	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1994	grown and there are insufficient resources to do so
sl@0	1995	*/
sl@0	1996	EXPORT_C void LString8::AppendNumL(TUint64 aVal, TRadix aRadix)
sl@0	1997	{
sl@0	1998	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1999	RBuf8::AppendNum(aVal, aRadix);
sl@0	2000	}
sl@0	2001
sl@0	2002	/**
sl@0	2003	Formats and appends text onto the end of this descriptor's data.
sl@0	2004
sl@0	2005	The length of this descriptor is incremented to reflect the new content.
sl@0	2006
sl@0	2007	The function takes a format string and a variable number of arguments.
sl@0	2008	The format string contains literal text, embedded with directives,
sl@0	2009	for converting the trailing list of arguments into text.
sl@0	2010
sl@0	2011	The embedded directives are character sequences prefixed with the '%' character.
sl@0	2012	The literal text is simply copied into this descriptor unaltered while
sl@0	2013	the '%' directives are used to convert successive arguments from the
sl@0	2014	trailing list. See the description of the Format() function.
sl@0	2015
sl@0	2016	Literal text is appended on a character by character basis, and the
sl@0	2017	underlying buffer is grown as necessary to accommodate it.
sl@0	2018
sl@0	2019	Text converted from a trailing argument is appended as a complete
sl@0	2020	string, and the underlying buffer is grown as necessary to accommodate
sl@0	2021	it.
sl@0	2022
sl@0	2023	This leaving variant of the standard, non-leaving descriptor method
sl@0	2024	differs in that this operation may cause the string descriptor's heap
sl@0	2025	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2026	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2027	and any existing raw pointers to into the descriptor data may be
sl@0	2028	invalidated.
sl@0	2029
sl@0	2030	@param aFmt The 8-bit non-modifiable descriptor containing the
sl@0	2031	format string. The TRefByValue class provides a
sl@0	2032	constructor which takes a TDesC8 type.
sl@0	2033
sl@0	2034	@param ... A variable number of arguments to be converted to text
sl@0	2035	as dictated by the format string.
sl@0	2036
sl@0	2037	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2038	grown and there are insufficient resources to do so
sl@0	2039
sl@0	2040	@panic USER 12 if the format string has incorrect syntax.
sl@0	2041
sl@0	2042	@see TDes8::Format()
sl@0	2043	@see TDes8Overflow::Overflow()
sl@0	2044	*/
sl@0	2045	EXPORT_C void LString8::AppendFormatL(TRefByValue<const TDesC8> aFmt,...)
sl@0	2046	{
sl@0	2047	VA_LIST list;
sl@0	2048	VA_START(list,aFmt);
sl@0	2049	AppendFormatListL(aFmt,list);
sl@0	2050	}
sl@0	2051
sl@0	2052	class TRetryOverflow8 : public TDes8Overflow
sl@0	2053	{
sl@0	2054	public:
sl@0	2055	TRetryOverflow8() : iOverflow(EFalse)
sl@0	2056	{
sl@0	2057	}
sl@0	2058
sl@0	2059	virtual void Overflow(TDes8& /aDes/)
sl@0	2060	{
sl@0	2061	iOverflow = ETrue;
sl@0	2062	}
sl@0	2063
sl@0	2064	TBool iOverflow;
sl@0	2065	};
sl@0	2066
sl@0	2067	/**
sl@0	2068	Formats and appends text onto the end of this descriptor's data.
sl@0	2069
sl@0	2070	The length of this descriptor is incremented to reflect the new content.
sl@0	2071
sl@0	2072	The behaviour of this function is the same as
sl@0	2073	AppendFormatL(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...).
sl@0	2074	In practice, it is better and easier to use AppendFormat(), passing a variable number of
sl@0	2075	arguments as required by the format string.
sl@0	2076
sl@0	2077	This leaving variant of the standard, non-leaving descriptor method
sl@0	2078	differs in that this operation may cause the string descriptor's heap
sl@0	2079	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2080	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2081	and any existing raw pointers to into the descriptor data may be
sl@0	2082	invalidated.
sl@0	2083
sl@0	2084	@param aFmt The descriptor containing the format string.
sl@0	2085	@param aList A pointer to an argument list.
sl@0	2086
sl@0	2087	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2088	grown and there are insufficient resources to do so
sl@0	2089
sl@0	2090	@see TDes8::AppendFormat
sl@0	2091	@see VA_LIST
sl@0	2092	*/
sl@0	2093	EXPORT_C void LString8::AppendFormatListL(const TDesC8& aFmt,VA_LIST aList)
sl@0	2094	{
sl@0	2095	ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint
sl@0	2096	for (;;)
sl@0	2097	{
sl@0	2098	TInt before = Length();
sl@0	2099	TRetryOverflow8 overflow;
sl@0	2100	RBuf8::AppendFormatList(aFmt, aList, &overflow);
sl@0	2101	if (overflow.iOverflow)
sl@0	2102	{
sl@0	2103	SetLengthL(before); // Can't leave
sl@0	2104	ReserveCapacityGrowExponentialL();
sl@0	2105	}
sl@0	2106	else
sl@0	2107	{
sl@0	2108	break;
sl@0	2109	}
sl@0	2110	}
sl@0	2111	}
sl@0	2112
sl@0	2113
sl@0	2114	/**
sl@0	2115	Unlinks and transfers ownership of the specified 8-bit resizable descriptor's
sl@0	2116	buffer to this object. The source descriptor is detached from the buffer.
sl@0	2117
sl@0	2118	@param aString The source 8-bit resizable buffer. The ownership of this
sl@0	2119	object's buffer is to be transferred.
sl@0	2120
sl@0	2121	*/
sl@0	2122	EXPORT_C void LString8::Assign(const LString8& aString)
sl@0	2123	{
sl@0	2124	// free any previously owned resource
sl@0	2125	Reset();
sl@0	2126
sl@0	2127	RBuf8::Assign(aString);
sl@0	2128	// unlink buffer from original descriptor
sl@0	2129	new (const_cast<LString8*>(&aString)) LString8();
sl@0	2130	}
sl@0	2131
sl@0	2132
sl@0	2133	/**
sl@0	2134	Transfers ownership of the specified 8-bit resizable descriptor's
sl@0	2135	buffer to this object. The source descriptor is detached from the buffer.
sl@0	2136
sl@0	2137	@param aRBuf The source 8-bit resizable buffer. The ownership of this
sl@0	2138	object's buffer is to be transferred.
sl@0	2139
sl@0	2140	@see RBuf8::Assign()
sl@0	2141	*/
sl@0	2142
sl@0	2143	EXPORT_C void LString8::Assign(const RBuf8& aRBuf)
sl@0	2144	{
sl@0	2145	// free any previously owned resource
sl@0	2146	Reset();
sl@0	2147
sl@0	2148	RBuf8::Assign(aRBuf);
sl@0	2149
sl@0	2150	// reset the RBuf;
sl@0	2151	new (const_cast<RBuf8*>(&aRBuf)) RBuf8();
sl@0	2152	}
sl@0	2153
sl@0	2154
sl@0	2155	/**
sl@0	2156	Transfers ownership of the specified 8-bit resizable descriptor's this object.
sl@0	2157
sl@0	2158	@param aHBuf The heap descriptor to be transferred to this object.
sl@0	2159	The ownership of this object's buffer is to be transferred.
sl@0	2160
sl@0	2161	@see RBuf8::Assign()
sl@0	2162	*/
sl@0	2163	EXPORT_C void LString8::Assign(HBufC8* aHBuf)
sl@0	2164	{
sl@0	2165	// free any previously owned resource
sl@0	2166	Reset();
sl@0	2167
sl@0	2168	RBuf8::Assign(aHBuf);
sl@0	2169	}
sl@0	2170
sl@0	2171
sl@0	2172	/**
sl@0	2173	Assigns ownership of the specified allocated memory to this object.
sl@0	2174
sl@0	2175	@param aHeapCell The allocated memory to be assigned to this object.
sl@0	2176	This pointer can be NULL, which means that a zero length
sl@0	2177	8-bit resizable buffer descriptor is created.
sl@0	2178
sl@0	2179	@param aMaxLength The maximum length of the descriptor.
sl@0	2180
sl@0	2181	@panic USER 8 If the specified maximum length is greater then the size of the
sl@0	2182	allocated heap cell, or the specified maximum length is NOT
sl@0	2183	zero when the pointer to the heap cell is NULL.
sl@0	2184
sl@0	2185	@see RBuf8::Assign()
sl@0	2186	*/
sl@0	2187	EXPORT_C void LString8::Assign(TUint8 *aHeapCell, TInt aMaxLength)
sl@0	2188	{
sl@0	2189	// free any previously owned resource
sl@0	2190	Reset();
sl@0	2191
sl@0	2192	RBuf8::Assign(aHeapCell, aMaxLength);
sl@0	2193	}
sl@0	2194
sl@0	2195
sl@0	2196	/**
sl@0	2197	Transfers ownership of the specified 16-bit resizable descriptor's this object.
sl@0	2198
sl@0	2199	@param aHeapCell The allocated memory to be assigned to this object.
sl@0	2200
sl@0	2201	@param aLength The length of the descriptor.
sl@0	2202
sl@0	2203	@param aMaxLength The maximum length of the descriptor.
sl@0	2204
sl@0	2205	@panic USER 8 If the specified maximum length is greater then the size of the
sl@0	2206	allocated heap cell, or the specified length is greater then
sl@0	2207	the specified maximum length, or the specified maximum length
sl@0	2208	is NOT zero when the pointer to the heap cell is NULL.
sl@0	2209
sl@0	2210	@see RBuf8::Assign()
sl@0	2211	*/
sl@0	2212	EXPORT_C void LString8::Assign(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0	2213	{
sl@0	2214	// free any previously owned resource
sl@0	2215	Reset();
sl@0	2216
sl@0	2217	RBuf8::Assign(aHeapCell, aLength, aMaxLength);
sl@0	2218	}
sl@0	2219
sl@0	2220	/**
sl@0	2221	Creates an 8-bit resizable buffer descriptor that has been initialised with
sl@0	2222	data from the specified read stream; leaves on failure.
sl@0	2223
sl@0	2224	Data is assigned to the new descriptor from the specified stream.
sl@0	2225	This variant assumes that the stream contains the length of the data followed
sl@0	2226	by the data itself.
sl@0	2227
sl@0	2228	The function is implemented by calling the HBufC8::NewL(RReadStream&,TInt)
sl@0	2229	variant and then assigning the resulting heap descriptor using
sl@0	2230	the RBuf8::Assign(HBufC8*) variant. The comments that describe
sl@0	2231	the HBufC8::NewL() variant also apply to this RBuf8::CreateL() function.
sl@0	2232
sl@0	2233	The function may leave with one of the system-wide error codes, specifically
sl@0	2234	KErrOverflow, if the length of the data as read from the stream is greater than
sl@0	2235	the upper limit as specified by the aMaxLength parameter.
sl@0	2236
sl@0	2237	@param aStream The stream from which the data length and the data to be
sl@0	2238	assigned to the new descriptor, are taken.
sl@0	2239	@param aMaxLength The upper limit on the length of data that the descriptor is
sl@0	2240	to represent. The value of this parameter must be non-negative
sl@0	2241	otherwise the underlying function will panic.
sl@0	2242	*/
sl@0	2243	EXPORT_C void LString8::CreateL(RReadStream &aStream,TInt aMaxLength)
sl@0	2244	{
sl@0	2245	Reset();
sl@0	2246	Assign(HBufC8::NewL(aStream,aMaxLength));
sl@0	2247	}
sl@0	2248
sl@0	2249	/**
sl@0	2250	Appends data onto the end of this descriptor's data.
sl@0	2251
sl@0	2252	The length of this descriptor is incremented to reflect the new content.
sl@0	2253
sl@0	2254	This leaving variant of the standard, non-leaving descriptor method
sl@0	2255	differs in that this operation may cause the string descriptor's heap
sl@0	2256	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2257	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2258	and any existing raw pointers to into the descriptor data may be
sl@0	2259	invalidated.
sl@0	2260
sl@0	2261	@param aZeroTerminatedString A pointer to a zero terminated string .
sl@0	2262	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2263	grown and there are insufficient resources to do so
sl@0	2264
sl@0	2265	@see LString8::AppendL
sl@0	2266	*/
sl@0	2267	EXPORT_C LString8& LString8::operator+=(const TUint8* aZeroTerminatedString)
sl@0	2268	{
sl@0	2269	AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
sl@0	2270	return *this;
sl@0	2271	}
sl@0	2272	/**
sl@0	2273	Appends data onto the end of this descriptor's data.
sl@0	2274
sl@0	2275	The length of this descriptor is incremented to reflect the new content.
sl@0	2276
sl@0	2277	This leaving variant of the standard, non-leaving descriptor method
sl@0	2278	differs in that this operation may cause the string descriptor's heap
sl@0	2279	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2280	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2281	and any existing raw pointers to into the descriptor data may be
sl@0	2282	invalidated.
sl@0	2283
sl@0	2284	@param aZeroTerminatedString A pointer to the data to be copied.
sl@0	2285
sl@0	2286	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2287	grown and there are insufficient resources to do so
sl@0	2288
sl@0	2289	@panic USER 17 if aLength is negative.
sl@0	2290	*/
sl@0	2291	EXPORT_C void LString8::AppendL(const TUint8* aZeroTerminatedString)
sl@0	2292	{
sl@0	2293	AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
sl@0	2294	}
sl@0	2295	/**
sl@0	2296	Constructor to create a 8-bit resizable string descriptor containing
sl@0	2297	a copy of the specified (source) zero-terminated character string data, or leave
sl@0	2298	on failure.
sl@0	2299
sl@0	2300	The constructor allocates sufficient memory so that this string
sl@0	2301	descriptor's maximum length is the same as the length of the source
sl@0	2302	string. Both the current length and the maximum length of this string
sl@0	2303	descriptor are set to the length of the source string.
sl@0	2304
sl@0	2305	The data contained in the source string is copied into this string
sl@0	2306	descriptor. The zero terminator is not copied.
sl@0	2307
sl@0	2308	@param aCharStr A pointer to a zero-terminated wide character string
sl@0	2309
sl@0	2310	@leave KErrNoMemory If there is insufficient memory.
sl@0	2311
sl@0	2312	@see LString8::CopyL
sl@0	2313	*/
sl@0	2314	EXPORT_C LString8::LString8(const char* aCharStr)
sl@0	2315	: iReserved(0)
sl@0	2316	{
sl@0	2317	CopyL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2318	}
sl@0	2319
sl@0	2320	/**
sl@0	2321	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	2322	data, and expanding its heap buffer to accommodate if necessary.
sl@0	2323
sl@0	2324	The length of this descriptor is set to reflect the new data.
sl@0	2325
sl@0	2326	This operation may cause the target string descriptor's heap buffer to
sl@0	2327	be reallocated in order to accommodate the new data. As a result,
sl@0	2328	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	2329	existing raw pointers to into the descriptor data may be invalidated.
sl@0	2330
sl@0	2331	Note that the automatic resizing performed is a change to the
sl@0	2332	functionality of this operation compared to other descriptor
sl@0	2333	classes. This change is only active on objects directly declared
sl@0	2334	LString8; when LString8 instances are instead manipulated via
sl@0	2335	references to TDes8 or TDesC8, the standard (non-resizing, panicing)
sl@0	2336	variant is invoked.
sl@0	2337
sl@0	2338	@param aCharStr A pointer to a character zero-terminated string
sl@0	2339
sl@0	2340	@return A reference to this 8-bit string descriptor.
sl@0	2341
sl@0	2342	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	2343	assigned to needs to be expanded, but there is
sl@0	2344	insufficient memory to do so
sl@0	2345
sl@0	2346	@see LString8::CopyL
sl@0	2347	*/
sl@0	2348	EXPORT_C LString8& LString8::operator=(const char* aCharStr)
sl@0	2349	{
sl@0	2350	CopyL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2351	return *this;
sl@0	2352	}
sl@0	2353
sl@0	2354	/**
sl@0	2355	Appends data onto the end of this descriptor's data.
sl@0	2356
sl@0	2357	The length of this descriptor is incremented to reflect the new content.
sl@0	2358
sl@0	2359	This leaving variant of the standard, non-leaving descriptor method
sl@0	2360	differs in that this operation may cause the string descriptor's heap
sl@0	2361	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2362	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2363	and any existing raw pointers to into the descriptor data may be
sl@0	2364	invalidated.
sl@0	2365
sl@0	2366	@param aCharStr A pointer to a character zero terminated string .
sl@0	2367	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2368	grown and there are insufficient resources to do so
sl@0	2369
sl@0	2370	@see LString8::AppendL
sl@0	2371	*/
sl@0	2372	EXPORT_C LString8& LString8::operator+=(const char* aCharStr)
sl@0	2373	{
sl@0	2374	AppendL(reinterpret_cast<const TUint8>(aCharStr),User::StringLength(reinterpret_cast<const TUint8>(aCharStr)));
sl@0	2375	return *this;
sl@0	2376	}
sl@0	2377
sl@0	2378	/**
sl@0	2379	Copies data into this 8-bit string descriptor, replacing any existing
sl@0	2380	data, and expanding its heap buffer to accommodate if necessary.
sl@0	2381
sl@0	2382	The length of this descriptor is set according to the new
sl@0	2383	parameter.
sl@0	2384
sl@0	2385	This leaving variant of the standard, non-leaving descriptor method
sl@0	2386	differs in that this operation may cause the string descriptor's heap
sl@0	2387	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2388	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2389	and any existing raw pointers to into the descriptor data may be
sl@0	2390	invalidated.
sl@0	2391
sl@0	2392	@param aCharStr A pointer to a character zero terminated string to be copied.
sl@0	2393
sl@0	2394
sl@0	2395	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	2396	assigned to needs to be expanded, but there is
sl@0	2397	insufficient memory to do so
sl@0	2398
sl@0	2399	@panic USER 11 if aLength is negative.
sl@0	2400
sl@0	2401	@see TDes8::Copy
sl@0	2402	*/
sl@0	2403	EXPORT_C void LString8::CopyL(const char* aCharStr)
sl@0	2404	{
sl@0	2405	CopyL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2406	}
sl@0	2407
sl@0	2408	/**
sl@0	2409	Appends data onto the end of this descriptor's data and justifies it.
sl@0	2410
sl@0	2411	The source of the appended data is a memory location.
sl@0	2412
sl@0	2413	The target area is considered to be an area of specified width, immediately
sl@0	2414	following this descriptor's existing data. Source data is copied into, and
sl@0	2415	aligned within, this target area according to the specified alignment instruction.
sl@0	2416
sl@0	2417	If the length of the target area is larger than the length of the source,
sl@0	2418	then spare space within the target area is padded with the fill character.
sl@0	2419
sl@0	2420	This leaving variant of the standard, non-leaving descriptor method
sl@0	2421	differs in that this operation may cause the string descriptor's heap
sl@0	2422	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2423	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2424	and any existing raw pointers to into the descriptor data may be
sl@0	2425	invalidated.
sl@0	2426
sl@0	2427	@param aCharStr A pointer to a source memory location.
sl@0	2428
sl@0	2429	@param aLength The length of data to be copied. If this is greater than the
sl@0	2430	width of the target area, then the length of data copied is
sl@0	2431	limited to the width.
sl@0	2432
sl@0	2433	@param aWidth The width of the target area. If this has the specific negative
sl@0	2434	value KDefaultJustifyWidth, then the width is
sl@0	2435	re-set to the length of the data source.
sl@0	2436
sl@0	2437	@param aAlignment The alignment of the data within the target area.
sl@0	2438
sl@0	2439	@param aFill The fill character used to pad the target area.
sl@0	2440
sl@0	2441	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2442	grown and there are insufficient resources to do so
sl@0	2443
sl@0	2444	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	2445
sl@0	2446	@panic USER 17 if aLength is negative.
sl@0	2447	*/
sl@0	2448	EXPORT_C void LString8::AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	2449	{
sl@0	2450	AppendJustifyL(reinterpret_cast<const TUint8*>( aCharStr),aWidth,anAlignment,aFill);
sl@0	2451	}
sl@0	2452
sl@0	2453	/**
sl@0	2454	Appends data onto the end of this descriptor's data.
sl@0	2455
sl@0	2456	The length of this descriptor is incremented to reflect the new content.
sl@0	2457
sl@0	2458	This leaving variant of the standard, non-leaving descriptor method
sl@0	2459	differs in that this operation may cause the string descriptor's heap
sl@0	2460	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2461	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2462	and any existing raw pointers to into the descriptor data may be
sl@0	2463	invalidated.
sl@0	2464
sl@0	2465	@param aCharStr A pointer to the data to be copied.
sl@0	2466	@param aLength The length of data to be copied.
sl@0	2467
sl@0	2468	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2469	grown and there are insufficient resources to do so
sl@0	2470
sl@0	2471	@panic USER 17 if aLength is negative.
sl@0	2472	*/
sl@0	2473	EXPORT_C void LString8::AppendL(const char* aCharStr,TInt aLength)
sl@0	2474	{
sl@0	2475	AppendL(reinterpret_cast<const TUint8*>(aCharStr),aLength);
sl@0	2476	}
sl@0	2477
sl@0	2478	/**
sl@0	2479	Appends data onto the end of this descriptor's data.
sl@0	2480
sl@0	2481	The length of this descriptor is incremented to reflect the new content.
sl@0	2482
sl@0	2483	This leaving variant of the standard, non-leaving descriptor method
sl@0	2484	differs in that this operation may cause the string descriptor's heap
sl@0	2485	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2486	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2487	and any existing raw pointers to into the descriptor data may be
sl@0	2488	invalidated.
sl@0	2489
sl@0	2490	@param aCharStr A pointer to the data to be copied.
sl@0	2491
sl@0	2492	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2493	grown and there are insufficient resources to do so
sl@0	2494
sl@0	2495	@panic USER 17 if aLength is negative.
sl@0	2496	*/
sl@0	2497	EXPORT_C void LString8::AppendL(const char* aCharStr)
sl@0	2498	{
sl@0	2499	AppendL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2500	}
sl@0	2501
sl@0	2502	/**
sl@0	2503	Determines whether this Descriptor's data is equal to the specified
sl@0	2504	string's data.
sl@0	2505
sl@0	2506	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2507
sl@0	2508	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2509	with this Descriptor's data.
sl@0	2510
sl@0	2511	@return True if equal, false otherwise.
sl@0	2512
sl@0	2513	@see TDesC8::Compare
sl@0	2514	*/
sl@0	2515	EXPORT_C TBool LString8::operator==( const char* aCharStr) const
sl@0	2516	{
sl@0	2517	return LString8::operator==(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2518	}
sl@0	2519
sl@0	2520	/**
sl@0	2521	Determines whether this Descriptor's data is equal to the specified
sl@0	2522	string's data.
sl@0	2523
sl@0	2524	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2525
sl@0	2526	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2527	is to be compared with this Descriptor's data.
sl@0	2528
sl@0	2529	@return True if equal, false otherwise.
sl@0	2530
sl@0	2531	@see TDesC8::Compare
sl@0	2532	*/
sl@0	2533	EXPORT_C TBool LString8::operator==( const TUint8* aZeroTerminatedString) const
sl@0	2534	{
sl@0	2535	return RBuf8::operator==(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2536	}
sl@0	2537
sl@0	2538	/**
sl@0	2539	Determines whether this descriptor's data is less than the specified
sl@0	2540	strings's data.
sl@0	2541
sl@0	2542	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2543
sl@0	2544	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2545	with this Descriptor's data.
sl@0	2546
sl@0	2547	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2548
sl@0	2549	@see TDesC8::Compare
sl@0	2550	*/
sl@0	2551	EXPORT_C TBool LString8::operator<( const char* aCharStr) const
sl@0	2552	{
sl@0	2553	return LString8::operator<(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2554	}
sl@0	2555
sl@0	2556	/**
sl@0	2557	Determines whether this descriptor's data is less than the specified
sl@0	2558	strings's data.
sl@0	2559
sl@0	2560	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2561
sl@0	2562	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2563	is to be compared with this Descriptor's data.
sl@0	2564
sl@0	2565	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2566
sl@0	2567	@see TDesC8::Compare
sl@0	2568	*/
sl@0	2569	EXPORT_C TBool LString8::operator<(const TUint8* aZeroTerminatedString) const
sl@0	2570	{
sl@0	2571	return RBuf8::operator<(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2572	}
sl@0	2573
sl@0	2574	/**
sl@0	2575	Determines whether this descriptor's data is less than the specified
sl@0	2576	strings's data.
sl@0	2577
sl@0	2578	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2579
sl@0	2580	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2581	with this Descriptor's data.
sl@0	2582
sl@0	2583	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2584
sl@0	2585	@see TDesC8::Compare
sl@0	2586	*/
sl@0	2587	EXPORT_C TBool LString8::operator<=( const char* aCharStr) const
sl@0	2588	{
sl@0	2589	return LString8::operator<=(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2590	}
sl@0	2591
sl@0	2592	/**
sl@0	2593	Determines whether this descriptor's data is less than/equal to the specified
sl@0	2594	strings's data.
sl@0	2595
sl@0	2596	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2597
sl@0	2598	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2599	is to be compared with this Descriptor's data.
sl@0	2600
sl@0	2601	@return True if this descriptor's data is less than/equal to that of the specified string's data
sl@0	2602
sl@0	2603	@see TDesC8::Compare
sl@0	2604	*/
sl@0	2605	EXPORT_C TBool LString8::operator<=(const TUint8* aZeroTerminatedString) const
sl@0	2606	{
sl@0	2607	return RBuf8::operator<=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2608	}
sl@0	2609
sl@0	2610	/**
sl@0	2611	Determines whether this descriptor's data is greater than the specified
sl@0	2612	strings's data.
sl@0	2613
sl@0	2614	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2615
sl@0	2616	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2617	with this Descriptor's data.
sl@0	2618
sl@0	2619	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2620
sl@0	2621	@see TDesC8::Compare
sl@0	2622	*/
sl@0	2623	EXPORT_C TBool LString8::operator>( const char* aCharStr) const
sl@0	2624	{
sl@0	2625	return LString8::operator>(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2626	}
sl@0	2627
sl@0	2628	/**
sl@0	2629	Determines whether this descriptor's data is greater than the specified
sl@0	2630	strings's data.
sl@0	2631
sl@0	2632	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2633
sl@0	2634	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2635	is to be compared with this Descriptor's data.
sl@0	2636
sl@0	2637	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2638
sl@0	2639	@see TDesC8::Compare
sl@0	2640	*/
sl@0	2641	EXPORT_C TBool LString8::operator>(const TUint8* aZeroTerminatedString) const
sl@0	2642	{
sl@0	2643	return RBuf8::operator>(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2644	}
sl@0	2645
sl@0	2646	/**
sl@0	2647	Determines whether this descriptor's data is greater than/equal to the specified
sl@0	2648	strings's data.
sl@0	2649
sl@0	2650	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2651
sl@0	2652	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2653	with this Descriptor's data.
sl@0	2654
sl@0	2655	@return True if this descriptor's data is greater than/equal to that of the specified string's data
sl@0	2656
sl@0	2657	@see TDesC8::Compare
sl@0	2658	*/
sl@0	2659	EXPORT_C TBool LString8::operator>=( const char* aCharStr) const
sl@0	2660	{
sl@0	2661	return LString8::operator>=(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2662	}
sl@0	2663
sl@0	2664	/**
sl@0	2665	Determines whether this descriptor's data is greater than the specified
sl@0	2666	strings's data.
sl@0	2667
sl@0	2668	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2669
sl@0	2670	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2671	is to be compared with this Descriptor's data.
sl@0	2672
sl@0	2673	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2674
sl@0	2675	@see TDesC8::Compare
sl@0	2676	*/
sl@0	2677	EXPORT_C TBool LString8::operator>=(const TUint8* aZeroTerminatedString) const
sl@0	2678	{
sl@0	2679	return RBuf8::operator>=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2680	}
sl@0	2681
sl@0	2682	/**
sl@0	2683	Determines whether this descriptor's data is not equal to the specified
sl@0	2684	strings's data.
sl@0	2685
sl@0	2686	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2687
sl@0	2688	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2689	with this Descriptor's data.
sl@0	2690
sl@0	2691	@return True if this descriptor's data is not equal to the specified string's data
sl@0	2692
sl@0	2693	@see TDesC8::Compare
sl@0	2694	*/
sl@0	2695	EXPORT_C TBool LString8::operator!=( const char* aCharStr) const
sl@0	2696	{
sl@0	2697	return LString8::operator!=(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2698	}
sl@0	2699
sl@0	2700	/**
sl@0	2701	Determines whether this descriptor's data is not equal to the specified
sl@0	2702	strings's data.
sl@0	2703
sl@0	2704	The comparison is implemented internally using the TDesC8::Compare() function.
sl@0	2705
sl@0	2706	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2707	is to be compared with this Descriptor's data.
sl@0	2708
sl@0	2709	@return True if this descriptor's data is not equal to the specified string's data
sl@0	2710
sl@0	2711	@see TDesC8::Compare
sl@0	2712	*/
sl@0	2713	EXPORT_C TBool LString8::operator!=(const TUint8* aZeroTerminatedString) const
sl@0	2714	{
sl@0	2715	return RBuf8::operator!=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2716	}
sl@0	2717
sl@0	2718	/**
sl@0	2719	Searches this descriptor's data for a match with the match pattern supplied
sl@0	2720	in the specified string.
sl@0	2721
sl@0	2722	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2723	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2724	a single occurrence of any character.
sl@0	2725
sl@0	2726	Note that there is no 'escape character', which means that it is not possible
sl@0	2727	to match either the "*" character itself or the "?" character itself using
sl@0	2728	this function.
sl@0	2729
sl@0	2730	@param aCharStr The 8-bit character string whose data is to be matched
sl@0	2731	with this Descriptor's data.
sl@0	2732
sl@0	2733	@return If a match is found, the offset within this descriptor's data where
sl@0	2734	the match first occurs. KErrNotFound, if there is no match.
sl@0	2735	*/
sl@0	2736	EXPORT_C TInt LString8::Match(const char* aCharStr) const
sl@0	2737	{
sl@0	2738	return LString8::Match(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2739	}
sl@0	2740
sl@0	2741	/**
sl@0	2742	Searches this descriptor's data for a match with the match pattern supplied
sl@0	2743	in the specified string.
sl@0	2744
sl@0	2745	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2746	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2747	a single occurrence of any character.
sl@0	2748
sl@0	2749	Note that there is no 'escape character', which means that it is not possible
sl@0	2750	to match either the "*" character itself or the "?" character itself using
sl@0	2751	this function.
sl@0	2752
sl@0	2753	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2754	is to be matched with this Descriptor's data.
sl@0	2755
sl@0	2756	@return If a match is found, the offset within this descriptor's data where
sl@0	2757	the match first occurs. KErrNotFound, if there is no match.
sl@0	2758	*/
sl@0	2759	EXPORT_C TInt LString8::Match(const TUint8* aZeroTerminatedString) const
sl@0	2760	{
sl@0	2761	return RBuf8::Match(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2762	}
sl@0	2763	/**
sl@0	2764	Searches this descriptor's folded data for a match with the folded match
sl@0	2765	pattern supplied in the specified string.
sl@0	2766
sl@0	2767	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2768	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2769	a single occurrence of any character.
sl@0	2770
sl@0	2771	Note that folding is locale-independent behaviour. It is also important to
sl@0	2772	note that there can be no guarantee that folding is in any way culturally
sl@0	2773	appropriate, and should not be used for matching strings in natural language;
sl@0	2774	use MatchC() for this.
sl@0	2775
sl@0	2776	Note that there is no 'escape character', which means that it is not possible
sl@0	2777	to match either the "*" character itself or the "?" character itself using
sl@0	2778	this function.
sl@0	2779
sl@0	2780	@param aCharStr The 8-bit character string whose data is to be matched
sl@0	2781	with this Descriptor's data.
sl@0	2782
sl@0	2783	@return If a match is found, the offset within this descriptor's data where
sl@0	2784	the match first occurs. KErrNotFound, if there is no match.
sl@0	2785
sl@0	2786	@see TDesC8::MatchC()
sl@0	2787	*/
sl@0	2788	EXPORT_C TInt LString8::MatchF(const char* aCharStr) const
sl@0	2789	{
sl@0	2790	return LString8::MatchF(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2791	}
sl@0	2792	/**
sl@0	2793	Searches this descriptor's folded data for a match with the folded match
sl@0	2794	pattern supplied in the specified string.
sl@0	2795
sl@0	2796	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2797	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2798	a single occurrence of any character.
sl@0	2799
sl@0	2800	Note that folding is locale-independent behaviour. It is also important to
sl@0	2801	note that there can be no guarantee that folding is in any way culturally
sl@0	2802	appropriate, and should not be used for matching strings in natural language;
sl@0	2803	use MatchC() for this.
sl@0	2804
sl@0	2805	Note that there is no 'escape character', which means that it is not possible
sl@0	2806	to match either the "*" character itself or the "?" character itself using
sl@0	2807	this function.
sl@0	2808
sl@0	2809	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2810	is to be matched with this Descriptor's data.
sl@0	2811
sl@0	2812	@return If a match is found, the offset within this descriptor's data where
sl@0	2813	the match first occurs. KErrNotFound, if there is no match.
sl@0	2814
sl@0	2815	@see TDesC8::MatchC()
sl@0	2816	*/
sl@0	2817	EXPORT_C TInt LString8::MatchF(const TUint8* aZeroTerminatedString) const
sl@0	2818	{
sl@0	2819	return RBuf8::MatchF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2820	}
sl@0	2821	/**
sl@0	2822	Compares this descriptor's data with the specified string's data.
sl@0	2823
sl@0	2824	The comparison proceeds on a byte for byte basis. The result of the comparison
sl@0	2825	is based on the difference of the first bytes to disagree.
sl@0	2826
sl@0	2827	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2828	with this Descriptor's data.
sl@0	2829
sl@0	2830	@return Positive, if this descriptor is greater than the specified string.
sl@0	2831	Negative, if this descriptor is less than the specified string.
sl@0	2832	Zero, if both the descriptor and the string have the same length
sl@0	2833	and the their contents are the same.
sl@0	2834	*/
sl@0	2835	EXPORT_C TInt LString8::Compare(const char* aCharStr) const
sl@0	2836	{
sl@0	2837	return LString8::Compare(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2838	}
sl@0	2839
sl@0	2840	/**
sl@0	2841	Compares this descriptor's data with the specified string's data.
sl@0	2842
sl@0	2843	The comparison proceeds on a byte for byte basis. The result of the comparison
sl@0	2844	is based on the difference of the first bytes to disagree.
sl@0	2845
sl@0	2846	@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
sl@0	2847	is to be compared with this Descriptor's data.
sl@0	2848
sl@0	2849	@return Positive, if this descriptor is greater than the specified string.
sl@0	2850	Negative, if this descriptor is less than the specified string.
sl@0	2851	Zero, if both the descriptor and the string have the same length
sl@0	2852	and the their contents are the same.
sl@0	2853	*/
sl@0	2854	EXPORT_C TInt LString8::Compare(const TUint8* aZeroTerminatedString) const
sl@0	2855	{
sl@0	2856	return RBuf8::Compare(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2857	}
sl@0	2858	/**
sl@0	2859	Compares this descriptor's folded data with the specified string's folded
sl@0	2860	data.
sl@0	2861
sl@0	2862	Note that folding is locale-independent behaviour. It is also important to
sl@0	2863	note that there can be no guarantee that folding is in any way culturally
sl@0	2864	appropriate, and should not be used for comparing strings in natural language;
sl@0	2865
sl@0	2866	@param aCharStr The 8-bit character string whose data is to be compared
sl@0	2867	with this Descriptor's data.
sl@0	2868
sl@0	2869	@return Positive, if this descriptor is greater than the specified string.
sl@0	2870	Negative, if this descriptor is less than the specified string.
sl@0	2871	Zero, if the descriptor and the specified string have the same length
sl@0	2872	and the their contents are the same.
sl@0	2873
sl@0	2874	@see TDesC8::Compare()
sl@0	2875	*/
sl@0	2876	EXPORT_C TInt LString8::CompareF(const char* aCharStr) const
sl@0	2877	{
sl@0	2878	return LString8::CompareF(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2879	}
sl@0	2880
sl@0	2881	/**
sl@0	2882	Compares this descriptor's folded data with the specified string's folded
sl@0	2883	data.
sl@0	2884
sl@0	2885	Note that folding is locale-independent behaviour. It is also important to
sl@0	2886	note that there can be no guarantee that folding is in any way culturally
sl@0	2887	appropriate, and should not be used for comparing strings in natural language;
sl@0	2888
sl@0	2889	@param aZeroTerminatedString The 8-bit Zero Terminated String whose data
sl@0	2890	is to be compared with this string's data.
sl@0	2891
sl@0	2892	@return Positive, if this descriptor is greater than the specified string.
sl@0	2893	Negative, if this descriptor is less than the specified string.
sl@0	2894	Zero, if the descriptor and the specified string have the same length
sl@0	2895	and the their contents are the same.
sl@0	2896
sl@0	2897	@see TDesC8::Compare()
sl@0	2898	*/
sl@0	2899	EXPORT_C TInt LString8::CompareF(const TUint8* aZeroTerminatedString) const
sl@0	2900	{
sl@0	2901	return RBuf8::CompareF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2902	}
sl@0	2903
sl@0	2904	/**
sl@0	2905	Searches for the first occurrence of the specified data sequence within this
sl@0	2906	descriptor.
sl@0	2907
sl@0	2908	Searching always starts at the beginning of this descriptor's data.
sl@0	2909
sl@0	2910	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	2911	within this Descriptor's data.
sl@0	2912
sl@0	2913	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2914	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2915	*/
sl@0	2916	EXPORT_C TInt LString8::Find(const char* aCharStr) const
sl@0	2917	{
sl@0	2918	return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2919	}
sl@0	2920
sl@0	2921	/**
sl@0	2922	Searches for the first occurrence of the specified data sequence within this
sl@0	2923	descriptor.
sl@0	2924
sl@0	2925	Searching always starts at the beginning of this descriptor's data.
sl@0	2926
sl@0	2927	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	2928	within this Descriptor's data.
sl@0	2929
sl@0	2930	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2931	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2932	*/
sl@0	2933	EXPORT_C TInt LString8::Find(const TUint8* aZeroTerminatedString) const
sl@0	2934	{
sl@0	2935	return RBuf8::Find(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2936	}
sl@0	2937
sl@0	2938	/**
sl@0	2939	Searches for the first occurrence of the specified data sequence within this
sl@0	2940	descriptor.
sl@0	2941
sl@0	2942	Searching always starts at the beginning of this descriptor's data.
sl@0	2943
sl@0	2944	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	2945	within this Descriptor's data.
sl@0	2946	@param aLenS The length of the data sequence to be searched for. This value
sl@0	2947	must not be negative, otherwise the function raises a panic.
sl@0	2948
sl@0	2949	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2950	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2951
sl@0	2952	@panic USER 29 if aLenS is negative.
sl@0	2953	*/
sl@0	2954	EXPORT_C TInt LString8::Find(const char* aCharStr,TInt aLenS) const
sl@0	2955	{
sl@0	2956	return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr), aLenS);
sl@0	2957	}
sl@0	2958
sl@0	2959	/**
sl@0	2960	Searches for the first occurrence of the specified folded data sequence within
sl@0	2961	this descriptor's folded data.
sl@0	2962
sl@0	2963	Searching always starts at the beginning of this descriptor's data.
sl@0	2964
sl@0	2965	Note that folding is locale-independent behaviour. It is also important to
sl@0	2966	note that there can be no guarantee that folding is in any way culturally
sl@0	2967	appropriate, and should not be used for finding strings in natural language;
sl@0	2968
sl@0	2969	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	2970	within this Descriptor's data.
sl@0	2971
sl@0	2972	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2973	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	2974	length of the search data sequence is zero.
sl@0	2975
sl@0	2976	*/
sl@0	2977	EXPORT_C TInt LString8::FindF(const char* aCharStr) const
sl@0	2978	{
sl@0	2979	return LString8::FindF(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	2980	}
sl@0	2981
sl@0	2982	/**
sl@0	2983	Searches for the first occurrence of the specified folded data sequence within
sl@0	2984	this descriptor's folded data.
sl@0	2985
sl@0	2986	Searching always starts at the beginning of this descriptor's data.
sl@0	2987
sl@0	2988	Note that folding is locale-independent behaviour. It is also important to
sl@0	2989	note that there can be no guarantee that folding is in any way culturally
sl@0	2990	appropriate, and should not be used for finding strings in natural language;
sl@0	2991
sl@0	2992	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	2993	within this Descriptor's data.
sl@0	2994
sl@0	2995	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2996	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	2997	length of the search data sequence is zero.
sl@0	2998
sl@0	2999	*/
sl@0	3000	EXPORT_C TInt LString8::FindF(const TUint8* aZeroTerminatedString) const
sl@0	3001	{
sl@0	3002	return RBuf8::FindF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3003	}
sl@0	3004	/**
sl@0	3005	Searches for the first occurrence of the specified folded data sequence within
sl@0	3006	this descriptor's folded data.
sl@0	3007
sl@0	3008	Searching always starts at the beginning of this descriptor's data.
sl@0	3009
sl@0	3010	Note that folding is locale-independent behaviour. It is also important to
sl@0	3011	note that there can be no guarantee that folding is in any way culturally
sl@0	3012	appropriate, and should not be used for finding strings in natural language;
sl@0	3013
sl@0	3014	@param aCharStr The 8-bit character string whose data is to be searched for,
sl@0	3015	within this Descriptor's data.
sl@0	3016	@param aLenS The length of the data sequence to be searched for. This value
sl@0	3017	must not be negative, otherwise the function raises a panic.
sl@0	3018
sl@0	3019	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	3020	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	3021	length of the search data sequence is zero.
sl@0	3022
sl@0	3023	@panic USER 29 if aLenS is negative
sl@0	3024
sl@0	3025	*/
sl@0	3026	EXPORT_C TInt LString8::FindF(const char* aCharStr, TInt aLen) const
sl@0	3027	{
sl@0	3028	return RBuf8::FindF(reinterpret_cast<const TUint8*>(aCharStr),aLen);
sl@0	3029	}
sl@0	3030
sl@0	3031	/**
sl@0	3032	Copies and folds data from the specified string into this descriptor replacing
sl@0	3033	any existing data.
sl@0	3034
sl@0	3035	The length of this descriptor is set to reflect the new
sl@0	3036	data.
sl@0	3037
sl@0	3038	Note that folding is locale-independent behaviour. It is also important to
sl@0	3039	note that there can be no guarantee that folding is in any way culturally
sl@0	3040	appropriate, and should not be used when dealing with strings in natural
sl@0	3041	language.
sl@0	3042
sl@0	3043	This leaving variant of the standard, non-leaving descriptor method
sl@0	3044	differs in that this operation may cause the string descriptor's heap
sl@0	3045	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3046	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3047	and any existing raw pointers to into the descriptor data may be
sl@0	3048	invalidated.
sl@0	3049
sl@0	3050	@param aCharStr A 8-bit character string
sl@0	3051
sl@0	3052	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3053	grown and there are insufficient resources to do so
sl@0	3054	*/
sl@0	3055	EXPORT_C void LString8:: CopyFL(const char* aCharStr )
sl@0	3056	{
sl@0	3057	LString8::CopyFL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3058	}
sl@0	3059
sl@0	3060	/**
sl@0	3061	Copies and folds data from the specified string into this descriptor replacing
sl@0	3062	any existing data.
sl@0	3063
sl@0	3064	The length of this descriptor is set to reflect the new
sl@0	3065	data.
sl@0	3066
sl@0	3067	Note that folding is locale-independent behaviour. It is also important to
sl@0	3068	note that there can be no guarantee that folding is in any way culturally
sl@0	3069	appropriate, and should not be used when dealing with strings in natural
sl@0	3070	language.
sl@0	3071
sl@0	3072	This leaving variant of the standard, non-leaving descriptor method
sl@0	3073	differs in that this operation may cause the string descriptor's heap
sl@0	3074	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3075	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3076	and any existing raw pointers to into the descriptor data may be
sl@0	3077	invalidated.
sl@0	3078
sl@0	3079	@param aZeroTerminatedString A 8-bit zero terminated string
sl@0	3080
sl@0	3081	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3082	grown and there are insufficient resources to do so
sl@0	3083	*/
sl@0	3084	EXPORT_C void LString8:: CopyFL(const TUint8* aZeroTerminatedString )
sl@0	3085	{
sl@0	3086	LString8::CopyFL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3087	}
sl@0	3088
sl@0	3089	/**
sl@0	3090	Copies text from the specified string and converts it to lower case before
sl@0	3091	putting it into this descriptor, replacing any existing data.
sl@0	3092
sl@0	3093	The length of this descriptor is set to reflect the new data.
sl@0	3094
sl@0	3095	Conversion to lower case is implemented as appropriate to the current locale.
sl@0	3096
sl@0	3097	This leaving variant of the standard, non-leaving descriptor method
sl@0	3098	differs in that this operation may cause the string descriptor's heap
sl@0	3099	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3100	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3101	and any existing raw pointers to into the descriptor data may be
sl@0	3102	invalidated.
sl@0	3103
sl@0	3104	@param aCharStr A 8-bit character string.
sl@0	3105
sl@0	3106	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3107	grown and there are insufficient resources to do so
sl@0	3108	*/
sl@0	3109	EXPORT_C void LString8:: CopyLCL(const char* aCharStr)
sl@0	3110	{
sl@0	3111	LString8::CopyLCL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3112	}
sl@0	3113
sl@0	3114	/**
sl@0	3115	Copies text from the specified string and converts it to lower case before
sl@0	3116	putting it into this descriptor, replacing any existing data.
sl@0	3117
sl@0	3118	The length of this descriptor is set to reflect the new data.
sl@0	3119
sl@0	3120	Conversion to lower case is implemented as appropriate to the current locale.
sl@0	3121
sl@0	3122	This leaving variant of the standard, non-leaving descriptor method
sl@0	3123	differs in that this operation may cause the string descriptor's heap
sl@0	3124	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3125	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3126	and any existing raw pointers to into the descriptor data may be
sl@0	3127	invalidated.
sl@0	3128
sl@0	3129	@param aZeroTerminatedString A 8-bit zero terminated string.
sl@0	3130
sl@0	3131	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3132	grown and there are insufficient resources to do so
sl@0	3133	*/
sl@0	3134	EXPORT_C void LString8:: CopyLCL(const TUint8* aZeroTerminatedString)
sl@0	3135	{
sl@0	3136	LString8::CopyLCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3137	}
sl@0	3138
sl@0	3139	/**
sl@0	3140	Copies text from the specified string and converts it to upper case before
sl@0	3141	putting it into this descriptor, replacing any existing data.
sl@0	3142
sl@0	3143	The length of this descriptor is set to reflect the new data.
sl@0	3144
sl@0	3145	Conversion to upper case is implemented as appropriate to the current locale.
sl@0	3146
sl@0	3147	This leaving variant of the standard, non-leaving descriptor method
sl@0	3148	differs in that this operation may cause the string descriptor's heap
sl@0	3149	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3150	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3151	and any existing raw pointers to into the descriptor data may be
sl@0	3152	invalidated.
sl@0	3153
sl@0	3154	@param aCharStr A 8-bit character string.
sl@0	3155
sl@0	3156	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3157	grown and there are insufficient resources to do so
sl@0	3158	*/
sl@0	3159	EXPORT_C void LString8:: CopyUCL(const char* aCharStr)
sl@0	3160	{
sl@0	3161	LString8::CopyUCL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3162	}
sl@0	3163
sl@0	3164	/**
sl@0	3165	Copies text from the specified string and converts it to upper case before
sl@0	3166	putting it into this descriptor, replacing any existing data.
sl@0	3167
sl@0	3168	The length of this descriptor is set to reflect the new data.
sl@0	3169
sl@0	3170	Conversion to upper case is implemented as appropriate to the current locale.
sl@0	3171
sl@0	3172	This leaving variant of the standard, non-leaving descriptor method
sl@0	3173	differs in that this operation may cause the string descriptor's heap
sl@0	3174	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3175	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3176	and any existing raw pointers to into the descriptor data may be
sl@0	3177	invalidated.
sl@0	3178
sl@0	3179	@param aZeroTerminatedString A 8-bit zero terminated string.
sl@0	3180
sl@0	3181	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3182	grown and there are insufficient resources to do so
sl@0	3183	*/
sl@0	3184	EXPORT_C void LString8:: CopyUCL(const TUint8* aZeroTerminatedString)
sl@0	3185	{
sl@0	3186	LString8::CopyUCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3187	}
sl@0	3188
sl@0	3189	/**
sl@0	3190	Copies text from the specified string and capitalises it before putting
sl@0	3191	it into this descriptor, replacing any existing data.
sl@0	3192
sl@0	3193	The length of this descriptor is set to reflect the new data.
sl@0	3194
sl@0	3195	Capitalisation is implemented as appropriate to the current locale.
sl@0	3196
sl@0	3197	This leaving variant of the standard, non-leaving descriptor method
sl@0	3198	differs in that this operation may cause the string descriptor's heap
sl@0	3199	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3200	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3201	and any existing raw pointers to into the descriptor data may be
sl@0	3202	invalidated.
sl@0	3203
sl@0	3204	@param aCharStr A 8-bit character string.
sl@0	3205
sl@0	3206	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3207	grown and there are insufficient resources to do so
sl@0	3208	*/
sl@0	3209	EXPORT_C void LString8:: CopyCPL(const char* aCharStr)
sl@0	3210	{
sl@0	3211	LString8::CopyCPL(reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3212	}
sl@0	3213
sl@0	3214	/**
sl@0	3215	Copies text from the specified string and capitalises it before putting
sl@0	3216	it into this descriptor, replacing any existing data.
sl@0	3217
sl@0	3218	The length of this descriptor is set to reflect the new data.
sl@0	3219
sl@0	3220	Capitalisation is implemented as appropriate to the current locale.
sl@0	3221
sl@0	3222	This leaving variant of the standard, non-leaving descriptor method
sl@0	3223	differs in that this operation may cause the string descriptor's heap
sl@0	3224	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3225	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3226	and any existing raw pointers to into the descriptor data may be
sl@0	3227	invalidated.
sl@0	3228
sl@0	3229	@param aZeroTerminatedString A 8-bit zero terminated string.
sl@0	3230
sl@0	3231	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3232	grown and there are insufficient resources to do so
sl@0	3233	*/
sl@0	3234	EXPORT_C void LString8:: CopyCPL(const TUint8* aZeroTerminatedString)
sl@0	3235	{
sl@0	3236	LString8::CopyCPL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3237	}
sl@0	3238	/**
sl@0	3239	Inserts data into this descriptor.
sl@0	3240
sl@0	3241	The length of this descriptor is changed to reflect the extra data.
sl@0	3242
sl@0	3243	This leaving variant of the standard, non-leaving descriptor method
sl@0	3244	differs in that this operation may cause the string descriptor's heap
sl@0	3245	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3246	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3247	and any existing raw pointers to into the descriptor data may be
sl@0	3248	invalidated.
sl@0	3249
sl@0	3250	@param aPos The position within the data where insertion is to start. This
sl@0	3251	is an offset value; a zero value refers to the leftmost data
sl@0	3252	position.
sl@0	3253
sl@0	3254	@param aCharStr A 8-bit character string.
sl@0	3255
sl@0	3256	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3257	grown and there are insufficient resources to do so
sl@0	3258
sl@0	3259	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3260	descriptor.
sl@0	3261	*/
sl@0	3262	EXPORT_C void LString8:: InsertL(TInt aPos,const char* aCharStr)
sl@0	3263	{
sl@0	3264	LString8::InsertL(aPos, reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3265	}
sl@0	3266
sl@0	3267	/**
sl@0	3268	Inserts data into this descriptor.
sl@0	3269
sl@0	3270	The length of this descriptor is changed to reflect the extra data.
sl@0	3271
sl@0	3272	This leaving variant of the standard, non-leaving descriptor method
sl@0	3273	differs in that this operation may cause the string descriptor's heap
sl@0	3274	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3275	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3276	and any existing raw pointers to into the descriptor data may be
sl@0	3277	invalidated.
sl@0	3278
sl@0	3279	@param aPos The position within the data where insertion is to start. This
sl@0	3280	is an offset value; a zero value refers to the leftmost data
sl@0	3281	position.
sl@0	3282
sl@0	3283	@param aZeroTerminatedString A 8-bit null terminated string.
sl@0	3284
sl@0	3285	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3286	grown and there are insufficient resources to do so
sl@0	3287
sl@0	3288	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3289	descriptor.
sl@0	3290	*/
sl@0	3291	EXPORT_C void LString8:: InsertL(TInt aPos,const TUint8* aZeroTerminatedString)
sl@0	3292	{
sl@0	3293	LString8::InsertL(aPos,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3294	}
sl@0	3295
sl@0	3296	/**
sl@0	3297	Replaces data in this descriptor.
sl@0	3298
sl@0	3299	The specified length can be different to the length of the replacement data.
sl@0	3300	The length of this descriptor changes to reflect the change of data.
sl@0	3301
sl@0	3302	This leaving variant of the standard, non-leaving descriptor method
sl@0	3303	differs in that this operation may cause the string descriptor's heap
sl@0	3304	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3305	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3306	and any existing raw pointers to into the descriptor data may be
sl@0	3307	invalidated.
sl@0	3308
sl@0	3309	@param aPos The position within the data where replacement is to start.
sl@0	3310	This is an offset value; a zero value refers to the leftmost
sl@0	3311	data position.
sl@0	3312
sl@0	3313	@param aLength The length of data to be replaced.
sl@0	3314
sl@0	3315	@param aCharStr The source 8-bit character string
sl@0	3316
sl@0	3317	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3318	grown and there are insufficient resources to do so
sl@0	3319
sl@0	3320	@panic USER 8 if aLength is negative
sl@0	3321
sl@0	3322	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3323	descriptor.
sl@0	3324
sl@0	3325	@panic USER 16 if the length of the source descriptor aDes is negative
sl@0	3326	*/
sl@0	3327	EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const char* aCharStr)
sl@0	3328	{
sl@0	3329	LString8::ReplaceL(aPos,aLength,reinterpret_cast<const TUint8*>(aCharStr));
sl@0	3330	}
sl@0	3331
sl@0	3332	/**
sl@0	3333	Replaces data in this descriptor.
sl@0	3334
sl@0	3335	The specified length can be different to the length of the replacement data.
sl@0	3336	The length of this descriptor changes to reflect the change of data.
sl@0	3337
sl@0	3338	This leaving variant of the standard, non-leaving descriptor method
sl@0	3339	differs in that this operation may cause the string descriptor's heap
sl@0	3340	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3341	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3342	and any existing raw pointers to into the descriptor data may be
sl@0	3343	invalidated.
sl@0	3344
sl@0	3345	@param aPos The position within the data where replacement is to start.
sl@0	3346	This is an offset value; a zero value refers to the leftmost
sl@0	3347	data position.
sl@0	3348
sl@0	3349	@param aLength The length of data to be replaced.
sl@0	3350
sl@0	3351	@param aZeroTerminatedString The source 8-bit null terminated character string
sl@0	3352
sl@0	3353	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3354	grown and there are insufficient resources to do so
sl@0	3355
sl@0	3356	@panic USER 8 if aLength is negative
sl@0	3357
sl@0	3358	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3359	descriptor.
sl@0	3360
sl@0	3361	@panic USER 16 if the length of the source descriptor aDes is negative
sl@0	3362	*/
sl@0	3363	EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString)
sl@0	3364	{
sl@0	3365	LString8::ReplaceL(aPos,aLength,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3366	}
sl@0	3367
sl@0	3368	/**
sl@0	3369	Copies data into this descriptor and justifies it, replacing any existing data.
sl@0	3370
sl@0	3371	The length of this descriptor is set to reflect the new data.
sl@0	3372
sl@0	3373	The target area is considered to be an area of specified width positioned at
sl@0	3374	the beginning of this descriptor's data area. Source data is copied into, and
sl@0	3375	aligned within this target area according to the specified alignment
sl@0	3376	instruction.
sl@0	3377
sl@0	3378	If the length of the target area is larger than the length of the source, then
sl@0	3379	spare space within the target area is padded with the fill character.
sl@0	3380
sl@0	3381	This leaving variant of the standard, non-leaving descriptor method
sl@0	3382	differs in that this operation may cause the string descriptor's heap
sl@0	3383	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3384	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3385	and any existing raw pointers to into the descriptor data may be
sl@0	3386	invalidated.
sl@0	3387
sl@0	3388	@param aCharStr A 8-bit character string containing the source data.
sl@0	3389	The length of the data to be copied is the smaller of:
sl@0	3390	the length of the source descriptor, and
sl@0	3391	the width of the target area (only if this is not the
sl@0	3392	explicit negative value KDefaultJustifyWidth).
sl@0	3393
sl@0	3394	@param aWidth The width of the target area. If this has the specific
sl@0	3395	negative value KDefaultJustifyWidth, then the width is
sl@0	3396	re-set to the length of the data source.
sl@0	3397
sl@0	3398	@param aAlignment The alignment of the data within the target area
sl@0	3399
sl@0	3400	@param aFill The fill character used to pad the target area.
sl@0	3401
sl@0	3402	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3403	grown and there are insufficient resources to do so
sl@0	3404
sl@0	3405	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3406	*/
sl@0	3407	EXPORT_C void LString8:: JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3408	{
sl@0	3409	LString8::JustifyL(reinterpret_cast<const TUint8*>(aCharStr),aWidth,anAlignment,aFill);
sl@0	3410	}
sl@0	3411
sl@0	3412	/**
sl@0	3413	Copies data into this descriptor and justifies it, replacing any existing data.
sl@0	3414
sl@0	3415	The length of this descriptor is set to reflect the new data.
sl@0	3416
sl@0	3417	The target area is considered to be an area of specified width positioned at
sl@0	3418	the beginning of this descriptor's data area. Source data is copied into, and
sl@0	3419	aligned within this target area according to the specified alignment
sl@0	3420	instruction.
sl@0	3421
sl@0	3422	If the length of the target area is larger than the length of the source, then
sl@0	3423	spare space within the target area is padded with the fill character.
sl@0	3424
sl@0	3425	This leaving variant of the standard, non-leaving descriptor method
sl@0	3426	differs in that this operation may cause the string descriptor's heap
sl@0	3427	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3428	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3429	and any existing raw pointers to into the descriptor data may be
sl@0	3430	invalidated.
sl@0	3431
sl@0	3432	@param aCharStr A 8-bit character string containing the source data.
sl@0	3433	The length of the data to be copied is the smaller of:
sl@0	3434	the length of the source descriptor, and
sl@0	3435	the width of the target area (only if this is not the
sl@0	3436	explicit negative value KDefaultJustifyWidth).
sl@0	3437
sl@0	3438	@param aWidth The width of the target area. If this has the specific
sl@0	3439	negative value KDefaultJustifyWidth, then the width is
sl@0	3440	re-set to the length of the data source.
sl@0	3441
sl@0	3442	@param aAlignment The alignment of the data within the target area
sl@0	3443
sl@0	3444	@param aFill The fill character used to pad the target area.
sl@0	3445
sl@0	3446	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3447	grown and there are insufficient resources to do so
sl@0	3448
sl@0	3449	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3450	*/
sl@0	3451	EXPORT_C void LString8:: JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3452	{
sl@0	3453	LString8::JustifyL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill);
sl@0	3454	}
sl@0	3455
sl@0	3456	/**
sl@0	3457	Appends data onto the end of this descriptor's data and justifies it.
sl@0	3458
sl@0	3459	The source of the appended data is a memory location.
sl@0	3460
sl@0	3461	The target area is considered to be an area of specified width, immediately
sl@0	3462	following this descriptor's existing data. Source data is copied into, and
sl@0	3463	aligned within, this target area according to the specified alignment instruction.
sl@0	3464
sl@0	3465	If the length of the target area is larger than the length of the source,
sl@0	3466	then spare space within the target area is padded with the fill character.
sl@0	3467
sl@0	3468	This leaving variant of the standard, non-leaving descriptor method
sl@0	3469	differs in that this operation may cause the string descriptor's heap
sl@0	3470	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3471	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3472	and any existing raw pointers to into the descriptor data may be
sl@0	3473	invalidated.
sl@0	3474
sl@0	3475	@param aString A pointer to a source memory location.
sl@0	3476
sl@0	3477	@param aLength The length of data to be copied. If this is greater than the
sl@0	3478	width of the target area, then the length of data copied is
sl@0	3479	limited to the width.
sl@0	3480
sl@0	3481	@param aWidth The width of the target area. If this has the specific negative
sl@0	3482	value KDefaultJustifyWidth, then the width is
sl@0	3483	re-set to the length of the data source.
sl@0	3484
sl@0	3485	@param aAlignment The alignment of the data within the target area.
sl@0	3486
sl@0	3487	@param aFill The fill character used to pad the target area.
sl@0	3488
sl@0	3489	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3490	grown and there are insufficient resources to do so
sl@0	3491
sl@0	3492	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3493
sl@0	3494	@panic USER 17 if aLength is negative.
sl@0	3495	*/
sl@0	3496	EXPORT_C void LString8:: AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3497	{
sl@0	3498	LString8::AppendJustifyL(reinterpret_cast<const TUint8*>(aCharStr),aLength, aWidth,anAlignment,aFill);
sl@0	3499	}
sl@0	3500
sl@0	3501	// eof

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--