Class: Textrepo::Timestamp

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable
Defined in:
lib/textrepo/timestamp.rb

Overview

Timestamp is generated from a Time object. It converts a time to string in the obvious format, such “20201023122400”.

Since the obvious format contains only year, month, day, hour, minute, and second, the resolution of time is a second. That is, two Time object those are different only in second will generates equal Timestamp objects.

If a client program of Textrepo::Timestamp wants to distinguish those Time objects, an attribute ‘suffix` could be used.

For example, the ‘suffix` will be converted into a 3 character string, such “012”, “345”, “678”, … etc. So, millisecond part of a Time object will be suitable to pass as `suffix` when creating a Timestamp object.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(time, suffix = nil) ⇒ Timestamp

Creates a Timestamp object from a Time object. In addition, an Integer can be passed as a suffix use.

Since Textrepo adapts 1 second as the time resolution, the subsec part of a given time will be ignored.

:call-seq:

new(Time, Integer = nil) -> Timestamp

Raises:



51
52
53
54
55
56
57
 
# File 'lib/textrepo/timestamp.rb', line 51

def initialize(time, suffix = nil)
  raise ArgumentRangeError, suffix unless is_valid_suffix?(suffix)
  parts = [:year, :mon, :day, :hour, :min, :sec].map{ |s| time.send(s) }
  @time = Time.new(*parts)
  @suffix = suffix
  @str = time_to_str(@time, @suffix)
end

Instance Attribute Details

#str ⇒ Object (readonly)

String object which is regarded as a value of Timestamp object. The value is generated from @time and @suffix.



39
40
41
 
# File 'lib/textrepo/timestamp.rb', line 39

def str
  @str
end

#suffix ⇒ Object (readonly)

