NumberBase10Format overview

This module implements a CVNumberBase10Format which describes the possible options to format/parse a base-10 number or BigDecimal and implements the formatting/parsing algortithms

Table of contents

• Constructors
  • make
• Destructors
  • eNotationChars
  • fractionalSeparator
  • maximumFractionalDigits
  • minimumFractionalDigits
  • roundingMode
  • scientificNotation
  • showNullIntegerPart
  • signDisplay
  • thousandSeparator
  • toDescription
• Formatting
  • toNumberFormatter
• Guards
  • has
• Instances
  • dutchStyleInteger
  • dutchStyleNumber
  • dutchStyleUngroupedNumber
  • frenchStyleInteger
  • frenchStyleNumber
  • frenchStyleUngroupedNumber
  • integer
  • ukStyleInteger
  • ukStyleNumber
  • ukStyleUngroupedNumber
• Models
  • ScientificNotation (namespace)
    • MantissaAdjuster (interface)
    • MantissaChecker (interface)
    • Parser (interface)
  • SignDisplay (namespace)
    • Formatter (interface)
    • Parser (interface)
    • SignString (type alias)
    • SignValue (type alias)
  • Type (interface)
• Modifiers
  • withCeilRoundingMode
  • withEngineeringScientificNotation
  • withExpandRoundingMode
  • withFloorRoundingMode
  • withFractionalSeparator
  • withHalfCeilRoundingMode
  • withHalfEvenRoundingMode
  • withHalfExpandRoundingMode
  • withHalfFloorRoundingMode
  • withHalfTruncRoundingMode
  • withMaxNDecimals
  • withMinNDecimals
  • withNDecimals
  • withNoScientificNotation
  • withNormalizedScientificNotation
  • withNullIntegerPartNotShowing
  • withNullIntegerPartShowing
  • withSignDisplay
  • withSignDisplayExceptZero
  • withSignDisplayForNegative
  • withSignDisplayForNegativeExceptZero
  • withStandardScientificNotation
  • withThousandSeparator
  • withTruncRoundingMode
  • withoutSignDisplay
  • withoutThousandSeparator
• Module markers
  • moduleTag
• Parsing
  • toBigDecimalExtractor
  • toBigDecimalParser
  • toRealExtractor
  • toRealParser
  • toThrowingBigDecimalExtractor
  • toThrowingBigDecimalParser
  • toThrowingRealExtractor
  • toThrowingRealParser

Constructors

make

Constructor

Signature

export declare const make: (params: MTypes.Data<Type>) => Type

Destructors

eNotationChars

Returns the eNotationChar property of self

Signature

export declare const eNotationChars: MTypes.OneArgFunction<Type, readonly string[]>

fractionalSeparator

Returns the fractionalSeparator property of self

Signature

export declare const fractionalSeparator: MTypes.OneArgFunction<Type, string>

maximumFractionalDigits

Returns the maximumFractionalDigits property of self

Signature

export declare const maximumFractionalDigits: MTypes.OneArgFunction<Type, number>

minimumFractionalDigits

Returns the minimumFractionalDigits property of self

Signature

export declare const minimumFractionalDigits: MTypes.OneArgFunction<Type, number>

roundingMode

Returns the roundingMode property of self

Signature

export declare const roundingMode: MTypes.OneArgFunction<Type, CVRoundingMode.Type>

scientificNotation

Returns the scientificNotation property of self

Signature

export declare const scientificNotation: MTypes.OneArgFunction<Type, ScientificNotation>

showNullIntegerPart

Returns the showNullIntegerPart property of self

Signature

export declare const showNullIntegerPart: MTypes.OneArgFunction<Type, boolean>

signDisplay

Returns the signDisplay property of self

Signature

export declare const signDisplay: MTypes.OneArgFunction<Type, SignDisplay>

thousandSeparator

Returns the thousandSeparator property of self

Signature

export declare const thousandSeparator: MTypes.OneArgFunction<Type, string>

toDescription

Returns a short description of self, e.g. ‘signed integer’

