Terminology & naming¶
This page defines the values, arguments, and naming conventions used in the guides.
Naming conventions¶
Methods and option keys use camelCase, such as timeZoneName(),
relativeDuration(), and minimumFractionDigits.
The temporal vocabulary¶
The date and time methods use these terms:
| Term | What it is | Has a direction? | Typical input | Method |
|---|---|---|---|---|
| Moment | A single point on the timeline (a date and a time together) | — | native date/time value | moment() |
| Date | The calendar-date part of a moment (year-month-day) | — | a moment | date() |
| Time | The clock-time part of a moment (hour-minute-second) | — | a moment | time() |
| Duration | The magnitude of a span — "how long", no past/future | No (undirected) | seconds, or a unit breakdown | duration() |
| Relative duration | A span oriented toward past or future — "3 days ago", "in 2 hours" | Yes (directed) | signed value + unit | relativeDuration() |
| Range | The interval between two values | — | two endpoints | dateRange() |
Moment values
See Dates & times for accepted native values and timestamp units.
Duration vs relative duration
duration(1222060) → "339:27:40" — a bare magnitude. relativeDuration(-3,
"day") → "3 days ago" — the same idea of elapsed time, but directed. If you
catch yourself wanting "ago" or "in" out of duration(), you want
relativeDuration() instead.
Core objects¶
| Term | Meaning |
|---|---|
| Locale | The identifier for a language + region + preferences — en_AU, fa-IR, or a full BCP-47 tag like fa-IR-u-nu-latn-ca-buddhist. Use hyphens between subtags. |
| Instance | A constructed Cosmo object, bound to one locale and its modifiers. You build it once and call methods on it. |
| Subtags | The pieces a locale decomposes into — language, script, region. You can construct from them directly with fromSubtags(). |
| Modifiers | The optional settings layered onto a locale at construction: timeZone, calendar, currency. A settings object or dictionary. |
| Options bag | A per-call settings object (e.g. rounding/grouping options on number()). Keys use camelCase. |
| Width | The verbosity of a formatted result, one scale shared by dates, units, and more: none · short · medium · long · full. |
Numbers & money¶
| Term | Meaning |
|---|---|
| Number | A locale-formatted decimal — grouping and decimal separators per locale. |
| Percentage | Formats a fraction as a percent (0.2 → "20%"). |
| Unit | A measured quantity with its unit (2.19 gigabytes, 26°C). |
| Money | A currency amount, formatted with the currency's symbol and placement. Cosmo only formats — it never converts between currencies. |
| Currency | The currency itself (its localised name or disambiguated symbol), independent of any amount. |
| Compact | Short magnitude notation — 1.2K, 1.2 thousand. |
| Scientific | Exponential notation — 1.2345E4. |
| Symbol | A locale's notation symbol by name — e.g. the decimal mark "٫" in fa. |
Money is not currency conversion
money(100, "AUD") formats 100 AUD in the locale's style. It does not
convert 100 of anything into AUD — convert the amount yourself first. See
Money & currency.
Locale, text & people¶
| Term | Meaning |
|---|---|
| Language / Country / Script / Calendar | The localised display name of a code — language("en") in fa → "انگلیسی". |
| Direction | The locale's text direction — "ltr" or "rtl". |
| Time zone | An IANA zone (Australia/Sydney); timeZoneName() gives its localised name. |
| Plural category | The CLDR plural class of a number (one, few, many, …) used to choose message forms. See Messages & plurals. |
| Collation | Locale-correct string ordering (sorting) — distinct from byte order. See Collation & text. |
Options & enumerations quick reference¶
These values recur across the library. Each row links to the relevant guide.
| Where it's used | Argument | Accepted values |
|---|---|---|
| Dates, units, lists, calendar names | width |
none · short · medium · long · full — see Width |
number() / percentage() / money() |
number options | minimumIntegerDigits, min/maximumFractionDigits, min/maximumSignificantDigits, roundingMode, roundingIncrement, useGrouping (plus signDisplay, trailingZeroDisplay, roundingPriority, notation, compactDisplay) |
| number options | roundingMode |
ceil · floor · expand · trunc · halfExpand (default) · halfTrunc · halfEven |
compare / sort / contains |
collation options | numeric (bool), caseFirst: upper · lower · false |
contains() |
sensitivity |
base (default) · accent · case · variant |
join() |
type |
conjunction (default) · disjunction · unit |
relativeDuration() |
unit |
second · minute · hour · day · week · month · quarter · year (singular) |
relativeDuration() |
numeric |
always · auto |
timeZoneName() |
style |
long (default) · short · shortOffset · longOffset · shortGeneric · longGeneric |
pluralCategory() |
returns | zero · one · two · few · many · other |
displayName() |
type |
language · region · script · calendar · currency |
supportedValues() |
key |
calendar · collation · currency · numberingSystem · timeZone · unit |