include/rtl/byteseq.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_RTL_BYTESEQ_H
  20 #define INCLUDED_RTL_BYTESEQ_H
  21
  22 #include "sal/config.h"
  23
  24 #include "rtl/alloc.h"
  25 #include "sal/saldllapi.h"
  26 #include "sal/types.h"
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33 /** Assures that the reference count of the given byte sequence is one. Otherwise a new copy
  34     of the sequence is created with a reference count of one.
  35
  36     @param ppSequence sequence
  37 */
  38 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_reference2One(
  39     sal_Sequence ** ppSequence )
  40     SAL_THROW_EXTERN_C();
  41
  42 /** Reallocates length of byte sequence.
  43
  44     @param ppSequence sequence
  45     @param nSize new size of sequence
  46 */
  47 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_realloc(
  48     sal_Sequence ** ppSequence, sal_Int32 nSize )
  49     SAL_THROW_EXTERN_C();
  50
  51 /** Acquires the byte sequence
  52
  53     @param pSequence sequence, that is to be acquired
  54 */
  55 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_acquire(
  56     sal_Sequence *pSequence )
  57     SAL_THROW_EXTERN_C();
  58
  59 /** Releases the byte sequence. If the refcount drops to zero, the sequence is freed.
  60
  61     @param pSequence sequence, that is to be released; invalid after call
  62 */
  63 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_release(
  64     sal_Sequence *pSequence )
  65     SAL_THROW_EXTERN_C();
  66
  67 /** Constructs a bytes sequence with length nLength. All bytes are set to zero.
  68
  69     @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
  70                       after the call, *ppSequence contains the newly constructed sequence
  71     @param nLength    length of new sequence
  72 */
  73 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_construct(
  74     sal_Sequence **ppSequence , sal_Int32 nLength )
  75     SAL_THROW_EXTERN_C();
  76
  77 /** Constructs a bytes sequence with length nLength. The data is not initialized.
  78
  79     @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
  80                       after the call, *ppSequence contains the newly constructed sequence
  81     @param nLength    length of new sequence
  82 */
  83 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_constructNoDefault(
  84     sal_Sequence **ppSequence , sal_Int32 nLength )
  85     SAL_THROW_EXTERN_C();
  86
  87 /** Constructs a byte sequence with length nLength and copies nLength bytes from pData.
  88
  89     @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
  90                       after the call, *ppSequence contains the newly constructed sequence
  91     @param pData      initial data
  92     @param nLength    length of new sequence
  93 */
  94 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_constructFromArray(
  95     sal_Sequence **ppSequence, const sal_Int8 *pData , sal_Int32 nLength )
  96     SAL_THROW_EXTERN_C();
  97
  98 /** Assigns the byte sequence pSequence to *ppSequence.
  99
 100     @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
 101                       after the call, *ppSequence references pSequence
 102     @param pSequence  the source sequence
 103 */
 104 SAL_DLLPUBLIC void SAL_CALL rtl_byte_sequence_assign(
 105     sal_Sequence **ppSequence , sal_Sequence *pSequence )
 106     SAL_THROW_EXTERN_C();
 107
 108 /** Compares two byte sequences.
 109
 110     @return true, if the data within the sequences are identical; false otherwise
 111 */
 112 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_byte_sequence_equals(
 113     sal_Sequence *pSequence1 , sal_Sequence *pSequence2 )
 114     SAL_THROW_EXTERN_C();
 115
 116 /** Returns the data array pointer of the sequence.
 117
 118     @return read-pointer to the data array of the sequence. If rtl_byte_sequence_reference2One()
 119             has been called before, the pointer may be casted to a non const pointer and
 120             the sequence may be modified
 121 */
 122 SAL_DLLPUBLIC const sal_Int8 *SAL_CALL rtl_byte_sequence_getConstArray(
 123     sal_Sequence *pSequence )
 124     SAL_THROW_EXTERN_C();
 125
 126 /** Returns the length of the sequence
 127
 128     @param pSequence sequence handle
 129     @return length of the sequence
 130 */
 131 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_byte_sequence_getLength(
 132     sal_Sequence *pSequence )
 133     SAL_THROW_EXTERN_C();
 134
 135 #ifdef __cplusplus
 136 }
 137 namespace rtl
 138 {
 139
 140 enum __ByteSequence_NoDefault
 141 {
 142     /** This enum value can be used to create a bytesequence with uninitialized data
 143     */
 144     BYTESEQ_NODEFAULT = 0xcafe
 145 };
 146
 147 enum __ByteSequence_NoAcquire
 148 {
 149     /** This enum value can be used to create a bytesequence from a C-Handle without
 150         acquiring the handle.
 151     */
 152     BYTESEQ_NOACQUIRE =
 153 #if defined _MSC_VER
 154         int(0xcafebabe)
 155 #else
 156         0xcafebabe
 157 #endif
 158 };
 159
 160 /** C++ class representing a SAL byte sequence.
 161     C++ Sequences are reference counted and shared, so the sequence keeps a handle to its data.
 162     To keep value semantics, copies are only generated if the sequence is to be modified
 163     (new handle).
 164 */
 165 class SAL_WARN_UNUSED ByteSequence
 166 {
 167     /** sequence handle
 168     */
 169     sal_Sequence * _pSequence;
 170
 171 public:
 172     /// @cond INTERNAL
 173     // these are here to force memory de/allocation to sal lib.
 174     static void * SAL_CALL operator new ( size_t nSize )
 175         { return ::rtl_allocateMemory( nSize ); }
 176     static void SAL_CALL operator delete ( void * pMem )
 177         { ::rtl_freeMemory( pMem ); }
 178     static void * SAL_CALL operator new ( size_t, void * pMem )
 179         { return pMem; }
 180     static void SAL_CALL operator delete ( void *, void * )
 181         {}
 182     /// @endcond
 183
 184     /** Default constructor: Creates an empty sequence.
 185     */
 186     inline ByteSequence();
 187     /** Copy constructor: Creates a copy of given sequence.
 188
 189         @param rSeq another byte sequence
 190     */
 191     inline ByteSequence( const ByteSequence & rSeq );
 192 #if defined LIBO_INTERNAL_ONLY
 193     inline ByteSequence( ByteSequence && rSeq );
 194 #endif
 195     /** Copy constructor Creates a copy from the C-Handle.
 196
 197         @param pSequence another byte sequence handle
 198     */
 199     inline ByteSequence( sal_Sequence *pSequence );
 200     /** Constructor: Creates a copy of given data bytes.
 201
 202         @param pElements an array of bytes
 203         @param len number of bytes
 204     */
 205     inline ByteSequence( const sal_Int8 * pElements, sal_Int32 len );
 206     /** Constructor: Creates sequence of given length and initializes all bytes to 0.
 207
 208         @param len initial sequence length
 209     */
 210     inline ByteSequence( sal_Int32 len );
 211     /** Constructor: Creates sequence of given length and does NOT initialize data.
 212                      Use this ctor for performance optimization only.
 213
 214         @param len initial sequence length
 215         @param nodefault dummy parameter forcing explicit BYTESEQ_NODEFAULT
 216     */
 217     inline ByteSequence( sal_Int32 len , enum __ByteSequence_NoDefault nodefault );
 218     /** Constructor:
 219         Creates a sequence from a C-Handle without acquiring the handle, thus taking
 220         over ownership. Eitherway the handle is released by the destructor.
 221         This ctor is useful, when working with a c-interface (it safes a pair of
 222         acquire and release call and is thus a performance optimization only).
 223
 224         @param pSequence sequence handle to be taken over
 225         @param noacquire dummy parameter forcing explicit BYTESEQ_NOACQUIRE
 226     */
 227     inline ByteSequence( sal_Sequence *pSequence , enum __ByteSequence_NoAcquire noacquire );
 228     /** Destructor: Releases sequence handle. Last handle will free memory.
 229     */
 230     inline ~ByteSequence();
 231
 232     /** Assignment operator: Acquires given sequence handle and releases a previously set handle.
 233
 234         @param rSeq another byte sequence
 235         @return this sequence
 236     */
 237     inline ByteSequence & SAL_CALL operator = ( const ByteSequence & rSeq );
 238 #if defined LIBO_INTERNAL_ONLY
 239     inline ByteSequence & SAL_CALL operator = ( ByteSequence && rSeq );
 240 #endif
 241
 242     /** Gets the length of sequence.
 243
 244         @return length of sequence
 245     */
 246     sal_Int32 SAL_CALL getLength() const
 247         { return _pSequence->nElements; }
 248
 249     /** Gets a pointer to byte array for READING. If the sequence has a length of 0, then the
 250         returned pointer is undefined.
 251
 252         @return pointer to byte array
 253     */
 254     const sal_Int8 * SAL_CALL getConstArray() const
 255         { return reinterpret_cast<sal_Int8 *>(_pSequence->elements); }
 256     /** Gets a pointer to elements array for READING AND WRITING. In general if the sequence
 257         has a handle acquired by other sequences (reference count > 1), then a new sequence is
 258         created copying all bytes to keep value semantics!
 259         If the sequence has a length of 0, then the returned pointer is undefined.
 260
 261         @return pointer to elements array
 262     */
 263     inline sal_Int8 * SAL_CALL getArray();
 264
 265     /** Non-const index operator:
 266         Obtains a reference to byte indexed at given position.
 267         In general if the sequence has a handle acquired by other
 268         sequences (reference count > 1), then a new sequence is created
 269         copying all bytes to keep value semantics!
 270
 271         @attention
 272         The implementation does NOT check for array bounds!
 273
 274         @param nIndex index
 275         @return non-const C++ reference to element at index nIndex
 276     */
 277     inline sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex );
 278
 279     /** Const index operator: Obtains a reference to byte indexed at given position.
 280                               The implementation does NOT check for array bounds!
 281
 282         @param nIndex index
 283         @return const C++ reference to byte at element of index nIndex
 284     */
 285     const sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) const
 286         { return getConstArray()[ nIndex ]; }
 287
 288     /** Equality operator: Compares two sequences.
 289
 290         @param rSeq another byte sequence (right side)
 291         @return true if both sequences are equal, false otherwise
 292     */
 293     inline bool SAL_CALL operator == ( const ByteSequence & rSeq ) const;
 294     /** Unequality operator: Compares two sequences.
 295
 296         @param rSeq another byte sequence (right side)
 297         @return false if both sequences are equal, true otherwise
 298     */
 299     inline bool SAL_CALL operator != ( const ByteSequence & rSeq ) const;
 300
 301     /** Reallocates sequence to new length. If the sequence has a handle acquired by other sequences
 302         (reference count > 1), then the remaining elements are copied to a new sequence handle to
 303         keep value semantics!
 304
 305         @param nSize new size of sequence
 306     */
 307     inline void SAL_CALL realloc( sal_Int32 nSize );
 308
 309     /** Returns the UNnacquired C handle of the sequence
 310
 311         @return UNacquired handle of the sequence
 312     */
 313     sal_Sequence * SAL_CALL getHandle() const
 314         { return _pSequence; }
 315     /** Returns the UNnacquired C handle of the sequence (for compatibility reasons)
 316
 317         @return UNacquired handle of the sequence
 318     */
 319     sal_Sequence * SAL_CALL get() const
 320         { return _pSequence; }
 321 };
 322
 323 }
 324 #endif
 325 #endif
 326
 327 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */