#88337# documentation

This commit is contained in:
Daniel Boelzle 2001-08-22 10:13:32 +00:00
parent 0350382896
commit 86d57df6ce
2 changed files with 189 additions and 180 deletions

View file

@ -2,9 +2,9 @@
*
* $RCSfile: byteseq.h,v $
*
* $Revision: 1.3 $
* $Revision: 1.4 $
*
* last change: $Author: jsc $ $Date: 2001-04-26 13:34:01 $
* last change: $Author: dbo $ $Date: 2001-08-22 11:13:32 $
*
* The Contents of this file are made available subject to the terms of
* either of the following licenses
@ -70,13 +70,14 @@ extern "C"
{
#endif
/** Assures that the reference count of the given byte sequence is one.
Otherwise a new copy of the sequence is created with a reference count of one.
<br>
/** Assures that the reference count of the given byte sequence is one. Otherwise a new copy
of the sequence is created with a reference count of one.
@param ppSequence sequence
*/
void SAL_CALL rtl_byte_sequence_reference2One(
sal_Sequence ** ppSequence );
sal_Sequence ** ppSequence )
SAL_THROW_EXTERN_C();
/** Reallocates length of byte sequence.
@ -84,71 +85,92 @@ void SAL_CALL rtl_byte_sequence_reference2One(
@param nSize new size of sequence
*/
void SAL_CALL rtl_byte_sequence_realloc(
sal_Sequence ** ppSequence, sal_Int32 nSize );
sal_Sequence ** ppSequence, sal_Int32 nSize )
SAL_THROW_EXTERN_C();
/** Acquires the byte sequence
@param pSequence sequence, that shall be acquired.
*/
void SAL_CALL rtl_byte_sequence_acquire( sal_Sequence *pSequence );
@param pSequence sequence, that is to be acquired
*/
void SAL_CALL rtl_byte_sequence_acquire(
sal_Sequence *pSequence )
SAL_THROW_EXTERN_C();
/** Releases the byte sequence. If the refcount drops to zero,
the sequence is freed.
/** Releases the byte sequence. If the refcount drops to zero, the sequence is freed.
@param pSequence sequence, that shall be released. Invalid after call.
*/
void SAL_CALL rtl_byte_sequence_release( sal_Sequence *pSequence );
@param pSequence sequence, that is to be released; invalid after call
*/
void SAL_CALL rtl_byte_sequence_release(
sal_Sequence *pSequence )
SAL_THROW_EXTERN_C();
/** Constructs a bytes sequence with length nLength. All bytes are set to zero.
@param On entry *ppSequence may be null , otherwise it is released.
After the call, ppSequence contains the newly constructed sequence.
*/
void SAL_CALL rtl_byte_sequence_construct( sal_Sequence **ppSequence , sal_Int32 nLength );
@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
after the call, *ppSequence contains the newly constructed sequence
@param nLength length of new sequence
*/
void SAL_CALL rtl_byte_sequence_construct(
sal_Sequence **ppSequence , sal_Int32 nLength )
SAL_THROW_EXTERN_C();
/** Constructs a bytes sequence with length nLength. The data is not initialized.
@param ppSequence contains the newly constructed sequence.
*ppSequence is released on entry if needed.
*/
@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
after the call, *ppSequence contains the newly constructed sequence
@param nLength length of new sequence
*/
void SAL_CALL rtl_byte_sequence_constructNoDefault(
sal_Sequence **ppSequence , sal_Int32 nLength );
sal_Sequence **ppSequence , sal_Int32 nLength )
SAL_THROW_EXTERN_C();
/** Constructs a byte sequence with length nLength and copies nLength bytes from pData.
@param ppSequence contains the newly constructed sequence.
*ppSequence is released on entry if needed.
*/
@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
after the call, *ppSequence contains the newly constructed sequence
@param pData initial data
@param nLength length of new sequence
*/
void SAL_CALL rtl_byte_sequence_constructFromArray(
sal_Sequence **ppSequence, const sal_Int8 *pData , sal_Int32 nLength );
sal_Sequence **ppSequence, const sal_Int8 *pData , sal_Int32 nLength )
SAL_THROW_EXTERN_C();
/** Assigns the byte sequence pSequence to ppSequence.
/** Assigns the byte sequence pSequence to *ppSequence.
@param On entry *ppSequence may be null , otherwise it is released.
ppSequence contains after the call a copy of pSequence.
@param pSequence the source sequence
*/
void SAL_CALL rtl_byte_sequence_assign( sal_Sequence **ppSequence , sal_Sequence *pSequence );
@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
after the call, *ppSequence references pSequence
@param pSequence the source sequence
*/
void SAL_CALL rtl_byte_sequence_assign(
sal_Sequence **ppSequence , sal_Sequence *pSequence )
SAL_THROW_EXTERN_C();
/** Compares two byte sequences.
@return sal_False, if the data within the sequences are different. <br>
sal_True, if the data within the sequences are identical <br>
*/
sal_Bool SAL_CALL rtl_byte_sequence_equals( sal_Sequence *pSequence1 , sal_Sequence *pSequence2 );
@return true, if the data within the sequences are identical; false otherwise
*/
sal_Bool SAL_CALL rtl_byte_sequence_equals(
sal_Sequence *pSequence1 , sal_Sequence *pSequence2 )
SAL_THROW_EXTERN_C();
/** Returns the data array pointer of the sequence.
/** Returns the data pointer of the sequence.
@return const pointer to the data of the sequence. If rtl_byte_sequence_reference2One
@return read-pointer to the data array of the sequence. If rtl_byte_sequence_reference2One()
has been called before, the pointer may be casted to a non const pointer and
the sequence may be modified.
*/
const sal_Int8 *SAL_CALL rtl_byte_sequence_getConstArray( sal_Sequence *pSequence );
the sequence may be modified
*/
const sal_Int8 *SAL_CALL rtl_byte_sequence_getConstArray(
sal_Sequence *pSequence )
SAL_THROW_EXTERN_C();
/** Returns the length of the sequence
**/
sal_Int32 SAL_CALL rtl_byte_sequence_getLength( sal_Sequence *pSequence );
@param pSequence sequence handle
@return length of the sequence
*/
sal_Int32 SAL_CALL rtl_byte_sequence_getLength(
sal_Sequence *pSequence )
SAL_THROW_EXTERN_C();
#ifdef __cplusplus
}
@ -157,8 +179,7 @@ namespace rtl
enum __ByteSequence_NoDefault
{
/** This enum value can be used to create a bytesequence with uninitalized data.
<br>
/** This enum value can be used to create a bytesequence with uninitalized data
*/
BYTESEQ_NODEFAULT = 0xcafe
};
@ -167,157 +188,149 @@ enum __ByteSequence_NoAcquire
{
/** This enum value can be used to create a bytesequence from a C-Handle without
acquiring the handle.
<br>
*/
BYTESEQ_NOACQUIRE = 0xcafebabe
};
/** C++ class representing a SAL byte sequence.<br>
C++ Sequences are reference counted and shared, so the sequence keeps a handle
to its data.
/** C++ class representing a SAL byte sequence.
C++ Sequences are reference counted and shared, so the sequence keeps a handle to its data.
To keep value semantics, copies are only generated if the sequence is to be modified
(new handle).
<br>
*/
class ByteSequence
{
/** sequence handle<br>
/** sequence handle
*/
sal_Sequence * _pSequence;
public:
/** Default constructor:
Creates an empty sequence.
<br>
/** Default constructor: Creates an empty sequence.
*/
inline ByteSequence();
/** Copy constructor:
Creates a copy of given sequence.
<br>
inline ByteSequence() SAL_THROW( () );
/** Copy constructor: Creates a copy of given sequence.
@param rSeq another byte sequence
*/
inline ByteSequence( const ByteSequence & rSeq );
/** Copy constructor
Creates a copy from the C-Handle.
inline ByteSequence( const ByteSequence & rSeq ) SAL_THROW( () );
/** Copy constructor Creates a copy from the C-Handle.
@param pSequence another byte sequence handle
*/
inline ByteSequence( sal_Sequence *pSequence );
/** Constructor:
Creates a copy of given bytes.
<br>
@param pElement an array of bytes
inline ByteSequence( sal_Sequence *pSequence ) SAL_THROW( () );
/** Constructor: Creates a copy of given data bytes.
@param pElements an array of bytes
@param len number of bytes
*/
inline ByteSequence( const sal_Int8 * pElements, sal_Int32 len );
/** Constructor:
Creates sequence of given length and initializes all bytes to 0.
<br>
@param len initial sequence length
*/
inline ByteSequence( sal_Int32 len );
/** Constructor:
Creates sequence of given length and does NOT initialize data. Use
this ctor for performance optimization only.
<br>
@param len initial sequence length
@param dummy parameter
*/
inline ByteSequence( sal_Int32 len , enum __ByteSequence_NoDefault nodefault );
/** Constructor:
Creates a sequence from a C-Handle without acquiring the handle. Eitherway
the handle is release by the destructor. This ctor is useful, when working
with a c-interface (it safes a pair of acquire and release call and is thus
a performance optimization only ).
<br>
*/
inline ByteSequence( sal_Sequence *pSequence , enum __ByteSequence_NoAcquire noacquire );
/** Destructor:
Releases sequence handle. Last handle will free memory.
<br>
*/
inline ~ByteSequence();
inline ByteSequence( const sal_Int8 * pElements, sal_Int32 len ) SAL_THROW( () );
/** Constructor: Creates sequence of given length and initializes all bytes to 0.
@param len initial sequence length
*/
inline ByteSequence( sal_Int32 len ) SAL_THROW( () );
/** Constructor: Creates sequence of given length and does NOT initialize data.
Use this ctor for performance optimization only.
@param len initial sequence length
@param nodefault dummy parameter forcing explicit BYTESEQ_NODEFAULT
*/
inline ByteSequence( sal_Int32 len , enum __ByteSequence_NoDefault nodefault ) SAL_THROW( () );
/** Constructor: Creates a sequence from a C-Handle without acquiring the handle, thus taking
over owenership. Eitherway the handle is release by the destructor.
This ctor is useful, when working with a c-interface (it safes a pair of
acquire and release call and is thus a performance optimization only).
@param pSequence sequence handle to be taken over
@param noacquire dummy parameter forcing explicit BYTESEQ_NOACQUIRE
*/
inline ByteSequence( sal_Sequence *pSequence , enum __ByteSequence_NoAcquire noacquire ) SAL_THROW( () );
/** Destructor: Releases sequence handle. Last handle will free memory.
*/
inline ~ByteSequence() SAL_THROW( () );
/** Assignment operator: Acquires given sequence handle and releases a previously set handle.
/** Assignment operator:
Acquires given sequence handle and releases previously set handle.
<br>
@param rSeq another byte sequence
@return this sequence
*/
inline ByteSequence & SAL_CALL operator = ( const ByteSequence & rSeq );
inline ByteSequence & SAL_CALL operator = ( const ByteSequence & rSeq ) SAL_THROW( () );
/** Gets the length of sequence.
/** Gets length of sequence.
<br>
@return length of sequence
*/
inline sal_Int32 SAL_CALL getLength() const
inline sal_Int32 SAL_CALL getLength() const SAL_THROW( () )
{ return _pSequence->nElements; }
/** Gets a pointer to byte array for <b>reading</b>.
If the sequence has a length of 0, then the returned pointer is undefined.
<br>
/** Gets a pointer to byte array for READING. If the sequence has a length of 0, then the
returned pointer is undefined.
@return pointer to byte array
*/
inline const sal_Int8 * SAL_CALL getConstArray() const
inline const sal_Int8 * SAL_CALL getConstArray() const SAL_THROW( () )
{ return (const sal_Int8 *)_pSequence->elements; }
/** Gets a pointer to elements array for <b>reading and writing</b>.<br>
In general if the sequence has a handle acquired by other sequences
(reference count > 1), then a new sequence is created copying
all bytes to keep value semantics!<br>
/** Gets a pointer to elements array for READING AND WRITING. In general if the sequence
has a handle acquired by other sequences (reference count > 1), then a new sequence is
created copying all bytes to keep value semantics!
If the sequence has a length of 0, then the returned pointer is undefined.
<br>
@return pointer to elements array
*/
inline sal_Int8 * SAL_CALL getArray();
inline sal_Int8 * SAL_CALL getArray() SAL_THROW( () );
/** Non-const index operator: Obtains a reference to byte indexed at given position.
The implementation does NOT check for array bounds!
In general if the sequence has a handle acquired by other
sequences (reference count > 1), then a new sequence is created
copying all bytes to keep value semantics!
/** Non-const index operator:
Obtains a reference to byte indexed at given position.<br>
The implementation does <b>not</b> check for array bounds!<br>
In general if the sequence has a handle acquired by other sequences
(reference count > 1), then a new sequence is created copying
all bytes to keep value semantics!
<br>
@param nIndex index
@return non-const C++ reference to element
@return non-const C++ reference to element at index nIndex
*/
inline sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex )
inline sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) SAL_THROW( () )
{ return getArray()[ nIndex ]; }
/** Const index operator:
Obtains a reference to byte indexed at given position.<br>
The implementation does <b>not</b> check for array bounds!<br>
<br>
/** Const index operator: Obtains a reference to byte indexed at given position.
The implementation does NOT check for array bounds!
@param nIndex index
@return const C++ reference to byte
@return const C++ reference to byte at element of indenx nIndex
*/
inline const sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) const
inline const sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) const SAL_THROW( () )
{ return getConstArray()[ nIndex ]; }
/** Equality operator:
Compares two sequences.
<br>
/** Equality operator: Compares two sequences.
@param rSeq another byte sequence (right side)
@return true if both sequences are equal, false otherwise
*/
inline sal_Bool SAL_CALL operator == ( const ByteSequence & rSeq ) const;
/** Unequality operator:
Compares two sequences.
<br>
inline sal_Bool SAL_CALL operator == ( const ByteSequence & rSeq ) const SAL_THROW( () );
/** Unequality operator: Compares two sequences.
@param rSeq another byte sequence (right side)
@return false if both sequences are equal, true otherwise
*/
inline sal_Bool SAL_CALL operator != ( const ByteSequence & rSeq ) const
{ return (! operator == ( rSeq )); }
/** Reallocates sequence to new length.
If the sequence has a handle acquired by other sequences
(reference count > 1), then the remaining elements are copied
to a new sequence handle to keep value semantics!
<br>
/** Reallocates sequence to new length. If the sequence has a handle acquired by other sequences
(reference count > 1), then the remaining elements are copied to a new sequence handle to
keep value semantics!
@param nSize new size of sequence
*/
inline void SAL_CALL realloc( sal_Int32 nSize );
inline void SAL_CALL realloc( sal_Int32 nSize ) SAL_THROW( () );
/** Returns the (unacquired) C-Handle of the sequence
*
**/
inline sal_Sequence * SAL_CALL getHandle() const
/** Returns the UNnacquired C handle of the sequence
@return UNacquired handle of the sequence
*/
inline sal_Sequence * SAL_CALL getHandle() const SAL_THROW( () )
{ return _pSequence; }
/** Returns the UNnacquired C handle of the sequence (for compatibility reasons)
@return UNacquired handle of the sequence
*/
inline sal_Sequence * SAL_CALL get() const SAL_THROW( () )
{ return _pSequence; }
};

