-
Notifications
You must be signed in to change notification settings - Fork 312
/
bslalg_arrayprimitives.h
4831 lines (4305 loc) · 227 KB
/
bslalg_arrayprimitives.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// bslalg_arrayprimitives.h -*-C++-*-
#ifndef INCLUDED_BSLALG_ARRAYPRIMITIVES
#define INCLUDED_BSLALG_ARRAYPRIMITIVES
#include <bsls_ident.h>
BSLS_IDENT("$Id$ $CSID$")
//@PURPOSE: Provide primitive algorithms that operate on arrays.
//
//@CLASSES:
// bslalg::ArrayPrimitives: namespace for array algorithms
//
//@SEE_ALSO: bslalg_dequeprimitives, bslma_constructionutil
//
//@DESCRIPTION: This component provides utilities to initialize, move, and
// otherwise perform various primitive manipulations on arrays with a uniform
// interface, but selecting a different implementation according to the various
// traits possessed by the underlying type. Such primitives are exceptionally
// useful for implementing generic components such as containers.
//
// Several algorithms are provided, with the following short synopsis
// describing the observable behavior and mentioning the relevant traits. See
// the full function-level contract for detailed description, including
// exception-safety guarantees. In the description below, 'ADP' stands for
// 'bslalg::ArrayDestructionPrimitives'. Note that some algorithms (e.g.,
// 'insert') are explained in terms of previous algorithms (e.g.,
// 'destructiveMove').
//..
// Algorithm Short description of observable behavior
// ---------------------------- ---------------------------------------------
// defaultConstruct Default construct from value for each element
// in the target range, or 'std::memset' if type
// has a trivial default constructor
//
// uninitializedFillN Copy construct from value for each element in
// the target range, or 'std::memset' if value
// is all 0s or 1s bits, and type is bit-wise
// copyable
//
// copyConstruct Copy construct from each element in the
// original range to the corresponding element
// in the target range, or 'std::memcpy' if
// value is null and type is bit-wise copyable
//
// destructiveMove Copy from each element in the original range
// to the corresponding element in the target
// and destroy objects in the original range, or
// 'std::memcpy' if type is bit-wise moveable
//
// destructiveMoveAndInsert 'destructiveMove' from the original range to
// target range, leaving a hole in the middle,
// followed by 'defaultConstruct',
// 'uninitializedFillN' or 'copyConstruct' to
// fill hole with the appropriate values
//
// destructiveMoveAndMoveInsert 'destructiveMove' from the original range to
// the target range, leaving a hole in the
// middle, followed by 'destructiveMove'
// from second range to fill hole
//
// insert 'std::memmove' or 'copyConstruct' by some
// positive offset to create a hole, followed by
// 'uninitializedFillN', 'copyConstruct', or
// copy assignment to fill hole with the
// appropriate values
//
// emplace 'std::memmove' or 'copyConstruct' by some
// positive offset to create a hole, followed by
// in-place construction, 'copyConstruct', or
// copy assignment to fill hole with the
// appropriate values
//
// moveInsert 'destructiveMove' by some positive offset to
// create a hole, followed by 'destructiveMove'
// to fill hole with the appropriate values
//
// erase 'ADP::destroy' elements in target range until
// specified position, followed by
// 'destructiveMove' by some negative offset
// from the end of the range to fill hole with
// the remaining values
//
// rotate 'destructiveMove' to move elements into a
// shifting hole along parallel cyclic
// permutations, or 'std::memmove' for small
// rotations if type is bit-wise moveable
//..
// The traits under consideration by this component are:
//..
// Trait English description
// -------------------------------------------- -----------------------------
// bsl::is_trivially_default_constructible "TYPE has the trivial default
// constructor trait", or
// "TYPE has a trivial default
// constructor"
//
// bsl::is_trivially_copyable "TYPE has the bit-wise
// copyable trait", or
// "TYPE is bit-wise copyable"
//
// bslmf::IsBitwiseMoveable "TYPE has the bit-wise
// moveable trait", or
// "TYPE is bit-wise moveable"
//..
//
///Aliasing
///--------
// There are some aliasing concerns in this component, due to the presence of
// the reference 'const TARGET_TYPE& value' argument, which may belong to a
// range that will be modified during the course of the operation. All such
// aliasing concerns are taken care of properly. Other aliasing concerns due
// to the copying or a range '[first, last)' are *not* taken care of, since
// their intended use is for range assignments and insertions in standard
// containers, for which the standard explicitly says that 'first' and 'last'
// shall not be iterators into the container.
//
///Usage
///-----
// In this section we show intended use of this component.
//
///Example 1: Defining a Vector-Like Type
/// - - - - - - - - - - - - - - - - - - -
// Suppose we want to define a STL-vector-like type. One requirement is that
// an object of this vector should forward its allocator to its contained
// elements when appropriate. Another requirement is that the vector should
// take advantage of the optimizations available for certain traits of the
// contained element type. For example, if the contained element type has the
// 'bslmf::IsBitwiseMoveable' trait, moving an element in a vector can be done
// using 'memcpy' instead of copy construction.
//
// We can utilize the class methods provided by 'bslalg::ArrayPrimitives' to
// satisfy the above requirements. Unlike 'bslma::ConstructionUtil', which
// operates on a single element, 'bslalg::ArrayPrimitives' operates on arrays,
// which will further help simplify our implementation.
//
// First, we create an elided definition of the class template 'MyVector':
//..
// template <class TYPE, class ALLOC>
// class MyVector {
// // This class implements a vector of elements of the (template
// // parameter) 'TYPE', which must be copy constructible. Note that for
// // the brevity of the usage example, this class does not provide any
// // Exception-Safety guarantee.
//
// // DATA
// TYPE *d_array_p; // pointer to the allocated array
// int d_capacity; // capacity of the allocated array
// int d_size; // number of objects
// ALLOC d_allocator; // allocator pointer (held, not owned)
//
// public:
// // TYPE TRAITS
// BSLMF_NESTED_TRAIT_DECLARATION(
// MyVector,
// BloombergLP::bslmf::IsBitwiseMoveable);
//
// // CREATORS
// explicit MyVector(bslma::Allocator *basicAllocator = 0)
// // Construct a 'MyVector' object having a size of 0 and and a
// // capacity of 0. Optionally specify a 'basicAllocator' used to
// // supply memory. If 'basicAllocator' is 0, the currently
// // installed default allocator is used.
// : d_array_p(0)
// , d_capacity(0)
// , d_size(0)
// , d_allocator_p(bslma::Default::allocator(basicAllocator))
// {
// }
//
// MyVector(const MyVector& original,
// bslma::Allocator *basicAllocator = 0);
// // Create a 'MyVector' object having the same value as the
// // specified 'original' object. Optionally specify a
// // 'basicAllocator' used to supply memory. If 'basicAllocator' is
// // 0, the currently installed default allocator is used.
//
// // ...
//
// // MANIPULATORS
// void reserve(int minCapacity);
// // Change the capacity of this vector to at least the specified
// // 'minCapacity' if it is greater than the vector's current
// // capacity.
//
// void insert(int dstIndex, int numElements, const TYPE& value);
// // Insert, into this vector, the specified 'numElements' of the
// // specified 'value' at the specified 'dstIndex'. The behavior is
// // undefined unless '0 <= dstIndex <= size()'.
//
// // ACCESSORS
// const TYPE& operator[](int position) const
// // Return a reference providing non-modifiable access to the
// // element at the specified 'position' in this vector.
// {
// return d_array_p[position];
// }
//
// int size() const
// // Return the size of this vector.
// {
// return d_size;
// }
// };
//..
// Then, we implement the copy constructor of 'MyVector':
//..
// template <class TYPE>
// MyVector<TYPE>::MyVector(const MyVector<TYPE>& original,
// bslma::Allocator *basicAllocator)
// : d_array_p(0)
// , d_capacity(0)
// , d_size(0)
// , d_allocator_p(bslma::Default::allocator(basicAllocator))
// {
// reserve(original.d_size);
//..
// Here, we call the 'bslalg::ArrayPrimitives::copyConstruct' class method to
// copy each element from 'original.d_array_p' to 'd_array_p' (When
// appropriate, this class method passes this vector's allocator to the copy
// constructor of 'TYPE' or uses bit-wise copy.):
//..
// bslalg::ArrayPrimitives::copyConstruct(
// d_array_p,
// original.d_array_p,
// original.d_array_p + original.d_size,
// d_allocator_p);
//
// d_size = original.d_size;
// }
//..
// Now, we implement the 'reserve' method of 'MyVector':
//..
// template <class TYPE>
// void MyVector<TYPE>::reserve(int minCapacity)
// {
// if (d_capacity >= minCapacity) return; // RETURN
//
// TYPE *newArrayPtr = static_cast<TYPE*>(d_allocator_p->allocate(
// BloombergLP::bslma::Allocator::size_type(minCapacity * sizeof(TYPE))));
//
// if (d_array_p) {
//..
// Here, we call the 'bslalg::ArrayPrimitives::destructiveMove' class method to
// copy each original element from 'd_array_p' to 'newArrayPtr' and then
// destroy all the original elements (When appropriate, this class method
// passes this vector's allocator to the copy constructor of 'TYPE' or uses
// bit-wise copy.):
//..
// bslalg::ArrayPrimitives::destructiveMove(newArrayPtr,
// d_array_p,
// d_array_p + d_size,
// d_allocator_p);
// d_allocator_p->deallocate(d_array_p);
// }
//
// d_array_p = newArrayPtr;
// d_capacity = minCapacity;
// }
//..
// Finally, we implement the 'insert' method of 'MyVector':
//..
// template <class TYPE>
// void
// MyVector<TYPE>::insert(int dstIndex, int numElements, const TYPE& value)
// {
// int newSize = d_size + numElements;
//
// if (newSize > d_capacity) {
// int newCapacity = d_capacity == 0 ? 2 : d_capacity * 2;
// reserve(newCapacity);
// }
//..
// Here, we call the 'bslalg::ArrayPrimitives::insert' class method to first
// move each element after 'dstIndex' by 'numElements' and then copy construct
// 'numElements' of 'value' at 'dstIndex'. (When appropriate, this class
// method passes this vector's allocator to the copy constructor of 'TYPE' or
// uses bit-wise copy.):
//..
// bslalg::ArrayPrimitives::insert(d_array_p + dstIndex,
// d_array_p + d_size,
// value,
// numElements,
// d_allocator_p);
//
// d_size = newSize;
// }
//..
#include <bslscm_version.h>
#include <bslalg_arraydestructionprimitives.h>
#include <bslalg_autoarraydestructor.h>
#include <bslalg_autoarraymovedestructor.h>
#include <bslma_allocator.h>
#include <bslma_allocatortraits.h>
#include <bslma_constructionutil.h>
#include <bslma_default.h>
#include <bslma_destructorproctor.h>
#include <bslma_stdallocator.h>
#include <bslmf_assert.h>
#include <bslmf_functionpointertraits.h>
#include <bslmf_integralconstant.h>
#include <bslmf_isbitwisemoveable.h>
#include <bslmf_isconvertible.h>
#include <bslmf_isenum.h>
#include <bslmf_isfundamental.h>
#include <bslmf_ismemberpointer.h>
#include <bslmf_ispointer.h>
#include <bslmf_issame.h>
#include <bslmf_istriviallycopyable.h>
#include <bslmf_istriviallydefaultconstructible.h>
#include <bslmf_isvoid.h>
#include <bslmf_matchanytype.h>
#include <bslmf_metaint.h>
#include <bslmf_removeconst.h>
#include <bslmf_removecv.h>
#include <bslmf_removepointer.h>
#include <bslmf_util.h> // 'forward(V)'
#include <bsls_alignmentutil.h>
#include <bsls_assert.h>
#include <bsls_compilerfeatures.h>
#include <bsls_objectbuffer.h>
#include <bsls_performancehint.h>
#include <bsls_platform.h>
#include <bsls_types.h>
#include <bsls_util.h> // 'forward<T>(V)'
#include <cstddef> // 'std::size_t'
#include <cstring> // 'memset', 'memcpy', 'memmove'
#include <cwchar> // 'wmemset'
#ifndef BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
#include <bslalg_constructorproxy.h>
#endif
#if BSLS_COMPILERFEATURES_SIMULATE_CPP11_FEATURES
// Include version that can be compiled with C++03
// Generated on Thu Oct 21 10:11:37 2021
// Command line: sim_cpp11_features.pl bslalg_arrayprimitives.h
# define COMPILING_BSLALG_ARRAYPRIMITIVES_H
# include <bslalg_arrayprimitives_cpp03.h>
# undef COMPILING_BSLALG_ARRAYPRIMITIVES_H
#else
#if defined(BSLS_PLATFORM_CMP_IBM) // IBM needs specific workarounds.
# define BSLALG_ARRAYPRIMITIVES_CANNOT_REMOVE_POINTER_FROM_FUNCTION_POINTER 1
// xlC has problem removing pointer from function pointer types.
# define BSLALG_ARRAYPRIMITIVES_NON_ZERO_NULL_VALUE_FOR_MEMBER_POINTERS 1
// xlC representation for a null member pointer is not all zero bits.
#endif
namespace BloombergLP {
namespace bslalg {
struct ArrayPrimitives_Imp;
// ======================
// struct ArrayPrimitives
// ======================
struct ArrayPrimitives {
// This 'struct' provides a namespace for a suite of independent utility
// functions that operate on arrays of elements of parameterized type
// 'TARGET_TYPE'. Depending on the traits of 'TARGET_TYPE', the default
// and copy constructors, destructor, assignment operators, etcetera may
// not be invoked, optimized away by no-op or bit-wise move or copy.
public:
// TYPES
typedef ArrayPrimitives_Imp Imp;
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
// CLASS METHODS
template <class ALLOCATOR, class FWD_ITER>
static void
copyConstruct(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
FWD_ITER fromBegin,
FWD_ITER fromEnd,
ALLOCATOR allocator);
template <class ALLOCATOR, class SOURCE_TYPE>
static void
copyConstruct(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
SOURCE_TYPE *fromBegin,
SOURCE_TYPE *fromEnd,
ALLOCATOR allocator);
// Copy the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location,
// using the specified 'allocator' to supply memory (if required). If
// a constructor throws an exception during this operation, the output
// array is left in an uninitialized state. The behavior is undefined
// unless 'toBegin' refers to space sufficient to hold
// 'fromEnd - fromBegin' elements.
template <class TARGET_TYPE, class FWD_ITER>
static void copyConstruct(TARGET_TYPE *toBegin,
FWD_ITER fromBegin,
FWD_ITER fromEnd,
bslma::Allocator *allocator);
template <class TARGET_TYPE, class SOURCE_TYPE>
static void copyConstruct(TARGET_TYPE *toBegin,
SOURCE_TYPE *fromBegin,
SOURCE_TYPE *fromEnd,
bslma::Allocator *allocator);
// Copy into an uninitialized array of (the template parameter)
// 'TARGET_TYPE' beginning at the specified 'toBegin' address, the
// elements in the array of 'TARGET_TYPE' starting at the specified
// 'fromBegin' address and ending immediately before the specified
// 'fromEnd' address. If the (template parameter) 'ALLOCATOR' type is
// derived from 'bslma::Allocator' and 'TARGET_TYPE' supports 'bslma'
// allocators, then the specified 'allocator' is passed to each
// invocation of the 'TARGET_TYPE' copy constructor. If a
// 'TARGET_TYPE' constructor throws an exception during the operation,
// then the destructor is called on any newly-constructed elements,
// leaving the output array in an uninitialized state.
template <class ALLOCATOR>
static void
moveConstruct(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
ALLOCATOR allocator);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location,
// using the specified 'allocator' to supply memory (if required). The
// elements in the input array are left in a valid but unspecified
// state. If a constructor throws an exception during this operation,
// the output array is left in an uninitialized state. The behavior is
// undefined unless 'toBegin' refers to space sufficient to hold
// 'fromEnd - fromBegin' elements.
template <class TARGET_TYPE>
static void moveConstruct(TARGET_TYPE *toBegin,
TARGET_TYPE *fromBegin,
TARGET_TYPE *fromEnd,
bslma::Allocator *allocator);
// Move the elements of the (template parameter) 'TARGET_TYPE' starting
// at the specified 'fromBegin' address and ending immediately before
// the specified 'fromEnd' address into the uninitialized array of
// 'TARGET_TYPE' beginning at the specified 'toBegin' address, using
// the specified 'allocator' to supply memory (if required). The
// elements in the input array are left in a valid but unspecified
// state. If a constructor throws an exception during this operation,
// the output array is left in an uninitialized state. The behavior is
// undefined unless 'toBegin' refers to space sufficient to hold
// 'fromEnd - fromBegin' elements.
template <class ALLOCATOR>
static void defaultConstruct(
typename bsl::allocator_traits<ALLOCATOR>::pointer begin,
size_type numElements,
ALLOCATOR allocator);
// Default-construct the specified 'numElements' objects of type
// 'allocator_traits<ALLOCATOR>::value_type' into the uninitialized
// array beginning at the specified 'begin' location, using the
// specified 'allocator' to supply memory (if required). If a
// constructor throws an exception during this operation, then the
// destructor is called on any newly constructed elements, leaving the
// output array in an uninitialized state. The behavior is undefined
// unless the 'begin' refers to space sufficient to hold 'numElements'.
template <class TARGET_TYPE>
static void defaultConstruct(TARGET_TYPE *begin,
size_type numElements,
bslma::Allocator *allocator);
// Call the default constructor on each of the elements of an array of
// the specified 'numElements' of the parameterized 'TARGET_TYPE'
// starting at the specified 'begin' address. If the (template
// parameter) 'ALLOCATOR' type is derived from 'bslma::Allocator' and
// 'TARGET_TYPE' supports 'bslma' allocators, then the specified
// 'allocator' is passed to each 'TARGET_TYPE' default constructor
// call. The behavior is undefined unless the output array contains at
// least 'numElements' uninitialized elements after 'begin'. If a
// 'TARGET_TYPE' constructor throws an exception during this operation,
// then the destructor is called on any newly-constructed elements,
// leaving the output array in an uninitialized state.
template <class ALLOCATOR>
static void destructiveMove(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
ALLOCATOR allocator);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location,
// using the specified 'allocator' to supply memory (if required). On
// return, the elements in the input range are invalid, i.e., their
// destructors must not be called after this operation returns. If a
// constructor throws an exception during this operation, the output
// array is left in an uninitialized state. If a constructor other
// than the move constructor of a non-copy-constructible type throws
// an exception during this operation, the input array is unaffected;
// otherwise, if the move constructor of a non-copy-constructible type
// throws an exception during this operation, the input array is left
// in a valid but unspecified state. The behavior is undefined unless
// 'toBegin' refers to space sufficient to hold 'fromEnd - fromBegin'
// elements.
template <class TARGET_TYPE>
static void destructiveMove(TARGET_TYPE *toBegin,
TARGET_TYPE *fromBegin,
TARGET_TYPE *fromEnd,
bslma::Allocator *allocator);
// Move the elements of the parameterized 'TARGET_TYPE' in the array
// starting at the specified 'fromBegin' address and ending immediately
// before the specified 'fromEnd' address into an uninitialized array
// of 'TARGET_TYPE' beginning at the specified 'toBegin' address. On
// return, the elements in the input range are invalid, i.e., their
// destructors must not be called after this operation returns. If the
// parameterized 'ALLOCATOR' type is derived from 'bslma::Allocator'
// and 'TARGET_TYPE' supports 'bslma' allocators, then the specified
// 'allocator' is used by the objects in their new location. If an
// exception is thrown by a 'TARGET_TYPE' constructor during the
// operation, then the output array is left in an uninitialized state
// and the input elements remain in their original state.
#if !BSLS_COMPILERFEATURES_SIMULATE_CPP11_FEATURES // $var-args=10
template <class ALLOCATOR, class... ARGS>
static void destructiveMoveAndEmplace(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer *fromEndPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer position,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
ALLOCATOR allocator,
ARGS&&... arguments);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the specified range '[fromBegin .. fromEnd)' into the
// uninitialized array beginning at the specified 'toBegin' location,
// using the specified 'allocator' to supply memory (if required),
// inserting at the specified 'position' (after translating from
// 'fromBegin' to 'toBegin') a newly created object constructed by
// forwarding 'allocator' (if required) and the specified (variable
// number of) 'arguments' to the corresponding constructor of the
// target type, ensuring that the specified 'fromEndPtr' points to the
// first uninitialized element in '[fromBegin .. fromEnd)' as the
// elements are moved from source to destination. On return, the
// elements in the input range are invalid, i.e., their destructors
// must not be called after this operation returns. If a constructor
// throws an exception during this operation, the output array is left
// in an uninitialized state. If an exception is thrown during the
// in-place construction of the new object, the input array is
// unaffected; otherwise, if a (copy or move) constructor throws an
// exception during this operation, the input elements in the range
// '[fromBegin .. *fromEndPtr)' are left in a valid but unspecified
// state and the remaining portion of the input array is left in an
// uninitialized state. The behavior is undefined unless
// 'fromBegin <= position <= fromEnd' and 'toBegin' refers to space
// sufficient to hold 'fromEnd - fromBegin + 1' elements.
#endif
template <class ALLOCATOR>
static void destructiveMoveAndInsert(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer *fromEndPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer position,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
size_type numElements,
ALLOCATOR allocator);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location
// using the specified 'allocator' to supply memory (if required),
// inserting at the specified 'position' (after translating from
// 'fromBegin' to 'toBegin') the specified 'numElements' objects
// initialized to default values, ensuring that the specified
// 'fromEndPtr' points to the first uninitialized element in
// '[fromBegin .. fromEnd)' as the elements are moved from source to
// destination. On return, the elements in the input range are
// invalid, i.e., their destructors must not be called after this
// operation returns. If a constructor throws an exception during this
// operation, the output array is left in an uninitialized state. If a
// default constructor throws an exception, the input array is
// unaffected; otherwise, if a (copy or move) constructor throws an
// exception during this operation, the input elements in the range
// '[fromBegin .. *fromEndPtr)' are left in a valid but unspecified
// state and the remaining portion of the input array is left in an
// uninitialized state. The behavior is undefined unless 'fromBegin <=
// position <= fromEnd' and 'toBegin' refers to space sufficient to
// hold 'fromEnd - fromBegin + 1' elements.
template <class TARGET_TYPE>
static void destructiveMoveAndInsert(TARGET_TYPE *toBegin,
TARGET_TYPE **fromEndPtr,
TARGET_TYPE *fromBegin,
TARGET_TYPE *position,
TARGET_TYPE *fromEnd,
size_type numElements,
bslma::Allocator *allocator);
// Move the elements of the (template parameter) 'TARGET_TYPE' in the
// starting at the specified 'fromBegin' address and ending immediately
// before the specified 'fromEnd' address into the uninitialized array
// beginning at the specified 'toBegin' location using the specified
// 'allocator' to supply memory (if required), inserting at the
// specified 'position' (after translating from 'fromBegin' to
// 'toBegin') 'numElements' objects initialized to default values,
// ensuring that the specified 'fromEndPtr' points to the first
// uninitialized element in '[fromBegin .. fromEnd)' as the elements
// are moved from source to destination. On return, the elements in
// the input range are invalid, i.e., their destructors must not be
// called after this operation returns. If a constructor throws an
// exception during this operation, the output array is left in an
// uninitialized state. If a default constructor throws an exception,
// the input array is unaffected; otherwise, if a (copy or move)
// constructor throws an exception during this operation, the input
// elements in the range '[fromBegin .. *fromEndPtr)' are left in a
// valid but unspecified state and the remaining portion of the input
// array is left in an uninitialized state. The behavior is undefined
// unless 'fromBegin <= position <= fromEnd' and 'toBegin' refers to
// space sufficient to hold 'fromEnd - fromBegin + numElements'
// elements.
template <class ALLOCATOR>
static void destructiveMoveAndInsert(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer *fromEndPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer position,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
const typename bsl::allocator_traits<ALLOCATOR>::value_type& value,
size_type numElements,
ALLOCATOR allocator);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location
// using the specified 'allocator' to supply memory (if required),
// inserting at the specified 'position' (after translating from
// 'fromBegin' to 'toBegin') the specified 'numElements' copies of the
// specified 'value', ensuring that the specified 'fromEndPtr' points
// to the first uninitialized element in '[fromBegin .. fromEnd)' as
// the elements are moved from source to destination. On return, the
// elements in the input range are invalid, i.e., their destructors
// must not be called after this operation returns. If a constructor
// throws an exception during this operation, the output array is left
// in an uninitialized state. If a (copy or move) constructor throws
// an exception during this operation, the input elements in the range
// '[fromBegin .. *fromEndPtr)' are left in a valid but unspecified
// state and the remaining portion of the input array is left in an
// uninitialized state. The behavior is undefined unless
// 'fromBegin <= position <= fromEnd' and 'toBegin' refers to space
// sufficient to hold 'fromEnd - fromBegin + numElements' elements.
template <class TARGET_TYPE>
static void destructiveMoveAndInsert(TARGET_TYPE *toBegin,
TARGET_TYPE **fromEndPtr,
TARGET_TYPE *fromBegin,
TARGET_TYPE *position,
TARGET_TYPE *fromEnd,
const TARGET_TYPE& value,
size_type numElements,
bslma::Allocator *allocator);
// Move the elements of the parameterized 'TARGET_TYPE' in the array
// starting at the specified 'fromBegin' address and ending immediately
// before the specified 'fromEnd' address into an uninitialized array
// of 'TARGET_TYPE' at the specified 'toBegin' address, inserting at
// the specified 'position' (after translating from 'fromBegin' to
// 'toBegin') the specified 'numElements' copies of the specified
// 'value'. Keep the pointer at the specified 'fromEndPtr' address
// pointing to the first uninitialized element in '[ fromBegin,
// fromEnd)' as the elements are moved from source to destination. The
// behavior is undefined unless 'fromBegin <= position <= fromEnd' and
// the destination array contains at least
// '(fromEnd - fromBegin) + numElements' uninitialized elements. If a
// copy constructor or assignment operator for 'TARGET_TYPE' throws an
// exception, then any elements created in the output array are
// destroyed and the elements in the range '[ fromBegin, *fromEndPtr )'
// will have unspecified but valid values.
template <class ALLOCATOR, class FWD_ITER>
static void destructiveMoveAndInsert(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer *fromEndPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer position,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
FWD_ITER first,
FWD_ITER last,
size_type numElements,
ALLOCATOR allocator);
// Move the elements of type 'allocator_traits<ALLOCATOR>::value_type'
// in the range beginning at the specified 'fromBegin' location and
// ending immediately before the specified 'fromEnd' location into the
// uninitialized array beginning at the specified 'toBegin' location
// using the specified 'allocator' to supply memory (if required),
// inserting at the specified 'position' (after translating from
// 'fromBegin' to 'toBegin') the specified 'numElements' copies of the
// non-modifiable elements from the range starting at the specified
// 'first' iterator of (template parameter) type 'FWD_ITER' and ending
// immediately before the specified 'last' iterator, ensuring that the
// specified 'fromEndPtr' points to the first uninitialized element in
// '[fromBegin .. fromEnd)' as the elements are moved from source to
// destination. On return, the elements in the input range are
// invalid, i.e., their destructors must not be called after this
// operation returns. If a constructor throws an exception during this
// operation, the output array is left in an uninitialized state. If
// a constructor other than the copy or move constructor throws an
// exception during this operation, the input array is unaffected;
// otherwise, if a copy or move constructor throws an exception during
// this operation, the input elements in the range
// '[fromBegin .. *fromEndPtr)' are left in a valid but unspecified
// state and the remaining portion of the input array is left in an
// uninitialized state. The behavior is undefined unless
// 'fromBegin <= position <= fromEnd' and 'toBegin' refers to space
// sufficient to hold 'fromEnd - fromBegin + numElements' elements.
template <class TARGET_TYPE, class FWD_ITER>
static void destructiveMoveAndInsert(TARGET_TYPE *toBegin,
TARGET_TYPE **fromEndPtr,
TARGET_TYPE *fromBegin,
TARGET_TYPE *position,
TARGET_TYPE *fromEnd,
FWD_ITER first,
FWD_ITER last,
size_type numElements,
bslma::Allocator *allocator);
// Move the elements of the parameterized 'TARGET_TYPE' in the array
// starting at the specified 'fromBegin' address and ending immediately
// before the specified 'fromEnd' address into an uninitialized array
// of 'TARGET_TYPE' at the specified 'toBegin' address, inserting at
// the specified 'position' (after translating from 'fromBegin' to
// 'toBegin') the specified 'numElements' copies of the non-modifiable
// elements from the range starting at the specified 'first' iterator
// of the parameterized 'FWD_ITER' type and ending immediately before
// the specified 'last' iterator. Keep the pointer at the specified
// 'fromEndPtr' to point to the first uninitialized element in
// '[fromBegin, fromEnd)' as the elements are moved from source to
// destination. The behavior is undefined unless
// 'fromBegin <= position <= fromEnd', the destination array contains
// at least '(fromEnd - fromBegin) + numElements' uninitialized
// elements after 'toBegin', and 'numElements' is the distance from
// 'first' to 'last'. If a copy constructor or assignment operator for
// 'TARGET_TYPE' throws an exception, then any elements created in the
// output array are destroyed and the elements in the range
// '[ fromBegin, *fromEndPtr )' will have unspecified but valid values.
template <class ALLOCATOR>
static void destructiveMoveAndMoveInsert(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer *fromEndPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer *lastPtr,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer position,
typename bsl::allocator_traits<ALLOCATOR>::pointer fromEnd,
typename bsl::allocator_traits<ALLOCATOR>::pointer first,
typename bsl::allocator_traits<ALLOCATOR>::pointer last,
size_type numElements,
ALLOCATOR allocator);
// TBD: improve comment
// Move, into an uninitialized array beginning at the specified
// 'toBegin' pointer, elements of type given by the 'allocator_traits'
// class template for (template parameter) 'ALLOCATOR', from elements
// starting at the specified 'fromBegin' pointer and ending immediately
// before the specified 'fromEnd' address, moving into the specified
// 'position' (after translating from 'fromBegin' to 'toBegin') the
// specified 'numElements' elements starting at the specified 'first'
// pointer and ending immediately before the specified 'last' pointer.
// Keep the pointer at the specified 'fromEndPtr' address pointing to
// the first uninitialized element in '[ fromBegin, fromEnd)' as the
// elements are moved from source to destination. The behavior is
// undefined unless 'fromBegin <= position <= fromEnd' and the
// destination array contains at least
// '(fromEnd - fromBegin) + numElements' uninitialized elements. If a
// constructor or assignment operator for the target type throws an
// exception, then any elements created in the output array are
// destroyed and the elements in the range '[ fromBegin, *fromEndPtr )'
// will have valid but unspecified values.
template <class TARGET_TYPE>
static void destructiveMoveAndMoveInsert(TARGET_TYPE *toBegin,
TARGET_TYPE **fromEndPtr,
TARGET_TYPE **lastPtr,
TARGET_TYPE *fromBegin,
TARGET_TYPE *position,
TARGET_TYPE *fromEnd,
TARGET_TYPE *first,
TARGET_TYPE *last,
size_type numElements,
bslma::Allocator *allocator);
// Move the elements of (template parameter) 'TARGET_TYPE' in the array
// starting at the specified 'fromBegin' address and ending immediately
// before the specified 'fromEnd' address into an uninitialized array
// of 'TARGET_TYPE' at the specified 'toBegin' address, moving into the
// specified 'position' (after translating from 'fromBegin' to
// 'toBegin') the specified 'numElements' of the 'TARGET_TYPE' from the
// array starting at the specified 'first' address and ending
// immediately before the specified 'last' address. Keep the pointer
// at the specified 'fromEndPtr' address pointing to the first
// uninitialized element in '[fromBegin, fromEnd)', and the pointer at
// the specified 'lastPtr' address pointing to the end of the moved
// range as the elements from the range '[ first, last)' are moved from
// source to destination. The behavior is undefined unless
// 'fromBegin <= position <= fromEnd', the destination array contains
// at least '(fromEnd - fromBegin) + numElements' uninitialized
// elements after 'toBegin', and 'numElements' is the distance from
// 'first' to 'last'. If a copy constructor or assignment operator for
// 'TARGET_TYPE' throws an exception, then any elements in
// '[ *lastPtr, last )' as well as in '[ toBegin, ... )' are destroyed,
// and the elements in the ranges '[ first, *lastPtr )' and
// '[ fromBegin, *fromEndPtr )' will have unspecified but valid values.
#if !BSLS_COMPILERFEATURES_SIMULATE_CPP11_FEATURES // $var-args=10
template <class ALLOCATOR, class... ARGS>
static void emplace(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer toEnd,
ALLOCATOR allocator,
ARGS&&... arguments);
// Insert a newly created 'allocator_traits<ALLOCATOR>::value_type'
// object, constructed by forwarding the specified 'allocator' (if
// required) and the specified (variable number of) 'arguments' to the
// corresponding constructor of
// 'allocator_traits<ALLOCATOR>::value_type', into the array at the
// specified 'toBegin' location, shifting forward the elements from
// 'toBegin' to the specified 'toEnd' location by one position. If an
// exception is thrown during the in-place construction of the new
// object, the elements in the range '[toBegin .. toEnd)' are
// unaffected; otherwise, if a (copy or move) constructor or a (copy or
// move) assignment operator throws an exception, then any elements
// created after 'toEnd' are destroyed and the elements in the range
// '[toBegin .. toEnd )' are left in a valid but unspecified state.
// The behavior is undefined unless 'toBegin' refers to sufficient
// space to hold at least 'toEnd - toBegin + 1' elements.
template <class TARGET_TYPE, class... ARGS>
static void emplace(TARGET_TYPE *toBegin,
TARGET_TYPE *toEnd,
bslma::Allocator *allocator,
ARGS&&... args);
// Insert a newly created object of the (template parameter) type
// 'TARGET_TYPE', constructed by forwarding the specified 'allocator'
// (if required) and the specified (variable number of) 'arguments' to
// the corresponding constructor of 'TARGET_TYPE', into the array at
// the specified 'toBegin' address, shifting the elements from
// 'toBegin' to the specified 'toEnd' address up one position towards
// larger addresses. If an exception is thrown during the in-place
// construction of the new object, the elements in the range
// '[toBegin .. toEnd)' are unaffected; otherwise, if a (copy or move)
// constructor or a (copy or move) assignment operator throws an
// exception, then any elements created after 'toEnd' are destroyed and
// the elements in the range '[toBegin .. toEnd )' are left in a valid
// but unspecified state. The behavior is undefined unless 'toBegin'
// refers to sufficient space to hold at least 'toEnd - toBegin + 1'
// elements.
#endif
#if defined(BSLS_PLATFORM_CMP_MSVC) && BSLS_PLATFORM_CMP_VERSION < 1900
template <class CLASS_TYPE, class MEMBER_TYPE, class... ARGS>
static void emplace(MEMBER_TYPE CLASS_TYPE::* *toBegin,
MEMBER_TYPE CLASS_TYPE::* *toEnd,
bslma::Allocator *allocator)
// Old Microsoft compilers need help value-initializing elements that
// are pointer-to-member types.
{
emplace(toBegin, toEnd, allocator, nullptr);
}
#endif
template <class ALLOCATOR>
static void
erase(typename bsl::allocator_traits<ALLOCATOR>::pointer first,
typename bsl::allocator_traits<ALLOCATOR>::pointer middle,
typename bsl::allocator_traits<ALLOCATOR>::pointer last,
ALLOCATOR allocator);
// TBD: improve comment
// Destroy the elements of type given by the 'allocator_traits' class
// template for (template parameter) 'ALLOCATOR' starting at the
// specified 'first' 'first' pointer and ending immediately before the
// specified 'middle' pointer, and move the elements in the array
// starting at 'middle' and ending at the specified 'last' pointer down
// to the 'first' pointer. If an assignment throws an exception during
// this process, all of the elements in the range '[ first, last )'
// will have unspecified but valid values, and no elements are
// destroyed. The behavior is undefined unless
// 'first <= middle <= last'.
template <class TARGET_TYPE>
static void erase(TARGET_TYPE *first,
TARGET_TYPE *middle,
TARGET_TYPE *last,
bslma::Allocator *allocator = 0);
// Destroy the elements of the parameterized 'TARGET_TYPE' in the array
// starting at the specified 'first' address and ending immediately
// before the specified 'middle' address, and move the elements in the
// array starting at 'middle' and ending at the specified 'last'
// address down to the 'first' address. If an assignment throws an
// exception during this process, all of the elements in the range
// '[ first, last )' will have unspecified but valid values, and no
// elements are destroyed. The behavior is undefined unless
// 'first <= middle <= last'.
template <class ALLOCATOR>
static void
insert(typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer toEnd,
bslmf::MovableRef<
typename bsl::allocator_traits<ALLOCATOR>::value_type> value,
ALLOCATOR allocator);
// Insert the specified 'value' into the array of
// 'allocator_traits<ALLOCATOR>::value_type' objects at the specified
// 'toBegin' location, shifting forward the elements from 'toBegin' to
// the specified 'toEnd' location by one position. 'value' is left in
// a valid but unspecified state. If a (copy or move) constructor or a
// (copy or move) assignment operator throws an exception, then any
// elements created after 'toEnd' are destroyed and the elements in the
// range '[toBegin .. toEnd )' are left in a valid but unspecified
// state. The behavior is undefined unless 'toBegin' refers to
// sufficient space to hold at least 'toEnd - toBegin + 1' elements.
template <class TARGET_TYPE>
static void insert(TARGET_TYPE *toBegin,
TARGET_TYPE *toEnd,
bslmf::MovableRef<TARGET_TYPE> value,
bslma::Allocator *allocator);
// Insert the specified 'value' into the array of the (template
// parameter) type 'TARGET_TYPE' at the specified 'toBegin' address,
// shifting the elements from 'toBegin' to the specified 'toEnd'
// address by one position towards larger addresses. 'value' is left
// in a valid but unspecified state. If a (copy or move) constructor
// or a (copy or move) assignment operator throws an exception, then
// any elements created after 'toEnd' are destroyed and the elements in
// the range '[toBegin .. toEnd )' are left in a valid but unspecified
// state. The behavior is undefined unless 'toBegin' refers to
// sufficient space to hold at least 'toEnd - toBegin + 1' elements.
template <class ALLOCATOR>
static void
insert(
typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer toEnd,
const typename bsl::allocator_traits<ALLOCATOR>::value_type& value,
size_type numElements,
ALLOCATOR allocator);
// Insert the specified 'numElements' copies of the specified 'value'
// into the array of type 'allocator_traits<ALLOCATOR>::value_type'
// starting at the specified 'toBegin' location, shifting forward the
// elements from 'toBegin' to the specified 'toEnd' location by
// 'numElements' positions. If a (copy or move) constructor or a (copy
// or move) assignment operator throws an exception, any elements
// created after 'toEnd' are destroyed and the elements in the range
// '[toBegin .. toEnd)' are left in a valid but unspecified state. The
// behavior is undefined unless 'toBegin' refers to space sufficient to
// hold at least 'toEnd - toBegin + numElements' elements.
template <class TARGET_TYPE>
static void insert(TARGET_TYPE *toBegin,
TARGET_TYPE *toEnd,
const TARGET_TYPE& value,
size_type numElements,
bslma::Allocator *allocator);
// Insert the specified 'numElements' copies of the specified 'value'
// into the array of (template parameter) 'TARGET_TYPE' starting at the
// specified 'toBegin' address and ending immediately before the
// specified 'toEnd' address, shifting the elements in the array by
// 'numElements' positions towards larger addresses. The behavior is
// undefined unless the destination array contains at least
// 'numElements' uninitialized elements after 'toEnd'. If a copy
// constructor or assignment operator for 'TARGET_TYPE' throws an
// exception, then any elements created after 'toEnd' are destroyed and
// the elements in the range '[ toBegin, toEnd )' will have
// unspecified, but valid, values.
template <class ALLOCATOR, class FWD_ITER>
static void
insert(typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer toEnd,
FWD_ITER fromBegin,
FWD_ITER fromEnd,
size_type numElements,
ALLOCATOR allocator);
template <class ALLOCATOR, class SOURCE_TYPE>
static void
insert(typename bsl::allocator_traits<ALLOCATOR>::pointer toBegin,
typename bsl::allocator_traits<ALLOCATOR>::pointer toEnd,
SOURCE_TYPE *fromBegin,
SOURCE_TYPE *fromEnd,
size_type numElements,
ALLOCATOR allocator);
// TBD: improve comment
// Insert the specified 'numElements' from the range starting at the
// specified 'fromBegin' and ending immediately before the specified