Symaptic: os/ossrv/lowlevellibsandfws/genericusabilitylib/src/lstring16.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	/**
sl@0	23	Aligns the supplied capacity to the nearest growth factor
sl@0	24
sl@0	25	For performance reasons the growth factor, KDefaultExpandSizeShift,
sl@0	26	is expressed as an exponent of 2 so shifting can be used to achieve the
sl@0	27	alignment.
sl@0	28
sl@0	29	a KDefaultExpandSizeShift value of 4 is equivalent to 16;
sl@0	30	giving newCapacity = ((newCapacity / 16) + 1) * 16
sl@0	31
sl@0	32	@param aNewCapacity The size to be aligned
sl@0	33
sl@0	34	@return The new, aligned capacity
sl@0	35	*/
sl@0	36	static inline TInt AlignCapacity(TInt aNewCapacity)
sl@0	37	{
sl@0	38	const TUint KDefaultExpandSizeShift = 4;
sl@0	39
sl@0	40	return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift);
sl@0	41	}
sl@0	42
sl@0	43	/**
sl@0	44	Guarantees that MaxLength() is greater than or equal to the supplied
sl@0	45	capacity, reallocating the supplied capacity if necessary.
sl@0	46
sl@0	47	The actual value of MaxLength() after a call may differ from the exact
sl@0	48	value requested, but if it does differ it will always be greater. This
sl@0	49	flexibility allows the implementation to manage heap buffers more
sl@0	50	efficiently.
sl@0	51
sl@0	52	The string descriptor's heap buffer may be reallocated in order to
sl@0	53	accommodate the new size. As a
sl@0	54	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	55	and any existing raw pointers to into the descriptor data may be
sl@0	56	invalidated.
sl@0	57
sl@0	58	@param aMinRequiredCapacity The minimum value of MaxLength() required
sl@0	59
sl@0	60	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	61	grown and there are insufficient resources to do so
sl@0	62	*/
sl@0	63	void LString16::ReserveL(TInt aMinRequiredCapacity)
sl@0	64	{
sl@0	65	if (MaxLength() < aMinRequiredCapacity)
sl@0	66	{
sl@0	67	ReAllocL(AlignCapacity(aMinRequiredCapacity));
sl@0	68	}
sl@0	69	}
sl@0	70
sl@0	71
sl@0	72	/**
sl@0	73	Guarantees that MaxLength() is greater than or equal to the supplied
sl@0	74	integer parameter, growing the underlying heap buffer if necessary.
sl@0	75
sl@0	76	The growth is exponential; maxLength *= 1.5
sl@0	77	This is reported to give an amortised complexity of O(n) when adding
sl@0	78	n characters.
sl@0	79	If the required capacity is larger than the expanded size then the
sl@0	80	required capacity is used instead.
sl@0	81
sl@0	82	The actual value of MaxLength() after a call may differ from the exact
sl@0	83	value requested, but if it does differ it will always be greater. This
sl@0	84	flexibility allows the implementation to manage heap buffers more
sl@0	85	efficiently.
sl@0	86
sl@0	87	@param aRequiredCapacity The minimum value of MaxLength() required
sl@0	88
sl@0	89	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	90	grown and there are insufficient resources to do so
sl@0	91	*/
sl@0	92	void LString16::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity)
sl@0	93	{
sl@0	94	//work in unsigned int for the appropriate shift operation
sl@0	95	TUint max_length = MaxLength();
sl@0	96	TUint requiredCapacity = aRequiredCapacity;
sl@0	97
sl@0	98	if (max_length < requiredCapacity)
sl@0	99	{
sl@0	100	// max_length *= 3/2;
sl@0	101	max_length = (max_length + (max_length << 1)) >> 1;
sl@0	102
sl@0	103	// take the bigger of the extended buffer or the required capactiy
sl@0	104	ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity)));
sl@0	105	}
sl@0	106	}
sl@0	107
sl@0	108	/**
sl@0	109	Guarantees that free space in the buffer greater than or equal the
sl@0	110	supplied integer parameter, growing the underlying heap buffer
sl@0	111	if necessary.
sl@0	112
sl@0	113	@param aRequiredEmptySpace The minimum value of free space required
sl@0	114
sl@0	115	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	116	grown and there are insufficient resources to do so
sl@0	117	*/
sl@0	118	void LString16::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace)
sl@0	119	{
sl@0	120	ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace);
sl@0	121	}
sl@0	122
sl@0	123	/**
sl@0	124	Grows the underlying buffer using the exponential growth
sl@0	125	function. Guarantees that MaxLength() is greater than or
sl@0	126	equal to 1.5 * the current MaxLength.
sl@0	127
sl@0	128
sl@0	129	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	130	grown and there are insufficient resources to do so
sl@0	131	*/
sl@0	132	void LString16::ReserveCapacityGrowExponentialL()
sl@0	133	{
sl@0	134	ReserveCapacityGrowExponentialL(MaxLength() + 1);
sl@0	135	}
sl@0	136
sl@0	137
sl@0	138	/**
sl@0	139	Default constructor.
sl@0	140
sl@0	141	Constructs a zero-length 16-bit resizable string descriptor.
sl@0	142
sl@0	143	Note that the resulting object owns no allocated memory yet. This
sl@0	144	default constructor never leaves.
sl@0	145	*/
sl@0	146	EXPORT_C LString16::LString16()
sl@0	147	: iReserved(0)
sl@0	148	{
sl@0	149	}
sl@0	150
sl@0	151	/**
sl@0	152	Destructor.
sl@0	153
sl@0	154	Frees any heap-allocated resources owned by this string descriptor. It
sl@0	155	is safe to rely on this destructor to perform all necessary cleanup;
sl@0	156	it is not necessary use the cleanup stack or to call Close() manually.
sl@0	157
sl@0	158	@see RBuf16::Close
sl@0	159	*/
sl@0	160	EXPORT_C LString16::~LString16()
sl@0	161	{
sl@0	162	RBuf16::Close();
sl@0	163	}
sl@0	164
sl@0	165	/**
sl@0	166	Constructor to create a 16-bit resizable string descriptor with an
sl@0	167	initial capacity.
sl@0	168
sl@0	169	The function allocates sufficient memory to contain descriptor data up to
sl@0	170	the specified initial maximum length.
sl@0	171
sl@0	172	The current length of the descriptor is set to zero. The maximum length of
sl@0	173	the descriptor is set to the specified value.
sl@0	174
sl@0	175	@param aMaxLength The maximum length of the descriptor.
sl@0	176
sl@0	177	@leave KErrNoMemory If there is insufficient memory.
sl@0	178
sl@0	179	@see RBuf16::CreateL
sl@0	180	*/
sl@0	181	EXPORT_C LString16::LString16(TInt aMaxLength)
sl@0	182	: iReserved(0)
sl@0	183	{
sl@0	184	RBuf16::CreateL(aMaxLength);
sl@0	185	}
sl@0	186
sl@0	187	/**
sl@0	188	Constructor to create a 16-bit resizable string descriptor from a
sl@0	189	pre-allocated heap descriptor.
sl@0	190
sl@0	191	Transfers ownership of the specified heap descriptor to this object.
sl@0	192
sl@0	193	@param aHBuf The heap descriptor to be transferred to this object.
sl@0	194	This pointer can be NULL, which means that a zero length
sl@0	195	16-bit resizable string descriptor is created.
sl@0	196
sl@0	197	@see RBuf16::RBuf16(HBufC16*)
sl@0	198	*/
sl@0	199	EXPORT_C LString16::LString16(HBufC16* aHBuf)
sl@0	200	: iReserved(0)
sl@0	201	{
sl@0	202	if (aHBuf)
sl@0	203	RBuf16::Assign (aHBuf);
sl@0	204	}
sl@0	205
sl@0	206	/**
sl@0	207	Constructor to create a 16-bit resizable string descriptor from a
sl@0	208	pre-allocated raw heap buffer.
sl@0	209
sl@0	210	The allocated memory forms the buffer for this string descriptor. The
sl@0	211	current length of the descriptor is set to zero.
sl@0	212
sl@0	213	@param aHeapCell The allocated memory to be assigned to this object. This
sl@0	214	pointer can be NULL, which means that a zero length 16-bit
sl@0	215	resizable buffer descriptor is created.
sl@0	216	@param aMaxLength The maximum length of the constructed string descriptor.
sl@0	217
sl@0	218	@panic USER 8 If the specified maximum length is greater then the size of
sl@0	219	the allocated heap cell, or the specified maximum length
sl@0	220	is NOT zero when the pointer to the heap cell is NULL.
sl@0	221
sl@0	222	@see RBuf16::Assign()
sl@0	223	*/
sl@0	224	EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aMaxLength)
sl@0	225	: iReserved(0)
sl@0	226	{
sl@0	227	RBuf16::Assign(aHeapCell, aMaxLength);
sl@0	228	}
sl@0	229
sl@0	230	/**
sl@0	231	Constructor to create a 16-bit resizable string descriptor from a
sl@0	232	pre-allocated raw heap buffer.
sl@0	233
sl@0	234	The allocated memory forms the buffer for this string descriptor. The
sl@0	235	current length of the descriptor is set to the value of the second
sl@0	236	parameter.
sl@0	237
sl@0	238	@param aHeapCell The allocated memory to be assigned to this object.
sl@0	239	@param aLength The length of the resulting string descriptor.
sl@0	240	@param aMaxLength The maximum length of the resulting string descriptor.
sl@0	241
sl@0	242	@panic USER 8 If the specified maximum length is greater then the size of
sl@0	243	the allocated heap cell, or the specified length is greater then
sl@0	244	the specified maximum length, or the specified maximum length
sl@0	245	is NOT zero when the pointer to the heap cell is NULL.
sl@0	246
sl@0	247	@see RBuf16::Assign()
sl@0	248	*/
sl@0	249	EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0	250	: iReserved(0)
sl@0	251	{
sl@0	252	RBuf16::Assign(aHeapCell, aLength, aMaxLength);
sl@0	253	}
sl@0	254
sl@0	255	/**
sl@0	256	Constructor to create a 16-bit resizable string descriptor to contain
sl@0	257	a copy of the specified (source) descriptor, or leave on failure.
sl@0	258
sl@0	259	The constructor allocates sufficient memory so that this string
sl@0	260	descriptor's maximum length is the same as the length of the source
sl@0	261	descriptor. Both the current length and the maximum length of this
sl@0	262	string descriptor are set to the length of the source descriptor.
sl@0	263
sl@0	264	The data contained in the source descriptor is copied into this string
sl@0	265	descriptor.
sl@0	266
sl@0	267	@param aDes Source descriptor to be copied into this object.
sl@0	268
sl@0	269	@leave KErrNoMemory If there is insufficient memory.
sl@0	270
sl@0	271	@see RBuf16::CreateL()
sl@0	272	*/
sl@0	273	EXPORT_C LString16::LString16(const TDesC16& aDes)
sl@0	274	: iReserved(0)
sl@0	275	{
sl@0	276	RBuf16::CreateL(aDes);
sl@0	277	}
sl@0	278
sl@0	279	/**
sl@0	280	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	281	data, and expanding its heap buffer to accommodate if necessary.
sl@0	282
sl@0	283	The length of this descriptor is set to reflect the new data.
sl@0	284
sl@0	285	This operation may cause the target string descriptor's heap buffer to
sl@0	286	be reallocated in order to accommodate the new data. As a result,
sl@0	287	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	288	existing raw pointers to into the descriptor data may be invalidated.
sl@0	289
sl@0	290	Note that the automatic resizing performed is a change to the
sl@0	291	functionality of this operation compared to other descriptor
sl@0	292	classes. This change is only active on objects directly declared
sl@0	293	LString16; when LString16 instances are instead manipulated via
sl@0	294	references to TDes16 or TDesC16, the standard (non-resizing, panicing)
sl@0	295	variant is invoked.
sl@0	296
sl@0	297	@param aDes A 16-bit non-modifiable descriptor.
sl@0	298
sl@0	299	@return A reference to this 16-bit string descriptor.
sl@0	300
sl@0	301	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	302	assigned to needs to be expanded, but there is
sl@0	303	insufficient memory to do so
sl@0	304
sl@0	305	@see LString16::CopyL
sl@0	306	*/
sl@0	307	EXPORT_C LString16& LString16::operator=(const TDesC16& aDes)
sl@0	308	{
sl@0	309	CopyL(aDes);
sl@0	310	return *this;
sl@0	311	}
sl@0	312
sl@0	313
sl@0	314	/**
sl@0	315	Transfers ownership of the specified 16-bit resizable descriptor's this object.
sl@0	316
sl@0	317	@param aBuf The source 16-bit resizable buffer. The ownership of this
sl@0	318	object's buffer is to be transferred.
sl@0	319
sl@0	320	@return A reference to this 16-bit string descriptor.
sl@0	321
sl@0	322	@see Assign()
sl@0	323	*/
sl@0	324	EXPORT_C LString16& LString16::operator=(HBufC16* aBuf)
sl@0	325	{
sl@0	326	Assign(aBuf);
sl@0	327	return *this;
sl@0	328	}
sl@0	329
sl@0	330
sl@0	331	/**
sl@0	332	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	333	data, and expanding its heap buffer to accommodate if necessary.
sl@0	334
sl@0	335	The length of this descriptor is set to reflect the new data.
sl@0	336
sl@0	337	This leaving variant of the standard, non-leaving descriptor method
sl@0	338	differs in that this operation may cause the string descriptor's heap
sl@0	339	buffer to be reallocated in order to accommodate the new data. As a
sl@0	340	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	341	and any existing raw pointers to into the descriptor data may be
sl@0	342	invalidated.
sl@0	343
sl@0	344	@param aDes A 16-bit non-modifiable descriptor.
sl@0	345
sl@0	346	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	347	assigned to needs to be expanded, but there is
sl@0	348	insufficient memory to do so
sl@0	349
sl@0	350	@see LString16::operator=
sl@0	351	@see TDes16::Copy
sl@0	352	*/
sl@0	353	EXPORT_C void LString16::CopyL(const TDesC16& aDes)
sl@0	354	{
sl@0	355	ReserveL(aDes.Length());
sl@0	356	RBuf16::Copy(aDes);
sl@0	357	}
sl@0	358
sl@0	359	/**
sl@0	360	Copy constructor to create a 16-bit resizable string descriptor to
sl@0	361	contain a copy of the specified (source) string descriptor's data, or
sl@0	362	leave on failure.
sl@0	363
sl@0	364	The constructor allocates sufficient memory so that this string
sl@0	365	descriptor's maximum length is the same as the length of the source
sl@0	366	string descriptor. Both the current length and the maximum length of
sl@0	367	this string descriptor are set to the length of the source descriptor.
sl@0	368
sl@0	369	The data contained in the source string descriptor is copied into this
sl@0	370	string descriptor.
sl@0	371
sl@0	372	@param aDes Source string descriptor to be copied into this object.
sl@0	373
sl@0	374	@leave KErrNoMemory If there is insufficient memory.
sl@0	375
sl@0	376	@see RBuf16::CreateL()
sl@0	377	*/
sl@0	378	EXPORT_C LString16::LString16(const LString16& aDes)
sl@0	379	: iReserved(0)
sl@0	380	{
sl@0	381	RBuf16::CreateL(aDes);
sl@0	382	}
sl@0	383
sl@0	384
sl@0	385	/**
sl@0	386	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	387	data, and expanding its heap buffer to accommodate if necessary.
sl@0	388
sl@0	389	The length of this descriptor is set to reflect the new data.
sl@0	390
sl@0	391	This operation may cause the target string descriptor's heap buffer to
sl@0	392	be reallocated in order to accommodate the new data. As a result,
sl@0	393	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	394	existing raw pointers to into the descriptor data may be invalidated.
sl@0	395
sl@0	396	Note that the automatic resizing performed is a change to the
sl@0	397	functionality of this operation compared to other descriptor
sl@0	398	classes. This change is only active on objects directly declared
sl@0	399	LString16; when LString16 instances are instead manipulated via
sl@0	400	references to TDes16 or TDesC16, the standard (non-resizing, panicing)
sl@0	401	variant is invoked.
sl@0	402
sl@0	403	@param aDes A 16-bit string descriptor.
sl@0	404
sl@0	405	@return A reference to this 16-bit string descriptor.
sl@0	406
sl@0	407	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	408	assigned to needs to be expanded, but there is
sl@0	409	insufficient memory to do so
sl@0	410
sl@0	411	@see LString16::CopyL
sl@0	412	*/
sl@0	413	EXPORT_C LString16& LString16::operator=(const LString16& aDes)
sl@0	414	{
sl@0	415	CopyL(aDes);
sl@0	416	return *this;
sl@0	417	}
sl@0	418
sl@0	419	/**
sl@0	420	Constructor to create a 16-bit resizable string descriptor containing
sl@0	421	a copy of the specified (source) zero-terminated string data, or leave
sl@0	422	on failure.
sl@0	423
sl@0	424	The constructor allocates sufficient memory so that this string
sl@0	425	descriptor's maximum length is the same as the length of the source
sl@0	426	string. Both the current length and the maximum length of this string
sl@0	427	descriptor are set to the length of the source string.
sl@0	428
sl@0	429	The data contained in the source string is copied into this string
sl@0	430	descriptor. The zero terminator is not copied.
sl@0	431
sl@0	432	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	433
sl@0	434	@leave KErrNoMemory If there is insufficient memory.
sl@0	435
sl@0	436	@see LString16::CopyL
sl@0	437	*/
sl@0	438	EXPORT_C LString16::LString16(const TUint16* aZeroTerminatedString)
sl@0	439	: iReserved(0)
sl@0	440	{
sl@0	441	CopyL(aZeroTerminatedString);
sl@0	442	}
sl@0	443
sl@0	444	/**
sl@0	445	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	446	data, and expanding its heap buffer to accommodate if necessary.
sl@0	447
sl@0	448	The length of this descriptor is set to reflect the new data.
sl@0	449
sl@0	450	This operation may cause the target string descriptor's heap buffer to
sl@0	451	be reallocated in order to accommodate the new data. As a result,
sl@0	452	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	453	existing raw pointers to into the descriptor data may be invalidated.
sl@0	454
sl@0	455	Note that the automatic resizing performed is a change to the
sl@0	456	functionality of this operation compared to other descriptor
sl@0	457	classes. This change is only active on objects directly declared
sl@0	458	LString16; when LString16 instances are instead manipulated via
sl@0	459	references to TDes16 or TDesC16, the standard (non-resizing, panicing)
sl@0	460	variant is invoked.
sl@0	461
sl@0	462	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	463
sl@0	464	@return A reference to this 16-bit string descriptor.
sl@0	465
sl@0	466	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	467	assigned to needs to be expanded, but there is
sl@0	468	insufficient memory to do so
sl@0	469
sl@0	470	@see LString16::CopyL
sl@0	471	*/
sl@0	472	EXPORT_C LString16& LString16::operator=(const TUint16* aZeroTerminatedString)
sl@0	473	{
sl@0	474	CopyL(aZeroTerminatedString);
sl@0	475	return *this;
sl@0	476	}
sl@0	477
sl@0	478	/**
sl@0	479	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	480	data, and expanding its heap buffer to accommodate if necessary.
sl@0	481
sl@0	482	The length of this descriptor is set to reflect the new data.
sl@0	483
sl@0	484	This leaving variant of the standard, non-leaving descriptor method
sl@0	485	differs in that this operation may cause the string descriptor's heap
sl@0	486	buffer to be reallocated in order to accommodate the new data. As a
sl@0	487	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	488	and any existing raw pointers to into the descriptor data may be
sl@0	489	invalidated.
sl@0	490
sl@0	491	@param aZeroTerminatedString A pointer to a zero-terminated string
sl@0	492
sl@0	493	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	494	assigned to needs to be expanded, but there is
sl@0	495	insufficient memory to do so
sl@0	496
sl@0	497	@see LString16::operator=
sl@0	498	@see TDes16::Copy
sl@0	499	*/
sl@0	500	EXPORT_C void LString16::CopyL(const TUint16* aZeroTerminatedString)
sl@0	501	{
sl@0	502	ReserveL(User::StringLength(aZeroTerminatedString));
sl@0	503	RBuf16::Copy(aZeroTerminatedString);
sl@0	504	}
sl@0	505
sl@0	506	/**
sl@0	507	Copies 8-bit descriptor data into this 16-bit string descriptor,
sl@0	508	replacing any existing data, and expanding its heap buffer to
sl@0	509	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	Each 8-bit character value is widened to a 16-bit character value as
sl@0	514	part of the copying process.
sl@0	515
sl@0	516	This leaving variant of the standard, non-leaving descriptor method
sl@0	517	differs in that this operation may cause the string descriptor's heap
sl@0	518	buffer to be reallocated in order to accommodate the new data. As a
sl@0	519	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	520	and any existing raw pointers to into the descriptor data may be
sl@0	521	invalidated.
sl@0	522
sl@0	523	@param aDes An 8 bit non modifiable descriptor.
sl@0	524
sl@0	525	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	526	assigned to needs to be expanded, but there is
sl@0	527	insufficient memory to do so
sl@0	528
sl@0	529	@see LString16::operator=
sl@0	530	@see TDes16::Copy
sl@0	531	*/
sl@0	532	EXPORT_C void LString16::CopyL(const TDesC8& aDes)
sl@0	533	{
sl@0	534	ReserveL(aDes.Length());
sl@0	535	RBuf16::Copy(aDes);
sl@0	536	}
sl@0	537
sl@0	538	/**
sl@0	539	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	540	data, and expanding its heap buffer to accommodate if necessary.
sl@0	541
sl@0	542	The length of this descriptor is set according to the second
sl@0	543	parameter.
sl@0	544
sl@0	545	This leaving variant of the standard, non-leaving descriptor method
sl@0	546	differs in that this operation may cause the string descriptor's heap
sl@0	547	buffer to be reallocated in order to accommodate the new data. As a
sl@0	548	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	549	and any existing raw pointers to into the descriptor data may be
sl@0	550	invalidated.
sl@0	551
sl@0	552	@param aBuf The start address of data to be copied.
sl@0	553	@param aLength The length of data to be copied.
sl@0	554
sl@0	555	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	556	assigned to needs to be expanded, but there is
sl@0	557	insufficient memory to do so
sl@0	558
sl@0	559	@panic USER 11 if aLength is negative.
sl@0	560
sl@0	561	@see TDes16::Copy
sl@0	562	*/
sl@0	563	EXPORT_C void LString16::CopyL(const TUint16* aBuf,TInt aLength)
sl@0	564	{
sl@0	565	ReserveL(aLength);
sl@0	566	RBuf16::Copy(aBuf, aLength);
sl@0	567	}
sl@0	568
sl@0	569
sl@0	570	/**
sl@0	571	Sets the length of the data represented by the string descriptor to
sl@0	572	the specified value.
sl@0	573
sl@0	574	This leaving variant of the standard, non-leaving descriptor method
sl@0	575	differs in that this operation may cause the string descriptor's heap
sl@0	576	buffer to be reallocated in order to accommodate the new data. As a
sl@0	577	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	578	and any existing raw pointers to into the descriptor data may be
sl@0	579	invalidated.
sl@0	580
sl@0	581	@param aLength The new length of the descriptor.
sl@0	582
sl@0	583	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	584	grown and there are insufficient resources to do so
sl@0	585
sl@0	586	@panic USER 11 if aLength is negative
sl@0	587	*/
sl@0	588	EXPORT_C void LString16::SetLengthL(TInt aLength)
sl@0	589	{
sl@0	590	ReserveL(aLength);
sl@0	591	RBuf16::SetLength(aLength);
sl@0	592	}
sl@0	593
sl@0	594
sl@0	595	/**
sl@0	596	Sets the storage space allocated to this descriptor to the specified
sl@0	597	value by growing or compressing its buffer size.
sl@0	598
sl@0	599	If the current length of the descriptor is greater than the specified
sl@0	600	max length, length is truncated to max length.
sl@0	601
sl@0	602	This leaving variant of the standard, non-leaving descriptor method
sl@0	603	differs in that this operation may cause the string descriptor's heap
sl@0	604	buffer to be reallocated in order to accommodate the new data. As a
sl@0	605	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	606	and any existing raw pointers to into the descriptor data may be
sl@0	607	invalidated.
sl@0	608
sl@0	609	@param aMaxLength The new maximum length of the descriptor.
sl@0	610
sl@0	611	@leave KErrNoMemory if the the buffer needs to be
sl@0	612	reallocated and there are insufficient resources to do so
sl@0	613
sl@0	614	@panic USER 11 if aLength is negative
sl@0	615	*/
sl@0	616	EXPORT_C void LString16::SetMaxLengthL(TInt aMaxLength)
sl@0	617	{
sl@0	618	if (MaxLength() == aMaxLength)
sl@0	619	{
sl@0	620	return;
sl@0	621	}
sl@0	622
sl@0	623	if (Length() > aMaxLength)
sl@0	624	{
sl@0	625	// truncate the current length
sl@0	626	RBuf16::SetLength(aMaxLength);
sl@0	627	}
sl@0	628
sl@0	629	ReAllocL(aMaxLength);
sl@0	630	}
sl@0	631
sl@0	632
sl@0	633	/**
sl@0	634	Ensures that the remaining unused space is more than the supplied value.
sl@0	635
sl@0	636	May reallocate a larger storage space to meet the requirement.
sl@0	637	As a result MaxLength() and Ptr() may return different values afterwards,
sl@0	638	and any existing raw pointers to into the descriptor data may be
sl@0	639	invalidated.
sl@0	640
sl@0	641	Typically, you use this method to reserve a known amount of required space
sl@0	642	in one go instead of relying on the automatic growth pattern.
sl@0	643
sl@0	644	@param aExtraSpaceLength The extra space required.
sl@0	645
sl@0	646	@leave KErrNoMemory if the the buffer needs to be
sl@0	647	reallocated and there are insufficient resources to do so.
sl@0	648
sl@0	649	@panic USER 11 if aLength is negative
sl@0	650	*/
sl@0	651	EXPORT_C void LString16::ReserveFreeCapacityL(TInt aExtraSpaceLength)
sl@0	652	{
sl@0	653	ReserveL(Length() + aExtraSpaceLength);
sl@0	654	}
sl@0	655
sl@0	656
sl@0	657	/**
sl@0	658	Re-initialises the descriptor destroying its payload
sl@0	659
sl@0	660	*/
sl@0	661	EXPORT_C void LString16::Reset()
sl@0	662	{
sl@0	663	RBuf16::Close();
sl@0	664	}
sl@0	665
sl@0	666
sl@0	667	/**
sl@0	668	Re-allocates a smaller descriptor buffer space to the current
sl@0	669	descriptor length
sl@0	670
sl@0	671	This may cause the string descriptor's heap buffer to be reallocated
sl@0	672	in order to accommodate the new data. As a
sl@0	673	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	674	and any existing raw pointers to into the descriptor data may be
sl@0	675	invalidated.
sl@0	676
sl@0	677	If there is insufficient memory to re-allocate the buffer then the
sl@0	678	descriptor left unchanged
sl@0	679	*/
sl@0	680	EXPORT_C void LString16::Compress()
sl@0	681	{
sl@0	682	TInt length = Length();
sl@0	683	if (MaxLength() > length)
sl@0	684	{
sl@0	685	ReAlloc(length);
sl@0	686	}
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 LString16::operator+=
sl@0	709	*/
sl@0	710	EXPORT_C void LString16::AppendL(TChar aChar)
sl@0	711	{
sl@0	712	ReserveFreeCapacityGrowExponentialL(1);
sl@0	713	RBuf16::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 LString16::AppendL
sl@0	735	*/
sl@0	736	EXPORT_C LString16& LString16::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 16-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 LString16::AppendL(const TDesC16& aDes)
sl@0	760	{
sl@0	761	ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0	762	RBuf16::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 16-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 LString16::AppendL
sl@0	783	*/
sl@0	784	EXPORT_C LString16& LString16::operator+=(const TDesC16& 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 LString16::AppendL(const TUint16* aBuf,TInt aLength)
sl@0	811	{
sl@0	812	ReserveFreeCapacityGrowExponentialL(aLength);
sl@0	813	RBuf16::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 LString16::FillL(TChar aChar,TInt aLength)
sl@0	840	{
sl@0	841	ReserveL(aLength);
sl@0	842	RBuf16::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 LString16::FillZL(TInt aLength)
sl@0	868	{
sl@0	869	ReserveL(aLength);
sl@0	870	RBuf16::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 LString16::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 LString16::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	946	{
sl@0	947	ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0	948	RBuf16::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 TUint16 *LString16::PtrZL()
sl@0	971	{
sl@0	972	ReserveFreeCapacityL(1);
sl@0	973	return RBuf16::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 16-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 LString16::CopyFL(const TDesC16& aDes)
sl@0	1001	{
sl@0	1002	ReserveL(aDes.Length());
sl@0	1003	RBuf16::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 16-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 LString16::CopyCL(const TDesC16& aDes)
sl@0	1025	{
sl@0	1026	ReserveL(aDes.Length());
sl@0	1027	RBuf16::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 16-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 LString16::CopyLCL(const TDesC16& aDes)
sl@0	1051	{
sl@0	1052	ReserveL(aDes.Length());
sl@0	1053	RBuf16::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 16-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 LString16::CopyUCL(const TDesC16& aDes)
sl@0	1077	{
sl@0	1078	ReserveL(aDes.Length());
sl@0	1079	RBuf16::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 16-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 LString16::CopyCPL(const TDesC16& aDes)
sl@0	1103	{
sl@0	1104	ReserveL(aDes.Length());
sl@0	1105	RBuf16::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 LString16::AppendFillL(TChar aChar,TInt aLength)
sl@0	1130	{
sl@0	1131	ReserveFreeCapacityGrowExponentialL(aLength);
sl@0	1132	RBuf16::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 LString16::ZeroTerminateL()
sl@0	1152	{
sl@0	1153	ReserveFreeCapacityL(1);
sl@0	1154	RBuf16::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 LString16, then the function
sl@0	1169	raises a USER 11 panic. The target LString16 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 16-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 LString16
sl@0	1187	*/
sl@0	1188	EXPORT_C void LString16::SwapL(TDes16& aDes)
sl@0	1189	{
sl@0	1190	ReserveL(aDes.Length());
sl@0	1191	TDes16::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 16-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 LString16::SwapL(LString16& aDes)
sl@0	1216	{
sl@0	1217	this->ReserveL(aDes.Length());
sl@0	1218	aDes.ReserveL(this->Length());
sl@0	1219	TDes16::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 16-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 LString16::InsertL(TInt aPos,const TDesC16& aDes)
sl@0	1248	{
sl@0	1249	ReserveFreeCapacityGrowExponentialL(aDes.Length());
sl@0	1250	RBuf16::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 16-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 LString16::ReplaceL(TInt aPos,TInt aLength,const TDesC16& 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	RBuf16::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 16-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 LString16::JustifyL(const TDesC16& 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	RBuf16::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 TDes16::Format()
sl@0	1380	*/
sl@0	1381	EXPORT_C void LString16::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 LString16::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 LString16::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 LString16::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 LString16::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 TDes16::Num()
sl@0	1590	@see TDes16::NumUC()
sl@0	1591	*/
sl@0	1592	EXPORT_C void LString16::FormatL(TRefByValue<const TDesC16> 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 TDes16::Format()
sl@0	1622	@see VA_LIST
sl@0	1623	*/
sl@0	1624	EXPORT_C void LString16::FormatListL(const TDesC16& 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 16-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 LString16::AppendJustifyL(const TDesC16& 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	RBuf16::AppendJustify(Des, aWidth, aAlignment, aFill);
sl@0	1674	}
sl@0	1675
sl@0	1676	/**
sl@0	1677	Appends data onto the end of this descriptor's data and justifies it.
sl@0	1678
sl@0	1679	The source of the appended data is an existing descriptor.
sl@0	1680
sl@0	1681	The target area is considered to be an area of specified width, immediately
sl@0	1682	following this descriptor's existing data. Source data is copied into, and
sl@0	1683	aligned within this target area according to the specified alignment instruction.
sl@0	1684
sl@0	1685	If the length of the target area is larger than the length of the source,
sl@0	1686	then spare space within the target area is padded with the fill character.
sl@0	1687
sl@0	1688	This leaving variant of the standard, non-leaving descriptor method
sl@0	1689	differs in that this operation may cause the string descriptor's heap
sl@0	1690	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1691	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1692	and any existing raw pointers to into the descriptor data may be
sl@0	1693	invalidated.
sl@0	1694
sl@0	1695	@param aDes An 8-bit non-modifiable descriptor containing the source data.
sl@0	1696
sl@0	1697	@param aLength The length of data to be copied from the source descriptor.
sl@0	1698	If this is greater than the width of the target area, then
sl@0	1699	the length of data copied is limited to the width.
sl@0	1700	The length of data to be copied must not be greater than
sl@0	1701	the length of the source descriptor. Note that this
sl@0	1702	condition is not automatically tested.
sl@0	1703
sl@0	1704	@param aWidth The width of the target area. If this has the specific negative
sl@0	1705	value KDefaultJustifyWidth, then the width is
sl@0	1706	re-set to the length of the data source.
sl@0	1707
sl@0	1708	@param aAlignment The alignment of the data within the target area.
sl@0	1709
sl@0	1710	@param aFill The fill character used to pad the target area.
sl@0	1711
sl@0	1712	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1713	grown and there are insufficient resources to do so
sl@0	1714
sl@0	1715	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1716	*/
sl@0	1717	EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1718	{
sl@0	1719
sl@0	1720	TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
sl@0	1721	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1722
sl@0	1723	RBuf16::AppendJustify(Des, aLength, aWidth, aAlignment, aFill);
sl@0	1724	}
sl@0	1725
sl@0	1726	/**
sl@0	1727	Appends a zero terminated string onto the end of this descriptor's data and
sl@0	1728	justifies it.
sl@0	1729
sl@0	1730	The zero terminator is not copied.
sl@0	1731
sl@0	1732	The target area is considered to be an area of specified width, immediately
sl@0	1733	following this descriptor's existing data. Source data is copied into, and
sl@0	1734	aligned within, this target area according to the specified alignment instruction.
sl@0	1735
sl@0	1736	If the length of the target area is larger than the length of the source,
sl@0	1737	then spare space within the target area is padded with the fill character.
sl@0	1738
sl@0	1739	This leaving variant of the standard, non-leaving descriptor method
sl@0	1740	differs in that this operation may cause the string descriptor's heap
sl@0	1741	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1742	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1743	and any existing raw pointers to into the descriptor data may be
sl@0	1744	invalidated.
sl@0	1745
sl@0	1746	@param aZeroTerminatedString A pointer to a zero terminated string The length of the data
sl@0	1747	to be copied is the smaller of: the length of the string (excluding the zero
sl@0	1748	terminator), the width of the target area (only if this is not the explicit
sl@0	1749	negative value KDefaultJustifyWidth).
sl@0	1750
sl@0	1751	@param aWidth The width of the target area. If this has the specific negative
sl@0	1752	value KDefaultJustifyWidth, then the width is re-set to the length of the
sl@0	1753	zero terminated string (excluding the zero terminator).
sl@0	1754
sl@0	1755	@param aAlignment The alignment of the data within the target area.
sl@0	1756
sl@0	1757	@param aFill The fill character used to pad the target area.
sl@0	1758
sl@0	1759	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1760	grown and there are insufficient resources to do so
sl@0	1761
sl@0	1762	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1763	*/
sl@0	1764	EXPORT_C void LString16::AppendJustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1765	{
sl@0	1766
sl@0	1767	TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth);
sl@0	1768	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1769
sl@0	1770	RBuf16::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill);
sl@0	1771
sl@0	1772	}
sl@0	1773
sl@0	1774	/**
sl@0	1775	Appends data onto the end of this descriptor's data and justifies it.
sl@0	1776
sl@0	1777	The source of the appended data is a memory location.
sl@0	1778
sl@0	1779	The target area is considered to be an area of specified width, immediately
sl@0	1780	following this descriptor's existing data. Source data is copied into, and
sl@0	1781	aligned within, this target area according to the specified alignment instruction.
sl@0	1782
sl@0	1783	If the length of the target area is larger than the length of the source,
sl@0	1784	then spare space within the target area is padded with the fill character.
sl@0	1785
sl@0	1786	This leaving variant of the standard, non-leaving descriptor method
sl@0	1787	differs in that this operation may cause the string descriptor's heap
sl@0	1788	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1789	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1790	and any existing raw pointers to into the descriptor data may be
sl@0	1791	invalidated.
sl@0	1792
sl@0	1793	@param aString A pointer to a source memory location.
sl@0	1794
sl@0	1795	@param aLength The length of data to be copied. If this is greater than the
sl@0	1796	width of the target area, then the length of data copied is
sl@0	1797	limited to the width.
sl@0	1798
sl@0	1799	@param aWidth The width of the target area. If this has the specific negative
sl@0	1800	value KDefaultJustifyWidth, then the width is
sl@0	1801	re-set to the length of the data source.
sl@0	1802
sl@0	1803	@param aAlignment The alignment of the data within the target area.
sl@0	1804
sl@0	1805	@param aFill The fill character used to pad the target area.
sl@0	1806
sl@0	1807	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1808	grown and there are insufficient resources to do so
sl@0	1809
sl@0	1810	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	1811
sl@0	1812	@panic USER 17 if aLength is negative.
sl@0	1813	*/
sl@0	1814	EXPORT_C void LString16::AppendJustifyL(const TUint16* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
sl@0	1815	{
sl@0	1816
sl@0	1817	TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
sl@0	1818	ReserveFreeCapacityGrowExponentialL(width);
sl@0	1819
sl@0	1820	RBuf16::AppendJustify(aString, aLength, aWidth, aAlignment, aFill);
sl@0	1821	}
sl@0	1822
sl@0	1823	/**
sl@0	1824	Converts the specified unsigned integer into a fixed width character
sl@0	1825	representation based on the specified number system and appends the conversion
sl@0	1826	onto the end of this descriptor's data.
sl@0	1827
sl@0	1828	The length of this descriptor is incremented to reflect the new content.
sl@0	1829
sl@0	1830	The function generates the exact number of specified characters, either
sl@0	1831	padding to the left with character zeroes or discarding low order characters
sl@0	1832	as necessary.
sl@0	1833
sl@0	1834	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1835	upper case.
sl@0	1836
sl@0	1837	This leaving variant of the standard, non-leaving descriptor method
sl@0	1838	differs in that this operation may cause the string descriptor's heap
sl@0	1839	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1840	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1841	and any existing raw pointers to into the descriptor data may be
sl@0	1842	invalidated.
sl@0	1843
sl@0	1844	@param aVal The unsigned integer value.
sl@0	1845	@param aRadix The number system representation for the unsigned integer.
sl@0	1846	@param aWidth The number of characters: to be used to contain the conversion,
sl@0	1847	to be appended to this descriptor.
sl@0	1848
sl@0	1849	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1850	grown and there are insufficient resources to do so
sl@0	1851
sl@0	1852	*/
sl@0	1853	EXPORT_C void LString16::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
sl@0	1854	{
sl@0	1855	ReserveFreeCapacityGrowExponentialL(aWidth);
sl@0	1856	RBuf16::AppendNumFixedWidthUC(aVal, aRadix, aWidth);
sl@0	1857	}
sl@0	1858
sl@0	1859	/**
sl@0	1860	Converts the specified 64 bit integer into a character representation
sl@0	1861	based on the specified number system and appends the conversion onto the end
sl@0	1862	of this descriptor's data.
sl@0	1863
sl@0	1864	The length of this descriptor is incremented to reflect the new content.
sl@0	1865
sl@0	1866	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1867	upper case.
sl@0	1868
sl@0	1869	This leaving variant of the standard, non-leaving descriptor method
sl@0	1870	differs in that this operation may cause the string descriptor's heap
sl@0	1871	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1872	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1873	and any existing raw pointers to into the descriptor data may be
sl@0	1874	invalidated.
sl@0	1875
sl@0	1876	@param aVal The 64 bit integer value. This is always treated as an unsigned
sl@0	1877	value.
sl@0	1878	@param aRadix The number system representation for the 64 bit integer. If no
sl@0	1879	explicit value is specified, then EDecimal is the default.
sl@0	1880
sl@0	1881	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1882	grown and there are insufficient resources to do so
sl@0	1883	*/
sl@0	1884	EXPORT_C void LString16::AppendNumUCL(TUint64 aVal, TRadix aRadix)
sl@0	1885	{
sl@0	1886	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1887	RBuf16::AppendNumUC(aVal, aRadix);
sl@0	1888	}
sl@0	1889
sl@0	1890	/**
sl@0	1891	Converts the specified floating point number into a character representation
sl@0	1892	and appends the conversion onto the end of this descriptor's data.
sl@0	1893
sl@0	1894	The length of this descriptor is incremented to reflect the new content.
sl@0	1895
sl@0	1896	The character representation of the real number is dictated by the specified
sl@0	1897	format.
sl@0	1898
sl@0	1899	This leaving variant of the standard, non-leaving descriptor method
sl@0	1900	differs in that this operation may cause the string descriptor's heap
sl@0	1901	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1902	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1903	and any existing raw pointers to into the descriptor data may be
sl@0	1904	invalidated.
sl@0	1905
sl@0	1906	@param aVal The floating point number to be converted.
sl@0	1907	@param aFormat The format of the conversion.
sl@0	1908
sl@0	1909	@return If the conversion is successful, the length of this descriptor. If
sl@0	1910	the conversion fails, a negative value indicating the cause of failure.
sl@0	1911	In addition, extra information on the cause of the failure may be
sl@0	1912	appended onto this descriptor. The possible values and their meaning
sl@0	1913	are:
sl@0	1914
sl@0	1915	1.KErrArgument - the supplied floating point number is not a valid
sl@0	1916	number. The three characters NaN are appended to this descriptor.
sl@0	1917
sl@0	1918	2.KErrOverflow - the number is too large to represent.
sl@0	1919	2.1 For positive overflow, the three characters Inf are appended
sl@0	1920	to this descriptor.
sl@0	1921	2.2 For negative overflow, the four characters -Inf are appended
sl@0	1922	to this descriptor.
sl@0	1923
sl@0	1924	3.KErrUnderflow - the number is too small to represent.
sl@0	1925	3.1 For positive underflow, the three characters Inf are appended
sl@0	1926	to this descriptor.
sl@0	1927	3.2 For negative underflow, the four characters -Inf are appended
sl@0	1928	to this descriptor.
sl@0	1929
sl@0	1930	4.KErrGeneral - the conversion cannot be completed. There are a
sl@0	1931	number of possible reasons for this, but the most common is:
sl@0	1932	4.1 The character representation format (i.e. the format type), as
sl@0	1933	defined in the TRealFormat object is not recognised.
sl@0	1934
sl@0	1935	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1936	grown and there are insufficient resources to do so
sl@0	1937	*/
sl@0	1938	EXPORT_C TInt LString16::AppendNumL(TReal aVal,const TRealFormat& aFormat)
sl@0	1939	{
sl@0	1940	ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize);
sl@0	1941	return RBuf16::AppendNum(aVal, aFormat);
sl@0	1942	}
sl@0	1943
sl@0	1944	/**
sl@0	1945	Converts the 64-bit signed integer into a decimal character representation
sl@0	1946	and appends the conversion onto the end of this descriptor's data.
sl@0	1947
sl@0	1948	The length of this descriptor is incremented to reflect the new content.
sl@0	1949
sl@0	1950	If the integer is negative, the character representation is prefixed by a
sl@0	1951	minus sign.
sl@0	1952
sl@0	1953	This leaving variant of the standard, non-leaving descriptor method
sl@0	1954	differs in that this operation may cause the string descriptor's heap
sl@0	1955	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1956	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1957	and any existing raw pointers to into the descriptor data may be
sl@0	1958	invalidated.
sl@0	1959
sl@0	1960	@param aVal The 64-bit signed integer value.
sl@0	1961
sl@0	1962	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1963	grown and there are insufficient resources to do so
sl@0	1964	*/
sl@0	1965	EXPORT_C void LString16::AppendNumL(TInt64 aVal)
sl@0	1966	{
sl@0	1967	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1968	RBuf16::AppendNum(aVal);
sl@0	1969	}
sl@0	1970
sl@0	1971	/**
sl@0	1972	Converts the specified 64 bit integer into a character representation
sl@0	1973	based on the specified number system and appends the conversion onto the end
sl@0	1974	of this descriptor's data.
sl@0	1975
sl@0	1976	The length of this descriptor is incremented to reflect the new content.
sl@0	1977
sl@0	1978	When a hexadecimal conversion is specified, hexadecimal characters are in
sl@0	1979	lower case.
sl@0	1980
sl@0	1981	This leaving variant of the standard, non-leaving descriptor method
sl@0	1982	differs in that this operation may cause the string descriptor's heap
sl@0	1983	buffer to be reallocated in order to accommodate the new data. As a
sl@0	1984	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	1985	and any existing raw pointers to into the descriptor data may be
sl@0	1986	invalidated.
sl@0	1987
sl@0	1988	@param aVal The 64 bit integer value. This is always treated as an unsigned
sl@0	1989	value.
sl@0	1990	@param aRadix The number system representation for the 64 bit integer.
sl@0	1991
sl@0	1992	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	1993	grown and there are insufficient resources to do so
sl@0	1994	*/
sl@0	1995	EXPORT_C void LString16::AppendNumL(TUint64 aVal, TRadix aRadix)
sl@0	1996	{
sl@0	1997	ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
sl@0	1998	RBuf16::AppendNum(aVal, aRadix);
sl@0	1999	}
sl@0	2000
sl@0	2001	/**
sl@0	2002	Formats and appends text onto the end of this descriptor's data.
sl@0	2003
sl@0	2004	The length of this descriptor is incremented to reflect the new content.
sl@0	2005
sl@0	2006	The function takes a format string and a variable number of arguments.
sl@0	2007	The format string contains literal text, embedded with directives,
sl@0	2008	for converting the trailing list of arguments into text.
sl@0	2009
sl@0	2010	The embedded directives are character sequences prefixed with the '%' character.
sl@0	2011	The literal text is simply copied into this descriptor unaltered while
sl@0	2012	the '%' directives are used to convert successive arguments from the
sl@0	2013	trailing list. See the description of the Format() function.
sl@0	2014
sl@0	2015	Literal text is appended on a character by character basis, and the
sl@0	2016	underlying buffer is grown as necessary to accommodate it.
sl@0	2017
sl@0	2018	Text converted from a trailing argument is appended as a complete
sl@0	2019	string, and the underlying buffer is grown as necessary to accommodate
sl@0	2020	it.
sl@0	2021
sl@0	2022	This leaving variant of the standard, non-leaving descriptor method
sl@0	2023	differs in that this operation may cause the string descriptor's heap
sl@0	2024	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2025	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2026	and any existing raw pointers to into the descriptor data may be
sl@0	2027	invalidated.
sl@0	2028
sl@0	2029	@param aFmt The 16-bit non-modifiable descriptor containing the
sl@0	2030	format string. The TRefByValue class provides a
sl@0	2031	constructor which takes a TDesC16 type.
sl@0	2032
sl@0	2033	@param ... A variable number of arguments to be converted to text
sl@0	2034	as dictated by the format string.
sl@0	2035
sl@0	2036	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2037	grown and there are insufficient resources to do so
sl@0	2038
sl@0	2039	@panic USER 12 if the format string has incorrect syntax.
sl@0	2040
sl@0	2041	@see TDes16::Format()
sl@0	2042	@see TDes16Overflow::Overflow()
sl@0	2043	*/
sl@0	2044	EXPORT_C void LString16::AppendFormatL(TRefByValue<const TDesC16> aFmt,...)
sl@0	2045	{
sl@0	2046	VA_LIST list;
sl@0	2047	VA_START(list,aFmt);
sl@0	2048	AppendFormatListL(aFmt,list);
sl@0	2049	}
sl@0	2050
sl@0	2051	class TRetryOverflow16 : public TDes16Overflow
sl@0	2052	{
sl@0	2053	public:
sl@0	2054	TRetryOverflow16() : iOverflow(EFalse)
sl@0	2055	{
sl@0	2056	}
sl@0	2057
sl@0	2058	virtual void Overflow(TDes16& /aDes/)
sl@0	2059	{
sl@0	2060	iOverflow = ETrue;
sl@0	2061	}
sl@0	2062
sl@0	2063	TBool iOverflow;
sl@0	2064	};
sl@0	2065
sl@0	2066	/**
sl@0	2067	Formats and appends text onto the end of this descriptor's data.
sl@0	2068
sl@0	2069	The length of this descriptor is incremented to reflect the new content.
sl@0	2070
sl@0	2071	The behaviour of this function is the same as
sl@0	2072	AppendFormatL(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...).
sl@0	2073	In practice, it is better and easier to use AppendFormat(), passing a variable number of
sl@0	2074	arguments as required by the format string.
sl@0	2075
sl@0	2076	This leaving variant of the standard, non-leaving descriptor method
sl@0	2077	differs in that this operation may cause the string descriptor's heap
sl@0	2078	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2079	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2080	and any existing raw pointers to into the descriptor data may be
sl@0	2081	invalidated.
sl@0	2082
sl@0	2083	@param aFmt The descriptor containing the format string.
sl@0	2084	@param aList A pointer to an argument list.
sl@0	2085
sl@0	2086	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2087	grown and there are insufficient resources to do so
sl@0	2088
sl@0	2089	@see TDes16::AppendFormat
sl@0	2090	@see VA_LIST
sl@0	2091	*/
sl@0	2092	EXPORT_C void LString16::AppendFormatListL(const TDesC16& aFmt,VA_LIST aList)
sl@0	2093	{
sl@0	2094	ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint
sl@0	2095	for (;;)
sl@0	2096	{
sl@0	2097	TInt before = Length();
sl@0	2098	TRetryOverflow16 overflow;
sl@0	2099	RBuf16::AppendFormatList(aFmt, aList, &overflow);
sl@0	2100	if (overflow.iOverflow)
sl@0	2101	{
sl@0	2102	SetLengthL(before); // Can't leave
sl@0	2103	ReserveCapacityGrowExponentialL();
sl@0	2104	}
sl@0	2105	else
sl@0	2106	{
sl@0	2107	break;
sl@0	2108	}
sl@0	2109	}
sl@0	2110	}
sl@0	2111
sl@0	2112
sl@0	2113	/**
sl@0	2114	Unlinks and transfers ownership of the specified 16-bit resizable descriptor's
sl@0	2115	buffer to this object. The source descriptor is detached from the buffer.
sl@0	2116
sl@0	2117	@param aString The source 16-bit resizable buffer. The ownership of this
sl@0	2118	object's buffer is to be transferred.
sl@0	2119
sl@0	2120	@see RBuf16::Close()
sl@0	2121	*/
sl@0	2122	EXPORT_C void LString16::Assign(const LString16& aString)
sl@0	2123	{
sl@0	2124	// free any previously owned resource
sl@0	2125	Reset();
sl@0	2126
sl@0	2127	RBuf16::Assign(aString);
sl@0	2128	// unlink buffer from original descriptor
sl@0	2129	new (const_cast<LString16*>(&aString)) LString16();
sl@0	2130	}
sl@0	2131
sl@0	2132
sl@0	2133	/**
sl@0	2134	Transfers ownership of the specified 16-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 16-bit resizable buffer. The ownership of this
sl@0	2138	object's buffer is to be transferred.
sl@0	2139
sl@0	2140	@see RBuf16::Assign()
sl@0	2141	*/
sl@0	2142
sl@0	2143	EXPORT_C void LString16::Assign(const RBuf16& aRBuf)
sl@0	2144	{
sl@0	2145	// free any previously owned resource
sl@0	2146	Reset();
sl@0	2147
sl@0	2148	RBuf16::Assign(aRBuf);
sl@0	2149
sl@0	2150	// reset the RBuf;
sl@0	2151	new (const_cast<RBuf16*>(&aRBuf)) RBuf16();
sl@0	2152	}
sl@0	2153
sl@0	2154
sl@0	2155	/**
sl@0	2156	Transfers ownership of the specified 16-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 RBuf16::Assign()
sl@0	2162	*/
sl@0	2163	EXPORT_C void LString16::Assign(HBufC16* aHBuf)
sl@0	2164	{
sl@0	2165	// free any previously owned resource
sl@0	2166	Reset();
sl@0	2167
sl@0	2168	RBuf16::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	16-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 RBuf16::Close()
sl@0	2186	@see RBuf16::Assign()
sl@0	2187	*/
sl@0	2188	EXPORT_C void LString16::Assign(TUint16* aHeapCell, TInt aMaxLength)
sl@0	2189	{
sl@0	2190	// free any previously owned resource
sl@0	2191	Reset();
sl@0	2192
sl@0	2193	RBuf16::Assign(aHeapCell, aMaxLength);
sl@0	2194	}
sl@0	2195
sl@0	2196
sl@0	2197	/**
sl@0	2198	Transfers ownership of the specified 16-bit resizable descriptor's this object.
sl@0	2199
sl@0	2200	@param aHeapCell The allocated memory to be assigned to this object.
sl@0	2201
sl@0	2202	@param aLength The length of the descriptor.
sl@0	2203
sl@0	2204	@param aMaxLength The maximum length of the descriptor.
sl@0	2205
sl@0	2206	@panic USER 8 If the specified maximum length is greater then the size of the
sl@0	2207	allocated heap cell, or the specified length is greater then
sl@0	2208	the specified maximum length, or the specified maximum length
sl@0	2209	is NOT zero when the pointer to the heap cell is NULL.
sl@0	2210
sl@0	2211	@see RBuf16::Close()
sl@0	2212	@see RBuf16::Assign()
sl@0	2213	*/
sl@0	2214	EXPORT_C void LString16::Assign(TUint16* aHeapCell,TInt aLength,TInt aMaxLength)
sl@0	2215	{
sl@0	2216	// free any previously owned resource
sl@0	2217	Reset();
sl@0	2218
sl@0	2219	RBuf16::Assign(aHeapCell, aLength, aMaxLength);
sl@0	2220	}
sl@0	2221
sl@0	2222	/**
sl@0	2223	Creates a 16-bit resizable buffer descriptor that has been initialised with
sl@0	2224	data from the specified read stream; leaves on failure.
sl@0	2225
sl@0	2226	Data is assigned to the new descriptor from the specified stream.
sl@0	2227	This variant assumes that the stream contains the length of the data followed
sl@0	2228	by the data itself.
sl@0	2229
sl@0	2230	The function is implemented by calling the HBufC16::NewL(RReadStream&,TInt)
sl@0	2231	variant and then assigning the resulting heap descriptor using
sl@0	2232	the RBuf16::Assign(HBufC16*) variant. The comments that describe
sl@0	2233	the HBufC16::NewL() variant also apply to this RBuf16::CreateL() function.
sl@0	2234
sl@0	2235	The function may leave with one of the system-wide error codes, specifically
sl@0	2236	KErrOverflow, if the length of the data as read from the stream is greater than
sl@0	2237	the upper limit as specified by the aMaxLength parameter.
sl@0	2238
sl@0	2239	@param aStream The stream from which the data length and the data to be
sl@0	2240	assigned to the new descriptor, are taken.
sl@0	2241	@param aMaxLength The upper limit on the length of data that the descriptor is
sl@0	2242	to represent. The value of this parameter must be non-negative
sl@0	2243	otherwise the underlying function will panic.
sl@0	2244	*/
sl@0	2245	EXPORT_C void LString16::CreateL(RReadStream &aStream,TInt aMaxLength)
sl@0	2246	{
sl@0	2247	Reset();
sl@0	2248	Assign(HBufC16::NewL(aStream,aMaxLength));
sl@0	2249	}
sl@0	2250
sl@0	2251	/**
sl@0	2252	Appends data onto the end of this descriptor's data.
sl@0	2253
sl@0	2254	The length of this descriptor is incremented to reflect the new content.
sl@0	2255
sl@0	2256	This leaving variant of the standard, non-leaving descriptor method
sl@0	2257	differs in that this operation may cause the string descriptor's heap
sl@0	2258	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2259	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2260	and any existing raw pointers to into the descriptor data may be
sl@0	2261	invalidated.
sl@0	2262
sl@0	2263	@param aZeroTerminatedString A pointer to a zero terminated string .
sl@0	2264	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2265	grown and there are insufficient resources to do so
sl@0	2266
sl@0	2267	@see LString16::AppendL
sl@0	2268	*/
sl@0	2269	EXPORT_C LString16& LString16::operator+=(const TUint16* aZeroTerminatedString)
sl@0	2270	{
sl@0	2271	AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
sl@0	2272	return *this;
sl@0	2273	}
sl@0	2274	/**
sl@0	2275	Appends data onto the end of this descriptor's data.
sl@0	2276
sl@0	2277	The length of this descriptor is incremented to reflect the new content.
sl@0	2278
sl@0	2279	This leaving variant of the standard, non-leaving descriptor method
sl@0	2280	differs in that this operation may cause the string descriptor's heap
sl@0	2281	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2282	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2283	and any existing raw pointers to into the descriptor data may be
sl@0	2284	invalidated.
sl@0	2285
sl@0	2286	@param aZeroTerminatedString A pointer to the data to be copied.
sl@0	2287
sl@0	2288	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2289	grown and there are insufficient resources to do so
sl@0	2290
sl@0	2291	@panic USER 17 if aLength is negative.
sl@0	2292	*/
sl@0	2293	EXPORT_C void LString16::AppendL(const TUint16* aZeroTerminatedString)
sl@0	2294	{
sl@0	2295	AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
sl@0	2296	}
sl@0	2297
sl@0	2298	/**
sl@0	2299	Constructor to create a 16-bit resizable string descriptor containing
sl@0	2300	a copy of the specified (source) zero-terminated wide character string data, or leave
sl@0	2301	on failure.
sl@0	2302
sl@0	2303	The constructor allocates sufficient memory so that this string
sl@0	2304	descriptor's maximum length is the same as the length of the source
sl@0	2305	string. Both the current length and the maximum length of this string
sl@0	2306	descriptor are set to the length of the source string.
sl@0	2307
sl@0	2308	The data contained in the source string is copied into this string
sl@0	2309	descriptor. The zero terminator is not copied.
sl@0	2310
sl@0	2311	@param aWideCharStr A pointer to a zero-terminated wide character string
sl@0	2312
sl@0	2313	@leave KErrNoMemory If there is insufficient memory.
sl@0	2314
sl@0	2315	@see LString16::CopyL
sl@0	2316	*/
sl@0	2317	EXPORT_C LString16::LString16(const wchar_t* aWideCharStr)
sl@0	2318	: iReserved(0)
sl@0	2319	{
sl@0	2320	CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2321	}
sl@0	2322
sl@0	2323	/**
sl@0	2324	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	2325	data, and expanding its heap buffer to accommodate if necessary.
sl@0	2326
sl@0	2327	The length of this descriptor is set to reflect the new data.
sl@0	2328
sl@0	2329	This operation may cause the target string descriptor's heap buffer to
sl@0	2330	be reallocated in order to accommodate the new data. As a result,
sl@0	2331	MaxLength() and Ptr() may return different values afterwards, and any
sl@0	2332	existing raw pointers to into the descriptor data may be invalidated.
sl@0	2333
sl@0	2334	Note that the automatic resizing performed is a change to the
sl@0	2335	functionality of this operation compared to other descriptor
sl@0	2336	classes. This change is only active on objects directly declared
sl@0	2337	LString16; when LString16 instances are instead manipulated via
sl@0	2338	references to TDes16 or TDesC16, the standard (non-resizing, panicing)
sl@0	2339	variant is invoked.
sl@0	2340
sl@0	2341	@param aWideCharStr A pointer to a wide character zero-terminated string
sl@0	2342
sl@0	2343	@return A reference to this 16-bit string descriptor.
sl@0	2344
sl@0	2345	@leave KErrNoMemory If the heap buffer of the string descriptor being
sl@0	2346	assigned to needs to be expanded, but there is
sl@0	2347	insufficient memory to do so
sl@0	2348
sl@0	2349	@see LString16::CopyL
sl@0	2350	*/
sl@0	2351	EXPORT_C LString16& LString16::operator=(const wchar_t* aWideCharStr)
sl@0	2352	{
sl@0	2353	CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2354	return *this;
sl@0	2355	}
sl@0	2356
sl@0	2357	/**
sl@0	2358	Appends data onto the end of this descriptor's data.
sl@0	2359
sl@0	2360	The length of this descriptor is incremented to reflect the new content.
sl@0	2361
sl@0	2362	This leaving variant of the standard, non-leaving descriptor method
sl@0	2363	differs in that this operation may cause the string descriptor's heap
sl@0	2364	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2365	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2366	and any existing raw pointers to into the descriptor data may be
sl@0	2367	invalidated.
sl@0	2368
sl@0	2369	@param aWideCharStr A pointer to a wide character zero terminated string .
sl@0	2370	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2371	grown and there are insufficient resources to do so
sl@0	2372
sl@0	2373	@see LString16::AppendL
sl@0	2374	*/
sl@0	2375	EXPORT_C LString16& LString16::operator+=(const wchar_t* aWideCharStr)
sl@0	2376	{
sl@0	2377	AppendL(reinterpret_cast<const TUint16>(aWideCharStr),User::StringLength(reinterpret_cast<const TUint16>(aWideCharStr)));
sl@0	2378	return *this;
sl@0	2379	}
sl@0	2380
sl@0	2381	/**
sl@0	2382	Copies data into this 16-bit string descriptor, replacing any existing
sl@0	2383	data, and expanding its heap buffer to accommodate if necessary.
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 aWideCharStr A pointer to a wide 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 TDes16::Copy
sl@0	2402	*/
sl@0	2403	EXPORT_C void LString16::CopyL(const wchar_t* aWideCharStr)
sl@0	2404	{
sl@0	2405	CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
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 aWideCharStr 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 LString16::AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	2449	{
sl@0	2450	AppendJustifyL(reinterpret_cast<const TUint16*>( aWideCharStr),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 aWideCharStr 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 LString16::AppendL(const wchar_t* aWideCharStr,TInt aLength)
sl@0	2474	{
sl@0	2475	AppendL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength);
sl@0	2476	}
sl@0	2477	/**
sl@0	2478	Appends data onto the end of this descriptor's data.
sl@0	2479
sl@0	2480	The length of this descriptor is incremented to reflect the new content.
sl@0	2481
sl@0	2482	This leaving variant of the standard, non-leaving descriptor method
sl@0	2483	differs in that this operation may cause the string descriptor's heap
sl@0	2484	buffer to be reallocated in order to accommodate the new data. As a
sl@0	2485	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	2486	and any existing raw pointers to into the descriptor data may be
sl@0	2487	invalidated.
sl@0	2488
sl@0	2489	@param aWideCharStr A pointer to the data to be copied.
sl@0	2490
sl@0	2491	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	2492	grown and there are insufficient resources to do so
sl@0	2493
sl@0	2494	@panic USER 17 if aLength is negative.
sl@0	2495	*/
sl@0	2496	EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr)
sl@0	2497	{
sl@0	2498	AppendL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2499	}
sl@0	2500	/**
sl@0	2501	Determines whether this Descriptor's data is equal to the specified
sl@0	2502	string's data.
sl@0	2503
sl@0	2504	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2505
sl@0	2506	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2507	with this Descriptor's data.
sl@0	2508
sl@0	2509	@return True if equal, false otherwise.
sl@0	2510
sl@0	2511	@see TDesC::Compare
sl@0	2512	*/
sl@0	2513	EXPORT_C TBool LString16::operator==( const wchar_t* aWideCharStr) const
sl@0	2514	{
sl@0	2515	return LString16::operator==(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2516	}
sl@0	2517
sl@0	2518	/**
sl@0	2519	Determines whether this Descriptor's data is equal to the specified
sl@0	2520	string's data.
sl@0	2521
sl@0	2522	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2523
sl@0	2524	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2525	is to be compared with this Descriptor's data.
sl@0	2526
sl@0	2527	@return True if equal, false otherwise.
sl@0	2528
sl@0	2529	@see TDesC::Compare
sl@0	2530	*/
sl@0	2531	EXPORT_C TBool LString16::operator==( const TUint16* aZeroTerminatedString) const
sl@0	2532	{
sl@0	2533	return RBuf16::operator==(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2534	}
sl@0	2535
sl@0	2536	/**
sl@0	2537	Determines whether this descriptor's data is less than the specified
sl@0	2538	strings's data.
sl@0	2539
sl@0	2540	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2541
sl@0	2542	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2543	with this Descriptor's data.
sl@0	2544
sl@0	2545	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2546
sl@0	2547	@see TDesC::Compare
sl@0	2548	*/
sl@0	2549	EXPORT_C TBool LString16::operator<( const wchar_t* aWideCharStr) const
sl@0	2550	{
sl@0	2551	return LString16::operator<(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2552	}
sl@0	2553
sl@0	2554	/**
sl@0	2555	Determines whether this descriptor's data is less than the specified
sl@0	2556	strings's data.
sl@0	2557
sl@0	2558	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2559
sl@0	2560	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2561	is to be compared with this Descriptor's data.
sl@0	2562
sl@0	2563	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2564
sl@0	2565	@see TDesC::Compare
sl@0	2566	*/
sl@0	2567	EXPORT_C TBool LString16::operator<(const TUint16* aZeroTerminatedString) const
sl@0	2568	{
sl@0	2569	return RBuf16::operator<(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2570	}
sl@0	2571
sl@0	2572	/**
sl@0	2573	Determines whether this descriptor's data is less than the specified
sl@0	2574	strings's data.
sl@0	2575
sl@0	2576	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2577
sl@0	2578	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2579	with this Descriptor's data.
sl@0	2580
sl@0	2581	@return True if this descriptor's data is less than that of the specified string's data
sl@0	2582
sl@0	2583	@see TDesC::Compare
sl@0	2584	*/
sl@0	2585	EXPORT_C TBool LString16::operator<=( const wchar_t* aWideCharStr) const
sl@0	2586	{
sl@0	2587	return LString16::operator<=(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2588	}
sl@0	2589
sl@0	2590	/**
sl@0	2591	Determines whether this descriptor's data is less than/equal to the specified
sl@0	2592	strings's data.
sl@0	2593
sl@0	2594	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2595
sl@0	2596	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2597	is to be compared with this Descriptor's data.
sl@0	2598
sl@0	2599	@return True if this descriptor's data is less than/equal to that of the specified string's data
sl@0	2600
sl@0	2601	@see TDesC::Compare
sl@0	2602	*/
sl@0	2603	EXPORT_C TBool LString16::operator<=(const TUint16* aZeroTerminatedString) const
sl@0	2604	{
sl@0	2605	return RBuf16::operator<=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2606	}
sl@0	2607
sl@0	2608	/**
sl@0	2609	Determines whether this descriptor's data is greater than the specified
sl@0	2610	strings's data.
sl@0	2611
sl@0	2612	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2613
sl@0	2614	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2615	with this Descriptor's data.
sl@0	2616
sl@0	2617	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2618
sl@0	2619	@see TDesC::Compare
sl@0	2620	*/
sl@0	2621	EXPORT_C TBool LString16::operator>( const wchar_t* aWideCharStr) const
sl@0	2622	{
sl@0	2623	return LString16::operator>(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2624	}
sl@0	2625
sl@0	2626	/**
sl@0	2627	Determines whether this descriptor's data is greater than the specified
sl@0	2628	strings's data.
sl@0	2629
sl@0	2630	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2631
sl@0	2632	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2633	is to be compared with this Descriptor's data.
sl@0	2634
sl@0	2635	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2636
sl@0	2637	@see TDesC::Compare
sl@0	2638	*/
sl@0	2639	EXPORT_C TBool LString16::operator>(const TUint16* aZeroTerminatedString) const
sl@0	2640	{
sl@0	2641	return RBuf16::operator>(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2642	}
sl@0	2643
sl@0	2644	/**
sl@0	2645	Determines whether this descriptor's data is greater than/equal to the specified
sl@0	2646	strings's data.
sl@0	2647
sl@0	2648	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2649
sl@0	2650	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2651	with this Descriptor's data.
sl@0	2652
sl@0	2653	@return True if this descriptor's data is greater than/equal to that of the specified string's data
sl@0	2654
sl@0	2655	@see TDesC::Compare
sl@0	2656	*/
sl@0	2657	EXPORT_C TBool LString16::operator>=( const wchar_t* aWideCharStr) const
sl@0	2658	{
sl@0	2659	return LString16::operator>=(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2660	}
sl@0	2661
sl@0	2662	/**
sl@0	2663	Determines whether this descriptor's data is greater than the specified
sl@0	2664	strings's data.
sl@0	2665
sl@0	2666	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2667
sl@0	2668	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2669	is to be compared with this Descriptor's data.
sl@0	2670
sl@0	2671	@return True if this descriptor's data is greater than that of the specified string's data
sl@0	2672
sl@0	2673	@see TDesC::Compare
sl@0	2674	*/
sl@0	2675	EXPORT_C TBool LString16::operator>=(const TUint16* aZeroTerminatedString) const
sl@0	2676	{
sl@0	2677	return RBuf16::operator>=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2678	}
sl@0	2679
sl@0	2680	/**
sl@0	2681	Determines whether this descriptor's data is not equal to the specified
sl@0	2682	strings's data.
sl@0	2683
sl@0	2684	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2685
sl@0	2686	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2687	with this Descriptor's data.
sl@0	2688
sl@0	2689	@return True if this descriptor's data is not equal to the specified string's data
sl@0	2690
sl@0	2691	@see TDesC::Compare
sl@0	2692	*/
sl@0	2693	EXPORT_C TBool LString16::operator!=( const wchar_t* aWideCharStr) const
sl@0	2694	{
sl@0	2695	return LString16::operator!=(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2696	}
sl@0	2697
sl@0	2698	/**
sl@0	2699	Determines whether this descriptor's data is not equal to the specified
sl@0	2700	strings's data.
sl@0	2701
sl@0	2702	The comparison is implemented internally using the TDesC::Compare() function.
sl@0	2703
sl@0	2704	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2705	is to be compared with this Descriptor's data.
sl@0	2706
sl@0	2707	@return True if this descriptor's data is not equal to the specified string's data
sl@0	2708
sl@0	2709	@see TDesC::Compare
sl@0	2710	*/
sl@0	2711	EXPORT_C TBool LString16::operator!=(const TUint16* aZeroTerminatedString) const
sl@0	2712	{
sl@0	2713	return RBuf16::operator!=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2714	}
sl@0	2715
sl@0	2716	/**
sl@0	2717	Searches this descriptor's data for a match with the match pattern supplied
sl@0	2718	in the specified string.
sl@0	2719
sl@0	2720	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2721	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2722	a single occurrence of any character.
sl@0	2723
sl@0	2724	Note that there is no 'escape character', which means that it is not possible
sl@0	2725	to match either the "*" character itself or the "?" character itself using
sl@0	2726	this function.
sl@0	2727
sl@0	2728	@param aWideCharStr The wide character string whose data is to be matched
sl@0	2729	with this Descriptor's data.
sl@0	2730
sl@0	2731	@return If a match is found, the offset within this descriptor's data where
sl@0	2732	the match first occurs. KErrNotFound, if there is no match.
sl@0	2733	*/
sl@0	2734	EXPORT_C TInt LString16::Match(const wchar_t* aWideCharStr) const
sl@0	2735	{
sl@0	2736	return LString16::Match(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2737	}
sl@0	2738
sl@0	2739	/**
sl@0	2740	Searches this descriptor's data for a match with the match pattern supplied
sl@0	2741	in the specified string.
sl@0	2742
sl@0	2743	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2744	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2745	a single occurrence of any character.
sl@0	2746
sl@0	2747	Note that there is no 'escape character', which means that it is not possible
sl@0	2748	to match either the "*" character itself or the "?" character itself using
sl@0	2749	this function.
sl@0	2750
sl@0	2751	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2752	is to be matched with this Descriptor's data.
sl@0	2753
sl@0	2754	@return If a match is found, the offset within this descriptor's data where
sl@0	2755	the match first occurs. KErrNotFound, if there is no match.
sl@0	2756	*/
sl@0	2757	EXPORT_C TInt LString16::Match(const TUint16* aZeroTerminatedString) const
sl@0	2758	{
sl@0	2759	return RBuf16::Match(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2760	}
sl@0	2761	/**
sl@0	2762	Searches this descriptor's folded data for a match with the folded match
sl@0	2763	pattern supplied in the specified string.
sl@0	2764
sl@0	2765	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2766	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2767	a single occurrence of any character.
sl@0	2768
sl@0	2769	Note that folding is locale-independent behaviour. It is also important to
sl@0	2770	note that there can be no guarantee that folding is in any way culturally
sl@0	2771	appropriate, and should not be used for matching strings in natural language;
sl@0	2772	use MatchC() for this.
sl@0	2773
sl@0	2774	Note that there is no 'escape character', which means that it is not possible
sl@0	2775	to match either the "*" character itself or the "?" character itself using
sl@0	2776	this function.
sl@0	2777
sl@0	2778	@param aWideCharStr The wide character string whose data is to be matched
sl@0	2779	with this Descriptor's data.
sl@0	2780
sl@0	2781	@return If a match is found, the offset within this descriptor's data where
sl@0	2782	the match first occurs. KErrNotFound, if there is no match.
sl@0	2783
sl@0	2784	@see TDesC::MatchC()
sl@0	2785	*/
sl@0	2786	EXPORT_C TInt LString16::MatchF(const wchar_t* aWideCharStr) const
sl@0	2787	{
sl@0	2788	return LString16::MatchF(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2789	}
sl@0	2790	/**
sl@0	2791	Searches this descriptor's folded data for a match with the folded match
sl@0	2792	pattern supplied in the specified string.
sl@0	2793
sl@0	2794	The match pattern can contain the wildcard characters "" and "?", where ""
sl@0	2795	matches zero or more consecutive occurrences of any character and "?" matches
sl@0	2796	a single occurrence of any character.
sl@0	2797
sl@0	2798	Note that folding is locale-independent behaviour. It is also important to
sl@0	2799	note that there can be no guarantee that folding is in any way culturally
sl@0	2800	appropriate, and should not be used for matching strings in natural language;
sl@0	2801	use MatchC() for this.
sl@0	2802
sl@0	2803	Note that there is no 'escape character', which means that it is not possible
sl@0	2804	to match either the "*" character itself or the "?" character itself using
sl@0	2805	this function.
sl@0	2806
sl@0	2807	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2808	is to be matched with this Descriptor's data.
sl@0	2809
sl@0	2810	@return If a match is found, the offset within this descriptor's data where
sl@0	2811	the match first occurs. KErrNotFound, if there is no match.
sl@0	2812
sl@0	2813	@see TDesC::MatchC()
sl@0	2814	*/
sl@0	2815	EXPORT_C TInt LString16::MatchF(const TUint16* aZeroTerminatedString) const
sl@0	2816	{
sl@0	2817	return RBuf16::MatchF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2818	}
sl@0	2819	/**
sl@0	2820	Compares this descriptor's data with the specified string's data.
sl@0	2821
sl@0	2822	The comparison proceeds on a byte for byte basis. The result of the comparison
sl@0	2823	is based on the difference of the first bytes to disagree.
sl@0	2824
sl@0	2825	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2826	with this Descriptor's data.
sl@0	2827
sl@0	2828	@return Positive, if this descriptor is greater than the specified string.
sl@0	2829	Negative, if this descriptor is less than the specified string.
sl@0	2830	Zero, if both the descriptor and the string have the same length
sl@0	2831	and the their contents are the same.
sl@0	2832	*/
sl@0	2833	EXPORT_C TInt LString16::Compare(const wchar_t* aWideCharStr) const
sl@0	2834	{
sl@0	2835	return LString16::Compare(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2836	}
sl@0	2837
sl@0	2838	/**
sl@0	2839	Compares this descriptor's data with the specified string's data.
sl@0	2840
sl@0	2841	The comparison proceeds on a byte for byte basis. The result of the comparison
sl@0	2842	is based on the difference of the first bytes to disagree.
sl@0	2843
sl@0	2844	@param aZeroTerminatedString The wide Zero TerminatedString string whose data
sl@0	2845	is to be compared with this Descriptor's data.
sl@0	2846
sl@0	2847	@return Positive, if this descriptor is greater than the specified string.
sl@0	2848	Negative, if this descriptor is less than the specified string.
sl@0	2849	Zero, if both the descriptor and the string have the same length
sl@0	2850	and the their contents are the same.
sl@0	2851	*/
sl@0	2852	EXPORT_C TInt LString16::Compare(const TUint16* aZeroTerminatedString) const
sl@0	2853	{
sl@0	2854	return RBuf16::Compare(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2855	}
sl@0	2856	/**
sl@0	2857	Compares this descriptor's folded data with the specified string's folded
sl@0	2858	data.
sl@0	2859
sl@0	2860	Note that folding is locale-independent behaviour. It is also important to
sl@0	2861	note that there can be no guarantee that folding is in any way culturally
sl@0	2862	appropriate, and should not be used for comparing strings in natural language;
sl@0	2863
sl@0	2864	@param aWideCharStr The wide character string whose data is to be compared
sl@0	2865	with this Descriptor's data.
sl@0	2866
sl@0	2867	@return Positive, if this descriptor is greater than the specified string.
sl@0	2868	Negative, if this descriptor is less than the specified string.
sl@0	2869	Zero, if the descriptor and the specified string have the same length
sl@0	2870	and the their contents are the same.
sl@0	2871
sl@0	2872	@see TDesC::Compare()
sl@0	2873	*/
sl@0	2874	EXPORT_C TInt LString16::CompareF(const wchar_t* aWideCharStr) const
sl@0	2875	{
sl@0	2876	return LString16::CompareF(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2877	}
sl@0	2878
sl@0	2879	/**
sl@0	2880	Compares this descriptor's folded data with the specified string's folded
sl@0	2881	data.
sl@0	2882
sl@0	2883	Note that folding is locale-independent behaviour. It is also important to
sl@0	2884	note that there can be no guarantee that folding is in any way culturally
sl@0	2885	appropriate, and should not be used for comparing strings in natural language;
sl@0	2886
sl@0	2887	@param aZeroTerminatedString The wide Zero Terminated String whose data
sl@0	2888	is to be compared with this string's data.
sl@0	2889
sl@0	2890	@return Positive, if this descriptor is greater than the specified string.
sl@0	2891	Negative, if this descriptor is less than the specified string.
sl@0	2892	Zero, if the descriptor and the specified string have the same length
sl@0	2893	and the their contents are the same.
sl@0	2894
sl@0	2895	@see TDesC::Compare()
sl@0	2896	*/
sl@0	2897	EXPORT_C TInt LString16::CompareF(const TUint16* aZeroTerminatedString) const
sl@0	2898	{
sl@0	2899	return RBuf16::CompareF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2900	}
sl@0	2901
sl@0	2902	/**
sl@0	2903	Searches for the first occurrence of the specified data sequence within this
sl@0	2904	descriptor.
sl@0	2905
sl@0	2906	Searching always starts at the beginning of this descriptor's data.
sl@0	2907
sl@0	2908	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	2909	within this Descriptor's data.
sl@0	2910
sl@0	2911	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2912	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2913	*/
sl@0	2914	EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr) const
sl@0	2915	{
sl@0	2916	return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2917	}
sl@0	2918
sl@0	2919	/**
sl@0	2920	Searches for the first occurrence of the specified data sequence within this
sl@0	2921	descriptor.
sl@0	2922
sl@0	2923	Searching always starts at the beginning of this descriptor's data.
sl@0	2924
sl@0	2925	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	2926	within this Descriptor's data.
sl@0	2927
sl@0	2928	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2929	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2930	*/
sl@0	2931	EXPORT_C TInt LString16::Find(const TUint16* aZeroTerminatedString) const
sl@0	2932	{
sl@0	2933	return RBuf16::Find(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	2934	}
sl@0	2935
sl@0	2936	/**
sl@0	2937	Searches for the first occurrence of the specified data sequence within this
sl@0	2938	descriptor.
sl@0	2939
sl@0	2940	Searching always starts at the beginning of this descriptor's data.
sl@0	2941
sl@0	2942	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	2943	within this Descriptor's data.
sl@0	2944	@param aLenS The length of the data sequence to be searched for. This value
sl@0	2945	must not be negative, otherwise the function raises a panic.
sl@0	2946
sl@0	2947	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2948	data. KErrNotFound, if the data sequence cannot be found.
sl@0	2949
sl@0	2950	@panic USER 29 if aLenS is negative.
sl@0	2951	*/
sl@0	2952	EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr,TInt aLenS) const
sl@0	2953	{
sl@0	2954	return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr), aLenS);
sl@0	2955	}
sl@0	2956
sl@0	2957	/**
sl@0	2958	Searches for the first occurrence of the specified folded data sequence within
sl@0	2959	this descriptor's folded data.
sl@0	2960
sl@0	2961	Searching always starts at the beginning of this descriptor's data.
sl@0	2962
sl@0	2963	Note that folding is locale-independent behaviour. It is also important to
sl@0	2964	note that there can be no guarantee that folding is in any way culturally
sl@0	2965	appropriate, and should not be used for finding strings in natural language;
sl@0	2966
sl@0	2967	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	2968	within this Descriptor's data.
sl@0	2969
sl@0	2970	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2971	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	2972	length of the search data sequence is zero.
sl@0	2973
sl@0	2974	*/
sl@0	2975	EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr) const
sl@0	2976	{
sl@0	2977	return LString16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	2978	}
sl@0	2979
sl@0	2980	/**
sl@0	2981	Searches for the first occurrence of the specified folded data sequence within
sl@0	2982	this descriptor's folded data.
sl@0	2983
sl@0	2984	Searching always starts at the beginning of this descriptor's data.
sl@0	2985
sl@0	2986	Note that folding is locale-independent behaviour. It is also important to
sl@0	2987	note that there can be no guarantee that folding is in any way culturally
sl@0	2988	appropriate, and should not be used for finding strings in natural language;
sl@0	2989
sl@0	2990	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	2991	within this Descriptor's data.
sl@0	2992
sl@0	2993	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	2994	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	2995	length of the search data sequence is zero.
sl@0	2996
sl@0	2997	*/
sl@0	2998	EXPORT_C TInt LString16::FindF(const TUint16* aZeroTerminatedString) const
sl@0	2999	{
sl@0	3000	return RBuf16::FindF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3001	}
sl@0	3002	/**
sl@0	3003	Searches for the first occurrence of the specified folded data sequence within
sl@0	3004	this descriptor's folded data.
sl@0	3005
sl@0	3006	Searching always starts at the beginning of this descriptor's data.
sl@0	3007
sl@0	3008	Note that folding is locale-independent behaviour. It is also important to
sl@0	3009	note that there can be no guarantee that folding is in any way culturally
sl@0	3010	appropriate, and should not be used for finding strings in natural language;
sl@0	3011
sl@0	3012	@param aWideCharStr The wide character string whose data is to be searched for,
sl@0	3013	within this Descriptor's data.
sl@0	3014	@param aLenS The length of the data sequence to be searched for. This value
sl@0	3015	must not be negative, otherwise the function raises a panic.
sl@0	3016
sl@0	3017	@return The offset of the data sequence from the beginning of this descriptor's
sl@0	3018	data. KErrNotFound, if the data sequence cannot be found. Zero, if the
sl@0	3019	length of the search data sequence is zero.
sl@0	3020
sl@0	3021	@panic USER 29 if aLenS is negative
sl@0	3022
sl@0	3023	*/
sl@0	3024	EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr, TInt aLen) const
sl@0	3025	{
sl@0	3026	return RBuf16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr),aLen);
sl@0	3027	}
sl@0	3028
sl@0	3029	/**
sl@0	3030	Copies and folds data from the specified string into this descriptor replacing
sl@0	3031	any existing data.
sl@0	3032
sl@0	3033	The length of this descriptor is set to reflect the new
sl@0	3034	data.
sl@0	3035
sl@0	3036	Note that folding is locale-independent behaviour. It is also important to
sl@0	3037	note that there can be no guarantee that folding is in any way culturally
sl@0	3038	appropriate, and should not be used when dealing with strings in natural
sl@0	3039	language.
sl@0	3040
sl@0	3041	This leaving variant of the standard, non-leaving descriptor method
sl@0	3042	differs in that this operation may cause the string descriptor's heap
sl@0	3043	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3044	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3045	and any existing raw pointers to into the descriptor data may be
sl@0	3046	invalidated.
sl@0	3047
sl@0	3048	@param aWideCharStr A wide character string
sl@0	3049
sl@0	3050	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3051	grown and there are insufficient resources to do so
sl@0	3052	*/
sl@0	3053	EXPORT_C void LString16:: CopyFL(const wchar_t* aWideCharStr )
sl@0	3054	{
sl@0	3055	LString16::CopyFL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3056	}
sl@0	3057
sl@0	3058	/**
sl@0	3059	Copies and folds data from the specified string into this descriptor replacing
sl@0	3060	any existing data.
sl@0	3061
sl@0	3062	The length of this descriptor is set to reflect the new
sl@0	3063	data.
sl@0	3064
sl@0	3065	Note that folding is locale-independent behaviour. It is also important to
sl@0	3066	note that there can be no guarantee that folding is in any way culturally
sl@0	3067	appropriate, and should not be used when dealing with strings in natural
sl@0	3068	language.
sl@0	3069
sl@0	3070	This leaving variant of the standard, non-leaving descriptor method
sl@0	3071	differs in that this operation may cause the string descriptor's heap
sl@0	3072	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3073	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3074	and any existing raw pointers to into the descriptor data may be
sl@0	3075	invalidated.
sl@0	3076
sl@0	3077	@param aZeroTerminatedString A wide zero terminated string
sl@0	3078
sl@0	3079	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3080	grown and there are insufficient resources to do so
sl@0	3081	*/
sl@0	3082	EXPORT_C void LString16:: CopyFL(const TUint16* aZeroTerminatedString )
sl@0	3083	{
sl@0	3084	LString16::CopyFL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3085	}
sl@0	3086
sl@0	3087	/**
sl@0	3088	Copies text from the specified string and converts it to lower case before
sl@0	3089	putting it into this descriptor, replacing any existing data.
sl@0	3090
sl@0	3091	The length of this descriptor is set to reflect the new data.
sl@0	3092
sl@0	3093	Conversion to lower case is implemented as appropriate to the current locale.
sl@0	3094
sl@0	3095	This leaving variant of the standard, non-leaving descriptor method
sl@0	3096	differs in that this operation may cause the string descriptor's heap
sl@0	3097	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3098	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3099	and any existing raw pointers to into the descriptor data may be
sl@0	3100	invalidated.
sl@0	3101
sl@0	3102	@param aWideCharStr A wide character string.
sl@0	3103
sl@0	3104	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3105	grown and there are insufficient resources to do so
sl@0	3106	*/
sl@0	3107	EXPORT_C void LString16:: CopyLCL(const wchar_t* aWideCharStr)
sl@0	3108	{
sl@0	3109	LString16::CopyLCL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3110	}
sl@0	3111
sl@0	3112	/**
sl@0	3113	Copies text from the specified string and converts it to lower case before
sl@0	3114	putting it into this descriptor, replacing any existing data.
sl@0	3115
sl@0	3116	The length of this descriptor is set to reflect the new data.
sl@0	3117
sl@0	3118	Conversion to lower case is implemented as appropriate to the current locale.
sl@0	3119
sl@0	3120	This leaving variant of the standard, non-leaving descriptor method
sl@0	3121	differs in that this operation may cause the string descriptor's heap
sl@0	3122	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3123	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3124	and any existing raw pointers to into the descriptor data may be
sl@0	3125	invalidated.
sl@0	3126
sl@0	3127	@param aZeroTerminatedString A wide zero terminated string.
sl@0	3128
sl@0	3129	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3130	grown and there are insufficient resources to do so
sl@0	3131	*/
sl@0	3132	EXPORT_C void LString16:: CopyLCL(const TUint16* aZeroTerminatedString)
sl@0	3133	{
sl@0	3134	LString16::CopyLCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3135	}
sl@0	3136
sl@0	3137	/**
sl@0	3138	Copies text from the specified string and converts it to upper case before
sl@0	3139	putting it into this descriptor, replacing any existing data.
sl@0	3140
sl@0	3141	The length of this descriptor is set to reflect the new data.
sl@0	3142
sl@0	3143	Conversion to upper case is implemented as appropriate to the current locale.
sl@0	3144
sl@0	3145	This leaving variant of the standard, non-leaving descriptor method
sl@0	3146	differs in that this operation may cause the string descriptor's heap
sl@0	3147	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3148	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3149	and any existing raw pointers to into the descriptor data may be
sl@0	3150	invalidated.
sl@0	3151
sl@0	3152	@param aWideCharStr A wide character string.
sl@0	3153
sl@0	3154	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3155	grown and there are insufficient resources to do so
sl@0	3156	*/
sl@0	3157	EXPORT_C void LString16:: CopyUCL(const wchar_t* aWideCharStr)
sl@0	3158	{
sl@0	3159	LString16::CopyUCL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3160	}
sl@0	3161
sl@0	3162	/**
sl@0	3163	Copies text from the specified string and converts it to upper case before
sl@0	3164	putting it into this descriptor, replacing any existing data.
sl@0	3165
sl@0	3166	The length of this descriptor is set to reflect the new data.
sl@0	3167
sl@0	3168	Conversion to upper case is implemented as appropriate to the current locale.
sl@0	3169
sl@0	3170	This leaving variant of the standard, non-leaving descriptor method
sl@0	3171	differs in that this operation may cause the string descriptor's heap
sl@0	3172	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3173	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3174	and any existing raw pointers to into the descriptor data may be
sl@0	3175	invalidated.
sl@0	3176
sl@0	3177	@param aZeroTerminatedString A wide zero terminated string.
sl@0	3178
sl@0	3179	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3180	grown and there are insufficient resources to do so
sl@0	3181	*/
sl@0	3182	EXPORT_C void LString16:: CopyUCL(const TUint16* aZeroTerminatedString)
sl@0	3183	{
sl@0	3184	LString16::CopyUCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3185	}
sl@0	3186
sl@0	3187	/**
sl@0	3188	Copies text from the specified string and capitalises it before putting
sl@0	3189	it into this descriptor, replacing any existing data.
sl@0	3190
sl@0	3191	The length of this descriptor is set to reflect the new data.
sl@0	3192
sl@0	3193	Capitalisation is implemented as appropriate to the current locale.
sl@0	3194
sl@0	3195	This leaving variant of the standard, non-leaving descriptor method
sl@0	3196	differs in that this operation may cause the string descriptor's heap
sl@0	3197	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3198	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3199	and any existing raw pointers to into the descriptor data may be
sl@0	3200	invalidated.
sl@0	3201
sl@0	3202	@param aWideCharStr A wide character string.
sl@0	3203
sl@0	3204	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3205	grown and there are insufficient resources to do so
sl@0	3206	*/
sl@0	3207	EXPORT_C void LString16:: CopyCPL(const wchar_t* aWideCharStr)
sl@0	3208	{
sl@0	3209	LString16::CopyCPL(reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3210	}
sl@0	3211
sl@0	3212	/**
sl@0	3213	Copies text from the specified string and capitalises it before putting
sl@0	3214	it into this descriptor, replacing any existing data.
sl@0	3215
sl@0	3216	The length of this descriptor is set to reflect the new data.
sl@0	3217
sl@0	3218	Capitalisation is implemented as appropriate to the current locale.
sl@0	3219
sl@0	3220	This leaving variant of the standard, non-leaving descriptor method
sl@0	3221	differs in that this operation may cause the string descriptor's heap
sl@0	3222	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3223	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3224	and any existing raw pointers to into the descriptor data may be
sl@0	3225	invalidated.
sl@0	3226
sl@0	3227	@param aZeroTerminatedString A wide zero terminated string.
sl@0	3228
sl@0	3229	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3230	grown and there are insufficient resources to do so
sl@0	3231	*/
sl@0	3232	EXPORT_C void LString16:: CopyCPL(const TUint16* aZeroTerminatedString)
sl@0	3233	{
sl@0	3234	LString16::CopyCPL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3235	}
sl@0	3236	/**
sl@0	3237	Inserts data into this descriptor.
sl@0	3238
sl@0	3239	The length of this descriptor is changed to reflect the extra data.
sl@0	3240
sl@0	3241	This leaving variant of the standard, non-leaving descriptor method
sl@0	3242	differs in that this operation may cause the string descriptor's heap
sl@0	3243	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3244	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3245	and any existing raw pointers to into the descriptor data may be
sl@0	3246	invalidated.
sl@0	3247
sl@0	3248	@param aPos The position within the data where insertion is to start. This
sl@0	3249	is an offset value; a zero value refers to the leftmost data
sl@0	3250	position.
sl@0	3251
sl@0	3252	@param aWideCharStr A wide character string.
sl@0	3253
sl@0	3254	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3255	grown and there are insufficient resources to do so
sl@0	3256
sl@0	3257	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3258	descriptor.
sl@0	3259	*/
sl@0	3260	EXPORT_C void LString16:: InsertL(TInt aPos,const wchar_t* aWideCharStr)
sl@0	3261	{
sl@0	3262	LString16::InsertL(aPos, reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3263	}
sl@0	3264
sl@0	3265	/**
sl@0	3266	Inserts data into this descriptor.
sl@0	3267
sl@0	3268	The length of this descriptor is changed to reflect the extra data.
sl@0	3269
sl@0	3270	This leaving variant of the standard, non-leaving descriptor method
sl@0	3271	differs in that this operation may cause the string descriptor's heap
sl@0	3272	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3273	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3274	and any existing raw pointers to into the descriptor data may be
sl@0	3275	invalidated.
sl@0	3276
sl@0	3277	@param aPos The position within the data where insertion is to start. This
sl@0	3278	is an offset value; a zero value refers to the leftmost data
sl@0	3279	position.
sl@0	3280
sl@0	3281	@param aZeroTerminatedString A wide null terminated string.
sl@0	3282
sl@0	3283	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3284	grown and there are insufficient resources to do so
sl@0	3285
sl@0	3286	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3287	descriptor.
sl@0	3288	*/
sl@0	3289	EXPORT_C void LString16:: InsertL(TInt aPos,const TUint16* aZeroTerminatedString)
sl@0	3290	{
sl@0	3291	LString16::InsertL(aPos,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3292	}
sl@0	3293
sl@0	3294	/**
sl@0	3295	Replaces data in this descriptor.
sl@0	3296
sl@0	3297	The specified length can be different to the length of the replacement data.
sl@0	3298	The length of this descriptor changes to reflect the change of data.
sl@0	3299
sl@0	3300	This leaving variant of the standard, non-leaving descriptor method
sl@0	3301	differs in that this operation may cause the string descriptor's heap
sl@0	3302	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3303	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3304	and any existing raw pointers to into the descriptor data may be
sl@0	3305	invalidated.
sl@0	3306
sl@0	3307	@param aPos The position within the data where replacement is to start.
sl@0	3308	This is an offset value; a zero value refers to the leftmost
sl@0	3309	data position.
sl@0	3310
sl@0	3311	@param aLength The length of data to be replaced.
sl@0	3312
sl@0	3313	@param aWideCharStr The source wide character string
sl@0	3314
sl@0	3315	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3316	grown and there are insufficient resources to do so
sl@0	3317
sl@0	3318	@panic USER 8 if aLength is negative
sl@0	3319
sl@0	3320	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3321	descriptor.
sl@0	3322
sl@0	3323	@panic USER 16 if the length of the source descriptor aDes is negative
sl@0	3324	*/
sl@0	3325	EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr)
sl@0	3326	{
sl@0	3327	LString16::ReplaceL(aPos,aLength,reinterpret_cast<const TUint16*>(aWideCharStr));
sl@0	3328	}
sl@0	3329
sl@0	3330	/**
sl@0	3331	Replaces data in this descriptor.
sl@0	3332
sl@0	3333	The specified length can be different to the length of the replacement data.
sl@0	3334	The length of this descriptor changes to reflect the change of data.
sl@0	3335
sl@0	3336	This leaving variant of the standard, non-leaving descriptor method
sl@0	3337	differs in that this operation may cause the string descriptor's heap
sl@0	3338	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3339	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3340	and any existing raw pointers to into the descriptor data may be
sl@0	3341	invalidated.
sl@0	3342
sl@0	3343	@param aPos The position within the data where replacement is to start.
sl@0	3344	This is an offset value; a zero value refers to the leftmost
sl@0	3345	data position.
sl@0	3346
sl@0	3347	@param aLength The length of data to be replaced.
sl@0	3348
sl@0	3349	@param aZeroTerminatedString The source wide null terminated character string
sl@0	3350
sl@0	3351	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3352	grown and there are insufficient resources to do so
sl@0	3353
sl@0	3354	@panic USER 8 if aLength is negative
sl@0	3355
sl@0	3356	@panic USER 10 if aPos is negative or is greater than the length of this
sl@0	3357	descriptor.
sl@0	3358
sl@0	3359	@panic USER 16 if the length of the source descriptor aDes is negative
sl@0	3360	*/
sl@0	3361	EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString)
sl@0	3362	{
sl@0	3363	LString16::ReplaceL(aPos,aLength,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
sl@0	3364	}
sl@0	3365
sl@0	3366	/**
sl@0	3367	Copies data into this descriptor and justifies it, replacing any existing data.
sl@0	3368
sl@0	3369	The length of this descriptor is set to reflect the new data.
sl@0	3370
sl@0	3371	The target area is considered to be an area of specified width positioned at
sl@0	3372	the beginning of this descriptor's data area. Source data is copied into, and
sl@0	3373	aligned within this target area according to the specified alignment
sl@0	3374	instruction.
sl@0	3375
sl@0	3376	If the length of the target area is larger than the length of the source, then
sl@0	3377	spare space within the target area is padded with the fill character.
sl@0	3378
sl@0	3379	This leaving variant of the standard, non-leaving descriptor method
sl@0	3380	differs in that this operation may cause the string descriptor's heap
sl@0	3381	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3382	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3383	and any existing raw pointers to into the descriptor data may be
sl@0	3384	invalidated.
sl@0	3385
sl@0	3386	@param aWideCharStr A wide character string containing the source data.
sl@0	3387	The length of the data to be copied is the smaller of:
sl@0	3388	the length of the source descriptor, and
sl@0	3389	the width of the target area (only if this is not the
sl@0	3390	explicit negative value KDefaultJustifyWidth).
sl@0	3391
sl@0	3392	@param aWidth The width of the target area. If this has the specific
sl@0	3393	negative value KDefaultJustifyWidth, then the width is
sl@0	3394	re-set to the length of the data source.
sl@0	3395
sl@0	3396	@param aAlignment The alignment of the data within the target area
sl@0	3397
sl@0	3398	@param aFill The fill character used to pad the target area.
sl@0	3399
sl@0	3400	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3401	grown and there are insufficient resources to do so
sl@0	3402
sl@0	3403	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3404	*/
sl@0	3405	EXPORT_C void LString16:: JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3406	{
sl@0	3407	LString16::JustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aWidth,anAlignment,aFill);
sl@0	3408	}
sl@0	3409
sl@0	3410	/**
sl@0	3411	Copies data into this descriptor and justifies it, replacing any existing data.
sl@0	3412
sl@0	3413	The length of this descriptor is set to reflect the new data.
sl@0	3414
sl@0	3415	The target area is considered to be an area of specified width positioned at
sl@0	3416	the beginning of this descriptor's data area. Source data is copied into, and
sl@0	3417	aligned within this target area according to the specified alignment
sl@0	3418	instruction.
sl@0	3419
sl@0	3420	If the length of the target area is larger than the length of the source, then
sl@0	3421	spare space within the target area is padded with the fill character.
sl@0	3422
sl@0	3423	This leaving variant of the standard, non-leaving descriptor method
sl@0	3424	differs in that this operation may cause the string descriptor's heap
sl@0	3425	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3426	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3427	and any existing raw pointers to into the descriptor data may be
sl@0	3428	invalidated.
sl@0	3429
sl@0	3430	@param aWideCharStr A wide character string containing the source data.
sl@0	3431	The length of the data to be copied is the smaller of:
sl@0	3432	the length of the source descriptor, and
sl@0	3433	the width of the target area (only if this is not the
sl@0	3434	explicit negative value KDefaultJustifyWidth).
sl@0	3435
sl@0	3436	@param aWidth The width of the target area. If this has the specific
sl@0	3437	negative value KDefaultJustifyWidth, then the width is
sl@0	3438	re-set to the length of the data source.
sl@0	3439
sl@0	3440	@param aAlignment The alignment of the data within the target area
sl@0	3441
sl@0	3442	@param aFill The fill character used to pad the target area.
sl@0	3443
sl@0	3444	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3445	grown and there are insufficient resources to do so
sl@0	3446
sl@0	3447	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3448	*/
sl@0	3449	EXPORT_C void LString16:: JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3450	{
sl@0	3451	LString16::JustifyL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill);
sl@0	3452	}
sl@0	3453
sl@0	3454	/**
sl@0	3455	Appends data onto the end of this descriptor's data and justifies it.
sl@0	3456
sl@0	3457	The source of the appended data is a memory location.
sl@0	3458
sl@0	3459	The target area is considered to be an area of specified width, immediately
sl@0	3460	following this descriptor's existing data. Source data is copied into, and
sl@0	3461	aligned within, this target area according to the specified alignment instruction.
sl@0	3462
sl@0	3463	If the length of the target area is larger than the length of the source,
sl@0	3464	then spare space within the target area is padded with the fill character.
sl@0	3465
sl@0	3466	This leaving variant of the standard, non-leaving descriptor method
sl@0	3467	differs in that this operation may cause the string descriptor's heap
sl@0	3468	buffer to be reallocated in order to accommodate the new data. As a
sl@0	3469	result, MaxLength() and Ptr() may return different values afterwards,
sl@0	3470	and any existing raw pointers to into the descriptor data may be
sl@0	3471	invalidated.
sl@0	3472
sl@0	3473	@param aString A pointer to a source memory location.
sl@0	3474
sl@0	3475	@param aLength The length of data to be copied. If this is greater than the
sl@0	3476	width of the target area, then the length of data copied is
sl@0	3477	limited to the width.
sl@0	3478
sl@0	3479	@param aWidth The width of the target area. If this has the specific negative
sl@0	3480	value KDefaultJustifyWidth, then the width is
sl@0	3481	re-set to the length of the data source.
sl@0	3482
sl@0	3483	@param aAlignment The alignment of the data within the target area.
sl@0	3484
sl@0	3485	@param aFill The fill character used to pad the target area.
sl@0	3486
sl@0	3487	@leave KErrNoMemory if the underlying buffer needs to be
sl@0	3488	grown and there are insufficient resources to do so
sl@0	3489
sl@0	3490	@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
sl@0	3491
sl@0	3492	@panic USER 17 if aLength is negative.
sl@0	3493	*/
sl@0	3494	EXPORT_C void LString16:: AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
sl@0	3495	{
sl@0	3496	LString16::AppendJustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength, aWidth,anAlignment,aFill);
sl@0	3497	}
sl@0	3498	//eof

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