Merge pull request #48 from rudashi/str-43

resolve(#str-43): Added `take` method

docs/methods.md

@@ -70,6 +70,7 @@
 - [substrCount](#substrcount)
 - [substrReplace](#substrreplace)
 - [swap](#swap)
+- [take](#take)
 - [tap](#tap)
 - [test](#test)
 - [title](#title)
@@ -779,6 +780,13 @@ Stringable.of('Tacos are great!').swap({
 
 // 'Burritos are fantastic!'
 ```
+### take
+The `take` method returns a specified number of characters from the beginning of a string:
+```js
+Stringable.of('Build something amazing!').take(5);
+
+// 'Build'
+```
 ### tap
 The `tap` method passes the string to the given closure, allowing you to examine and interact with the string while
 not affecting the string itself. The original string is returned by the `tap` method regardless of what is returned by the closure:

docs/statics.md

@@ -565,6 +565,13 @@ Str.upper('laravel');
 
 // 'LARAVEL'
 ```
+### take
+The `take` function returns a specified number of characters from the beginning of a string:
+```js
+Str.take('Build something amazing!', 5);
+
+// 'Build'
+```
 ### title
 The `title` function converts the given string to `Title Case`:
 ```js

src/Str.ts

@@ -51,6 +51,7 @@ import {
     substrCount,
     substrReplace,
     swap,
+    take,
     trim,
     ltrim,
     rtrim,
@@ -232,6 +233,7 @@ export const Str = {
     reverse,
     start,
     upper,
+    take,
     title,
     headline,
     slug,

src/Stringable.ts

@@ -602,6 +602,12 @@ export class Stringable {
         return this;
     }
 
+    public take = (limit: number): this => {
+        this._value = Str.take(this._value, limit);
+
+        return this;
+    }
+
     public toHtmlString = (): Element | Node | null => {
         const template = document.createElement('template');
 

src/methods.ts

@@ -603,6 +603,14 @@ export const swap = (map: Record<string, string>, subject: string): string => {
         .join('');
 }
 
+export const take = (value: string, limit: number): string => {
+    if (limit < 0) {
+        return substr(value, limit);
+    }
+
+    return substr(value, 0, limit);
+}
+
 export const trim = (value: string, characters?: string): string => {
     return characters
         ? rtrim(ltrim(value, characters), characters)

tests/take.test.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const {Stringable} = require('../src/Stringable');
+const {Str} = require('../src/Str');
+const {take} = require('../src/methods');
+
+it('returns a specified number of characters from the beginning of a string', () => {
+    expect(Stringable.of('Build something amazing!').take(5).toString())
+        .toBe('Build');
+
+    expect(Stringable.of('abcdef').take(2).toString())
+        .toBe('ab');
+
+    expect(Stringable.of('abcdef').take(-2).toString())
+        .toBe('ef');
+
+    expect(Str.take('abcdef', 2))
+        .toBe('ab');
+
+    expect(take('abcdef', 2))
+        .toBe('ab');
+});