Signature

export declare const toDescription: (self: Type) => string

Formatting

toNumberFormatter

Returns a function that tries to format a number respecting the options represented by selfand an optional parameter fillChars. If successful, that function returns a Some of the formatted number. Otherwise, it returns a None. number can be of type number or BigDecimal for better accuracy. There is a difference between number and BigDecimal (and bigint) regarding the sign of 0. In Javascript, Object.is(0,-0) is false whereas Object.is(0n,-0n) is true. So if the sign of zero is important to you, prefer passing a number to the function. 0 as a BigDecimal will always be interpreted as a positive 0 as we have no means of knowing if it is negative or positive.

fillChars is a string whose first characters will be inserted between the sign and the number (or at the start of the number if it is unsigned) so that the formatted number has at least the same number of characters as fillChars (e.g. the result will be ‘-02’ if you try to format the value -2 with fillChars = ‘000’)

Signature

export declare const toNumberFormatter: (
  self: Type,
  fillChars?: string
) => MTypes.OneArgFunction<BigDecimal.BigDecimal | CVReal.Type, string>

Guards

has

Type guard

Signature

export declare const has: (u: unknown) => u is Type

Instances

dutchStyleInteger

Dutch-style integer CVNumberBase10Format instance. Used in countries like Dutch-speaking Belgium, the Netherlands, Germany, Italy, Norway, Croatia, Spain…

Signature

export declare const dutchStyleInteger: Type

dutchStyleNumber

CVNumberBase10Format instance that uses a comma as fractional separator, a dot as thousand separator and shows at most three fractional digits. Used in countries like Dutch-speaking Belgium, the Netherlands, Germany, Italy, Norway, Croatia, Spain…

Signature

export declare const dutchStyleNumber: Type

dutchStyleUngroupedNumber

CVNumberBase10Format instance that uses a comma as fractional separator, no thousand separator and shows at most three fractional digits. Used in countries like Dutch-speaking Belgium, the Netherlands, Germany, Italy, Norway, Croatia, Spain…

Signature

export declare const dutchStyleUngroupedNumber: Type

frenchStyleInteger

French-style integer CVNumberBase10Format instance. Used in countries like France, French-speaking Canada, French-speaking Belgium, Denmark, Finland, Sweden…

Signature

export declare const frenchStyleInteger: Type

frenchStyleNumber

CVNumberBase10Format instance that uses a comma as fractional separator, a space as thousand separator and shows at most three fractional digits. Used in countries like France, French-speaking Canada, French-speaking Belgium, Denmark, Finland, Sweden…

Signature

export declare const frenchStyleNumber: Type

frenchStyleUngroupedNumber

CVNumberBase10Format instance that uses a comma as fractional separator, no thousand separator and shows at most three fractional digits. Used in countries like France, French-speaking Canada, French-speaking Belgium, Denmark, Finland, Sweden…

Signature

export declare const frenchStyleUngroupedNumber: Type

integer

Integer CVNumberBase10Format instance with no thousand separator

Signature

export declare const integer: Type

ukStyleInteger

Uk-style integer CVNumberBase10Format instance. Used in countries like the UK, the US, English-speaking Canada, Australia, Thaïland, Bosnia…

Signature

export declare const ukStyleInteger: Type

ukStyleNumber

CVNumberBase10Format instance that uses a dot as fractional separator, a comma as thousand separator and shows at most three fractional digits. Used in countries like the UK, the US, English-speaking Canada, Australia, Thaïland, Bosnia…

Signature

export declare const ukStyleNumber: Type

ukStyleUngroupedNumber

CVNumberBase10Format instance that uses a dot as fractional separator, no thousand separator and shows at most three fractional digits. Used in countries like the UK, the US, English-speaking Canada, Australia, Thaïland, Bosnia…

Signature

export declare const ukStyleUngroupedNumber: Type

Models

ScientificNotation (namespace)

ScientificNotation namespace

MantissaAdjuster (interface)

Type of a MantissaAdjuster

Signature

