Mapping of Sequence Types
An IDL sequence is mapped to:
template< class t > com::sun::star::uno::Sequence< t >
The sequence class is a reference to a reference counted handle that is allocated on the heap.
The sequence follows a copy-on-modify strategy. If a sequence is about to be modified, it is checked if the reference count of the sequence is 1. If this is the case, it gets modified directly, otherwise a copy of the sequence is created that has a reference count of 1.
A sequence can be created with an arbitrary UNO type as element type, but do not use a non-UNO type. The full reflection data provided by the type library are needed for construction, destruction and comparison.
You can construct a sequence with an initial number of elements. Each element is default constructed.
{ // create an integer sequence with 3 elements, // elements default to zero. Sequence< sal_Int32 > seqInt( 3 ); // get a read/write array pointer (this method checks for // the refcount and does a copy on demand). sal_Int32 *pArray = seqInt.getArray(); // if you know, that the refocunt is one // as in this case, where the sequence has just been // constructed, you could avoid the check, // which is a C-call overhead, // by writing sal_Int32 *pArray = (sal_Int32*) seqInt.getConstArray(); // modify the members pArray[0] = 4; pArray[1] = 5; pArray[2] = 3; }
You can also initialize a sequence from an array of the same type by using a different constructor. The new sequence is allocated on the heap and all elements are copied from the source.
{ sal_Int32 sourceArray[3] = {3,5,3}; // result is the same as above, but we initialize from a buffer. Sequence< sal_Int32 > seqInt( sourceArray , 3 ); }
Complex UNO types like structs can be stored within sequences, too:
{ // construct a sequence of Property structs, // the structs are default constructed Sequence< Property > seqProperty(2); seqProperty[0].Name = OUString::createFromAscii( "A" ); seqProperty[0].Handle = 0; seqProperty[1].Name = OUString::createFromAscii( "B" ); seqProperty[1].Handle = 1; // copy construct the sequence (The refcount is raised) Sequence< Property > seqProperty2 = seqProperty; // access a sequence for( sal_Int32 i = 0 ; i < seqProperty.getLength() ; i ++ ) { // Please NOTE : seqProperty.getArray() would also work, but // it is more expensive, because a // unnessecary copy construction // of the sequence takes place. printf( "%d\n" , seqProperty.getConstArray()[i].Handle ); } }
The size of sequences can be changed using the realloc() method, which takes the new number of elements as a parameter. For instance:
// construct an empty sequence Sequence < Any > anySequence; // get your enumeration from somewhere Reference< XEnumeration > rEnum = ...; // iterate over the enumeration while( rEnum->hasMoreElements() ) { anySequence.realloc( anySequence.getLength() + 1 ); anySequence[anySequence.getLength()-1] = rEnum->nextElement(); }
The above code shows an enumeration is transformed into a sequence, using an inefficient method. The realloc() default constructs a new element at the end of the sequence. If the sequence is shrunk by realloc, the elements at the end are destroyed.
The sequence is meant as a transportation container only, therefore it lacks methods for efficient insertion and removal of elements. Use a C++ Standard Template Library vector as an intermediate container to manipulate a list of elements and finally copy the elements into the sequence.
Sequences of a specific type are a fully supported UNO type. There can also be a sequence of sequences. This is similar to a multidimensional array with the exception that each row may vary in length. For instance:
{ sal_Int32 a[ ] = { 1,2,3 }, b[] = {4,5,6}, c[] = {7,8,9,10}; Sequence< Sequence< sal_Int32 > > aaSeq ( 3 ); aaSeq[0] = Sequence< sal_Int32 >( a , 3 ); aaSeq[1] = Sequence< sal_Int32 >( b , 3 ); aaSeq[2] = Sequence< sal_Int32 >( c , 4 ); }
is a valid sequence of sequence< sal_Int32>.
The maximal length of a com::sun::star::uno::Sequence is limited; therefore, it is an error if a UNO sequence that is too long is used in the context of the C++ language binding.
| Content on this page is licensed under the Public Documentation License (PDL). |
