feat(capitalize): add capitalize (#161)

* feat(capitalize): add capitalize

* fix(capitalize): return type

* Update docs/ko/reference/string/capitalize.md

---------

Co-authored-by: Sojin Park <raon0211@gmail.com>

benchmarks/capitalize.bench.ts

@@ -0,0 +1,15 @@
+import { bench, describe } from 'vitest';
+import { capitalize as capitalizeToolkit } from 'es-toolkit';
+import { capitalize as capitalizeLodash } from 'lodash';
+
+describe('capitalize', () => {
+ bench('es-toolkit/capitalize', () => {
+ const str = 'camelCase';
+ capitalizeToolkit(str);
+ });
+
+ bench('lodash/capitalize', () => {
+ const str = 'camelCase';
+ capitalizeLodash(str);
+ });
+});

docs/.vitepress/en.mts

@@ -146,7 +146,10 @@ function sidebar(): DefaultTheme.Sidebar {
  },
  {
  text: 'String Utilities',
- items: [{ text: 'snakeCase', link: '/reference/string/snakeCase' }],
+ items: [
+ { text: 'snakeCase', link: '/reference/string/snakeCase' },
+ { text: 'capitalize', link: '/reference/string/capitalize' },
+ ],
  },
  ],
  },

docs/.vitepress/ko.mts

@@ -145,7 +145,10 @@ function sidebar(): DefaultTheme.Sidebar {
  },
  {
  text: '문자열',
- items: [{ text: 'snakeCase', link: '/ko/reference/string/snakeCase' }],
+ items: [
+ { text: 'snakeCase', link: '/ko/reference/string/snakeCase' },
+ { text: 'capitalize', link: '/ko/reference/string/capitalize' },
+ ],
  },
  ],
  },

docs/ko/reference/string/capitalize.md

@@ -0,0 +1,26 @@
+# capitalize
+
+문자열의 첫 번째 문자를 대문자로 변환하고, 나머지 문자는 소문자로 변환해요.
+
+## 인터페이스
+
+```typescript
+function capitalize<T extends string>(str: T): Capitalize<T>;
+```
+
+### 파라미터
+
+`str` (`T`): 대문자로 변환할 문자열.
+
+### 반환 값
+
+(`Capitalize<string>`): 대문자로 변환된 문자열.
+
+## 예시
+
+```typescript
+import { capitalize } from 'es-toolkit/string';
+
+capitalize('fred'); // returns 'Fred'
+capitalize('FRED'); // returns 'Fred'
+```

docs/reference/string/capitalize.md

@@ -0,0 +1,26 @@
+# capitalize
+
+Converts the first character of string to upper case and the remaining to lower case.
+
+## Signature
+
+```typescript
+function capitalize<T extends string>(str: T): Capitalize<T>;
+```
+
+### Parameters
+
+`str` (`T`): The string to be converted to uppercase.
+
+### Returns
+
+(`Capitalize<string>`): The capitalized string.
+
+## Examples
+
+```typescript
+import { capitalize } from 'es-toolkit/string';
+
+capitalize('fred'); // returns 'Fred'
+capitalize('FRED'); // returns 'Fred'
+```

src/string/capitalize.spec.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { capitalize } from './capitalize';
+
+describe('capitalize', () => {
+ it('should converts the first character of string to upper case', async () => {
+ expect(capitalize('fred')).toEqual('Fred');
+ });
+
+ it('should converts the first character of string to upper case and the remaining to lower case.', async () => {
+ expect(capitalize('FRED')).toEqual('Fred');
+ });
+
+ it('should handle special characters correctly', async () => {
+ expect(capitalize('special@characters!')).toEqual('Special@characters!');
+ });
+
+ it('should handle hyphen correctly', async () => {
+ expect(capitalize('hyphen-text')).toEqual('Hyphen-text');
+ });
+
+ it('should handle leading whitepspace', async () => {
+ expect(capitalize(' fred')).toEqual(' fred');
+ });
+
+ it('should handle strings that are already in capitalize', async () => {
+ expect(capitalize('Fred')).toEqual('Fred');
+ });
+
+ it('should work with an empty string', async () => {
+ expect(capitalize('')).toEqual('');
+ });
+});

src/string/capitalize.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts the first character of string to upper case and the remaining to lower case.
+ *
+ * @template T - Literal type of the string.
+ * @param {T} str - The string to be converted to uppercase.
+ * @returns {Capitalize<T>} - The capitalized string.
+ *
+ * @example
+ * const result = capitalize('fred') // returns 'Fred'
+ * const result2 = capitalize('FRED') // returns 'Fred'
+ */
+
+export const capitalize = <T extends string>(str: T): Capitalize<T> => {
+ return (str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()) as Capitalize<T>;
+};

src/string/index.ts

@@ -1 +1,2 @@
 export { snakeCase } from './snakeCase.ts';
+export { capitalize } from './capitalize.ts';