{"id":18246171,"url":"https://github.com/mfcovington/number-rangetracker","last_synced_at":"2025-04-08T18:55:59.483Z","repository":{"id":9157232,"uuid":"10952283","full_name":"mfcovington/Number-RangeTracker","owner":"mfcovington","description":"A Perl 5 module to keep track of numerical ranges quickly","archived":false,"fork":false,"pushed_at":"2016-01-31T11:49:53.000Z","size":198,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-02-14T15:14:56.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://cpan.me/Number::RangeTracker","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfcovington.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-25T22:39:52.000Z","updated_at":"2016-01-31T11:49:54.000Z","dependencies_parsed_at":"2022-09-08T09:30:25.325Z","dependency_job_id":null,"html_url":"https://github.com/mfcovington/Number-RangeTracker","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfcovington%2FNumber-RangeTracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfcovington%2FNumber-RangeTracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfcovington%2FNumber-RangeTracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfcovington%2FNumber-RangeTracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfcovington","download_url":"https://codeload.github.com/mfcovington/Number-RangeTracker/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247909161,"owners_count":21016478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T09:24:50.084Z","updated_at":"2025-04-08T18:55:59.455Z","avatar_url":"https://github.com/mfcovington.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/mfcovington/Number-RangeTracker.svg?branch=master)](https://travis-ci.org/mfcovington/Number-RangeTracker) [![Coverage Status](https://coveralls.io/repos/mfcovington/Number-RangeTracker/badge.png?branch=master)](https://coveralls.io/r/mfcovington/Number-RangeTracker?branch=master)\n\n# NAME\n\nNumber::RangeTracker - Keep track of numerical ranges quickly\n\n# VERSION\n\nVersion 0.6.1\n\n# SYNOPSIS\n\nCreate and modify ranges (three range syntaxes shown):\n\n    my $range = Number::RangeTracker-\u003enew;\n    $range-\u003eadd( [ 1, 10 ], '11..20' );\n    $range-\u003eremove( 6, 15 );\n\nOutput ranges, their complement, or integers within ranges\n(differences between scalar and list contexts shown):\n\n    $range-\u003eoutput;\n      # Scalar context: '1..5,16..20'\n      # List context:   ( 1 =\u003e 5, 16 =\u003e 20 )\n\n    $range-\u003ecomplement;\n      # Scalar context: '-inf..0,6..15,21..+inf'\n      # List context:   ( -inf =\u003e 0, 6 =\u003e 15, 21 =\u003e +inf )\n\n    $range-\u003eintegers;\n      # Scalar context: '1,2,3,4,5,16,17,18,19,20'\n      # List context:   ( 1, 2, 3, 4, 5, 16, 17, 18, 19, 20 )\n\nExamine range characteristics:\n\n    $range-\u003elength;              # 8\n    $range-\u003esize;                # 10\n\n    $range-\u003eis_in_range(100);    # 0\n    $range-\u003eis_in_range(18);     # 1, 16, 20\n\n# DESCRIPTION\n\nAn instance of the Number::RangeTracker class is used to keep track of\na set of numerical ranges. Ranges can be added to and removed from\nthis collection of ranges. Overlapping ranges are collapsed to form a\nsingle, longer range. Ranges can be manipulated, examined, and output\nin a variety of ways.\n\nWhile some other modules associate values with a range of keys (see\n[\"SEE ALSO\"](#see-also)), the objective of Number::RangeTracker is to quickly and\neasily monitor the integers on a number line that are covered by at\nleast one range. Number::RangeTracker performs significantly faster\nthan other modules that have similar functions (see [\"SEE ALSO\"](#see-also)).\n\n- new\n\n    Initializes a new Number::RangeTracker object.\n\n- add( START, END )\n\n    Add one or more ranges. This can be used multiple times to add ranges\n    to the object. Ranges can be added in several ways. The following are\n    equivalent.\n\n        $range-\u003eadd( [ 1, 10 ], [ 16, 20 ] );\n        $range-\u003eadd( 1, 10, 16, 20 );\n        $range-\u003eadd( '1..10', '16..20' );\n\n- remove( START, END )\n\n    Remove one or more ranges from the current set of ranges. This can be\n    used multiple times to remove ranges from the object. Ranges can be\n    removed with the same syntax used for adding ranges.\n\n- collapse\n\n    When ranges are added or removed, overlapping ranges are not collapsed\n    until necessary. This allows range Number::RangeTracker to be very\n    fast.\n\n    Ranges can be manually collapsed to avoid memory issues when\n    working with very large amounts of ranges. In one test, a million\n    overlapping ranges required ~100 MB of memory. This requirement was\n    cut drastically by collapsing ranges after every 100,000th range was\n    added.\n\n    Ranges are automatically collapsed (and merged or removed where\n    appropriate) (1) before ranges are added (if there are ranges still\n    waiting to be removed) and (2) before each of the following methods is\n    executed.\n\n- length\n\n    Returns the total length of all ranges combined.\n\n- size\n\n    Returns the total number of elements (i.e., integers) of all ranges.\n\n- is\\_in\\_range( VALUE )\n\n    Test whether a VALUE is contained within one of the ranges. Returns 0\n    for a negative result. Returns a list of three numbers for a positive\n    result: 1, start position of the containing range, end position of the\n    containing range.\n\n- output\n\n    Returns all ranges sorted by their start positions. In list context,\n    returns a list of all ranges sorted by start positions. This is\n    suitable for populating a hash, an array, or even another range\n    object. In scalar context, returns a string of ranges formatted as:\n    `1..10,16..20`.\n\n- integers\n\n    Returns each integer contained within the ranges. In list context,\n    returns a sorted list. In scalar context, returns a sorted,\n    comma-delimited string of integers.\n\n- complement( UNIVERSE\\_START, UNIVERSE\\_END )\n\n    Returns the complement of a set of ranges. The output is in list\n    context sorted by range start positions.\n\n        my $original_range = Number::RangeTracker-\u003enew;\n        $original_range-\u003eadd( [ 11, 20 ], [ 41, 60 ], [ 91, 110 ] );\n\n        my %complement = $original_range-\u003ecomplement;\n        # -inf =\u003e 10,\n        # 21   =\u003e 40,\n        # 61   =\u003e 90,\n        # 111  =\u003e +inf\n\n    UNIVERSE\\_START and UNIVERSE\\_END can be used to specify a finite subset\n    of the 'universe' of numbers (defaults are -/+ infinity. The\n    complement ranges are bounded by these values.\n\n        %complement = $original_range-\u003ecomplement( 1, 50 );\n        # 1  =\u003e 10,\n        # 21 =\u003e 40\n\n    A new object with the complement of a set of ranges can be created\n    quickly and easily.\n\n        my $complement_range = Number::RangeTracker-\u003enew;\n        $complement_range-\u003eadd( $original_range-\u003ecomplement );\n\n# SEE ALSO\n\n- Monitor the integers covered by at least one range\n\n    Although there is some functional overlap between this module,\n    [Number::Range](https://metacpan.org/pod/Number::Range), and\n    [Range::Object::Serial](https://metacpan.org/pod/Range::Object::Serial), Number::RangeTracker\n    is significantly faster.\n\n    It takes less than one second for Number::RangeTracker to add 100,000\n    overlapping ranges. Over this same period of time, Number::Range and\n    Range::Serial::Object are only able to add 1,000 and 300 ranges,\n    respectively.\n\n    Some tasks require even higher throughput. When adding 1 million\n    overlapping ranges, Number::Range took \u003e250 times as long as\n    Number::RangeTracker (35 min 31 sec vs. 8 sec). Range::Object::Serial\n    slows exponentially as ranges are added and, therefore, it was not\n    feasible to test this many ranges.\n\n    ![See https://raw.githubusercontent.com/mfcovington/Number-RangeTracker/master/compare-modules/speed-comparison.png for a speed comparison of range modules](https://raw.githubusercontent.com/mfcovington/Number-RangeTracker/master/compare-modules/speed-comparison.png \"Speed comparison of range modules\")\n\n- Ranges with strandedness (like double-stranded DNA or mile posts\non a two-way road)\n\n    [Bio::Range](https://metacpan.org/pod/Bio::Range)\n\n- Compare numbers in an imprecision-tolerant manner\n\n    [Number::Tolerant](https://metacpan.org/pod/Number::Tolerant)\n\n- Named ranges\n\n    [Tie::RangeHash](https://metacpan.org/pod/Tie::RangeHash),\n    [Array::IntSpan](https://metacpan.org/pod/Array::IntSpan)\n\n# SOURCE AVAILABILITY\n\nThe source code is on Github:\n[https://github.com/mfcovington/Number-RangeTracker](https://github.com/mfcovington/Number-RangeTracker)\n\n# AUTHOR\n\nMichael F. Covington, \u003cmfcovington@gmail.com\u003e\n\n# BUGS\n\nPlease report any bugs or feature requests at\n[https://github.com/mfcovington/Number-RangeTracker/issues](https://github.com/mfcovington/Number-RangeTracker/issues).\n\n# INSTALLATION\n\nTo install this module from GitHub using cpanm:\n\n    cpanm git@github.com:mfcovington/Number-RangeTracker.git\n\nAlternatively, download and run the following commands:\n\n    perl Build.PL\n    ./Build\n    ./Build test\n    ./Build install\n\n# SUPPORT AND DOCUMENTATION\n\nYou can find documentation for this module with the perldoc command.\n\n    perldoc Number::RangeTracker\n\n# LICENSE AND COPYRIGHT\n\nCopyright 2014 Michael F. Covington.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the terms of the the Artistic License (2.0). You may obtain a\ncopy of the full license at:\n\n[http://www.perlfoundation.org/artistic\\_license\\_2\\_0](http://www.perlfoundation.org/artistic_license_2_0)\n\nAny use, modification, and distribution of the Standard or Modified\nVersions is governed by this Artistic License. By using, modifying or\ndistributing the Package, you accept this license. Do not use, modify,\nor distribute the Package, if you do not accept this license.\n\nIf your Modified Version has been derived from a Modified Version made\nby someone other than you, you are nevertheless required to ensure that\nyour Modified Version complies with the requirements of this license.\n\nThis license does not grant you the right to use any trademark, service\nmark, tradename, or logo of the Copyright Holder.\n\nThis license includes the non-exclusive, worldwide, free-of-charge\npatent license to make, have made, use, offer to sell, sell, import and\notherwise transfer the Package with respect to any patent claims\nlicensable by the Copyright Holder that are necessarily infringed by the\nPackage. If you institute patent litigation (including a cross-claim or\ncounterclaim) against any party alleging that the Package constitutes\ndirect or contributory patent infringement, then this Artistic License\nto you shall terminate on the date that such litigation is filed.\n\nDisclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER\nAND CONTRIBUTORS \"AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.\nTHE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR\nPURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY\nYOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR\nCONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR\nCONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,\nEVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfcovington%2Fnumber-rangetracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfcovington%2Fnumber-rangetracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfcovington%2Fnumber-rangetracker/lists"}