ts.el
1.0.0
ts é uma biblioteca de data e hora para Emacs. Seu objetivo é ser mais conveniente do que padrões como (string-to-number (format-time-string "%Y")) fornecendo acessadores fáceis, como (ts-year (ts-now)) .
Para melhorar o desempenho (significativamente), as partes de data formatadas são computadas lentamente, em vez de quando um objeto de carimbo de data/hora é instanciado, e as partes computadas são então armazenadas em cache para acesso posterior sem recalcular. Nos bastidores, isso evita chamadas desnecessárias (string-to-number (format-time-string... , que são surpreendentemente caras.
Obtenha partes da data atual:
; ; When the current date is 2018-12-08 23:09:14 -0600:
(ts-year (ts-now)) ; => 2018
(ts-month (ts-now)) ; => 12
(ts-day (ts-now)) ; => 8
(ts-hour (ts-now)) ; => 23
(ts-minute (ts-now)) ; => 9
(ts-second (ts-now)) ; => 14
(ts-tz-offset (ts-now)) ; => "-0600"
(ts-dow (ts-now)) ; => 6
(ts-day-abbr (ts-now)) ; => "Sat"
(ts-day-name (ts-now)) ; => "Saturday"
(ts-month-abbr (ts-now)) ; => "Dec"
(ts-month-name (ts-now)) ; => "December"
(ts-tz-abbr (ts-now)) ; => "CST"Incrementar a data atual:
; ; By 10 years:
( list :now (ts-format)
:future (ts-format (ts-adjust 'year 10 (ts-now))))
; ;=> ( :now "2018-12-15 22:00:34 -0600"
; ; :future "2028-12-15 22:00:34 -0600")
; ; By 10 years, 2 months, 3 days, 5 hours, and 4 seconds:
( list :now (ts-format)
:future (ts-format
(ts-adjust 'year 10 'month 2 'day 3
'hour 5 'second 4
(ts-now))))
; ;=> ( :now "2018-12-15 22:02:31 -0600"
; ; :future "2029-02-19 03:02:35 -0600")Que dia da semana foi há 2 dias?
(ts-day-name (ts-dec 'day 2 (ts-now))) ; => "Thursday"
; ; Or, with threading macros:
( thread-last (ts-now) (ts-dec 'day 2 ) ts-day-name) ; => "Thursday"
(-> > (ts-now) (ts-dec 'day 2 ) ts-day-name) ; => "Thursday"Obtenha o carimbo de data/hora deste horário na semana passada:
(ts-unix (ts-adjust 'day -7 (ts-now)))
; ;=> 1543728398.0
; ; To confirm that the difference really is 7 days:
( / ( - (ts-unix (ts-now))
(ts-unix (ts-adjust 'day -7 (ts-now))))
86400 )
; ;=> 7.000000567521762
; ; Or human-friendly as a list:
(ts-human-duration
(ts-difference (ts-now)
(ts-dec 'day 7 (ts-now))))
; ;=> (:years 0 :days 7 :hours 0 :minutes 0 :seconds 0)
; ; Or as a string:
(ts-human-format-duration
(ts-difference (ts-now)
(ts-dec 'day 7 (ts-now))))
; ;=> "7 days"
; ; Or confirm by formatting:
( list :now (ts-format)
:last-week (ts-format (ts-dec 'day 7 (ts-now))))
; ;=> ( :now "2018-12-08 23:31:37 -0600"
; ; :last-week "2018-12-01 23:31:37 -0600") Alguns acessadores têm aliases semelhantes aos construtores format-time-string :
(ts-hour (ts-now)) ; => 0
(ts-H (ts-now)) ; => 0
(ts-minute (ts-now)) ; => 56
(ts-min (ts-now)) ; => 56
(ts-M (ts-now)) ; => 56
(ts-second (ts-now)) ; => 38
(ts-sec (ts-now)) ; => 38
(ts-S (ts-now)) ; => 38
(ts-year (ts-now)) ; => 2018
(ts-Y (ts-now)) ; => 2018
(ts-month (ts-now)) ; => 12
(ts-m (ts-now)) ; => 12
(ts-day (ts-now)) ; => 9
(ts-d (ts-now)) ; => 9Analise uma string em um objeto timestamp e reformate-a:
(ts-format (ts-parse " sat dec 8 2018 12:12:12 " )) ; => "2018-12-08 12:12:12 -0600"
; ; With a threading macro:
(-> > " sat dec 8 2018 12:12:12 "
ts-parse
ts-format) ; ;=> "2018-12-08 12:12:12 -0600"Formate a diferença entre dois carimbos de data/hora:
(ts-human-format-duration
(ts-difference (ts-now)
(ts-adjust 'day -400
'hour -2 'minute -1 'second -5
(ts-now))))
; ; => "1 years, 35 days, 2 hours, 1 minutes, 5 seconds"
; ; Abbreviated:
(ts-human-format-duration
(ts-difference (ts-now)
(ts-adjust 'day -400
'hour -2 'minute -1 'second -5
(ts-now)))
'abbr )
; ; => "1y35d2h1m5s" Analise um elemento de carimbo de data/hora da organização diretamente do org-element-context e encontre a diferença entre ele e agora:
( with-temp-buffer
( org-mode )
( save-excursion
( insert " <2015-09-24 Thu .+1d> " ))
(ts-human-format-duration
(ts-difference (ts-now)
(ts-parse-org-element ( org-element-context )))))
; ;=> "3 years, 308 days, 2 hours, 24 minutes, 21 seconds"Analise uma string de carimbo de data/hora da organização (que possui um repetidor) e formate o ano e o mês:
; ; Note the use of `format' rather than `concat' , because `ts-year'
; ; returns the year as a number rather than a string.
( let* ((ts (ts-parse-org " <2015-09-24 Thu .+1d> " )))
( format " %s , %s " (ts-month-name ts) (ts-year ts)))
; ;=> "September, 2015"
; ; Or, using dash.el:
(-- > (ts-parse-org " <2015-09-24 Thu .+1d> " )
( format " %s , %s " (ts-month-name it) (ts-year it)))
; ;=> "September, 2015"
; ; Or, if you remember the format specifiers:
(ts-format " %B, %Y " (ts-parse-org " <2015-09-24 Thu .+1d> " ))
; ;=> "September, 2015"Há quanto tempo foi essa data em 1970?
( let* ((now (ts-now))
(then (ts-apply :year 1970 now)))
( list (ts-format then)
(ts-human-format-duration
(ts-difference now then))))
; ;=> ("1970-08-04 07:07:10 -0500"
; ; "49 years, 12 days")Há quanto tempo começou a época?
(ts-human-format-duration
(ts-diff (ts-now) (make-ts :unix 0 )))
; ;=> "49 years, 227 days, 12 hours, 12 minutes, 30 seconds"Em qual dos últimos 100 anos o Natal foi no sábado?
( let ((ts (ts-parse " 2019-12-25 " ))
(limit ( - (ts-year (ts-now)) 100 )))
( cl-loop while ( >= (ts-year ts) limit)
when ( string= " Saturday " (ts-day-name ts))
collect (ts-year ts)
do (ts-decf (ts-year ts))))
; ;=> (2010 2004 1999 1993 1982 1976 1971 1965 1954 1948 1943 1937 1926 1920)Para um exemplo mais interessante, um carimbo de data/hora cai na semana anterior?
; ; First, define a function to return the range of the previous calendar week.
( defun last-week-range ()
" Return timestamps (BEG . END) spanning the previous calendar week. "
( let* ( ; ; Bind `now' to the current timestamp to ensure all calculations
; ; begin from the same timestamp. (In the unlikely event that
; ; the execution of this code spanned from one day into the next,
; ; that would cause a wrong result.)
(now (ts-now))
; ; We start by calculating the offsets for the beginning and
; ; ending timestamps using the current day of the week. Note
; ; that the `ts-dow' slot uses the "%w" format specifier, which
; ; counts from Sunday to Saturday as a number from 0 to 6.
(adjust-beg-day ( - ( + 7 (ts-dow now))))
(adjust-end-day ( - ( - 7 ( - 6 (ts-dow now)))))
; ; Make beginning/end timestamps based on `now' , with adjusted
; ; day and hour/minute/second values. These functions return
; ; new timestamps, so `now' is unchanged.
(beg ( thread-last now
; ; `ts-adjust' makes relative adjustments to timestamps.
(ts-adjust 'day adjust-beg-day)
; ; `ts-apply' applies absolute values to timestamps.
(ts-apply :hour 0 :minute 0 :second 0 )))
(end ( thread-last now
(ts-adjust 'day adjust-end-day)
(ts-apply :hour 23 :minute 59 :second 59 ))))
( cons beg end)))
(-let* ( ; ; Bind the default format string for `ts-format' , so the
; ; results are easy to understand.
(ts-default-format " %a, %Y-%m-%d %H:%M:%S %z " )
; ; Get the timestamp for 3 days before now.
(check-ts (ts-adjust 'day -3 (ts-now)))
; ; Get the range for the previous week from the function we defined.
((beg . end) (last-week-range)))
( list :last-week-beg (ts-format beg)
:check-ts (ts-format check-ts)
:last-week-end (ts-format end)
:in-range-p (ts-in beg end check-ts)))
; ;=> (:last-week-beg "Sun, 2019-08-04 00:00:00 -0500"
; ; :check-ts "Fri, 2019-08-09 10:00:34 -0500"
; ; :last-week-end "Sat, 2019-08-10 23:59:59 -0500"
; ; :in-range-p t)ts-B (STRUCT)ts struct STRUCT .ts-H (STRUCT)ts struct STRUCT .ts-M (STRUCT)ts struct STRUCT .ts-S (STRUCT)ts struct STRUCT .ts-Y (STRUCT)ts struct STRUCT .ts-b (STRUCT)ts struct STRUCT .ts-d (STRUCT)ts struct STRUCT .ts-day (STRUCT)ts struct STRUCT .ts-day-abbr (STRUCT)ts struct STRUCT .ts-day-name (STRUCT)ts struct STRUCT .ts-day-of-month-num (STRUCT)ts struct STRUCT .ts-day-of-week-abbr (STRUCT)ts struct STRUCT .ts-day-of-week-name (STRUCT)ts struct STRUCT .ts-day-of-week-num (STRUCT)ts struct STRUCT .ts-day-of-year (STRUCT)ts struct STRUCT .ts-dom (STRUCT)ts struct STRUCT .ts-dow (STRUCT)ts struct STRUCT .ts-doy (STRUCT)ts struct STRUCT .ts-hour (STRUCT)ts struct STRUCT .ts-internal (STRUCT)ts struct STRUCT . Slot representa um valor de tempo interno do Emacs (por exemplo, conforme retornado por current-time ).ts-m (STRUCT)ts struct STRUCT .ts-min (STRUCT)ts struct STRUCT .ts-minute (STRUCT)ts struct STRUCT .ts-month (STRUCT)ts struct STRUCT .ts-month-abbr (STRUCT)ts struct STRUCT .ts-month-name (STRUCT)ts struct STRUCT .ts-month-num (STRUCT)ts struct STRUCT .ts-moy (STRUCT)ts struct STRUCT .ts-sec (STRUCT)ts struct STRUCT .ts-second (STRUCT)ts struct STRUCT .ts-tz-abbr (STRUCT)ts struct STRUCT .ts-tz-offset (STRUCT)ts STRUCT .ts-unix (STRUCT)ts struct STRUCT .ts-week (STRUCT)ts struct STRUCT .ts-week-of-year (STRUCT)ts struct STRUCT .ts-woy (STRUCT)ts struct STRUCT .ts-year (STRUCT)ts struct STRUCT . ts-apply (&rest SLOTS TS)TS com novos valores de slot. Preencha os slots de carimbo de data/hora, substitua os valores de slot fornecidos e retorne o novo carimbo de data/hora com o valor de carimbo de data/hora Unix derivado de novos valores de slot. SLOTS é uma lista de pares alternados de valores-chave como aquele passado para make-ts .ts-adjust (&rest ADJUSTMENTS)ADJUSTMENTS a TS . ADJUSTMENTS devem ser uma série de SLOTS e VALUES alternados para ajustá-los. Por exemplo, este formulário retorna um novo carimbo de data/hora com 47 horas no futuro: (ts-adjust 'hour -1 'day +2 (ts-now))
Como o argumento timestamp é o último, ele é adequado para uso em uma macro de threading.
ts-dec (SLOT VALUE TS)TS com seu SLOT decrementado em VALUE . SLOT deve ser especificado como um símbolo simples, não como uma palavra-chave.ts-inc (SLOT VALUE TS)TS com seu SLOT incrementado em VALUE . SLOT deve ser especificado como um símbolo simples, não como uma palavra-chave.ts-update (TS)TS após atualizar seu carimbo de data/hora Unix de seus outros slots. Não destrutivo. Para ser usado após definir slots com, por exemplo, ts-fill .Destrutivo
ts-adjustf (TS &rest ADJUSTMENTS)TS após aplicar ADJUSTMENTS . Esta função é destrutiva, pois chama setf em TS . ADJUSTMENTS devem ser uma série de SLOTS e VALUES alternados para ajustá-los. Por exemplo, este formulário ajusta um carimbo de data/hora para 47 horas no futuro:
(let ((ts (ts-now))) (ts-adjustf ts 'hour -1 'day +2))
ts-decf (PLACE &optional (VALUE 1))PLACE por VALUE (padrão 1), atualize seu carimbo de data/hora Unix e retorne o novo valor de PLACE .ts-incf (PLACE &optional (VALUE 1))PLACE por VALUE (padrão 1), atualize seu carimbo de data/hora Unix e retorne o novo valor de PLACE . ts-in (BEG END TS)TS estiver dentro do intervalo BEG a END , inclusive. Todos os argumentos devem ser estruturas ts .ts< (AB)A for menor que o carimbo de data/hora B .ts<= (AB)A for <= carimbo de data/hora B .ts= (AB)A for igual ao carimbo de data/hora B . Compara apenas os slots unix dos carimbos de data/hora. Observe que o slot Unix de um carimbo de data/hora é flutuante e pode diferir em menos de um segundo, fazendo com que sejam desiguais, mesmo que todas as partes formatadas do carimbo de data/hora sejam iguais.ts> (AB)A for maior que o carimbo de data/hora B .ts>= (AB)A for >= carimbo de data/hora B . ts-human-duration (SECONDS)SECONDS em anos, dias, horas, minutos e segundos. Este é um cálculo simples que não leva em conta anos bissextos, segundos bissextos, etc.ts-human-format-duration (SECONDS &optional ABBREVIATE)SECONDS . Se SECONDS for menor que 1, retornará "0 seconds" . Se ABBREVIATE não for nulo, retorne uma versão mais curta, sem espaços. Este é um cálculo simples que não leva em conta anos bissextos, segundos bissextos, etc. ts-format (&optional TS-OR-FORMAT-STRING TS)format-time-string . Se TS-OR-FORMAT-STRING for um carimbo de data/hora ou nulo, use o valor de ts-default-format . Se TS-OR-FORMAT-STRING e TS forem nulos, use a hora atual. ts-parse (STRING)ts , analisando STRING com parse-time-string .ts-parse-fill (FILL STRING)ts , analisando STRING com parse-time-string . Valores vazios de hora/minuto/segundo são preenchidos de acordo com FILL : se begin , com 0; se end , a hora será preenchida com 23 e o minuto/segundo com 59; se for nulo, um erro poderá ser sinalizado quando os valores de tempo estiverem vazios. Observe que quando FILL é end , um valor de tempo como “12:12” é preenchido para “12:12:00”, não “12:12:59”.ts-parse-org (ORG-TS-STRING)ORG-TS-STRING . Observe que a função org-parse-time-string é chamada, e deve ser carregada antes de chamar esta função.ts-parse-org-fill (FILL ORG-TS-STRING)ORG-TS-STRING . Observe que a função org-parse-time-string é chamada, e deve ser carregada antes de chamar esta função. Os valores de hora/minuto/segundo são preenchidos de acordo com FILL : se begin , com 0; se end , hour será preenchido com 23 e minuto/segundo com 59. Observe que org-parse-time-string não suporta carimbos de data/hora que contenham segundos.ts-parse-org-element (ELEMENT)ELEMENT . Element deve ser como aquele analisado por org-element , cujo primeiro elemento é timestamp . Assume que o carimbo de data/hora não é um intervalo. copy-ts (TS)TS .ts-difference (AB)A e B .ts-diffts-difference .ts-fill (TS &optional ZONE)TS tendo preenchido todos os slots de seu carimbo de data/hora Unix. Isso não é destrutivo. ZONE é passado para format-time-string , que veja.ts-nowts definida para agora.ts-p (STRUCT)ts-reset (TS)TS com todos os slots limpos, exceto unix . Não destrutivo. O mesmo que: (make-ts :unix (ts-unix ts))
ts-defstruct (&rest ARGS)cl-defstruct , mas com opções de slots adicionais.Opções e valores adicionais de slots:
:accessor-init : um sexp que inicializa o slot no acessador se o slot for nulo. A struct do símbolo será vinculada à estrutura atual. O acessador é definido após a struct ser totalmente definida, então ele pode se referir à definição da struct (por exemplo, usando a macro cl-struct pcase ).
:aliases : A lista de símbolos que terão o alias do acessador do slot, precedido pelo nome da estrutura (por exemplo, uma struct ts com year do slot e o alias y criaria um alias ts-y ).
ts-human-format-duration vs. format-seconds O Emacs possui uma função integrada, format-seconds , que produz uma saída semelhante à de ts-human-format-duration . Sua saída também é controlável com uma string de formato. No entanto, se a saída de ts-human-format-duration for suficiente, ela terá um desempenho muito melhor que format-seconds . Este benchmark simples, executado 100.000 vezes, mostra que ele roda muito mais rápido e gera menos lixo:
(bench-multi-lexical :times 100000
:forms (( " ts-human-format-duration " (ts-human-format-duration 15780.910933971405 t ))
( " format-seconds " ( format-seconds " %yy%dd%hh%mm%ss%z " 15780.910933971405 ))))| Forma | x mais rápido que o próximo | Tempo total de execução | Nº de GCs | Tempo total de execução do GC |
|---|---|---|---|---|
| duração do formato ts-humano | 5,82 | 0,832945 | 3 | 0,574929 |
| formato-segundos | mais lento | 4.848253 | 17 | 3.288799 |
(Veja o Manual do Desenvolvedor de Pacotes Emacs para a macro bench-multi-lexical .)
Adicionado
ts-fill aceita um argumento ZONE , como aquele passado para format-time-string , que veja. Fixo
ts-human-format-duration retornou uma string vazia para durações inferiores a 1 segundo (agora retorna "0 seconds" ). Adicionado
ts-parse-fill e ts-parse-org-fill .ts-in .Mudado
ts-now não está mais embutida. Isso permite que ele seja alterado em tempo de execução, por exemplo, cl-letf , o que é útil nos testes.Fixo
ts-fill . (A função split-string , chamada nela, modifica os dados de correspondência.)ts-parse-org . (A função org-parse-time-string , chamada nela, modifica os dados de correspondência.)Documentação
Primeiro lançamento marcado. Publicado no MELPA.
GPLv3
