github.com/go-chrono/chrono@v0.0.0-20240102183611-532f0d0d7c34/offset_time.go (about)

     1  package chrono
     2  
     3  // OffsetTime has the same semantics as LocalTime, but with the addition of a timezone offset.
     4  type OffsetTime struct {
     5  	v, o int64
     6  }
     7  
     8  // OffsetTimeOf returns an OffsetTime that represents the specified hour, minute, second,
     9  // and nanosecond offset within the specified second.
    10  // The supplied offset is applied to the returned OffsetTime in the same manner as OffsetOf.
    11  // A valid time is between 00:00:00 and 99:59:59.999999999. If an invalid time is specified, this function panics.
    12  func OffsetTimeOf(hour, min, sec, nsec, offsetHours, offsetMins int) OffsetTime {
    13  	v, err := makeTime(hour, min, sec, nsec)
    14  	if err != nil {
    15  		panic(err.Error())
    16  	}
    17  	return OffsetTime{
    18  		v: v,
    19  		o: makeOffset(offsetHours, offsetMins),
    20  	}
    21  }
    22  
    23  // OfTimeOffset combines a LocalTime and Offset into an OffsetTime.
    24  func OfTimeOffset(time LocalTime, offset Offset) OffsetTime {
    25  	return OffsetTime{
    26  		v: time.v,
    27  		o: int64(offset),
    28  	}
    29  }
    30  
    31  // BusinessHour returns the hour specified by t.
    32  // If the hour is greater than 23, that hour is returned without normalization.
    33  func (t OffsetTime) BusinessHour() int {
    34  	return timeBusinessHour(t.v)
    35  }
    36  
    37  // Clock returns the hour, minute and second represented by t.
    38  // If hour is greater than 23, the returned value is normalized so as to fit within
    39  // the 24-hour clock as specified by ISO 8601, e.g. 25 is returned as 01.
    40  func (t OffsetTime) Clock() (hour, min, sec int) {
    41  	hour, min, sec, _ = fromTime(int64(t.v))
    42  	return
    43  }
    44  
    45  // Nanosecond returns the nanosecond offset within the second specified by t, in the range [0, 999999999].
    46  func (t OffsetTime) Nanosecond() int {
    47  	return timeNanoseconds(t.v)
    48  }
    49  
    50  // Sub returns the duration t-u.
    51  func (t OffsetTime) Sub(u OffsetTime) Extent {
    52  	return Extent(t.utc() - u.utc())
    53  }
    54  
    55  // Add returns the time t+v, maintaining the offset of t.
    56  // If the result exceeds the maximum representable time, this function panics.
    57  // If the result would be earlier than 00:00:00, the returned time is moved to the previous day,
    58  // e.g. 01:00:00 - 2 hours = 23:00:00.
    59  func (t OffsetTime) Add(v Extent) OffsetTime {
    60  	out, err := addTime(t.v, int64(v))
    61  	if err != nil {
    62  		panic(err.Error())
    63  	}
    64  	return OffsetTime{
    65  		v: out,
    66  		o: t.o,
    67  	}
    68  }
    69  
    70  // CanAdd returns false if Add would panic if passed the same argument.
    71  func (t OffsetTime) CanAdd(v Extent) bool {
    72  	_, err := addTime(t.v, int64(v))
    73  	return err == nil
    74  }
    75  
    76  // Compare compares t with t2. If t is before t2, it returns -1;
    77  // if t is after t2, it returns 1; if they're the same, it returns 0.
    78  func (t OffsetTime) Compare(t2 OffsetTime) int {
    79  	return compareTimes(t.utc(), t2.utc())
    80  }
    81  
    82  func (t OffsetTime) String() string {
    83  	hour, min, sec, nsec := fromTime(t.v)
    84  	return simpleTimeStr(hour, min, sec, nsec, &t.o)
    85  }
    86  
    87  // In returns a copy of t, adjusted to the supplied offset.
    88  func (t OffsetTime) In(offset Offset) OffsetTime {
    89  	return OffsetTime{
    90  		v: t.v - int64(t.o) + int64(offset),
    91  		o: int64(offset),
    92  	}
    93  }
    94  
    95  // UTC is a shortcut for t.In(UTC).
    96  func (t OffsetTime) UTC() OffsetTime {
    97  	return OffsetTime{v: t.utc()}
    98  }
    99  
   100  // Local returns the LocalTime represented by t.
   101  func (t OffsetTime) Local() LocalTime {
   102  	return LocalTime{v: t.v}
   103  }
   104  
   105  // Offset returns the offset of t.
   106  func (t OffsetTime) Offset() Offset {
   107  	return Offset(t.o)
   108  }
   109  
   110  func (t OffsetTime) utc() int64 {
   111  	return t.v - int64(t.o)
   112  }
   113  
   114  // Format returns a textual representation of the time value formatted according to the layout defined by the argument.
   115  // See the constants section of the documentation to see how to represent the layout format.
   116  // Date format specifiers encountered in the layout results in a panic.
   117  func (t OffsetTime) Format(layout string) string {
   118  	out, err := formatDateTimeOffset(layout, nil, &t.v, &t.o)
   119  	if err != nil {
   120  		panic(err.Error())
   121  	}
   122  	return out
   123  }
   124  
   125  // Parse a formatted string and store the value it represents in t.
   126  // See the constants section of the documentation to see how to represent the layout format.
   127  // Date format specifiers encountered in the layout results in a panic.
   128  func (t *OffsetTime) Parse(layout, value string) error {
   129  	v, o := t.v, t.o
   130  	if err := parseDateAndTime(layout, value, nil, &v, &o); err != nil {
   131  		return err
   132  	}
   133  
   134  	t.v = v
   135  	t.o = o
   136  	return nil
   137  }