repeated_field.h

This section contains reference documentation for working with protocol buffer classes in C++.

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

RepeatedField and RepeatedPtrField are used by generated protocol message classes to manipulate repeated fields.

These classes are very similar to STL's vector, but include a number of optimizations found to be useful specifically in the case of Protocol Buffers. RepeatedPtrField is particularly different from STL vector as it manages ownership of the pointers that it contains.

Typically, clients should not need to access RepeatedField objects directly, but should instead use the accessor functions generated automatically by the protocol compiler.

Classes in this file

RepeatedField is used to represent repeated fields of a primitive type (in other words, everything except strings and nested Messages).
RepeatedPtrField is like RepeatedField, but used for repeated strings or Messages.

File Members

These definitions are not part of any class.
template internal::RepeatedFieldBackInsertIterator< T >
RepeatedFieldBackInserter(RepeatedField< T > *const mutable_field)
Provides a back insert iterator for RepeatedField instances, similar to std::back_inserter().
template internal::RepeatedPtrFieldBackInsertIterator< T >
RepeatedPtrFieldBackInserter(RepeatedPtrField< T > *const mutable_field)
Provides a back insert iterator for RepeatedPtrField instances, similar to std::back_inserter().
template internal::RepeatedPtrFieldBackInsertIterator< T >
RepeatedFieldBackInserter(RepeatedPtrField< T > *const mutable_field)
Special back insert iterator for RepeatedPtrField instances, just in case someone wants to write generic template code that can access both RepeatedFields and RepeatedPtrFields using a common name.
template internal::AllocatedRepeatedPtrFieldBackInsertIterator< T >
AllocatedRepeatedPtrFieldBackInserter(RepeatedPtrField< T > *const mutable_field)
Provides a back insert iterator for RepeatedPtrField instances similar to std::back_inserter() which transfers the ownership while copying elements.
template internal::UnsafeArenaAllocatedRepeatedPtrFieldBackInsertIterator< T >
UnsafeArenaAllocatedRepeatedPtrFieldBackInserter(RepeatedPtrField< T > *const mutable_field)
Similar to AllocatedRepeatedPtrFieldBackInserter, using UnsafeArenaAddAllocated instead of AddAllocated. more...

template internal::UnsafeArenaAllocatedRepeatedPtrFieldBackInsertIterator< T >
    protobuf::UnsafeArenaAllocatedRepeatedPtrFieldBackInserter(
        RepeatedPtrField< T > *const mutable_field)

Similar to AllocatedRepeatedPtrFieldBackInserter, using UnsafeArenaAddAllocated instead of AddAllocated.

This is slightly faster if that matters. It is also useful in legacy code that uses temporary ownership to avoid copies. Example:

RepeatedPtrField<T> temp_field;
temp_field.AddAllocated(new T);
... // Do something with temp_field
temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

If you put temp_field on the arena this fails, because the ownership transfers to the arena at the "AddAllocated" call and is not released anymore causing a double delete. Using UnsafeArenaAddAllocated prevents this.

template class RepeatedField

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

template <typename >

RepeatedField is used to represent repeated fields of a primitive type (in other words, everything except strings and nested Messages).

Most users will not ever use a RepeatedField directly; they will use the get-by-index, set-by-index, and add accessors that are generated for all repeated fields.

Members

