MODULES Uize.Str.Limit
1. Introduction
The Uize.Str.Limit module provides methods for limiting the length of strings and performing truncation in different ways.
DEVELOPERS: Chris van Rensburg
1.1. Examples
There are no dedicated showcase example pages for the Uize.Str.Limit module.
SEARCH FOR EXAMPLES
Use the link below to search for example pages on the UIZE Web site that reference the Uize.Str.Limit module...
SEARCH
1.2. Implementation Info
The Uize.Str.Limit module defines the Uize.Str.Limit package under the Uize.Str namespace.
1.2.1. Features Introduced in This Module
The features listed in this section have been introduced in this module.
STATIC METHODS
Uize.Str.Limit.joinUsingSuffixPriority | Uize.Str.Limit.lengthize | Uize.Str.Limit.limitLength
STATIC PROPERTIES
1.2.2. Features Overridden in This Module
No features have been overridden in this module.
1.2.3. Features Inherited From Other Modules
This module has no inherited features.
1.2.4. Modules Directly Under This Namespace
There are no modules directly under this namespace.
1.2.5. Unit Tests
The Uize.Str.Limit module is unit tested by the Uize.Test.Uize.Str.Limit test module.
2. Static Methods
2.1. Uize.Str.Limit.joinUsingSuffixPriority
Returns a string, that is the concatenation of the two specified strings, limited to the specified maximum length, and such that the suffix string takes precedence if any characters must be lost in order to limit the length of the resulting string.
SYNTAX
joinedSTR = Uize.Str.Limit.joinUsingSuffixPriority (prefixSTR,suffixSTR,maxLengthINT);
EXAMPLE
Uize.Str.Limit.joinUsingSuffixPriority ('Some Greate Product Title',' - Customized',30);
In the above example, this method would produce the result 'Some Greate Produ - Customized'.
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.2. Uize.Str.Limit.lengthize
Returns a string, that is the specified source string with its length adjusted to the specified new length, with padding added or truncation performed as necessary.
This method behaves in the following way...
| When the specified new length is greater than the source string's length, then padding with space characters will be added as necessary to achieve the new length. | |
| When the specified new length is less than the source string's length, then the source string will be truncated as necessary to achieve the new length. | |
| When the new length is equal to the source string's current length, then the source string will be returned as is. | |
When the new length is less than 1, then an empty string will be returned. |
|
| If padding is to be added or truncation is to be performed, the side(s) of the string on which these operations will be performed is determined by the alignment value (see Adjust the Length of a Source String, Specifying Alignment). |
DIFFERENT USAGES
Adjust the Length of a Source String
resultSTR = Uize.Str.Limit.lengthize (sourceStr,newLengthINT);
Adjust the Length of a Source String, Specifying Alignment
resultSTR = Uize.Str.Limit.lengthize (sourceStr,newLengthINT,alignSTRorFLOAT);
2.2.1. Adjust the Length of a Source String
In the simplest usage, the length of a source string can be adjusted to a new length by specifying the source string as the first argument and the desired length as the second argument.
SYNTAX
resultSTR = Uize.Str.Limit.lengthize (sourceStr,newLengthINT);
If the value specified for the newLengthINT parameter is different to the length of the source string and padding needs to be added or truncation needs to be performed, the operation will be performed in a left-aligned manner. This is the same as if the value 'left' or 0 was specified for the optional alignSTRorFLOAT third argument (see the usage Adjust the Length of a Source String, Specifying Alignment).
EXAMPLES
Uize.Str.Limit.lengthize ('foobarbaz',12); // returns 'foobarbaz '
Uize.Str.Limit.lengthize ('foobarbaz',9); // returns 'foobarbaz'
Uize.Str.Limit.lengthize ('foobarbaz',3); // returns 'foo'
Uize.Str.Limit.lengthize ('foobarbaz',0); // returns ''
Uize.Str.Limit.lengthize ('foobarbaz',-10); // returns ''
// when the source string is an empty string
Uize.Str.Limit.lengthize ('',12); // returns ' '
Uize.Str.Limit.lengthize ('',9); // returns ' '
Uize.Str.Limit.lengthize ('',3); // returns ' '
Uize.Str.Limit.lengthize ('',0); // returns ''
Uize.Str.Limit.lengthize ('',-10); // returns ''
2.2.2. Adjust the Length of a Source String, Specifying Alignment
In cases where padding needs to be added or truncation needs to be performed and you wish to control how content from the source string is aligned in the result string, alignment can be specified using the optional alignSTRorFLOAT third argument.
SYNTAX
resultSTR = Uize.Str.Limit.lengthize (sourceStr,newLengthINT,alignSTRorFLOAT);
2.2.2.1. Named Alignment
Alignment can be specified by name by specifying a string value for the alignSTRorFLOAT parameter.
The following string value can be specified...
'left' - The source text will be left-aligned in the returned string, and any padding or truncation necessary will be applied on the right side of the string. |
|
'center' - The source text will be center-aligned in the returned string, and any padding or truncation necessary will be applied evenly (half on each side) on the left and right sides of the string. |
|
'right' The source text will be right-aligned in the returned string, and any padding or truncation necessary will be applied on the left side of the string. |
EXAMPLES
// when the new length is greater than the current length
Uize.Str.Limit.lengthize ('foobar',10,'left'); // returns 'foobar '
Uize.Str.Limit.lengthize ('foobar',10,'center'); // returns ' foobar '
Uize.Str.Limit.lengthize ('foobar',10,'right'); // returns ' foobar'
// when the new length is less than the current length
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,'left'); // returns 'aaa'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,'center'); // returns 'ccc'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,'right'); // returns 'eee'
2.2.2.2. Fractional Alignment
Beyond the conventional left, center, and right named alignment, any arbitrary fractional alignment can be achieved by specifying a floating point number in the range of 0 to 1 for the alignSTRorFLOAT parameter.
When a floating point number is specified for the alignSTRorFLOAT parameter, that number is used to determine what fraction of the padding or truncation necessary will be applied to the left side of the string. Then, the remainder of the padding or truncation necessary will be applied to the right side of the string.
So, for example, if the value .25 is specified for the alignSTRorFLOAT parameter, then a quarter of the padding or truncation necessary will be applied to the left side of the string while the remaining three quarters will be applied to the right side of the string.
According to this behavior, fractional alignment values are equivalent to named alignment values as follows...
0 - equivalent to 'left' alignment |
|
.5 - equivalent to 'center' alignment |
|
1 - equivalent to 'right' alignment |
EXAMPLES
// when the new length is greater than the current length
Uize.Str.Limit.lengthize ('foobar',10,0); // returns 'foobar '
Uize.Str.Limit.lengthize ('foobar',10,.25); // returns ' foobar '
Uize.Str.Limit.lengthize ('foobar',10,.5); // returns ' foobar '
Uize.Str.Limit.lengthize ('foobar',10,.75); // returns ' foobar '
Uize.Str.Limit.lengthize ('foobar',10,1); // returns ' foobar'
// when the new length is less than the current length
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,0); // returns 'aaa'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,.25); // returns 'bbb'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,.5); // returns 'ccc'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,.75); // returns 'ddd'
Uize.Str.Limit.lengthize ('aaabbbcccdddeee',3,1); // returns 'eee'
IMPLEMENTATION INFO
| this feature was introduced in this module |
2.3. Uize.Str.Limit.limitLength
Returns a string, that is the specified source string limited to the specified maximum length.
SYNTAX
limitedSTR = Uize.Str.Limit.limitLength (sourceSTR,maxLengthINT);
If the string specified in the sourceSTR has to be truncated, it will be truncated to accommodate an ellipsis of "..." (three periods), such that the final length of the returned string is guaranteed to be no greater than the maximum length specified in the maxLengthINT parameter.
EXAMPLE
Uize.Str.Limit.limitLength ('012345678901',15); // returns '012345678901'
Uize.Str.Limit.limitLength ('0123456789012',15); // returns '0123456789012'
Uize.Str.Limit.limitLength ('01234567890123',15); // returns '01234567890123'
Uize.Str.Limit.limitLength ('012345678901234',15); // returns '012345678901234'
Uize.Str.Limit.limitLength ('0123456789012345',15); // returns '012345678901...'
Uize.Str.Limit.limitLength ('01234567890123456',15); // returns '012345678901...'
Uize.Str.Limit.limitLength ('012345678901234567',15); // returns '012345678901...'
Notice how, once the limit of 15 characters has been hit, all the resulting strings are only 15 characters long, with the last three characters being the ellipsis periods.
IMPLEMENTATION INFO
| this feature was introduced in this module |