diff --git a/docs/001_develop/03_client-capabilities/014_utility-methods/03_formatters-util.mdx b/docs/001_develop/03_client-capabilities/014_utility-methods/03_formatters-util.mdx new file mode 100644 index 0000000000..96a7fab0fb --- /dev/null +++ b/docs/001_develop/03_client-capabilities/014_utility-methods/03_formatters-util.mdx @@ -0,0 +1,65 @@ +--- +title: 'Formatting Utilities' +sidebar_label: 'Formatting Utilities' +id: formatting-utils +keywords: [utils, utility, data, formatters, number, date, datetime, unix, timestamp, separator, parse, parsing, parser, numeric] +tags: + - utils + - utility + - formatters + - number + - date + - datetime + - unix + - timestamp + - separator + - parse + - parsing + - parser + - numeric +--- + +Formatting utilities provide functions for parsing and formatting numbers and dates, ensuring that your application can accurately process and display data in user-friendly formats. + +:::info +For more detailed information on API and configurations, please refer to the [API documentation](docs/api/index.md). +::: + +## Key Features + +- **`formatDateTimestamp`** - Formats UNIX timestamps into ISO date strings (`YYYY-MM-DD`), making it easy to display dates in a standard format. +- **`formatDateTimeTimestamp`** - Formats UNIX timestamps into ISO date and time strings (`YYYY-MM-DD HH:MM:SS`), combining date and time for better precision. +- **`formatTimestamp`** - A flexible function to format UNIX timestamps. Includes or omits the time component based on a configurable flag. +- **Number Parsing** - Transforms localized number strings into numeric types, correctly interpreting group separators and decimal points to ensure reliable conversions. +- **Separator Detection** - Identifies if a localized number string includes a decimal separator, helping to distinguish between integers and floating-point numbers. + +## Examples + +### Date and Time Formatting + +```typescript +import { formatDateTimestamp, formatDateTimeTimestamp, formatTimestamp } from '@genesislcap/foundation-utils'; + +console.log(formatDateTimestamp(Date.now())); // Outputs current date in YYYY-MM-DD format +console.log(formatDateTimeTimestamp(Date.now())); // Outputs current date and time in YYYY-MM-DD HH:MM:SS format +console.log(formatTimestamp(Date.now(), true)); // Outputs current date and time based on the withTime flag +``` + +### Locale-Specific Number Parsing + +This class provides functionality for parsing localized number strings back into their numeric form, taking into account locale-specific grouping, decimal separators, and numerals. +The `NumberParser` class utilizes the `Intl.NumberFormat` API to adapt to various locales. It employs regular expressions to strip locale-specific formatting, allowing for accurate numeric parsing. + +```typescript +import { NumberParser } from '@genesislcap/foundation-utils'; + +const parser = new NumberParser('en-US'); +console.log(parser.parse('1,234.56')); // Outputs 1234.56 +console.log(parser.hasSeparator('1,234')); // Outputs false +``` + +## Considerations + +- **Consistent Temporal Data Representation**: Use the date and time formatting functions to ensure uniform representation of temporal data across your application. +- **Accurate Numeric Input Handling**: Leverage the NumberParser to parse user input, guaranteeing correct interpretation of numeric data regardless of locale settings. +- **Robustness in Global Applications**: Regularly test these utilities with diverse locale settings to ensure reliability, accuracy, and user-friendliness in a global context.