An integer specified in ‘new` method to create the Timestamp object.



33
34
35
 
# File 'lib/textrepo/timestamp.rb', line 33

def suffix
  @suffix
end

#time ⇒ Object (readonly)

Time object which generates the Timestamp object.



28
29
30
 
# File 'lib/textrepo/timestamp.rb', line 28

def time
  @time
end

Class Method Details

.now(suffix = nil) ⇒ Object

Returns a Timestamp object generated from the current time.



316
317
318
 
# File 'lib/textrepo/timestamp.rb', line 316

def now(suffix = nil)
  Timestamp.new(Time.now, suffix)
end

.parse_s(stamp_str) ⇒ Object

Generate a Timestamp object from a string which represents a timestamp, such “20201028163400”.

Raises InvalidTimestampStringError if cannot convert the argument into a Timestamp object.

:call-seq:

parse_s("20201028163400") -> Timestamp
parse_s("20201028163529_034") -> Timestamp

Raises:



350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/textrepo/timestamp.rb', line 350

def parse_s(stamp_str)
  raise InvalidTimestampStringError, "(nil)" if stamp_str.nil?
  raise InvalidTimestampStringError, "(empty string)" if stamp_str.empty?
  raise InvalidTimestampStringError, stamp_str if stamp_str.size < 14

  begin
    ye, mo, da, ho, mi, se, sfx = split_stamp(stamp_str).map(&:to_i)
    Timestamp.new(Time.new(ye, mo, da, ho, mi, se), sfx)
  rescue ArgumentRangeError, ArgumentError => _
    raise InvalidTimestampStringError, stamp_str
  end
end

.split_stamp(stamp_str) ⇒ Object

Splits a string which represents a timestamp into components. Each component represents a part of constructs to instantiate a Time object.

 yyyymoddhhmiss sfx      yyyy    mo    dd    hh    mi    ss    sfx
"20201230123456"     -> "2020", "12", "30", "12", "34", "56"
"20201230123456_789" -> "2020", "12", "30", "12", "34", "56", "789"

Raises InvalidTimestampStringError if nil was passed as an arguemnt.

Raises:



331
332
333
334
335
336
337
 
# File 'lib/textrepo/timestamp.rb', line 331

def split_stamp(stamp_str)
  raise InvalidTimestampStringError, "(nil)" if stamp_str.nil?
  #    yyyy  mo    dd    hh    mi      ss      sfx
  a = [0..3, 4..5, 6..7, 8..9, 10..11, 12..13, 15..17].map {|r| stamp_str[r]}
  a.delete_at(-1) if a[-1].nil?
  a.map{|e| e || "" }
end

Instance Method Details

#+(seconds) ⇒ Object

Returns a new Timestamp object which is given seconds ahead. Even if the suffix is not nil, the new Timestamp object will always have nil as its suffix.

:call-seq:

+(Integer) -> Timestamp



112
113
114
 
# File 'lib/textrepo/timestamp.rb', line 112

def +(seconds)
  Timestamp.new(@time + seconds, nil)
end

#-(arg) ⇒ Object

Returns difference of seconds between self and an argument. If the argument is an Integer object, returns a new Timestamp object which is the given seconds behind.

Even if the suffix is not nil, the new Timestamp object will always have nil as its suffix.

:call-seq:

-(Time) -> Float
-(Timetamp) -> Float
-(Integer) -> Timestamp



129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/textrepo/timestamp.rb', line 129

def -(arg)
  case arg
  when Time
    @time - arg
  when Timestamp
    @time - arg.time
  when Integer
    Timestamp.new(@time - arg, nil)
  when NilClass
    raise TypeError, "can't convert nil into an exact number"
  else
    raise ArgumentError, arg
  end
end

#<=>(other) ⇒ Object

:nodoc:



59
60
61
62
63
64
65
66
 
# File 'lib/textrepo/timestamp.rb', line 59

def <=>(other)              # :nodoc:
  result = (self.time <=> other.time)

  sfx = self.suffix || 0
  osfx = other.suffix || 0

  result == 0 ? (sfx <=> osfx) : result
end

#[](*args) ⇒ Object Also known as: slice

Returns a character or sub-string specified with args.

Following type of objects could be used as args:

  • Integer : specifies an index

  • Integer, Integer : specified an start index and length of sub-string

  • Range : specified range of sub-string

  • Symbol : specified a type of part

Following symbols could be specified:

  • :year

  • :mon, or :month

  • :day

  • :hour

  • :min

  • :sec

  • :suffix

:call-seq:

self[nth as Integer] -> String | nil
self[nth as Integer, len as Integer] -> String | nil
self[range as Range] -> String
self[symbol as Symbol] -> String

Raises:

  • (ArgumentError) 


190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/textrepo/timestamp.rb', line 190

def [](*args)
  raise ArgumentError, "wrong number of arguments (given %s, execpted 1..2)" % args.size unless (1..2).include?(args.size)

  arg = args[0]
  case arg
  when Symbol, String
    key = arg.to_sym
    if key == :suffix
      @suffix.nil? ? nil : FMTSTRS[key] % @suffix
    elsif FMTSTRS.keys.include?(key)
      @time.strftime(FMTSTRS[key])
    else
      nil
    end
  else
    @str[*args]
  end
end

#eql?(other) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/textrepo/timestamp.rb', line 100

def eql?(other)             # :nodoc:
  other.is_a?(Timestamp) && @time == other.time && @suffix == other.suffix
end

#freeze ⇒ Object 



283
 
# File 'lib/textrepo/timestamp.rb', line 283

def freeze;  @time.freeze;  @suffix.freeze;  @str.freeze;  end

#hash ⇒ Object

:startdoc:



96
97
98
 
# File 'lib/textrepo/timestamp.rb', line 96

def hash                    # :nodoc:
  @str[0, 14].to_i * 1000 + @suffix.to_i
end

#initialize_copy(_) ⇒ Object

:stopdoc:



277
278
279
280
281
 
# File 'lib/textrepo/timestamp.rb', line 277

def initialize_copy(_)
  @time = @time.dup
  @suffix = @suffix
  @str = @str.dup
end

#next(use_suffix = nil) ⇒ Object Also known as: succ

Returns a Timestamp object which has a next Time object.

If true was passed as an argument, use incremented suffix as base instead of a next Time object.

For example,

"20201110160100"     -> "20201110160101"     (false as arg)
"20201110160100"     -> "20201110160100_001" (true as arg)
"20201110160200_001" -> "20201110160201"     (false as arg)
"20201110160200_001" -> "20201110160200_002" (true as arg)

If suffix was 999 before call this method, raises ArgumentRangeError.



227
228
229
230
231
232
233
 
# File 'lib/textrepo/timestamp.rb', line 227

def next(use_suffix = nil)
  if use_suffix
    Timestamp.new(@time, increase_suffix(@suffix.to_i, 1))
  else
    Timestamp.new(@time + 1, nil)
  end
end

#next!(use_suffix = nil) ⇒ Object Also known as: succ!

Updates the time value to a next Time destructively. See the document for Timestamp#next for more details.

If suffix was 999 before call this method, raises ArgumentRangeError.



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/textrepo/timestamp.rb', line 244

def next!(use_suffix = nil)
  if use_suffix
    @suffix = increase_suffix(@suffix.to_i, 1)
  else
    @time += 1
    @suffix = nil
  end
  @str = time_to_str(@time, @suffix)
  self
end

#split(_ = $;, _ = 0, &blk) ⇒ Object

Splits the timestamp string into array of time parts, such as year, month, day, hour, minute, and second. Then, returns the array.

When a block was passed, it would apply to each part of the array. Then, returns self.



265
266
267
268
269
270
271
272
273
 
# File 'lib/textrepo/timestamp.rb', line 265

def split(_ = $;, _ = 0, &blk)
  parts = Timestamp.split_stamp(@str)
  if blk.nil?
    parts
  else
    parts.each { |p| yield p }
    self
  end
end

#taint ⇒ Object 



284
 
# File 'lib/textrepo/timestamp.rb', line 284

def taint;   @time.taint;   @suffix.taint;   @str.taint;   end

#to_a ⇒ Object

Generates an array contains components of the Timestamp object. Components means “year”, “mon”, “day”, “hour”, “min”, “sec”, and “suffix”.



149
150
151
152
153
 
# File 'lib/textrepo/timestamp.rb', line 149

def to_a
  a = [:year, :mon, :day, :hour, :min, :sec, :suffix].map { |s| self.send(s) }
  a.delete_at(-1) if a[-1].nil?
  a
end

#to_s ⇒ Object Also known as: to_str

Generates an obvious time string.

 %Y   %m %d %H %M %S  suffix
"2020-12-30 12:34:56  (0 | nil)" -> "20201230123456"
"2020-12-30 12:34:56  (7)"       -> "20201230123456_007"



75
76
77
 
# File 'lib/textrepo/timestamp.rb', line 75

def to_s
  @str
end

#untaint ⇒ Object 



285
 
# File 'lib/textrepo/timestamp.rb', line 285

def untaint; @time.untaint; @suffix.untaint; @str.untaint; end