export interface MantissaAdjuster
  extends MTypes.OneArgFunction<
    BigDecimal.BigDecimal,
    readonly [adjustedMantissa: BigDecimal.BigDecimal, exponent: Option.Option<number>]
  > {}

MantissaChecker (interface)

Type of a MantissaChecker

Signature

export interface MantissaChecker
  extends MTypes.OneArgFunction<BigDecimal.BigDecimal, Option.Option<BigDecimal.BigDecimal>> {}

Parser (interface)

Type of a ScientificNotation Parser

Signature

export interface Parser extends MTypes.OneArgFunction<string, Option.Option<number>> {}

SignDisplay (namespace)

SignDisplay namespace

Formatter (interface)

Type of a SignDisplay Formatter

Signature

export interface Formatter
  extends MTypes.OneArgFunction<{ readonly sign: SignValue; readonly isZero: boolean }, SignString> {}

Parser (interface)

Type of a SignDisplay Parser

Signature

export interface Parser
  extends MTypes.OneArgFunction<{ readonly sign: SignString; readonly isZero: boolean }, Option.Option<SignValue>> {}

SignString (type alias)

Type that represents the possible strings used to represent a sign

Signature

export type SignString = "-" | "+" | ""

SignValue (type alias)

Type that represents the possible values of a sign

Signature

export type SignValue = -1 | 1

Type (interface)

Type that represents a CVNumberBase10Format

Signature

export interface Type extends Inspectable.Inspectable, Pipeable.Pipeable {
  /**
   * Thousand separator. Use an empty string for no separator. Usually a string made of at most one
   * character different from `fractionalSeparator`. Will not throw otherwise but unexpected results
   * might occur.
   */
  readonly thousandSeparator: string

  /**
   * Fractional separator. Usually a one-character string different from `thousandSeparator`. Will
   * not throw otherwise but unexpected results might occur.
   */
  readonly fractionalSeparator: string

  /**
   * Formatting:
   *
   * - If `true`, numbers with a null integer part are displayed starting with `0`. Otherwise, they
   *   are displayed starting with `.` unless `maximumFractionalDigits===0`, in which case they are
   *   displayed starting wiyh `0`.
   *
   * Parsing
   *
   * - If `true`, conversion will fail for numbers starting with `.` (after an optional sign).
   * - If `false`, conversion will fail for numbers starting with `0.` (after an optional sign).
   */
  readonly showNullIntegerPart: boolean

  /**
   * Minimim number of digits forming the fractional part of a number. Must be a positive integer
   * (>=0) less than or equal to `maximumFractionalDigits`.
   *
   * Formatting: the string will be right-padded with `0`'s if necessary to respect the condition
   *
   * Parsing: will fail if the input string does not respect this condition (the string must be
   * right-padded with `0`'s to respect the condition if necessary).
   */
  readonly minimumFractionalDigits: number

  /**
   * Maximum number of digits forming the fractional part of a number. Must be an integer value
   * greater than or equal to `minimumFractionalDigits`. Can take the +Infinity value.
   *
   * Formatting: the number will be rounded using the roundingMode to respect the condition (unless
   * `maximumFractionalDigits` is `+Infinity`).
   *
   * Parsing: will fail if the input string has too many fractional digits.
   */
  readonly maximumFractionalDigits: number

  /**
   * Possible characters to use to represent e-notation. Usually ['e','E']. Must be an array of
   * one-character strings. Will not throw otherwise but unexpected results will occur. Not used if
   * `scientificNotation === None`
   *
   * Formatting: the string at index 0 is used
   *
   * Parsing: the first character of the e-notation must be one of the one-character strings present
   * in the array
   */
  readonly eNotationChars: ReadonlyArray<string>

  /** Scientific notation options. See ScientificNotation */
  readonly scientificNotation: ScientificNotation

  /** Rounding mode options. See RoundingMode.ts */
  readonly roundingMode: CVRoundingMode.Type

  /** Sign display options. See SignDisplay.ts */
  readonly signDisplay: SignDisplay

