Truncate Method (#52)

* Added the tests.

* Added limit method.

* Improved the formatting.

* Rename method and the length parameter.

* Changed to trimRight

* Updated the parameters.

* Fixed the tests.

* Added the characters package.

* Implemented includeSubstitutionLength and used the characters package.

* Updated the tests and added tests for some edge cases.

* Added docstring.

* Renamed the parameter name.

* Added new line.

* Simplified the calculation of final truncate length.

* Used the characters.length

* Fixed typo.

* Fixed formatting

* Fixed formatting.

Author: arielmagbanua

lib/string_basics.dart

@@ -2,6 +2,8 @@
 // All rights reserved. Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+import 'package:characters/characters.dart';
+
 import 'src/slice_indices.dart';
 
 /// Utility extension methods for the native [String] class.
@@ -201,6 +203,42 @@ extension StringBasics on String {
     return stringBuffer.toString();
   }
 
+  /// Returns a truncated version of the string.
+  ///
+  /// Example:
+  /// ```dart
+  /// final sentence = 'The quick brown fox jumps over the lazy dog';
+  /// final truncated = sentence.truncate(20); // 'The quick brown fox...'
+  /// ```
+  ///
+  /// The [length] is the truncated length of the string.
+  /// The [substitution] is the substituting string of the truncated characters.
+  /// If not null or empty it will be appended at the end of the truncated string.
+  /// The [trimTrailingWhitespace] is whether or not to trim the spaces of the truncated string
+  /// before appending the ending string.
+  /// The [includeSubstitutionInLength] is whether or not that the length of the substitution string will be included
+  /// with the intended truncated length.
+  String truncate(
+    int length, {
+    String substitution = '',
+    bool trimTrailingWhitespace = true,
+    bool includeSubstitutionInLength = false,
+  }) {
+    if (this.length <= length) {
+      return this;
+    }
+
+    // calculate the final truncate length where whether or not to include the length of substitution string
+    final truncatedLength = includeSubstitutionInLength
+        ? (length - substitution.characters.length)
+        : length;
+    final truncated = this.characters.take(truncatedLength).toString();
+
+    // finally trim the trailing white space if needed
+    return (trimTrailingWhitespace ? truncated.trimRight() : truncated) +
+        substitution;
+  }
+
   /// Returns a string with the first character in upper case.
   ///
   /// This method can capitalize first character

pubspec.yaml

@@ -10,6 +10,9 @@ repository: https://github.com/google/dart-basics
 environment:
   sdk: ">=2.17.0 <3.0.0"
 
+dependencies:
+  characters: ^1.2.1
+
 dev_dependencies:
   pedantic: ^1.8.0
   test: ^1.16.0

test/string_basics_test.dart

@@ -353,6 +353,89 @@ void main() {
     });
   });
 
+  group('truncate', () {
+    test(
+        'returns a truncated string that has the length'
+        'based on the limit provided', () {
+      final sentence = 'The quick brown fox jumps over the lazy dog';
+      expect(sentence.truncate(20), 'The quick brown fox');
+    });
+
+    test(
+        'returns the same string if the length of the string'
+        'is less than provided limit', () {
+      final sentence = 'The quick brown fox';
+      expect(sentence.truncate(20), 'The quick brown fox');
+    });
+
+    test(
+        'returns a truncated string that has the length based on the length'
+        'provided without trimming the spaces at the end', () {
+      final sentence = 'The quick brown fox jumps over the lazy dog';
+      expect(sentence.truncate(20, trimTrailingWhitespace: false),
+          'The quick brown fox ');
+    });
+
+    test(
+        'returns a truncated string that has the length based on the length'
+        'provided with a custom substitution string', () {
+      final sentence = 'The quick brown fox jumps over the lazy dog';
+      expect(sentence.truncate(20, substitution: ' (...)'),
+          'The quick brown fox (...)');
+      expect(
+          sentence.truncate(20, substitution: '...'), 'The quick brown fox...');
+    });
+
+    test(
+        'returns a truncated string that has the length based on the length'
+        'provided with a custom ending string but the substitution length will be included',
+        () {
+      final sentence = 'The quick brown fox jumps over the lazy dog';
+      expect(
+        sentence.truncate(
+          12,
+          substitution: '...',
+          includeSubstitutionInLength: true,
+        ),
+        'The quick...',
+      );
+    });
+
+    test(
+        'returns a truncated string with emojis that has the length'
+        'based on the length provided', () {
+      final sentence = 'The quick brown 🦊🦊🦊 jumps over the lazy 🐶🐶🐶';
+
+      expect(
+        sentence.truncate(42),
+        'The quick brown 🦊🦊🦊 jumps over the lazy 🐶🐶',
+      );
+
+      expect(
+        sentence.truncate(42, substitution: '🐾🐾🐾'),
+        'The quick brown 🦊🦊🦊 jumps over the lazy 🐶🐶🐾🐾🐾',
+      );
+
+      expect(
+        sentence.truncate(
+          18,
+          substitution: '...',
+          includeSubstitutionInLength: true,
+        ),
+        'The quick brown...',
+      );
+
+      expect(
+        sentence.truncate(
+          18,
+          substitution: '😀',
+          includeSubstitutionInLength: true,
+        ),
+        'The quick brown 🦊😀',
+      );
+    });
+  });
+
   group('capitalize', () {
     test('returns a new string with the first character in upper case', () {
       expect('foo'.capitalize(), 'Foo');