https://github.com/superioone/format_string
Replaces placeholders in a format string with provided named or positional arguments.
https://github.com/superioone/format_string
javascript string-formatter utility-library
Last synced: 7 months ago
JSON representation
Replaces placeholders in a format string with provided named or positional arguments.
- Host: GitHub
- URL: https://github.com/superioone/format_string
- Owner: SuperioOne
- License: mit
- Created: 2023-12-11T05:27:20.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-01-20T14:47:59.000Z (about 2 years ago)
- Last Synced: 2025-07-03T13:56:13.623Z (8 months ago)
- Topics: javascript, string-formatter, utility-library
- Language: JavaScript
- Homepage:
- Size: 69.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Yet another format string function
Fast, small and basic string templating function. This library is intended for use cases where the position of
parameters
in a format string is not known at compile-time.
> **For situations with predictable/constant string formats, using JavaScript's built-in string templating is highly
recommended.**
## Getting Started
1. Add the library into your project.
```shell
npm install @superior-one/format_string
```
2. Import `default` function and start using.
* Named parameters:
```javascript
import format_string from "@superior-one/format_string";
const format_tag = "({userTag}){name}, [{hash}]";
const format_email = "<{email}>{name}, {hash}";
const args = {
email: "john+doe@abc.com",
name: "John Doe",
hash: "18c54d073b2",
userTag: "@john"
};
const text0 = format_string(format_tag, args);
console.log(text0); // (@john)John Doe, [18c54d073b2]
const text1 = format_string(format_email, args);
console.log(text1); // John Doe, 18c54d073b2
```
* Positional parameters:
```javascript
import format_string from "@superior-one/format_string";
const format = "{2} {1} {0} {0} {2}\n{2} {0} {1} {0} {2}\n{2} {0} {0} {1} {2}\n";
const text = format_string(format, ["a", 5, "|"]);
console.log(text);
// | 5 a a |
// | a 5 a |
// | a a 5 |
```
## Format Syntax
Consider `arg="value"`
| Format | Output | Description |
|-----------------|-----------------|---------------------------------------------------------------------------|
| `{arg}` | `value` | Replaces `{arg}` with the value of `arg` |
| `{arg }` | `{arg }` | Treats `{arg }` as a string as it doesn't follow correct formatting |
| `{ arg}` | `{ arg}` | Treats `{ arg}` as a string since it doesn't follow correct formatting |
| `{arg arg}` | `{arg arg}` | Treats `{arg arg}` as a string since it doesn't follow correct formatting |
| `{\narg}` | `{\narg}` | Treats `{\narg}` as a string since it doesn't follow correct formatting |
| `{}` | `{}` | Empty placeholders are ignored and treats as a string |
| `{{arg}}` | `{arg}` | Escapes the placeholder syntax |
| `{{{{arg}}}}` | `{{{arg}}}` | Escapes the inner placeholder syntax, outputting `{{{arg}}}` as a string |
| `{{{ {arg} }}}` | `{{{ value }}}` | Inserts `value` within triple curly braces, outputting `{{{ value }}}` |
Avoid using space, feed, tab and separator characters in placeholder names as they will be interpreted as strings, not
placeholders.
List of invalid placeholder characters;
- `{`
- `}`
- `' '`
- `\f`
- `\n`
- `\r`
- `\t`
- `\v`
- `\u00a0`
- `\u1680`
- `\u2000` to `\u200a`
- `\u2028`
- `\u2029`
- `\u202f`
- `\u205f`
- `\u3000`
- `\ufeff`
## Building the Project
Build step only generates type decleration and CommonJS version.
```shell
npm install
npm run build
```
## Contributing
Pull requests are welcome, especially ideas for time and memory allocation reduction.
## Benchmarks
Tested against some popular packages with four parameters and single escape.
> Keep in mind some of the listed libraries provides more features like number formatting, padding etc.
```
Test Environment:
CPU : AMD Ryzen 9 5950X 16-Core @ 32x 5.177GHz
OS : x86_64 Linux 6.6.3-1
node : v20.7.0
vitest : v1.0.4
tinybench : v2.5.1
name hz min max mean p75 p99 p995 p999 rme samples
· @superior-one/format_string with positional args 2,693,972.54 0.0003 0.9917 0.0004 0.0004 0.0004 0.0006 0.0016 ±0.31% 2693973
· @superior-one/format_string with named args 2,260,906.19 0.0004 0.5987 0.0004 0.0004 0.0009 0.0009 0.0010 ±0.20% 2260907
· string-template with named args 858,246.92 0.0011 0.2475 0.0012 0.0011 0.0021 0.0022 0.0024 ±0.16% 858247
· string-template with positional args 1,016,520.83 0.0009 0.1932 0.0010 0.0010 0.0011 0.0012 0.0019 ±0.11% 1016521
· @stdlib/string-format with positional args 1,771,259.33 0.0005 0.2183 0.0006 0.0006 0.0007 0.0008 0.0011 ±0.19% 1771260
· string-format with positional args 548,726.51 0.0017 0.2494 0.0018 0.0018 0.0021 0.0029 0.0036 ±0.22% 548727
· string-format with named args 377,298.69 0.0025 0.1892 0.0027 0.0026 0.0029 0.0030 0.0061 ±0.16% 377299
· pupa with positional args 522,948.55 0.0018 0.1503 0.0019 0.0019 0.0021 0.0035 0.0041 ±0.15% 522949
· pupa with named args 455,937.12 0.0021 0.9894 0.0022 0.0022 0.0038 0.0043 0.0051 ±0.23% 455938
· string replaceAll positional args 1,619,706.37 0.0006 0.1692 0.0006 0.0006 0.0007 0.0008 0.0011 ±0.13% 1619707
· string replaceAll named args 1,705,262.53 0.0005 0.2296 0.0006 0.0006 0.0007 0.0011 0.0012 ±0.07% 1705263
BENCH Summary
@superior-one/format_string with positional args - index.bench.js >
1.19x faster than @superior-one/format_string with named args
1.52x faster than @stdlib/string-format with positional args
1.58x faster than string replaceAll named args
1.66x faster than string replaceAll positional args
2.65x faster than string-template with positional args
3.14x faster than string-template with named args
4.91x faster than string-format with positional args
5.15x faster than pupa with positional args
5.91x faster than pupa with named args
7.14x faster than string-format with named args
```
## License
This project is licensed under the terms of the MIT license.