  /** @internal */
  readonly [_TypeId]: _TypeId
}

Modifiers

withCeilRoundingMode

Returns a copy of self with roundingMode set to Ceil

Signature

export declare const withCeilRoundingMode: MTypes.OneArgFunction<Type>

withEngineeringScientificNotation

Returns a copy of self with scientificNotation set to Engineering

Signature

export declare const withEngineeringScientificNotation: MTypes.OneArgFunction<Type>

withExpandRoundingMode

Returns a copy of self with roundingMode set to Expand

Signature

export declare const withExpandRoundingMode: MTypes.OneArgFunction<Type>

withFloorRoundingMode

Returns a copy of self with roundingMode set to Floor

Signature

export declare const withFloorRoundingMode: MTypes.OneArgFunction<Type>

withFractionalSeparator

Returns a copy of self with fractionalSeparator set to fractionalSeparator

Signature

export declare const withFractionalSeparator: (fractionalSeparator: string) => MTypes.OneArgFunction<Type>

withHalfCeilRoundingMode

Returns a copy of self with roundingMode set to HalfCeil

Signature

export declare const withHalfCeilRoundingMode: MTypes.OneArgFunction<Type>

withHalfEvenRoundingMode

Returns a copy of self with roundingMode set to HalfEven

Signature

export declare const withHalfEvenRoundingMode: MTypes.OneArgFunction<Type>

withHalfExpandRoundingMode

Returns a copy of self with roundingMode set to HalfExpand

Signature

export declare const withHalfExpandRoundingMode: MTypes.OneArgFunction<Type>

withHalfFloorRoundingMode

Returns a copy of self with roundingMode set to HalfFloor

Signature

export declare const withHalfFloorRoundingMode: MTypes.OneArgFunction<Type>

withHalfTruncRoundingMode

Returns a copy of self with roundingMode set to HalfTrunc

Signature

export declare const withHalfTruncRoundingMode: MTypes.OneArgFunction<Type>

withMaxNDecimals

Returns a copy of self with maximumFractionalDigits set to n. n must be a positive integer (+Infinity allowed). Pass 0 for an integer format

Signature

export declare const withMaxNDecimals: (maxDecimalNumber: number) => (self: Type) => Type

withMinNDecimals

Returns a copy of self with minimumFractionalDigits set to n. n must be a finite positive integer

Signature

export declare const withMinNDecimals: (minDecimalNumber: number) => (self: Type) => Type

withNDecimals

Returns a copy of self with minimumFractionalDigits and maximumFractionalDigits set to n. n must be a finite positive integer

Signature

export declare const withNDecimals: (decimalNumber: number) => MTypes.OneArgFunction<Type>

withNoScientificNotation

Returns a copy of self with scientificNotation set to None

Signature

export declare const withNoScientificNotation: MTypes.OneArgFunction<Type>

withNormalizedScientificNotation

Returns a copy of self with scientificNotation set to Normalized

Signature

export declare const withNormalizedScientificNotation: MTypes.OneArgFunction<Type>

withNullIntegerPartNotShowing

Returns a copy of self with showNullIntegerPart set to false

Signature

export declare const withNullIntegerPartNotShowing: MTypes.OneArgFunction<Type>

withNullIntegerPartShowing

Returns a copy of self with showNullIntegerPart set to true

Signature

export declare const withNullIntegerPartShowing: MTypes.OneArgFunction<Type>

withSignDisplay

Returns a copy of self with signDisplay set to Always

Signature

export declare const withSignDisplay: MTypes.OneArgFunction<Type>

withSignDisplayExceptZero

Returns a copy of self with signDisplay set to ExceptZero

Signature

export declare const withSignDisplayExceptZero: MTypes.OneArgFunction<Type>

withSignDisplayForNegative

Returns a copy of self with signDisplay set to Auto

Signature

export declare const withSignDisplayForNegative: MTypes.OneArgFunction<Type>

withSignDisplayForNegativeExceptZero

Returns a copy of self with signDisplay set to Negative

Signature

