CompressedList
in package
Compressed list
Values are single scalar values. Continuous ranges of values from X to Y (inclusive) are represented as "X-Y". The list is composed of values and/or ranges. They are separated by comma.
Definitions: Value Any single scalar value, either numeric or string, that MUST consist of digits [0-9] and/or letters [A-Za-z]. In particular, it MUST NOT contain spaces, commas (,), or dashes (-). Range Any single value, or two values separated by a single dash (-). For two value ranges, the first value SHOULD be less or equal than the second, otherwise results may be either unpredictable or plain wrong. List Any combination of values and ranges, separated by single commas (,). Also called "compressed list".
Notes:
- Ranges may be regarded as a special case of a list with only one element. Thus, wherever a list parameter is expected, a range can be used. The reverse will generally not work.
- Values may be regarded as a special case of a range with only one element. Thus, wherever a range parameter is expected, a value can be used. The reverse will generally not work.
- When using string values, mind that string comparison is case sensitive. So, 'b' is contained in the range 'a-c', but not in 'A-C'.
- However, mind your step when mixing cases or, even worse, numeric and non-numeric strings in one list! E.g. the string "0-99,a-z" will happily be compressed to "0-99" as soon as you create an object from it. When comparing mixed values, "99" is considered bigger than both "a" and "z" because it's longer, so the second range is indeed part of the first to start with.
Examples:
- The array (1, 2, 3, 5) will be compressed to the list (string) "1-3,5".
- The list (string) "aa-zz" contains all combinations of two lower case letters when interpreted as a list: ('aa', 'ab', 'ac', ... 'zy', 'zz'). That's 2x26x26 = 1352 characters packed to just 5 (not to mention the overhead when you put the strings into an array)!
Tags
Table of Contents
Constants
- RE_VALUE = '[0-9A-Za-z]'
- This regex limits the characters allowed in values
Properties
- $list : string
- The string representation of the list
Methods
- __construct() : CompressedList
- Constructs a list from the given string or array
- add() : mixed
- Adds the value to the list
- append() : mixed
- Appends the value to the list
- array_to_string() : string
- Returns the ranges in an array as a string representing the compressed list
- as_string() : string
- Returns this list, in its compressed string representation
- clean() : mixed
- Cleans up this compressed list
- contains() : bool
- Returns true if $value is included in this list
- prepend() : mixed
- Prepends the value to the list
- range_array() : array<string|int, mixed>
- Returns the ranges (and single values) in this list as an array
- range_limits() : array<string|int, mixed>
- Returns an array with the start and end values of a range (or value)
- range_remove() : CompressedList
- Removes the range from the list
- range_valid() : bool
- Returns true if the given $range is valid
- ranges_compatible() : bool
- Returns true if the two ranges are compatible
- test() : mixed
- _contains() : bool
- Returns true if $value is included in the $list
- _range_array() : array<string|int, mixed>
- Returns the ranges (and single values) in the given list string as an array
- cmp() : int
- Returns the result of comparing the two values
- cmp_range() : int
- Returns the result of comparing the two ranges
- dec() : mixed
- Decrement the $value by one
- range_extend() : string
- Returns the union of the given range with the range given in $reduce
- range_reduce() : string
- Returns the given range by the range given in $reduce
Constants
RE_VALUE
This regex limits the characters allowed in values
public
mixed
RE_VALUE
= '[0-9A-Za-z]'
See range_valid()
Properties
$list
The string representation of the list
private
string
$list
= \null
Methods
__construct()
Constructs a list from the given string or array
public
__construct(mixed $mixed) : CompressedList
Parameters
- $mixed : mixed
-
The string or array
Return values
CompressedList —The list
add()
Adds the value to the list
public
add(string $value) : mixed
If the same value is already present, no change is made. Otherwise, this method calls clean(), so mind that the order of your list and even some ranges in it may be modified. Note that this is a optimized version of range_extend() for simple values.
Parameters
- $value : string
-
The value
Tags
append()
Appends the value to the list
public
append(string $value) : mixed
If the same value is already present, no change is made.
Parameters
- $value : string
-
The value
Tags
array_to_string()
Returns the ranges in an array as a string representing the compressed list
public
static array_to_string(array<string|int, mixed> $array) : string
This is usually only called by __construct().
Parameters
- $array : array<string|int, mixed>
-
The value array
Tags
Return values
string —The string representing the list
as_string()
Returns this list, in its compressed string representation
public
as_string() : string
Return values
string —The list as a string
clean()
Cleans up this compressed list
public
clean() : mixed
Note that afterwards, the list is normalized, meaning that it is ordered and recompressed to its minimal form. That implies that duplicates will be removed, too.
Tags
contains()
Returns true if $value is included in this list
public
contains(int $value) : bool
Parameters
- $value : int
-
The value to search for
Tags
Return values
bool —True if found, false otherwise
prepend()
Prepends the value to the list
public
prepend(string $value) : mixed
If the same value is already present, no change is made.
Parameters
- $value : string
-
The value
Tags
range_array()
Returns the ranges (and single values) in this list as an array
public
range_array() : array<string|int, mixed>
Note that spaces and surplus commas are stripped.
Tags
Return values
array<string|int, mixed> —The value array
range_limits()
Returns an array with the start and end values of a range (or value)
public
static range_limits(string $range) : array<string|int, mixed>
The range string must be of the form "X" or "X-Y". For the first form, returns array(X, X) and for the second form array(X, Y) If the range string does not match either form, returns null.
Parameters
- $range : string
-
The range string
Tags
Return values
array<string|int, mixed> —The start and end value, or null
range_remove()
Removes the range from the list
public
range_remove(mixed $range) : CompressedList
If the range is not present at all, no change is made. If the range only partially overlaps, the overlapping part is removed. if the range overlaps with more than one range (or value), all of them are reduced or removed as necessary.
Parameters
- $range : mixed
Tags
Return values
CompressedList —The modified list
range_valid()
Returns true if the given $range is valid
public
static range_valid(string $range) : bool
Valid ranges MUST have an end value that is not smaller than the start value.
Parameters
- $range : string
-
The possible range
Return values
bool —True if the range is valid, false otherwise
ranges_compatible()
Returns true if the two ranges are compatible
public
static ranges_compatible(string $range1, string $range2) : bool
Two ranges are compatible iff their union can be represented by a single range. In other words, the list formed by both ranges must not contain any gaps.
Parameters
- $range1 : string
-
The first range
- $range2 : string
-
The second range
Tags
Return values
bool —True if the two ranges are compatible
test()
public
static test() : mixed
_contains()
Returns true if $value is included in the $list
private
static _contains(string $list, int $value) : bool
Parameters
- $list : string
-
The list string to search
- $value : int
-
The value to search for
Tags
Return values
bool —True if found, false otherwise
_range_array()
Returns the ranges (and single values) in the given list string as an array
private
static _range_array(string $list) : array<string|int, mixed>
Note that spaces and surplus commas are stripped.
Parameters
- $list : string
-
The list string
Tags
Return values
array<string|int, mixed> —The value array
cmp()
Returns the result of comparing the two values
private
static cmp(string $value1, string $value2) : int
If both values are numeric, they are compared as numbers. Otherwise, the shorter string is always considered smaller. Same length strings are compared by strcmp(). The result is -1 if the first is smaller, +1 if the first is bigger, or 0 if they are equal.
Parameters
- $value1 : string
-
A numeric or string value
- $value2 : string
-
A numeric or string value
Return values
int —-1, 0, or 1
cmp_range()
Returns the result of comparing the two ranges
private
static cmp_range(string $range1, string $range2) : int
Order is determined by the start values in each range. If they are equal, by the end values. Values are compared using cmp(). The result is -1 if the first is smaller, +1 if the first is bigger, or 0 if they are equal.
Parameters
- $range1 : string
-
The first range
- $range2 : string
-
The second range
Return values
int —-1, 0, or 1
dec()
Decrement the $value by one
private
static dec(string &$value) : mixed
Works for strings as well as integer numbers. Works around the disfunct "--" operator in PHP. Note that this will leave the value unchanged for empty values like null, false, or the empty string. Only strings matching /[a-zA-Z0-9]+/ will work properly, other characters will cause unexpected results! Any single digit will never be changed into a letter or vice versa. The case of letters will never change. Decrementing 0 (zero) results in -1, as expected. Decrementing either 'a' or 'A' results in the empty string.
Parameters
- $value : string
-
A numeric or string value, by reference
Tags
range_extend()
Returns the union of the given range with the range given in $reduce
private
static range_extend(string $range, string $extend) : string
The ranges may be provided in any order. If the union of the two ranges contains no gap, returns a single range that contains the values of both. Otherwise, returns a string with the two ranges concatenated to a list.
Parameters
- $range : string
-
The original range
- $extend : string
-
The range to extend with
Return values
string —The union of both ranges
range_reduce()
Returns the given range by the range given in $reduce
private
static range_reduce(string $range, string $reduce) : string
This literally cuts the range in $reduce out of the given $range and returns the remainder, which may consist of two ranges instead! If the two ranges do not overlap at all, the original range is returned without change. If $reduce contains the entire $range, returns the empty string. If only a single value is left over, that is returned.
Parameters
- $range : string
-
The original range
- $reduce : string
-
The range to remove
Return values
string —The remainder of the original range