string-etc
v0.4.0
Published
Collection of supplementary JavaScript String methods that works across module packaging systems and that can be included piece-wise
Downloads
1,046
Maintainers
Readme
A collection of handy String methods that works across various JavaScript module systems, including:
- Browser script tag
- CommonJS / Node.js
- AMD / Require.js.
Methods can be included piecewise.
Usage
Accessing these extensions will differ depending on our module system.
HTML web page
If we are on a vanilla web page or AMD, we can access these methods directly from an String object. For example, we can do:
'California'.cram(8) // returns Califor…
Node wrapper
However, this type of direct access may lead to conflicts on CommonJS systems like Node. Unlike AMD or web pages, libraries are automatically loaded in Node. We may have other libraries in our dependency tree that add similarly named methods to the same String.prototype object. When we call these methods, we may be in fact be calling the function that overwrote ours.
We added a special arrangement on Node to prevent this problem. We create a local wrapper function. Instead of attaching the methods to the global String.prototype object, we attach them to this function. We would have:
string('California').cram(8) // returns Califor…
where string is a constructed function that wraps around our String.
var string = require('array-etc').wrap(['cram']);
Since these kind of unintended collisions are a lot harder with script tag loads or AMD, where the end developer actively controls the loading of the modules, we have not extended the wrapper function to these systems.
Node loader
The wrapper function on Node guarantees safety. However, it may be harder to manipulate. We need an extra function call for every string operation, and string operations cannot be chained as elegantly.
If safety is not an issue, we can use the direct syntax in Node as well. We just need to call load instead of wrap in our setup.
For example:
require('array-etc').load(['cram']);
will load cram into String.prototype
Installation
Web page
If we use Bower, we would run:
bower install string-etc
If we use npm, we would run:
npm install string-etc
Then, we add the corresponding script tag to our page. e.g.
<script src="/bower_components/string-etc/lib/cram.js"></script>
Node
In our shell, run:
npm install string-etc
In our file, require string-etc.
Call wrap with the methods we desire. For example:
var string = require('string-etc').wrap(['cram']);
Or call load if we prefer the direct syntax without wrapping:
require('string-etc').load(['cram']);
Libraries
lib/cram.js
String.prototype.cram(space, opts)
Cram tries to fit a string within a given width, by replacing excess characters with an ellipsis:
For example, suppose we are building a web page that indexes different Objective-C methods. Objective-C has some pretty long function names that might mess up our layout. Using cram, we can shorten these. Let's try a pretty bad case:
"splitViewController:willHideViewController:withBarButtonItem:forPopoverController:".cram(); //"splitViewContro…"
By default, cram returns a string with max length 16. However, we can adjust this by passing in a number:
"splitViewController:willHideViewController:withBarButtonItem:forPopoverController:".cram(8); //"splitVi…"
opts.replacement
The replacement character by default is an ellipsis, but you can use another string. Specify the replacement string, and cram will adjust accordingly.
Technical Support
E-mail me:
- if you have problems or questions.
- if you find a String method that you think should be included, because it would be useful for others as well.
- if you have an interesting use case that I should consider