export declare const withSignDisplayForNegativeExceptZero: MTypes.OneArgFunction<Type>

withStandardScientificNotation

Returns a copy of self with scientificNotation set to Standard

Signature

export declare const withStandardScientificNotation: MTypes.OneArgFunction<Type>

withThousandSeparator

Returns a copy of self with thousandSeparator set to thousandSeparator

Signature

export declare const withThousandSeparator: (thousandSeparator: string) => MTypes.OneArgFunction<Type>

withTruncRoundingMode

Returns a copy of self with roundingMode set to Trunc

Signature

export declare const withTruncRoundingMode: MTypes.OneArgFunction<Type>

withoutSignDisplay

Returns a copy of self with signDisplay set to Never

Signature

export declare const withoutSignDisplay: MTypes.OneArgFunction<Type>

withoutThousandSeparator

Returns a copy of self with thousandSeparator set to ‘’

Signature

export declare const withoutThousandSeparator: MTypes.OneArgFunction<Type>

Module markers

moduleTag

Module tag

Signature

export declare const moduleTag: "@parischap/conversions/NumberBase10Format/"

Parsing

toBigDecimalExtractor

Returns a function that tries to parse, from the start of a string text, a number respecting the options represented by self and an optional fillChar parameter. If successful, that function returns a Some containing parsedText (the part of text that could be analyzed as representing a number) and value (parsedText converted to a BigDecimal value). Otherwise, it returns a None. As BigDecimal’s provide no possibility to distinguish -0n and 0n, parsing ‘-0’, ‘0’, ‘+0’ will yield the same result.

fillChar is a character that may be used as filler between the sign and the number (or at the start of the number if it is unsigned). It must be a one-character string (but no error is triggered if it’s not). You can use ‘0’ as fillChar but you should not use any other digit because the value of the number to parse would depend on the number of removed fillChar’s.

Signature

export declare const toBigDecimalExtractor: (
  self: Type,
  fillChar?: string
) => MTypes.OneArgFunction<string, Option.Option<MTypes.Pair<BigDecimal.BigDecimal, string>>>

toBigDecimalParser

Same as toBigDecimalExtractor but the whole of the input text must represent a number, not just its start

Signature

export declare const toBigDecimalParser: (
  self: Type,
  fillChar?: string
) => MTypes.OneArgFunction<string, Option.Option<BigDecimal.BigDecimal>>

toRealExtractor

Same as toBigDecimalExtractor but returns a CVReal. This is the most usual use case. Furthermore, this function will return -0 if your parse ‘-0’ and 0 if you parse ‘0’ or ‘+0’.

Signature

export declare const toRealExtractor: (
  self: Type,
  fillChar?: string
) => MTypes.OneArgFunction<string, Option.Option<MTypes.Pair<CVReal.Type, string>>>

toRealParser

Same as toRealExtractor but the whole of the input text must represent a number, not just its start

Signature

export declare const toRealParser: (
  self: Type,
  fillChar?: string
) => MTypes.OneArgFunction<string, Option.Option<CVReal.Type>>

toThrowingBigDecimalExtractor

Same as toBigDecimalExtractor but the returned parser throws in case of failure

Signature

export declare const toThrowingBigDecimalExtractor: (
  self: Type,
  fillChar?: string
) => (text: string) => MTypes.Pair<BigDecimal.BigDecimal, string>

toThrowingBigDecimalParser

Same as toBigDecimalParser but the returned parser throws in case of failure

Signature

export declare const toThrowingBigDecimalParser: (
  self: Type,
  fillChar?: string
) => (text: string) => BigDecimal.BigDecimal

toThrowingRealExtractor

Same as toRealExtractor but the returned parser throws in case of failure

Signature

export declare const toThrowingRealExtractor: (
  self: Type,
  fillChar?: string
) => (text: string) => MTypes.Pair<CVReal.Type, string>

toThrowingRealParser

Same as toRealParser but the returned parser throws in case of failure

Signature

export declare const toThrowingRealParser: (self: Type, fillChar?: string) => (text: string) => CVReal.Type