Skip to content

Terminology & naming

This page defines the values, arguments, and naming conventions used in the guides.

Naming conventions

Methods use snake_case, such as time_zone_name() and relative_duration(). Option keys use camelCase, such as 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 relative_duration()
Range The interval between two values — two endpoints date_range()

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 relative_duration() 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 from_subtags().
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.
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); time_zone_name() 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 (parse_number, parse_money, parse_date).
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, 가나다, あかさ…).

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
relative_duration() unit second · minute · hour · day · week · month · quarter · year (singular)
relative_duration() numeric always · auto
time_zone_name() style long (default) · short · shortOffset · longOffset · shortGeneric · longGeneric
plural_category() returns zero · one · two · few · many · other
display_name() type language · region · script · calendar · currency
supported_values() key timeZone · collation · numberingSystem · unit · transliterator