نام (NAME)

dateround - گرد کردن تاریخ/زمان به رخداد بعدی مشخص‌شده در RNDSPEC

خلاصه دستور (SYNOPSIS)

dateround [گزینه]... [DATE/TIME] RNDSPEC...

توضیحات (DESCRIPTION)

گرد کردن DATE/TIME به رخداد بعدی مشخص‌شده در RNDSPEC.

اگر DATE/TIME حذف شود، جریانی از تاریخ/زمان‌ها از stdin خوانده می‌شود.

مقدار DATE/TIME همچنین می‌تواند یکی از مقادیر ویژه زیر باشد:
- `now' به عنوان برچسب زمان جاری (UTC) تفسیر می‌شود
- `time' بخش زمان برچسب زمان جاری (UTC)
- `today' تاریخ امروز (بر اساس UTC)
- `tomo[rrow]' تاریخ فردا (بر اساس UTC)
- `y[ester]day' تاریخ دیروز (بر اساس UTC)

۱. شناسه‌های RNDSPEC می‌توانند نام ماه‌ها (Jan, Feb, ...)، نام روزهای هفته (Sun, Mon, ...)، یا اعدادی با پسوند y، q، mo، d، bd، h، m یا s باشند که احتمالاً یک خط تیره (`-`) به عنوان پیشوند برای نشان دادن جهت گرد کردن به سمت پایین دارند.

۲. شناسه‌های RNDSPEC پسونددار همچنین می‌توانند پیشوند اسلش (`/`) داشته باشند تا نشان دهند گرد کردن به مضربی از RNDSPEC مورد نظر است (گرد کردن رده هم‌ارزی - Co-class rounding).

در حالت اول، گرد کردن روی عنصر نام‌برده در تاریخ یا تاریخ/زمان مشخص‌شده و عناصر مهم‌تر (مرتبه‌بالاتر) اثر می‌گذارد؛ به این صورت که آن عنصر را روی مقدار مشخص‌شده تنظیم کرده و عناصر مرتبه‌بالاتر را به‌گونه‌ای تطبیق می‌دهد که نتیجه برای مقادیر مثبت بزرگتر (جدیدتر) یا مساوی با ورودی باشد (یا در صورت ارائه -n|--next اکیداً بزرگتر)، و برای عناصر نام‌برده‌ای که پیشوند خط تیره (`-`) دارند کمتر (قدیمی‌تر) یا مساوی باشد (مگر اینکه -n|--next داده شده باشد). در هر دو حالت، عناصر کم‌اهمیت‌تر (زیربخش‌های عنصر نام‌برده و زیربخش‌های آن‌ها) بدون تغییر باقی می‌مانند.

دستور dateround 2019-01-28T12:04:00 +6
حاصل می‌دهد 2019-02-06T12:04:00

به همین ترتیب دستور dateround -n 2019-01-28T12:04:00 -- -Oct
حاصل می‌دهد 2018-10-28T12:04:00

در حالت دوم، گرد کردن بیشتر شبیه گرد کردن کسرها به سمت منفی بی‌نهایت است. محور زمان با مضاربی از عنصر نام‌برده افراز می‌شود، و قدیمی‌ترین تاریخ یا زمان بازگردانده می‌شود که بزرگتر (جدیدتر) از تاریخ یا تاریخ/زمان مشخص‌شده باشد (یا در صورت حذف -n|--next مساوی با آن). هنگام گرد کردن به سمت پایین (با پیشوند `-`)، قدیمی‌ترین تاریخ یا زمانی بازگردانده می‌شود که کمتر (قدیمی‌تر) از تاریخ یا زمان مشخص‌شده باشد.

دستور dateround 2019-01-28T12:04:00 /1y
حاصل می‌دهد 2020-01-01T00:00:00

به همین ترتیب دستور dateround 2019-01-28T12:04:00 /-30m
حاصل می‌دهد 2019-01-28T12:00:00

تقسیم‌بندی‌های مافوق سال هزاره‌ها هستند؛ به عنوان نمونه در یک هزاره ۱۰۰۰ سال، ۵۰۰ دوره دو ساله، ۱۰۰ دهه و غیره وجود دارد.

چندین RNDSPEC از چپ به راست ارزیابی می‌شوند.

توجه داشته باشید که گرد کردن جابجایی‌پذیر (تبدیلی) نیست، برای نمونه: dateround 2012-03-01 Sat Sep -> 2012-09-03 در برابر: dateround 2012-03-01 Sep Sat -> 2012-09-01

توجه داشته باشید که رشته‌های غیرعددی با پیشوند `-' با گزینه‌های خط فرمان تداخل دارند و باید از جداکننده `--' استفاده شود.

گزینه‌های شناخته‌شده (OPTION):

