field_mask_util.h

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

#include <google/protobuf/util/field_mask_util.h>
namespace google::protobuf::util

Defines utilities for the FieldMask well known type.

Classes in this file

class FieldMaskUtil

#include <google/protobuf/util/field_mask_util.h>
namespace google::protobuf::util

Members

static std::string
ToString(const FieldMask & mask)
Converts FieldMask to/from string, formatted by separating each path with a comma (e.g., "foo_bar,baz.quz").
static void
FromString(StringPiece str, FieldMask * out)
template static void
FromFieldNumbers(const std::vector< int64_t > & field_numbers, FieldMask * out)
Populates the FieldMask with the paths corresponding to the fields with the given numbers, after checking that all field numbers are valid.
static bool
ToJsonString(const FieldMask & mask, std::string * out)
Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz"). more...
static bool
FromJsonString(StringPiece str, FieldMask * out)
static bool
GetFieldDescriptors(const Descriptor * descriptor, StringPiece path, std::vector< const FieldDescriptor * > * field_descriptors)
Get the descriptors of the fields which the given path from the message descriptor traverses, if field_descriptors is not null. more...
template static bool
IsValidPath(StringPiece path)
Checks whether the given path is valid for type T.
template static bool
IsValidFieldMask(const FieldMask & mask)
Checks whether the given FieldMask is valid for type T.
template static void
AddPathToFieldMask(StringPiece path, FieldMask * mask)
Adds a path to FieldMask after checking whether the given path is valid. more...
template static FieldMask
GetFieldMaskForAllFields()
Creates a FieldMask with all fields of type T. more...
template static void
GetFieldMaskForAllFields(FieldMask * out)
static void
GetFieldMaskForAllFields(const Descriptor * descriptor, FieldMask * out)
This flavor takes the protobuf type descriptor as an argument. more...
static void
ToCanonicalForm(const FieldMask & mask, FieldMask * out)
Converts a FieldMask to the canonical form. more...
static void
Union(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
Creates an union of two FieldMasks.
static void
Intersect(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
Creates an intersection of two FieldMasks.
template static void
Subtract(const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
Subtracts mask2 from mask1 base of type T.
static void
Subtract(const Descriptor * descriptor, const FieldMask & mask1, const FieldMask & mask2, FieldMask * out)
This flavor takes the protobuf type descriptor as an argument. more...
static bool
IsPathInFieldMask(StringPiece path, const FieldMask & mask)
Returns true if path is covered by the given FieldMask. more...
static void
MergeMessageTo(const Message & source, const FieldMask & mask, const MergeOptions & options, Message * destination)
Merges fields specified in a FieldMask into another message.
static bool
TrimMessage(const FieldMask & mask, Message * message)
Removes from 'message' any field that is not represented in the given FieldMask. more...
static bool
TrimMessage(const FieldMask & mask, Message * message, const TrimOptions & options)
Removes from 'message' any field that is not represented in the given FieldMask with customized TrimOptions. more...

static bool FieldMaskUtil::ToJsonString(
        const FieldMask & mask,
        std::string * out)

Converts FieldMask to/from string, formatted according to proto3 JSON spec for FieldMask (e.g., "fooBar,baz.quz").

If the field name is not style conforming (i.e., not snake_case when converted to string, or not camelCase when converted from string), the conversion will fail.


static bool FieldMaskUtil::GetFieldDescriptors(
        const Descriptor * descriptor,
        StringPiece path,
        std::vector< const FieldDescriptor * > * field_descriptors)

Get the descriptors of the fields which the given path from the message descriptor traverses, if field_descriptors is not null.

Return false if the path is not valid, and the content of field_descriptors is unspecified.


template static void FieldMaskUtil::AddPathToFieldMask(
        StringPiece path,
        FieldMask * mask)

Adds a path to FieldMask after checking whether the given path is valid.

This method check-fails if the path is not a valid path for type T.


template static FieldMask FieldMaskUtil::GetFieldMaskForAllFields()

Creates a FieldMask with all fields of type T.

This FieldMask only contains fields of T but not any sub-message fields.


static void FieldMaskUtil::GetFieldMaskForAllFields(
        const Descriptor * descriptor,
        FieldMask * out)

This flavor takes the protobuf type descriptor as an argument.

Useful when the type is not known at compile time.


static void FieldMaskUtil::ToCanonicalForm(
        const FieldMask & mask,
        FieldMask * out)

Converts a FieldMask to the canonical form.

It will:

1. Remove paths that are covered by another path. For example,
   "foo.bar" is covered by "foo" and will be removed if "foo"
   is also in the FieldMask.
2. Sort all paths in alphabetical order.

static void FieldMaskUtil::Subtract(
        const Descriptor * descriptor,
        const FieldMask & mask1,
        const FieldMask & mask2,
        FieldMask * out)

This flavor takes the protobuf type descriptor as an argument.

Useful when the type is not known at compile time.


static bool FieldMaskUtil::IsPathInFieldMask(
        StringPiece path,
        const FieldMask & mask)

Returns true if path is covered by the given FieldMask.

Note that path "foo.bar" covers all paths like "foo.bar.baz", "foo.bar.quz.x", etc. Also note that parent paths are not covered by explicit child path, i.e. "foo.bar" does NOT cover "foo", even if "bar" is the only child.


static bool FieldMaskUtil::TrimMessage(
        const FieldMask & mask,
        Message * message)

Removes from 'message' any field that is not represented in the given FieldMask.

If the FieldMask is empty, does nothing. Returns true if the message is modified.


static bool FieldMaskUtil::TrimMessage(
        const FieldMask & mask,
        Message * message,
        const TrimOptions & options)

Removes from 'message' any field that is not represented in the given FieldMask with customized TrimOptions.

If the FieldMask is empty, does nothing. Returns true if the message is modified.

class FieldMaskUtil::MergeOptions

#include <google/protobuf/util/field_mask_util.h>
namespace google::protobuf::util

Members

MergeOptions()
void
set_replace_message_fields(bool value)
When merging message fields, the default behavior is to merge the content of two message fields together. more...
bool
replace_message_fields() const
void
set_replace_repeated_fields(bool value)
The default merging behavior will append entries from the source repeated field to the destination repeated field. more...
bool
replace_repeated_fields() const

void MergeOptions::set_replace_message_fields(
        bool value)

When merging message fields, the default behavior is to merge the content of two message fields together.

If you instead want to use the field from the source message to replace the corresponding field in the destination message, set this flag to true. When this flag is set, specified submessage fields that are missing in source will be cleared in destination.


void MergeOptions::set_replace_repeated_fields(
        bool value)

The default merging behavior will append entries from the source repeated field to the destination repeated field.

If you only want to keep the entries from the source repeated field, set this flag to true.

class FieldMaskUtil::TrimOptions

#include <google/protobuf/util/field_mask_util.h>
namespace google::protobuf::util

Members

TrimOptions()
void
set_keep_required_fields(bool value)
When trimming message fields, the default behavior is to trim required fields of the present message if they are not specified in the field mask. more...
bool
keep_required_fields() const

void TrimOptions::set_keep_required_fields(
        bool value)

When trimming message fields, the default behavior is to trim required fields of the present message if they are not specified in the field mask.

If you instead want to keep required fields of the present message even they are not specified in the field mask, set this flag to true.