String View API

様々な string_view 移行をカバー

std::string を使用する C++ 文字列フィールド API は、内部の protobuf 実装とその進化を著しく制約します。例えば、mutable_string_field() は std::string* を返し、フィールドを格納するために std::string を使用することを強制します。これにより、アリーナ上での相互作用が複雑になり、文字列ペイロードの割り当てがアリーナからかヒープからかを追跡するためにアリーナ寄付状態を維持する必要があります。

長期的には、すべてのランタイム API と生成された API を、string_view を入力として受け入れ、アクセサから返すように移行したいと考えています。このドキュメントでは、30.x リリース時点での移行の状況を説明します。

文字列フィールドアクセサ

エディション 2023 の一部として、string_type 機能が VIEW オプションと共にリリースされ、生成された string_view API への段階的な移行を可能にしました。この機能を使用すると、string および bytes フィールドのC++ 生成コードに影響します。

ctype との相互作用

エディション 2023 では、ctype をフィールドレベルで指定することは引き続き可能ですが、string_type はファイルレベルまたはフィールドレベルのいずれかで指定できます。同じフィールドで両方を指定することは許可されていません。ファイルレベルで string_type が設定されている場合、フィールドで指定された ctype が優先されます。

VIEW オプションを除き、string_type のすべての可能な値には、同じスペルで同じ動作をする対応する ctype 値があります。たとえば、どちらの enum も CORD 値を持っています。

エディション 2024 以降では、ctype を指定することはできなくなります。

生成された単一フィールド

エディション 2023 のこれらのフィールド定義のいずれかの場合

bytes foo = 1 [features.(pb.cpp).string_type=VIEW];
string foo = 1 [features.(pb.cpp).string_type=VIEW];

コンパイラは以下のアクセサメソッドを生成します

  • ::absl::string_view foo() const: フィールドの現在の値を返します。フィールドが設定されていない場合、デフォルト値を返します。
  • void clear_foo(): フィールドの値をクリアします。これを呼び出した後、foo() はデフォルト値を返します。
  • bool has_foo(): フィールドが設定されている場合、true を返します。
  • void set_foo(::absl::string_view value): フィールドの値を設定します。これを呼び出した後、has_foo() は true を返し、foo() は value のコピーを返します。
  • void set_foo(const string& value): フィールドの値を設定します。これを呼び出した後、has_foo() は true を返し、foo() は value のコピーを返します。
  • void set_foo(string&& value): 渡された文字列から移動して、フィールドの値を設定します。これを呼び出した後、has_foo() は true を返し、foo() は value を返します。
  • void set_foo(const char* value): C スタイルのヌル終端文字列を使用してフィールドの値を設定します。これを呼び出した後、has_foo() は true を返し、foo() は value のコピーを返します。

生成された繰り返しフィールド

これらのフィールド定義のいずれかの場合

repeated string foo = 1 [features.(pb.cpp).string_type=VIEW];
repeated bytes foo = 1 [features.(pb.cpp).string_type=VIEW];

コンパイラは以下のアクセサメソッドを生成します

  • int foo_size() const: フィールド内の現在の要素数を返します。
  • ::absl::string_view foo(int index) const: 指定されたゼロベースのインデックスにある要素を返します。[0, foo_size()-1] の範囲外のインデックスでこのメソッドを呼び出すと未定義の動作になります。
  • void set_foo(int index, ::absl::string_view value): 指定されたゼロベースのインデックスにある要素の値を設定します。
  • void set_foo(int index, const string& value): 指定されたゼロベースのインデックスにある要素の値を設定します。
  • void set_foo(int index, string&& value): 渡された文字列から移動して、指定されたゼロベースのインデックスにある要素の値を設定します。
  • void set_foo(int index, const char* value): C スタイルのヌル終端文字列を使用して、指定されたゼロベースのインデックスにある要素の値を設定します。
  • void add_foo(::absl::string_view value): 指定された値を持つ新しい要素をフィールドの末尾に追加します。
  • void add_foo(const string& value): 指定された値を持つ新しい要素をフィールドの末尾に追加します。
  • void add_foo(string&& value): 渡された文字列から移動して、新しい要素をフィールドの末尾に追加します。
  • void add_foo(const char* value): C スタイルのヌル終端文字列を使用して、新しい要素をフィールドの末尾に追加します。
  • void clear_foo(): フィールドからすべての要素を削除します。これを呼び出した後、foo_size() はゼロを返します。
  • const RepeatedPtrField<string>& foo() const: フィールドの要素を格納する基になる RepeatedPtrField を返します。このコンテナクラスは STL のようなイテレータやその他のメソッドを提供します。
  • RepeatedPtrField<string>* mutable_foo(): フィールドの要素を格納する基になる変更可能な RepeatedPtrField へのポインタを返します。このコンテナクラスは STL のようなイテレータやその他のメソッドを提供します。

生成された Oneof フィールド

これらの oneof フィールド定義のいずれかの場合

oneof example_name {
    string foo = 1 [features.(pb.cpp).string_type=VIEW];
    ...
}
oneof example_name {
    bytes foo = 1 [features.(pb.cpp).string_type=VIEW];
    ...
}

コンパイラは以下のアクセサメソッドを生成します

  • bool has_foo() const: oneof ケースが kFoo の場合、true を返します。
  • ::absl::string_view foo() const: oneof ケースが kFoo の場合、フィールドの現在の値を返します。それ以外の場合、デフォルト値を返します。
  • void set_foo(::absl::string_view value):
    • 同じ oneof 内の他の oneof フィールドが設定されている場合、clear_example_name() を呼び出します。
    • このフィールドの値を設定し、oneof ケースを kFoo に設定します。
    • has_foo() は true を返し、foo() は value のコピーを返し、example_name_case() は kFoo を返します。
  • void set_foo(const string& value): 最初の set_foo() と同様ですが、const string 参照からコピーします。
  • void set_foo(string&& value): 最初の set_foo() と同様ですが、渡された文字列から移動します。
  • void set_foo(const char* value): 最初の set_foo() と同様ですが、C スタイルのヌル終端文字列からコピーします。
  • void clear_foo():
    • oneof ケースが kFoo でない場合、何も変更されません。
    • oneof ケースが kFoo の場合、フィールドを解放し、oneof ケースをクリアします。has_foo() は false を返し、foo() はデフォルト値を返し、example_name_case() は EXAMPLE_NAME_NOT_SET を返します。

列挙名ヘルパー

エディション 2024 から、新しい機能 enum_name_uses_string_view が導入され、デフォルトで true になります。無効にしない限り、以下のような enum の場合、

enum Foo {
  VALUE_A = 0;
  VALUE_B = 5;
  VALUE_C = 1234;
}

プロトコルバッファコンパイラは、Foo enum に加えて、標準の生成コードに加えて、以下の新しい関数を生成します。

  • ::absl::string_view Foo_Name(int value): 指定された数値に対応する名前を返します。そのような値が存在しない場合、空の文字列を返します。複数の値がこの数値を持つ場合、最初に定義されたものが返されます。上記の例では、Foo_Name(5) は VALUE_B を返します。

これは、以下のように機能オーバーライドを追加することで、以前の動作に戻すことができます。

enum Foo {
  option features.(pb.cpp).enum_name_uses_string_view = false;

  VALUE_A = 0;
  VALUE_B = 5;
  VALUE_C = 1234;
}

その場合、名前ヘルパーは const string& Foo_Name(int value) に切り替わります。