package timestamppb

Import Path
	google.golang.org/protobuf/types/known/timestamppb (on go.dev)

Dependency Relation
	imports 5 packages, and imported by one package


Involved Source Files

	
		Package timestamppb contains generated types for google/protobuf/timestamp.proto.

		The Timestamp message represents a timestamp,
		an instant in time since the Unix epoch (January 1st, 1970).

		Conversion to a Go Time

		The AsTime method can be used to convert a Timestamp message to a
		standard Go time.Time value in UTC:

			t := ts.AsTime()
			... // make use of t as a time.Time

		Converting to a time.Time is a common operation so that the extensive
		set of time-based operations provided by the time package can be leveraged.
		See https://golang.org/pkg/time for more information.

		The AsTime method performs the conversion on a best-effort basis. Timestamps
		with denormal values (e.g., nanoseconds beyond 0 and 99999999, inclusive)
		are normalized during the conversion to a time.Time. To manually check for
		invalid Timestamps per the documented limitations in timestamp.proto,
		additionally call the CheckValid method:

			if err := ts.CheckValid(); err != nil {
				... // handle error
			}

		Conversion from a Go Time

		The timestamppb.New function can be used to construct a Timestamp message
		from a standard Go time.Time value:

			ts := timestamppb.New(t)
			... // make use of ts as a *timestamppb.Timestamp

		In order to construct a Timestamp representing the current time, use Now:

			ts := timestamppb.Now()
			... // make use of ts as a *timestamppb.Timestamp


Package-Level Type Names (only one, which is exported)


	/* sort exporteds by:  |  */
	
		A Timestamp represents a point in time independent of any time zone or local
		calendar, encoded as a count of seconds and fractions of seconds at
		nanosecond resolution. The count is relative to an epoch at UTC midnight on
		January 1, 1970, in the proleptic Gregorian calendar which extends the
		Gregorian calendar backwards to year one.

		All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap
		second table is needed for interpretation, using a [24-hour linear
		smear](https://developers.google.com/time/smear).

		The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By
		restricting to that range, we ensure that we can convert to and from [RFC
		3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.

		# Examples

		Example 1: Compute Timestamp from POSIX `time()`.

		    Timestamp timestamp;
		    timestamp.set_seconds(time(NULL));
		    timestamp.set_nanos(0);

		Example 2: Compute Timestamp from POSIX `gettimeofday()`.

		    struct timeval tv;
		    gettimeofday(&tv, NULL);

		    Timestamp timestamp;
		    timestamp.set_seconds(tv.tv_sec);
		    timestamp.set_nanos(tv.tv_usec * 1000);

		Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.

		    FILETIME ft;
		    GetSystemTimeAsFileTime(&ft);
		    UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

		    // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
		    // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
		    Timestamp timestamp;
		    timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
		    timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

		Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.

		    long millis = System.currentTimeMillis();

		    Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
		        .setNanos((int) ((millis % 1000) * 1000000)).build();

		Example 5: Compute Timestamp from Java `Instant.now()`.

		    Instant now = Instant.now();

		    Timestamp timestamp =
		        Timestamp.newBuilder().setSeconds(now.getEpochSecond())
		            .setNanos(now.getNano()).build();

		Example 6: Compute Timestamp from current time in Python.

		    timestamp = Timestamp()
		    timestamp.GetCurrentTime()

		# JSON Mapping

		In JSON format, the Timestamp type is encoded as a string in the
		[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
		format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
		where {year} is always expressed using four digits while {month}, {day},
		{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
		seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
		are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
		is required. A proto3 JSON serializer should always use UTC (as indicated by
		"Z") when printing the Timestamp type and a proto3 JSON parser should be
		able to accept both UTC and other timezones (as indicated by an offset).

		For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
		01:30 UTC on January 15, 2017.

		In JavaScript, one can convert a Date object to this format using the
		standard
		[toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
		method. In Python, a standard `datetime.datetime` object can be converted
		to this format using
		[`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
		the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
		the Joda Time's [`ISODateTimeFormat.dateTime()`](
		http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D
		) to obtain a formatter capable of generating timestamps in this format.

		
			
				Non-negative fractions of a second at nanosecond resolution. Negative
				second values with fractions must still have non-negative nanos values
				that count forward in time. Must be from 0 to 999,999,999
				inclusive.

			
				Represents seconds of UTC time since Unix epoch
				1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
				9999-12-31T23:59:59Z inclusive.

			
		
			
				AsTime converts x to a time.Time.

			
				CheckValid returns an error if the timestamp is invalid.
				In particular, it checks whether the value represents a date that is
				in the range of 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.
				An error is reported for a nil Timestamp.

			
				Deprecated: Use Timestamp.ProtoReflect.Descriptor instead.

			(*T) GetNanos() int32
			(*T) GetSeconds() int64
			
				IsValid reports whether the timestamp is valid.
				It is equivalent to CheckValid == nil.

			(*T) ProtoMessage()
			(*T) ProtoReflect() protoreflect.Message
			(*T) Reset()
			(*T) String() string
			
		
			*T : google.golang.org/protobuf/reflect/protoreflect.ProtoMessage
			*T : google.golang.org/protobuf/runtime/protoiface.MessageV1
			*T : fmt.Stringer
			
		
			func New(t time.Time) *Timestamp
			func Now() *Timestamp
			func github.com/golang/protobuf/ptypes.TimestampNow() *timestamppb.Timestamp
			func github.com/golang/protobuf/ptypes.TimestampProto(t time.Time) (*timestamppb.Timestamp, error)
		
			func github.com/golang/protobuf/ptypes.Timestamp(ts *timestamppb.Timestamp) (time.Time, error)
			func github.com/golang/protobuf/ptypes.TimestampString(ts *timestamppb.Timestamp) string
			




Package-Level Functions (total 5, in which 2 are exported)


	
		New constructs a new Timestamp from the provided time.Time.


	
		Now constructs a new Timestamp from the current time.


	



Package-Level Constants (total 4, none are exported)