Struct Duration 

pub struct Duration {
    pub seconds: i64,
    pub nanos: i32,
    /* private fields */
}

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like “day” or “month”. It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

Examples

Example 1: Compute Duration from two Timestamps in pseudo code.

Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;

duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) {
  duration.seconds += 1;
  duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
  duration.seconds -= 1;
  duration.nanos += 1000000000;
}

Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;

end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) {
  end.seconds -= 1;
  end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
  end.seconds += 1;
  end.nanos -= 1000000000;
}

Example 3: Compute Duration from datetime.timedelta in Python.

td = datetime.timedelta(days=3, minutes=10)
duration = Duration()
duration.FromTimedelta(td)

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix “s” (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as “3s”, while 3 seconds and 1 nanosecond should be expressed in JSON format as “3.000000001s”, and 3 seconds and 1 microsecond should be expressed in JSON format as “3.000001s”.

Fields

seconds: i64

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

Field 1: seconds

nanos: i32

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

Field 2: nanos

Implementations

impl Duration

pub fn from_secs(seconds: i64) -> Self

Create a Duration from a whole number of seconds.

pub fn from_secs_nanos(seconds: i64, nanos: i32) -> Self

Create a Duration from seconds and nanoseconds.

Panics

Panics in debug mode if nanos is outside [-999_999_999, 999_999_999] or if its sign is inconsistent with seconds. When seconds is zero, nanos may be positive, negative, or zero. In release mode the value is stored as-is. Use Duration::from_secs_nanos_checked for a variant that returns None on invalid input.

pub fn from_secs_nanos_checked(seconds: i64, nanos: i32) -> Option<Self>

Create a Duration from seconds and nanoseconds, returning None if nanos is out of range or has a sign inconsistent with seconds.

pub fn from_millis(millis: i64) -> Self

Create a Duration from a number of milliseconds.

The sign of millis determines the sign of both seconds and the sub-second nanos field, per the protobuf sign-consistency rule.

pub fn from_micros(micros: i64) -> Self

Create a Duration from a number of microseconds.

pub fn from_nanos(nanos: i64) -> Self

Create a Duration from a number of nanoseconds.

impl Duration

pub const TYPE_URL: &'static str = "type.googleapis.com/google.protobuf.Duration"

Protobuf type URL for this message, for use with Any::pack and Any::unpack_if.

Format: type.googleapis.com/<fully.qualified.TypeName>

Trait Implementations

impl<'arbitrary> Arbitrary<'arbitrary> for Duration

Available on crate feature arbitrary only.

fn arbitrary(u: &mut Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the given unstructured data.

fn arbitrary_take_rest(u: Unstructured<'arbitrary>) -> Result<Self>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn try_size_hint( depth: usize, ) -> Result<(usize, Option<usize>), MaxRecursionReached>

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

impl Clone for Duration

fn clone(&self) -> Duration

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Duration

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Duration

fn default() -> Duration

Returns the “default value” for a type.

impl DefaultInstance for Duration

fn default_instance() -> &'static Self

Return a reference to the single default instance of this type.

impl<'de> Deserialize<'de> for Duration

Available on crate feature json only.

fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error>

Deserializes from a decimal seconds string (e.g. "1.5s").

impl ExtensionSet for Duration

const PROTO_FQN: &'static str = "google.protobuf.Duration"

Fully-qualified proto type name of this message (no leading dot), e.g. "google.protobuf.FieldOptions".

fn unknown_fields(&self) -> &UnknownFields

Immutable access to the extendee’s unknown-field storage.

fn unknown_fields_mut(&mut self) -> &mut UnknownFields

Mutable access to the extendee’s unknown-field storage.

fn extension<C>(&self, ext: &Extension<C>) -> <C as ExtensionCodec>::Output

where C: ExtensionCodec,

Read an extension value.

fn set_extension<C>( &mut self, ext: &Extension<C>, value: <C as ExtensionCodec>::Value, )

where C: ExtensionCodec,

Write an extension value, replacing any prior occurrences.

fn try_set_extension<C>( &mut self, ext: &Extension<C>, value: <C as ExtensionCodec>::Value, ) -> Result<(), EncodeError>

where C: ExtensionCodec,

Write an extension value, replacing any prior occurrences — returning an error instead of panicking if a message-typed value’s encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn has_extension<C>(&self, ext: &Extension<C>) -> bool

where C: ExtensionCodec,

Returns true if any record at the extension’s field number is present.

fn clear_extension<C>(&mut self, ext: &Extension<C>)

where C: ExtensionCodec,

Remove all records at the extension’s field number.

fn extension_or_default<C>( &self, ext: &Extension<C>, ) -> <C as ExtensionCodec>::Value

where C: ExtensionCodec<Output = Option<<C as ExtensionCodec>::Value>>, <C as ExtensionCodec>::Value: Default,

Read a singular extension value, returning the proto2 [default = ...] value if absent, or the type’s Default if no proto default was declared.

impl From<Duration> for Duration

Available on crate feature std only.

fn from(d: Duration) -> Self

Convert a std::time::Duration to a protobuf Duration.

Saturation

Durations whose as_secs() exceeds i64::MAX (~292 billion years) are saturated to i64::MAX seconds rather than wrapping, which would produce an incorrect negative value.

impl From<SignedDuration> for Duration

Available on crate feature jiff only.

fn from(d: SignedDuration) -> Self

Convert a jiff::SignedDuration to a protobuf Duration.

Infallible: both types represent a signed duration as a sign-consistent seconds + sub-second nanos pair, so this is a direct field copy.

Warning: proto JSON spec range

jiff::SignedDuration ranges to ±i64::MAX seconds (~2.9e11 years), while the proto spec restricts Duration to ±315,576,000,000 seconds (~10,000 years). A SignedDuration beyond that converts without error here — binary encoding round-trips it — but the resulting Duration will fail JSON serialization (json feature), which enforces the spec range.

Examples

use buffa_types::Duration;

let sd = jiff::SignedDuration::new(1, 500_000_000);
let proto: Duration = sd.into();
assert_eq!(proto.seconds, 1);
assert_eq!(proto.nanos, 500_000_000);

impl From<TimeDelta> for Duration

Available on crate feature chrono only.

fn from(d: TimeDelta) -> Self

Convert a chrono::TimeDelta to a protobuf Duration.

Both sides represent a signed duration as seconds + subsec_nanos with sign-consistent components, so this is a direct field copy.

Warning: proto JSON spec range

chrono::TimeDelta ranges to ±i64::MAX milliseconds (~9.2e15 seconds), while the proto spec restricts Duration to ±315,576,000,000 seconds (~10,000 years). A TimeDelta beyond that converts without error here — binary encoding round-trips it — but the resulting Duration will fail JSON serialization (json feature), which enforces the spec range.

Examples

use buffa_types::Duration;
use chrono::TimeDelta;

let proto: Duration = TimeDelta::milliseconds(1_500).into();
assert_eq!(proto.seconds, 1);
assert_eq!(proto.nanos, 500_000_000);

impl HasMessageView for Duration

type View<'a> = DurationView<'a>

The zero-copy view of Self, borrowing from a buffer with lifetime 'a.

type ViewHandle = DurationOwnedView

The generated 'static owned-view handle for Self (FooOwnedView).

fn decode_view(buf: &[u8]) -> Result<Self::View<'_>, DecodeError>

Decode a borrowed View from a byte slice.

fn decode_view_with_options<'a>( buf: &'a [u8], opts: &DecodeOptions, ) -> Result<Self::View<'a>, DecodeError>

Decode a borrowed View under custom DecodeOptions (recursion limit, max message size, unknown-field limit).

fn decode_view_handle(bytes: Bytes) -> Result<Self::ViewHandle, DecodeError>

Decode a ViewHandle from a Bytes buffer.

fn decode_view_handle_with_options( bytes: Bytes, opts: &DecodeOptions, ) -> Result<Self::ViewHandle, DecodeError>

Decode a ViewHandle with custom DecodeOptions (recursion limit, max message size).

impl Message for Duration

fn compute_size(&self, _cache: &mut SizeCache) -> u32

Returns the total encoded size in bytes.

Accumulates in u64 (which cannot overflow for in-memory data) and saturates to u32 at return, so a message whose encoded size exceeds the 2 GiB protobuf limit yields a value above ::buffa::MAX_MESSAGE_BYTES that the encode entry points reject, never a silently wrapped size.

fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink)

Write this message’s encoded bytes to a buffer, consuming nested-message sizes from cache (populated by a prior compute_size call on the same cache).

fn merge_field( &mut self, tag: Tag, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Processes a single already-decoded tag and its associated field data from buf.

fn clear(&mut self)

Clear all fields to their default values.

fn encode(&self, buf: &mut impl EncodeSink)

Compute size, then write. This is the primary encoding API.

fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError>

Encode, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_with_cache(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink)

Encode using a caller-supplied SizeCache, for reuse across many encodes in a hot loop. Clears the cache first.

fn try_encode_with_cache( &self, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode with a caller-supplied SizeCache, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES). Clears the cache first.

fn try_encode_bounded( &self, max_bytes: u32, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Encode this message into buf only if its encoded size fits within max_bytes, using a single size pass that is then reused for the write.

fn try_encode_bounded_with_cache( &self, max_bytes: u32, cache: &mut SizeCache, buf: &mut impl EncodeSink, ) -> Result<u32, EncodeError>

Like try_encode_bounded but reuses an existing SizeCache, clearing it first.

fn encoded_len(&self) -> u32

Compute the encoded byte size of this message.

fn try_encoded_len(&self) -> Result<u32, EncodeError>

Compute the encoded byte size, returning an error instead of panicking if it exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_length_delimited(&self, buf: &mut impl EncodeSink)

Encode this message as a length-delimited byte sequence.

fn try_encode_length_delimited( &self, buf: &mut impl EncodeSink, ) -> Result<(), EncodeError>

Encode as a length-delimited byte sequence, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_to_vec(&self) -> Vec<u8>

Encode this message to a new Vec<u8>.

fn try_encode_to_vec(&self) -> Result<Vec<u8>, EncodeError>

Encode to a new Vec<u8>, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn encode_to_bytes(&self) -> Bytes

Encode this message to a new bytes::Bytes.

fn try_encode_to_bytes(&self) -> Result<Bytes, EncodeError>

Encode to a new bytes::Bytes, returning an error instead of panicking if the encoded size exceeds the 2 GiB protobuf limit (MAX_MESSAGE_BYTES).

fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>

where Self: Sized,

Decode a message from a buffer.

fn decode_from_slice(data: &[u8]) -> Result<Self, DecodeError>

where Self: Sized,

Decode a message from a byte slice.

fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>

where Self: Sized,

Decode a length-delimited message from a buffer.

fn merge_to_limit( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, limit: usize, ) -> Result<(), DecodeError>

Merge fields from a buffer until buf.remaining() reaches limit.

fn merge_group( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, field_number: u32, ) -> Result<(), DecodeError>

Merges a group-encoded message from buf, reading fields until an EndGroup tag with the given field_number is encountered.

fn merge( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Merge fields from a buffer into this message.

fn merge_from_slice(&mut self, data: &[u8]) -> Result<(), DecodeError>

Merge fields from a byte slice into this message.

fn merge_length_delimited( &mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>, ) -> Result<(), DecodeError>

Merge fields from a length-delimited sub-message payload into this message.

impl MessageName for Duration

const PACKAGE: &'static str = "google.protobuf"

The protobuf package the message is declared in.

const NAME: &'static str = "Duration"

The unqualified message name, with . between nesting levels.

const FULL_NAME: &'static str = "google.protobuf.Duration"

The fully-qualified protobuf type name with no leading dot.

const TYPE_URL: &'static str = "type.googleapis.com/google.protobuf.Duration"

The google.protobuf.Any.type_url form for this message.

impl PartialEq for Duration

fn eq(&self, other: &Duration) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl ReflectElement for Duration

Available on crate feature reflect only.

fn as_value_ref(&self) -> ValueRef<'_>

Borrow this element as a ValueRef.

impl ReflectMessage for Duration

Available on crate feature reflect only.

fn message_descriptor(&self) -> &MessageDescriptor

The descriptor for this message type.

fn pool(&self) -> &Arc<DescriptorPool>

The pool the descriptor lives in. Use this to dereference MessageIndex / EnumIndex from FieldKind, or Arc::clone it to construct sibling DynamicMessages while navigating nested fields.

fn unknown_fields(&self) -> &UnknownFields

The fields preserved from decode that the message’s descriptor does not recognize.

fn get(&self, field: &FieldDescriptor) -> ValueRef<'_>

Get a field’s value.

fn has(&self, field: &FieldDescriptor) -> bool

Whether a field is present.

fn for_each_set(&self, f: &mut dyn FnMut(&FieldDescriptor, ValueRef<'_>))

Visit every set field.

fn to_dynamic(&self) -> DynamicMessage

Snapshot this message as an owned DynamicMessage.

fn which_oneof(&self, oneof: &OneofDescriptor) -> Option<&FieldDescriptor>

Which member of oneof is set, if any.

impl Reflectable for Duration

Available on crate feature reflect only.

fn reflect(&self) -> ReflectCow<'_>

Vtable-mode reflective handle: borrows self directly. No encode/decode round-trip and no allocation — the reflective accessors read this message’s fields in place.

impl Serialize for Duration

Available on crate feature json only.

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serializes as a decimal seconds string (e.g. "1.5s", "-0.001s").

Errors

Returns a serialization error if the duration is outside the proto spec range of ±315,576,000,000 seconds, or if nanos is invalid.

impl StructuralPartialEq for Duration

impl TextFormat for Duration

fn encode_text(&self, enc: &mut TextEncoder<'_>) -> Result

Write this message’s fields to enc.

fn merge_text(&mut self, dec: &mut TextDecoder<'_>) -> Result<(), ParseError>

Merge fields from dec into this message.

impl TryFrom<Duration> for Duration

Available on crate feature std only.

fn try_from(d: Duration) -> Result<Self, Self::Error>

Convert a protobuf Duration to a std::time::Duration.

Errors

Returns DurationError::InvalidNanos if nanos is outside [-999_999_999, 999_999_999] or if its sign is inconsistent with seconds (e.g. positive nanos with negative seconds).

Returns DurationError::NegativeDuration if the duration is negative but otherwise well-formed (e.g. seconds < 0, nanos ≤ 0), since std::time::Duration cannot represent negative values.

type Error = DurationError

The type returned in the event of a conversion error.

impl TryFrom<Duration> for TimeDelta

Available on crate feature chrono only.

fn try_from(d: Duration) -> Result<Self, Self::Error>

Convert a protobuf Duration to a chrono::TimeDelta.

Examples

use buffa_types::{Duration, DurationChronoError};
use chrono::TimeDelta;

let proto = Duration {
    seconds: 2,
    nanos: 250_000_000,
    ..Default::default()
};
let td: TimeDelta = proto.try_into().unwrap();
assert_eq!(td, TimeDelta::milliseconds(2_250));

let too_big = Duration {
    seconds: i64::MAX,
    nanos: 0,
    ..Default::default()
};
assert_eq!(
    TimeDelta::try_from(too_big),
    Err(DurationChronoError::Overflow)
);

Errors

Returns DurationChronoError::InvalidNanos if nanos is outside [-999_999_999, 999_999_999] or if its sign is inconsistent with seconds. Such values never come from the From<chrono::TimeDelta> impl, but seconds and nanos are independent wire fields, so a decoded Duration can carry any combination — the proto spec declares sign-mismatched ones invalid, and this conversion rejects them rather than silently reinterpreting them arithmetically.

Returns DurationChronoError::Overflow if the total duration exceeds chrono::TimeDelta’s representable range (±i64::MAX milliseconds).

type Error = DurationChronoError

The type returned in the event of a conversion error.

impl TryFrom<Duration> for SignedDuration

Available on crate feature jiff only.

fn try_from(d: Duration) -> Result<Self, Self::Error>

Convert a protobuf Duration to a jiff::SignedDuration.

Examples

use buffa_types::Duration;

let proto = Duration {
    seconds: 2,
    nanos: 250_000_000,
    ..Default::default()
};
let sd: jiff::SignedDuration = proto.try_into().unwrap();
assert_eq!(sd, jiff::SignedDuration::new(2, 250_000_000));

Errors

Returns DurationJiffError::InvalidNanos if nanos is outside [-999_999_999, 999_999_999] or if its sign is inconsistent with seconds. Such values never come from the From<jiff::SignedDuration> impl, but seconds and nanos are independent wire fields, so a decoded Duration can carry any combination — the proto spec declares sign-mismatched ones invalid, and this conversion rejects them rather than letting SignedDuration::new silently re-normalize them.

type Error = DurationJiffError

The type returned in the event of a conversion error.