typedef
Element * iterator
STL-like iterator support.
typedef
const Element * const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
constexpr
RepeatedField()
explicit
RepeatedField(Arena * arena)
RepeatedField(const RepeatedField & other)
template
RepeatedField(Iter begin, Iter end)
~RepeatedField()
RepeatedField &
operator=(const RepeatedField & other)
RepeatedField(RepeatedField && other)
RepeatedField &
operator=(RepeatedField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
Set(int index, const Element & value)
void
Add(const Element & value)
Element *
Add()
Appends a new element and return a pointer to it. more...
template void
Add(Iter begin, Iter end)
Append elements in the range [begin, end) after reserving the appropriate number of elements.
void
RemoveLast()
Remove the last element in the array.
void
ExtractSubrange(int start, int num, Element * elements)
Extract elements with indices in "[start .. start+num-1]". more...
void
Clear()
void
MergeFrom(const RepeatedField & other)
void
CopyFrom(const RepeatedField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
void
Truncate(int new_size)
Resize the RepeatedField to a new, smaller size. This is O(1).
void
AddAlreadyReserved(const Element & value)
Element *
AddAlreadyReserved()
Appends a new element and return a pointer to it. more...
Element *
AddNAlreadyReserved(int elements)
int
Capacity() const
void
Resize(int new_size, const Element & value)
Like STL resize. more...
Element *
mutable_data()
Gets the underlying array. more...
const Element *
data() const
void
Swap(RepeatedField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
size_t
SpaceUsedExcludingSelfLong() const
Returns the number of bytes used by the repeated field, excluding sizeof(*this)
int
SpaceUsedExcludingSelf() const
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [first, last). more...
Arena *
GetArena() const
Get the Arena on which this RepeatedField stores its elements.
void
InternalSwap(RepeatedField * other)
For internal use only. more...
template
RepeatedField(Iter begin, Iter end)

Element * RepeatedField::Add()

Appends a new element and return a pointer to it.

The new element is uninitialized if |Element| is a POD type.


void RepeatedField::ExtractSubrange(
        int start,
        int num,
        Element * elements)

Extract elements with indices in "[start .. start+num-1]".

Copy them into "elements[0 .. num-1]" if "elements" is not NULL. Caution: implementation also moves elements with indices [start+num ..]. Calling this routine inside a loop can cause quadratic behavior.


void RepeatedField::Reserve(
        int new_size)

Reserve space to expand the field to at least the given size.

Avoid inlining of Reserve(): new, copy, and delete[] lead to a significant amount of code bloat.

If the array is grown, it will always be at least doubled in size.


Element * RepeatedField::AddAlreadyReserved()

Appends a new element and return a pointer to it.

The new element is uninitialized if |Element| is a POD type. Should be called only if Capacity() > Size().


void RepeatedField::Resize(
        int new_size,
        const Element & value)

Like STL resize.

Uses value to fill appended elements. Like Truncate() if new_size <= size(), otherwise this is O(new_size - size()).


Element * RepeatedField::mutable_data()

Gets the underlying array.

This pointer is possibly invalidated by any add or remove operation.


void RepeatedField::Swap(
        RepeatedField * other)

Swap entire contents with "other".

If they are separate arenas then, copies data between each other.


void RepeatedField::UnsafeArenaSwap(
        RepeatedField * other)

Swap entire contents with "other".

Should be called only if the caller can guarantee that both repeated fields are on the same arena or are on the heap. Swapping between different arenas is disallowed and caught by a GOOGLE_DCHECK (see API docs for details).


iterator RepeatedField::erase(
        const_iterator position)

Removes the element referenced by position.

Returns an iterator to the element immediately following the removed element.

Invalidates all iterators at or after the removed element, including end().


iterator RepeatedField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [first, last).

Returns an iterator to the element immediately following the removed range.

Invalidates all iterators at or after the removed range, including end().


void RepeatedField::InternalSwap(
        RepeatedField * other)

For internal use only.

This is public due to it being called by generated code.

template class RepeatedPtrField

#include <google/protobuf/repeated_field.h>
namespace google::protobuf

template <typename >

RepeatedPtrField is like RepeatedField, but used for repeated strings or Messages.

Members

typedef
internal::RepeatedPtrIterator< Element > iterator
STL-like iterator support.
typedef
internal::RepeatedPtrIterator< const Element > const_iterator
typedef
Element value_type
typedef
value_type & reference
typedef
const value_type & const_reference
typedef
value_type * pointer
typedef
const value_type * const_pointer
typedef
int size_type
typedef
ptrdiff_t difference_type
typedef
std::reverse_iterator< const_iterator > const_reverse_iterator
Reverse iterator support.
typedef
std::reverse_iterator< iterator > reverse_iterator
typedef
internal::RepeatedPtrOverPtrsIterator< Element *, void * > pointer_iterator
Custom STL-like iterator that iterates over and returns the underlying pointers to Element rather than Element itself.
typedef
internal::RepeatedPtrOverPtrsIterator< const Element *const, const void *const > const_pointer_iterator
constexpr
RepeatedPtrField()
explicit
RepeatedPtrField(Arena * arena)
RepeatedPtrField(const RepeatedPtrField & other)
template
RepeatedPtrField(Iter begin, Iter end)
~RepeatedPtrField()
RepeatedPtrField &
operator=(const RepeatedPtrField & other)
RepeatedPtrField(RepeatedPtrField && other)
RepeatedPtrField &
operator=(RepeatedPtrField && other)
bool
empty() const
int
size() const
const Element &
Get(int index) const
Element *
Mutable(int index)
Element *
Add()
void
Add(Element && value)
template void
Add(Iter begin, Iter end)
Append elements in the range [begin, end) after reserving the appropriate number of elements.
const Element &
operator[](int index) const
Element &
operator[](int index)
const Element &
at(int index) const
Element &
at(int index)
void
RemoveLast()
Remove the last element in the array. more...
void
DeleteSubrange(int start, int num)
Delete elements with indices in the range [start . more...
void
Clear()
void
MergeFrom(const RepeatedPtrField & other)
void
CopyFrom(const RepeatedPtrField & other)
template void
Assign(Iter begin, Iter end)
Replaces the contents with RepeatedPtrField(begin, end).
void
Reserve(int new_size)
Reserve space to expand the field to at least the given size. more...
int
Capacity() const
Element **
mutable_data()
Gets the underlying array. more...
const Element *const *
data() const
void
Swap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
UnsafeArenaSwap(RepeatedPtrField * other)
Swap entire contents with "other". more...
void
SwapElements(int index1, int index2)
Swap two elements.
iterator
begin()
const_iterator
begin() const
const_iterator
cbegin() const
iterator
end()
const_iterator
end() const
const_iterator
cend() const
reverse_iterator
rbegin()
const_reverse_iterator
rbegin() const
reverse_iterator
rend()
const_reverse_iterator
rend() const
pointer_iterator
pointer_begin()
const_pointer_iterator
pointer_begin() const
pointer_iterator
pointer_end()
const_pointer_iterator
pointer_end() const
size_t
SpaceUsedExcludingSelfLong() const
Returns (an estimate of) the number of bytes used by the repeated field, excluding sizeof(*this).
int
SpaceUsedExcludingSelf() const
template
RepeatedPtrField(Iter begin, Iter end)

Advanced memory management

When hardcore memory management becomes necessary – as it sometimes does here at Google – the following methods may be useful.
void
AddAllocated(Element * value)
Add an already-allocated object, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseLast()
Remove the last element and return it, passing ownership to the caller. more...
void
UnsafeArenaAddAllocated(Element * value)
Add an already-allocated object, skipping arena-ownership checks. more...
Element *
UnsafeArenaReleaseLast()
Remove the last element and return it. more...
void
ExtractSubrange(int start, int num, Element ** elements)
Extract elements with indices in the range "[start .. start+num-1]". more...
void
UnsafeArenaExtractSubrange(int start, int num, Element ** elements)
Identical to ExtractSubrange() described above, except that when this repeated field is on an arena, no object copies are performed. more...
int
ClearedCount() const
Get the number of cleared objects that are currently being kept around for reuse.
void
AddCleared(Element * value)
Add an element to the pool of cleared objects, passing ownership to the RepeatedPtrField. more...
PROTOBUF_FUTURE_MUST_USE_RESULT Element *
ReleaseCleared()
Remove a single element from the cleared pool and return it, passing ownership to the caller. more...
iterator
erase(const_iterator position)
Removes the element referenced by position. more...
iterator
erase(const_iterator first, const_iterator last)
Removes the elements in the range [first, last). more...
Arena *
GetArena() const
Gets the arena on which this RepeatedPtrField stores its elements.
void
InternalSwap(RepeatedPtrField * other)
For internal use only. more...

void RepeatedPtrField::RemoveLast()

Remove the last element in the array.

Ownership of the element is retained by the array.


void RepeatedPtrField::DeleteSubrange(
        int start,
        int num)

Delete elements with indices in the range [start .

. start+num-1]. Caution: implementation moves all elements with indices [start+num .. ]. Calling this routine inside a loop can cause quadratic behavior.


void RepeatedPtrField::Reserve(
        int new_size)

Reserve space to expand the field to at least the given size.

This only resizes the pointer array; it doesn't allocate any objects. If the array is grown, it will always be at least doubled in size.


Element ** RepeatedPtrField::mutable_data()

Gets the underlying array.

This pointer is possibly invalidated by any add or remove operation.


void RepeatedPtrField::Swap(
        RepeatedPtrField * other)

Swap entire contents with "other".

If they are on separate arenas, then copies data.


void RepeatedPtrField::UnsafeArenaSwap(
        RepeatedPtrField * other)

Swap entire contents with "other".

Caller should guarantee that either both fields are on the same arena or both are on the heap. Swapping between different arenas with this function is disallowed and is caught via GOOGLE_DCHECK.


void RepeatedPtrField::AddAllocated(
        Element * value)

Add an already-allocated object, passing ownership to the RepeatedPtrField.

Note that some special behavior occurs with respect to arenas:

(i) if this field holds submessages, the new submessage will be copied if
the original is in an arena and this RepeatedPtrField is either in a
different arena, or on the heap.
(ii) if this field holds strings, the passed-in string *must* be
heap-allocated, not arena-allocated. There is no way to dynamically check
this at runtime, so User Beware.

PROTOBUF_FUTURE_MUST_USE_RESULT Element *
    RepeatedPtrField::ReleaseLast()

Remove the last element and return it, passing ownership to the caller.

Requires: size() > 0

If this RepeatedPtrField is on an arena, an object copy is required to pass ownership back to the user (for compatible semantics). Use UnsafeArenaReleaseLast() if this behavior is undesired.


void RepeatedPtrField::UnsafeArenaAddAllocated(
        Element * value)

Add an already-allocated object, skipping arena-ownership checks.

The user must guarantee that the given object is in the same arena as this RepeatedPtrField. It is also useful in legacy code that uses temporary ownership to avoid copies. Example:

RepeatedPtrField<T> temp_field;
temp_field.AddAllocated(new T);
... // Do something with temp_field
temp_field.ExtractSubrange(0, temp_field.size(), nullptr);

If you put temp_field on the arena this fails, because the ownership transfers to the arena at the "AddAllocated" call and is not released anymore causing a double delete. UnsafeArenaAddAllocated prevents this.


Element * RepeatedPtrField::UnsafeArenaReleaseLast()

Remove the last element and return it.

Works only when operating on an arena. The returned pointer is to the original object in the arena, hence has the arena's lifetime. Requires: current_size_ > 0


void RepeatedPtrField::ExtractSubrange(
        int start,
        int num,
        Element ** elements)

Extract elements with indices in the range "[start .. start+num-1]".

The caller assumes ownership of the extracted elements and is responsible for deleting them when they are no longer needed. If "elements" is non-NULL, then pointers to the extracted elements are stored in "elements[0 .. num-1]" for the convenience of the caller. If "elements" is NULL, then the caller must use some other mechanism to perform any further operations (like deletion) on these elements. Caution: implementation also moves elements with indices [start+num ..]. Calling this routine inside a loop can cause quadratic behavior.

Memory copying behavior is identical to ReleaseLast(), described above: if this RepeatedPtrField is on an arena, an object copy is performed for each returned element, so that all returned element pointers are to heap-allocated copies. If this copy is not desired, the user should call UnsafeArenaExtractSubrange().


void RepeatedPtrField::UnsafeArenaExtractSubrange(
        int start,
        int num,
        Element ** elements)

Identical to ExtractSubrange() described above, except that when this repeated field is on an arena, no object copies are performed.

Instead, the raw object pointers are returned. Thus, if on an arena, the returned objects must not be freed, because they will not be heap-allocated objects.


void RepeatedPtrField::AddCleared(
        Element * value)

Add an element to the pool of cleared objects, passing ownership to the RepeatedPtrField.

The element must be cleared prior to calling this method.

This method cannot be called when the repeated field is on an arena or when |value| is; both cases will trigger a GOOGLE_DCHECK-failure.


PROTOBUF_FUTURE_MUST_USE_RESULT Element *
    RepeatedPtrField::ReleaseCleared()

Remove a single element from the cleared pool and return it, passing ownership to the caller.

The element is guaranteed to be cleared. Requires: ClearedCount() > 0

This method cannot be called when the repeated field is on an arena; doing so will trigger a GOOGLE_DCHECK-failure.


iterator RepeatedPtrField::erase(
        const_iterator position)

Removes the element referenced by position.

Returns an iterator to the element immediately following the removed element.

Invalidates all iterators at or after the removed element, including end().


iterator RepeatedPtrField::erase(
        const_iterator first,
        const_iterator last)

Removes the elements in the range [first, last).

Returns an iterator to the element immediately following the removed range.

Invalidates all iterators at or after the removed range, including end().


void RepeatedPtrField::InternalSwap(
        RepeatedPtrField * other)

For internal use only.

This is public due to it being called by generated code.