View file

@ -2,9 +2,9 @@
*
* $RCSfile: byteseq.hxx,v $
*
* $Revision: 1.1.1.1 $
* $Revision: 1.2 $
*
* last change: $Author: hr $ $Date: 2000-09-18 15:17:13 $
* last change: $Author: dbo $ $Date: 2001-08-22 11:13:32 $
*
* The Contents of this file are made available subject to the terms of
* either of the following licenses
@ -79,74 +79,70 @@ namespace rtl
{
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence()
inline ByteSequence::ByteSequence() SAL_THROW( () )
: _pSequence( 0 )
{
rtl_byte_sequence_construct( &_pSequence , 0 );
::rtl_byte_sequence_construct( &_pSequence, 0 );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( const ByteSequence & rSeq ) :
_pSequence( 0 )
{
rtl_byte_sequence_assign( &_pSequence , rSeq._pSequence );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( sal_Sequence *pSequence) :
_pSequence( pSequence )
{
rtl_byte_sequence_acquire( pSequence );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( const sal_Int8 * pElements, sal_Int32 len )
inline ByteSequence::ByteSequence( const ByteSequence & rSeq ) SAL_THROW( () )
: _pSequence( 0 )
{
rtl_byte_sequence_constructFromArray( &_pSequence, pElements , len );
::rtl_byte_sequence_assign( &_pSequence, rSeq._pSequence );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( sal_Int32 len, enum __ByteSequence_NoDefault value )
inline ByteSequence::ByteSequence( sal_Sequence *pSequence) SAL_THROW( () )
: _pSequence( pSequence )
{
::rtl_byte_sequence_acquire( pSequence );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( const sal_Int8 * pElements, sal_Int32 len ) SAL_THROW( () )
: _pSequence( 0 )
{
rtl_byte_sequence_constructNoDefault( &_pSequence , len );
::rtl_byte_sequence_constructFromArray( &_pSequence, pElements, len );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( sal_Sequence *pSequence, enum __ByteSequence_NoAcquire value )
inline ByteSequence::ByteSequence( sal_Int32 len, enum __ByteSequence_NoDefault value ) SAL_THROW( () )
: _pSequence( 0 )
{
::rtl_byte_sequence_constructNoDefault( &_pSequence, len );
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( sal_Sequence *pSequence, enum __ByteSequence_NoAcquire value ) SAL_THROW( () )
: _pSequence( pSequence )
{
}
//__________________________________________________________________________________________________
inline ByteSequence::ByteSequence( sal_Int32 len )
inline ByteSequence::ByteSequence( sal_Int32 len ) SAL_THROW( () )
: _pSequence( 0 )
{
rtl_byte_sequence_construct( &_pSequence , len );
::rtl_byte_sequence_construct( &_pSequence, len );
}
//__________________________________________________________________________________________________
inline ByteSequence::~ByteSequence()
inline ByteSequence::~ByteSequence() SAL_THROW( () )
{
rtl_byte_sequence_release( _pSequence );
::rtl_byte_sequence_release( _pSequence );
}
//__________________________________________________________________________________________________
inline ByteSequence & ByteSequence::operator = ( const ByteSequence & rSeq )
inline ByteSequence & ByteSequence::operator = ( const ByteSequence & rSeq ) SAL_THROW( () )
{
rtl_byte_sequence_assign( &_pSequence , rSeq._pSequence );
::rtl_byte_sequence_assign( &_pSequence, rSeq._pSequence );
return *this;
}
//__________________________________________________________________________________________________
inline sal_Bool ByteSequence::operator == ( const ByteSequence & rSeq ) const
inline sal_Bool ByteSequence::operator == ( const ByteSequence & rSeq ) const SAL_THROW( () )
{
if (_pSequence == rSeq._pSequence)
return sal_True;
if (_pSequence->nElements != rSeq._pSequence->nElements)
return sal_False;
return (0 == ::rtl_compareMemory( _pSequence->elements, rSeq._pSequence->elements, _pSequence->nElements ));
return ::rtl_byte_sequence_equals( _pSequence, rSeq._pSequence );
}
//__________________________________________________________________________________________________
inline sal_Int8 * ByteSequence::getArray()
inline sal_Int8 * ByteSequence::getArray() SAL_THROW( () )
{
::rtl_byte_sequence_reference2One( &_pSequence );
return (sal_Int8 *)_pSequence->elements;
}
//__________________________________________________________________________________________________
inline void ByteSequence::realloc( sal_Int32 nSize )
inline void ByteSequence::realloc( sal_Int32 nSize ) SAL_THROW( () )
{
::rtl_byte_sequence_realloc( &_pSequence, nSize );
}