-h, --help: نمایش راهنما و خروج
-V, --version: نمایش نسخه و خروج
-q, --quiet: عدم نمایش پیام‌های خطای تجزیه‌کننده تاریخ/زمان و مدت و اصلاحات خودکار. پیش‌فرض چاپ یک هشدار یا مقدار اصلاح‌شده و بازگرداندن کد خطای ۲ است.
-f, --format=STRING: قالب خروجی. این می‌تواند یک رشته مشخص‌کننده فرمت (مشابه FMT در strftime()) یا نام یک گاه‌شمار باشد.
-i, --input-format=STRING...: قالب ورودی؛ می‌تواند چندین بار استفاده شود. هر تاریخ/زمان به ترتیب به تجزیه‌کننده‌های قالب ورودی ارسال می‌شود؛ اگر تاریخ/زمان بتواند با موفقیت با یک رشته قالب ورودی مشخص خوانده شود، همان مقدار استفاده خواهد شد.
-b, --base=DT: برای ورودی‌های ناکامل، از DT به عنوان جایگزین برای پر کردن فیلدهای گمشده استفاده می‌شود. همچنین برای مشخص‌کننده‌های قالب مبهم برای تعیین موقعیت بازه آن‌ها روی محور زمان مطلق استفاده می‌شود. باید یک تاریخ/زمان در قالب ISO8601 باشد. در صورت حذف، پیش‌فرض تاریخ/زمان جاری است.
-e, --backslash-escapes: فعال کردن تفسیر گریزهای بک‌اسلش در رشته‌های مشخص‌کننده قالب ورودی و خروجی.
-S, --sed-mode: کپی کردن بخش‌هایی از ورودی قبل و بعد از تاریخ/زمان منطبق. توجه داشته باشید که تمام رخدادهای تاریخ/زمان در یک خط پردازش خواهند شد.
-E, --empty-mode: خالی کردن خطوطی که قابل تجزیه نیستند.
--locale=LOCALE: قالب‌بندی نتایج بر اساس LOCALE؛ این گزینه فقط نام ماه‌ها و روزهای هفته را تحت تأثیر قرار می‌دهد.
--from-locale=LOCALE: تفسیر تاریخ‌ها در stdin یا خط فرمان به عنوان تاریخ‌های برگرفته از لوکال LOCALE؛ این فقط نام ماه‌ها و روزهای هفته را تحت تأثیر قرار می‌دهد، زیرا قالب‌های ورودی باید به صراحت مشخص شوند.
--from-zone=ZONE: تفسیر تاریخ‌ها در stdin یا خط فرمان به عنوان تاریخ‌های متعلق به منطقه زمانی ZONE.
-z, --zone=ZONE: تبدیل تاریخ‌های چاپ‌شده در stdout به منطقه زمانی ZONE (پیش‌فرض: UTC).
-n, --next: همیشه به یک تاریخ یا زمان متفاوت گرد شود.

مشخصات قالب (FORMAT SPECS)

مشخصات قالب در dateutils مشابه strftime() در استاندارد پوزیکس است.

با این حال، به دلیل پشتیبانی از طیف گسترده‌تری از گاه‌شمارها، dateutils باید قواعد متفاوتی را به کار گیرد.

مشخصات تاریخ:

%a  نام مخفف روز هفته
%A  نام کامل روز هفته
%_a نام روز هفته کوتاه شده به یک حرف (MTWRFAS)
%b  نام مخفف ماه
%B  نام کامل ماه
%_b نام ماه کوتاه شده به یک حرف (FGHJKMNQUVXZ)
%c  شمارش روز هفته در ماه (بازه 00 تا 05)
%C  شمارش روز هفته در سال (بازه 00 تا 53)
%d  روز ماه، ۲ رقمی (بازه 00 تا 31)
%D  روز سال، ۳ رقمی (بازه 000 تا 366)
%F  معادل %Y-%m-%d (قالب استاندارد ymd)
%g  سال تقویم هفته‌ای ISO بدون سده (بازه 00 تا 99)
%G  سال تقویم هفته‌ای ISO شامل سده
%j  معادل %D
%m  ماه در گاه‌شمار جاری (بازه 00 تا 12)
%Q  فصل سال (بازه Q1 تا Q4)
%q  شماره فصل (بازه 01 تا 04)
%s  تعداد ثانیه‌ها از مبدأ زمان (Epoch)
%u  روز هفته به صورت عدد (بازه 01 تا 07، یکشنبه 07 است)
%U  شمارش هفته‌ها، شروع هفته یکشنبه (بازه 00 تا 53)
%V  شمارش هفته‌های ISO، شروع هفته دوشنبه (بازه 01 تا 53)
%w  روز هفته به صورت عدد (بازه 00 تا 06، یکشنبه 00 است)
%W  شمارش هفته‌ها، شروع هفته دوشنبه (بازه 00 تا 53)
%y  سال بدون سده (بازه 00 تا 99)
%Y  سال شامل سده
%_y سال کوتاه شده به یک رقم
%Z  انحراف منطقه زمانی در ساعت و دقیقه (HH:MM) با
    علامت مقدم (+ برای مناطق شرق UTC، - برای غرب UTC)

