Skip to content

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. Underscore and hyphen forms are both accepted.
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 typed Modifiers object.
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.
Spellout A number written in words — "one hundred twenty".
Ordinal Ordinal text — "2nd". (For the ordinal plural category, see Messages & plurals.)
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.
Transliterate / Romanize Convert text between scripts; romanize is the to-Latin-then-ASCII special case (good for slugs). See Transliteration & parsing.
Confusable / Suspicious Spoof detection (UTS #39): whether two strings look alike, or one string is spoof-prone.
Parse The inverse of a formatter — turn locale-formatted text back into a value (parseNumber, parseMoney, parseDate).
Negotiation Choosing the best of your supported locales for a user, via CLDR language distance — see Negotiation & names.
Index buckets Alphabetical section headers for a list (A–Z, 가나다, あかさ…).
Person name A name formatted in the culture's order, spacing, and script.

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
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 · transliterator
personName() length / formality short·medium·long / formal·informal