{% extends "base.html" %} {% block title %}Rangesets (25){% endblock %} {% block content %}
Rangesets are a tool of the macro language to tag parts, or ranges, of the text, which shall be viewed as a group. A range is merely a contiguous range of characters between a start and an end position in the document, and a set of ranges belonging together is called a rangeset. So, a rangeset is nothing but an in general non-contiguous part of the text.
Rangesets can be assigned a background color to make them visible: characters within all ranges of a rangeset will have the background color of the rangeset. (If more than one rangeset includes a given character, its background color will be that of the most recently created rangeset which has a color defined.)
Applications of rangesets are for example:
Rangesets are manipulated only through macro routines. Rangesets must be created first using the rangeset_create()
function, which will return an identifier for the newly-created (empty) rangeset. This identifier is then passed to the other rangeset functions to manipulate the rangeset. For example, ranges are added to a rangeset with the rangeset_add()
function.
Notice that the ranges inside a rangeset do not have a particular identity. Only, they are given a (dynamically changing) numeric index, counting from 1, in the order of appearance in the text buffer. The ranges are adjusted when modifications are made to the text buffer: they shift around when characters are added or deleted staying with the original strings of characters. However, ranges within a set will coalesce if the characters between them are removed, or a new range is added to the set which bridges or overlaps others. For more on this, see "How rangesets change with modifications".
There is a limit to the number of rangesets which can exist at any time - currently up to 63 in each document. Care should be taken to destroy any rangesets which are no longer needed, by using the rangeset_destroy() function, if this limit is attained.
Rangesets can be named: this is useful for macros which need a fixed identification for rangesets which are used for the same purpose in different documents. Although a new rangeset's number is arbitrary, its name can be fixed. This is done using the rangeset_set_name() function. Note that rangeset names within a particular document may not be unique. For this reason, the rangeset_get_by_name() function returns an array of identifiers, which will be empty if the name has not been associated with a rangeset.
When changes are made to the document text, ranges within each set are altered with it, according to their behavioral mode. If changes are made outside of the ranges in a rangeset, each range simply maintains its size and adjusts its position to match the changes. When text within a range is deleted, the range's length is reduced by the same amount. When changes involving new text are made within a range of the set, or to one of the extremities of a range, different behaviours may be desirable. The rangeset_set_mode() function allows these modes to be chosen.
Note that the precise behaviour of these modes may change in future versions of NEdit.
The available modes are:
A rangeset is manipulated only through macro routines. Rangesets can easily become very large, and may exceed the capacity of the running process. Coloring relies on proper color names or specifications (such as the "#rrggbb" hexadecimal digit strings), and appropriate hardware support. If an invalid color name is given, the default background color is used instead. Behaviours set using rangeset_set_mode() are subject to change in future versions.
$rangeset_list
rangeset_create()
rangeset_create( n )
rangeset_destroy( r )
rangeset_destroy( array )
rangeset_add( r )
rangeset_add( r, start, end )
rangeset_add( r, r0 )
Adds to the rangeset r. The first form adds the range identified by the current primary selection to the rangeset, unless the selection is rectangular. The second form adds the range defined by the start and end positions given. The third form adds all ranges in the rangeset r0 to the rangeset r, and returns 0.
Returns the index of the newly-added range within the rangeset.
rangeset_subtract( r, [start, end] )
rangeset_subtract( r, r0 )
rangeset_invert( r )
rangeset_get_by_name( name )
rangeset_info( r )
rangeset_range( r, [index] )
rangeset_includes( r, pos )
rangeset_set_color( r, color )
rangeset_set_name( r, name )
rangeset_set_mode( r, type )