%Od روز به صورت اعداد رومی
%Om ماه به صورت اعداد رومی
%Oy سال دو رقمی به صورت اعداد رومی
%OY سال شامل سده به صورت اعداد رومی

%rs در سامانه‌های زمانی با مبدأ متفاوت از مبدأ یونیکس،
    تعداد ثانیه‌ها از آن زمان را انتخاب می‌کند.
%rY در تقویم‌هایی که سال آن‌ها با سال میلادی همزمان نیست،
    سال آن تقویم را انتخاب می‌کند.

%dth  روز ماه به صورت عدد ترتیبی (1st، 2nd، 3rd و غیره)
%mth  ماه سال به صورت عدد ترتیبی (1st، 2nd، 3rd و غیره)

%db روز کاری ماه (از پایان ماه قبل)
%dB تعداد روزهای کاری تا پایان این ماه

مشخصات زمان:

%H  ساعت در شبانه‌روز با ساعت ۲۴ ساعته، ۲ رقم (بازه 00 تا 23)
%I  ساعت در شبانه‌روز با ساعت ۱۲ ساعته، ۲ رقم (بازه 01 تا 12)
%M  دقیقه (بازه 00 تا 59)
%N  نانوثانیه (بازه 000000000 تا 999999999)
%p  رشته AM یا PM؛ ظهر PM و نیمه‌شب AM است.
%P  مشابه %p ولی با حروف کوچک
%S  ثانیه (بازه 00 تا 60، 60 برای ثانیه‌های کبیسه)
%T  معادل %H:%M:%S

مشخصات عمومی:

%n  کاراکتر خط جدید (newline)
%t  کاراکتر تب (tab)
%%  کاراکتر لفظی %

تعدیل‌کننده‌ها:

%O  تعدیل‌کننده برای تبدیل اعداد ده‌دهی به اعداد رومی
%r  تعدیل‌کننده برای تبدیل واحدها به واحدهای واقعی
%0  تعدیل‌کننده برای فعال کردن پیشوندهای صفر
%SPC  تعدیل‌کننده برای فعال کردن پیشوندهای فاصله
%-  تعدیل‌کننده برای غیرفعال کردن کامل پیشوندها
th  پسوند؛ خواندن و چاپ اعداد ترتیبی
b   پسوند؛ تلقی روزها به عنوان روزهای کاری

طبق طراحی، تاریخ‌های قبل از 1601-01-01 پشتیبانی نمی‌شوند.

برای انطباق، در اینجا فهرستی از نام‌های گاه‌شمار و رشته قالب متناظر آن‌ها آمده است:

ymd     %Y-%m-%d
ymcw    %Y-%m-%c-%w
ywd     %rY-W%V-%u
bizda   %Y-%m-%db
lilian     n/a
ldn        n/a
julian     n/a
jdn        n/a
matlab     n/a
mdn        n/a

این شناسه‌ها را می‌توان به عنوان رشته قالب خروجی استفاده کرد؛ افزون بر این، @code{lilian}/@code{ldn} و @code{julian}/@code{jdn} را می‌توان به عنوان رشته قالب ورودی نیز به کار برد.

تعیین مدت زمان (SPECIFYING DURATIONS)

برخی ابزارها ("dateadd", "dateseq") به عنوان ورودی خود به مدت زمان نیاز دارند. مدت‌های زمانی عموماً با فرمت‌های ورودی مشخص‌شده با "-i|--input-format" ناسازگار هستند و (در حال حاضر) ساختار ورودی آن‌ها ثابت است.

قالب عمومی "+-Nunit" است که در آن "+" یا "-" علامت، "N" یک عدد و "unit" واحد به شرح زیر است.

واحدها:

s  ثانیه
m  دقیقه
h  ساعت
rs ثانیه واقعی (شامل ثانیه‌های کبیسه)

d  روز
b  روز کاری
mo ماه
y  سال

به دلایل تاریخی، ما در گذشته "m" را در زمینه ورودی‌های فقط-تاریخ به عنوان نشانگر ماه‌ها می‌پذیرفتیم. از نسخه 0.4.4 به بعد دیگر چنین نیست.

مثال‌ها (EXAMPLES)

$ dateround 2012-03-01 2
2012-03-02
$

$ dateround -n 2012-03-01 1
2012-04-01
$

$ dateround 17:05:00 5m
17:05:00
$ dateround 17:04:00 /5m
17:05:00
$

$ dateround -n 17:04:00 4m
18:04:00
$ dateround -n 17:04:00 /1m
17:05:00
$

نویسنده (AUTHOR)

نوشته شده توسط Sebastian Freundt <freundt@fresse.org>

گزارش اشکالات (REPORTING BUGS)

گزارش اشکالات به: https://github.com/hroptatyr/dateutils/issues

همچنین ببینید (SEE ALSO)

مستندات کامل برای dateround به عنوان یک راهنمای Texinfo نگهداری می‌شود. اگر برنامه‌های info و dateround به درستی در سیستم شما نصب شده باشند، دستور

: info (dateutils)dateround

باید دسترسی شما را به راهنمای کامل فراهم کند.