feat(upperFirst): Add upperFirst function (#404)

* feat(upperFirst): Add upperFirst function

* Add upperFirst benchmark

* Add upperFirst english docs

* Update docs/reference/string/upperFirst.md

---------

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

benchmarks/performance/upperFirst.bench.ts

@@ -0,0 +1,28 @@
+import { bench, describe } from 'vitest';
+import { upperFirst as upperFirstToolkit } from 'es-toolkit';
+import { upperFirst as upperFirstLodash } from 'lodash';
+
+describe('upperFirst', () => {
+  describe('short string', () => {
+    bench('es-toolkit/upperFirst', () => {
+      const str = 'camelCase';
+      upperFirstToolkit(str);
+    });
+
+    bench('lodash/upperFirst', () => {
+      const str = 'camelCase';
+      upperFirstLodash(str);
+    });
+  });
+
+  describe('long string', () => {
+    const LONG_STR = 'camelCaseLongString'.repeat(1000);
+    bench('es-toolkit/upperFirst', () => {
+      upperFirstToolkit(LONG_STR);
+    });
+
+    bench('lodash/upperFirst', () => {
+      upperFirstLodash(LONG_STR);
+    });
+  });
+});

docs/reference/string/upperFirst.md

@@ -0,0 +1,27 @@
+# upperFirst
+
+Converts the first character of string to upper case.
+
+## Signature
+
+```typescript
+function upperFirst(str: string): string;
+```
+
+### Parameters
+
+- `str` (`string`): The string that is to be changed.
+
+### Returns
+
+(`string`) The string converted.
+
+## Examples
+
+```typescript
+import { upperFirst } from 'es-toolkit/string';
+
+upperFirst('fred') // returns 'Fred'
+upperFirst('Fred') // returns 'Fred'
+upperFirst('FRED') // returns 'FRED'
+```

src/string/index.ts

@@ -5,4 +5,5 @@ export { lowerCase } from './lowerCase.ts';
 export { startCase } from './startCase.ts';
 export { capitalize } from './capitalize.ts';
 export { pascalCase } from './pascalCase.ts';
+export { upperFirst } from './upperFirst.ts';
 export { lowerFirst } from './lowerFirst.ts';

src/string/upperFirst.spec.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { upperFirst } from './upperFirst';
+
+describe('upperFirst', () => {
+  it('should change first character of lower case to upper case', () => {
+    expect(upperFirst('fred')).toEqual('Fred');
+  });
+
+  it('should keep first character of upper case unaltered', () => {
+    expect(upperFirst('Fred')).toEqual('Fred');
+  });
+
+  it('should keep first character of all upper case unaltered', () => {
+    expect(upperFirst('FRED')).toEqual('FRED');
+  });
+
+  it('should work with an empty string', () => {
+    expect(upperFirst('')).toEqual('');
+  });
+
+  it('should keep white space and not alter string', () => {
+    expect(upperFirst('  fred')).toEqual('  fred');
+  });
+});

src/string/upperFirst.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts the first character of string to upper case.
+ *
+ * @param {string} str - The string that is to be changed
+ * @returns {string} - The converted string.
+ *
+ * @example
+ * const convertedStr1 = upperCase('fred') // returns 'fred'
+ * const convertedStr2 = upperCase('Fred') // returns 'Fred'
+ * const convertedStr3 = upperCase('FRED') // returns 'FRED'
+ */
+export const upperFirst = (str: string): string => {
+  return str.substring(0, 1).toUpperCase() + str.substring(1);
+};