Skip to content

Commit 51aa6af

Browse files
th0br0copybara-github
authored andcommitted
Fix stale Cord and extension sections in the Rust generated code guide.
Update the `[ctype = CORD]` section to remove a stale note that Cords are not implemented, clarify that `ProtoStringCow`/`ProtoBytesCow` are generated on the C++ kernel while the upb kernel uses standard string/bytes accessors, and fix the field names and code block fence. Update the extensions section so the `protobuf::ExtensionId` path, method trait bounds (`AsView`/`IntoView`/`AsMut`/`IntoMut`), and example constant names (`I32_EXT` and `REPEATED_I32_EXT`) match the generated Rust API. PiperOrigin-RevId: 1018031781
1 parent bc2f346 commit 51aa6af

1 file changed

Lines changed: 37 additions & 35 deletions

File tree

‎content/reference/rust/rust-generated.md‎

Lines changed: 37 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -420,11 +420,11 @@ instead.
420420

421421
`[ctype = CORD]` enables bytes and strings to be stored as an
422422
[absl::Cord](https://github.com/abseil/abseil-cpp/blob/master/absl/strings/cord.h)
423-
in C++ Protobuf. `absl::Cord` currently does not have an equivalent type in
424-
Rust . Protobuf Rust uses an enum to represent a cord
425-
field:
423+
in C++ Protobuf. Protobuf Rust does not expose these fields as a Rust Cord
424+
type. With the C++ kernel,
425+
Protobuf Rust uses an enum to represent a cord field:
426426

427-
```proto
427+
```rust
428428
enum ProtoStringCow<'a> {
429429
Owned(ProtoString),
430430
Borrowed(&'a ProtoStr)
@@ -449,21 +449,20 @@ bytes foo = 1 [ctype = CORD];
449449

450450
The compiler generates the following accessor methods:
451451

452-
* `fn my_field(&self) -> ProtoStringCow<'_>`: Returns the current value of the
452+
* `fn foo(&self) -> ProtoStringCow<'_>`: Returns the current value of the
453453
field. If the field is not set, returns the empty string/empty bytes.
454-
* `fn set_my_field(&mut self, value: IntoProxied<ProtoString>)`: Sets the
454+
* `fn set_foo(&mut self, value: impl IntoProxied<ProtoString>)`: Sets the
455455
field to `value`. After calling this function `foo()` returns `value` and
456456
`has_foo()` returns `true`.
457457
* `fn has_foo(&self) -> bool`: Returns `true` if the field is set.
458458
* `fn clear_foo(&mut self)`: Clears the value of the field. After calling
459459
this, `has_foo()` returns `false` and `foo()` returns the default value.
460-
Cords have not been implemented
461-
yet.
462460

463461
For fields of type `bytes` the compiler generates the `ProtoBytesCow` type
464462
instead.
465463

466-
The compiler generates the following accessor methods:
464+
With the upb kernel, `[ctype = CORD]` has no effect, and the compiler generates
465+
the same accessor methods as for a field without it. For example:
467466

468467
* `fn foo(&self) -> &ProtoStr`: Returns the current value of the field. If the
469468
field is not set, returns the empty string/empty bytes.
@@ -695,28 +694,31 @@ extend Foo {
695694
}
696695
```
697696

698-
The compiler generates constants of type `proto::ExtensionId` named `I32_EXT`
697+
The compiler generates constants of type `protobuf::ExtensionId` named `I32_EXT`
699698
and `REPEATED_I32_EXT`, which you can use to read and write the extensions on
700699
the `Foo` type.
701700

702701
### Accessing Extensions {#accessing-exts}
703702

704-
The `ExtensionId` type provides methods to interact with extensions on a
705-
message. These methods work with owned messages, views, and muts.
706-
707-
* `fn has(&self, msg: impl AsView<Target = M>) -> bool`: Returns `true` if the
708-
extension is set on the message. (Not available for repeated extensions, by
709-
design).
710-
* `fn get(&self, msg: impl AsView<Target = M>) -> View<'_, E>`: Returns the
711-
value of the extension. If not set, returns the default value. For repeated
712-
fields, returns a `RepeatedView`.
713-
* `fn set(&self, msg: impl AsMut<Target = M>, value: impl IntoProxied<E>)`:
714-
Sets the value of the extension.
715-
* `fn clear(&self, msg: impl AsMut<Target = M>)`: Clears the extension from
716-
the message.
717-
* `fn get_mut(&self, msg: impl AsMut<Target = M>) -> Mut<'_, E>`: Returns a
718-
mutable handle to the extension. For messages and repeated fields, this will
719-
create the field if it doesn't exist.
703+
The `ExtensionId<Extendee, T>` type provides methods to interact with extensions
704+
on a message, where `Extendee` is the extended message type (`Foo` above) and
705+
`T` is the type of the extension (`Repeated<E>` for repeated extensions). These
706+
methods work with owned messages, views, and muts.
707+
708+
* `fn has(&self, msg: impl AsView<Proxied = Extendee>) -> bool`: Returns
709+
`true` if the extension is set on the message. (Not available for repeated
710+
extensions, by design).
711+
* `fn get<'msg>(&self, msg: impl IntoView<'msg, Proxied = Extendee>) ->
712+
View<'msg, T>`: Returns the value of the extension. If not set, returns the
713+
default value. For repeated fields, returns a `RepeatedView`.
714+
* `fn set(&self, msg: impl AsMut<MutProxied = Extendee>, value: impl
715+
IntoProxied<T>)`: Sets the value of the extension.
716+
* `fn clear(&self, msg: impl AsMut<MutProxied = Extendee>)`: Clears the
717+
extension from the message.
718+
* `fn get_mut<'msg>(&self, msg: impl IntoMut<'msg, MutProxied = Extendee>) ->
719+
Mut<'msg, T>`: Returns a mutable handle to the extension. Only available for
720+
message and repeated extensions; this will create the field if it doesn't
721+
exist.
720722

721723
### Example Usage {#ext-example}
722724

@@ -726,23 +728,23 @@ use protobuf::prelude::*;
726728
let mut foo = xyz::Foo::new();
727729

728730
// Check and set scalar extension
729-
assert!(!xyz::INT32_EXT.has(&foo));
730-
xyz::INT32_EXT.set(&mut foo, 42);
731-
assert!(xyz::INT32_EXT.has(&foo));
732-
assert_eq!(xyz::INT32_EXT.get(&foo), 42);
731+
assert!(!xyz::I32_EXT.has(&foo));
732+
xyz::I32_EXT.set(&mut foo, 42);
733+
assert!(xyz::I32_EXT.has(&foo));
734+
assert_eq!(xyz::I32_EXT.get(&foo), 42);
733735

734736
// Clear scalar extension
735-
xyz::INT32_EXT.clear(&mut foo);
736-
assert!(!xyz::INT32_EXT.has(&foo));
737+
xyz::I32_EXT.clear(&mut foo);
738+
assert!(!xyz::I32_EXT.has(&foo));
737739

738740
// Working with repeated extensions
739741
{
740-
let mut rep_mut = xyz::REPEATED_INT32_EXT.get_mut(&mut foo);
742+
let mut rep_mut = xyz::REPEATED_I32_EXT.get_mut(&mut foo);
741743
rep_mut.push(1);
742744
rep_mut.push(2);
743745
}
744-
assert_eq!(xyz::REPEATED_INT32_EXT.get(&foo).len(), 2);
745-
assert_eq!(xyz::REPEATED_INT32_EXT.get(&foo).get(0), Some(1));
746+
assert_eq!(xyz::REPEATED_I32_EXT.get(&foo).len(), 2);
747+
assert_eq!(xyz::REPEATED_I32_EXT.get(&foo).get(0), Some(1));
746748
```
747749

748750
## Arena Allocation {#arena}

0 commit comments

Comments
 (0)