Description: Documentation

## variable KILL_ARRAY_SIZE

### Synopsis

The size of the internal kill buffer array

### Usage

Int_Type KILL_ARRAY_SIZE

### Description

This variable contains the value of the size of the internal kill array of character strings. Any number from zero up to but not including the value of KILL_ARRAY_SIZE may be used as an argument in the functions that manipulate this array.

### Notes

This variable is a read-only varaible and may not available on 16 bit systems.

### See also

insert_from_kill_array , copy_region_to_kill_array , append_region_to_kill_array

## function append_region_to_file

### Synopsis

append_region_to_file

### Usage

Integer append_region_to_file (String file);

### Description

Appends a marked region to file returning number of lines written or \-1 on error. This does NOT modify a buffer visiting the file; however, it does flag the buffer as being changed on disk.

## function append_region_to_kill_array

### Synopsis

append_region_to_kill_array

### Usage

Void append_region_to_kill_array (Integer n);

### Description

This function appends the currently defined region to the contents of nth element, specified by n , of an internal array of character strings. Note: This function is not available on 16 bit systems.

### See also

insert_from_kill_array , copy_region_to_kill_array

### See also

KILL_ARRAY_SIZE

## function bufsubstr

### Synopsis

bufsubstr

### Usage

String bufsubstr ();

### Description

This function returns a string that contains the characters in the region specified by a mark and the current editing point. If the region crosses lines, the string will contain newline characters.

### See also

insbuf , push_mark

## function check_region

### Synopsis

check_region

### Usage

Void check_region (Integer ps);

### Description

This function checks to see if a region is defined and may exchange the current editing point and the mark to define a canonical region. If the mark is not set, it signals an S-Lang error. A canonical region is one with the mark set earlier in the buffer than than the editing point. Always call this if using a region which requires such a situation. If the argument ps is non-zero, push_spot will be called, otherwise, ps is zero and it will not be called. As an example, the following function counts the number of lines in a region:

            define count_lines_region ()
            {
               variable n;
               check_region (1);   % spot pushed
               narrow ();
               n = what_line ();
               widen ();
               pop_spot ();
               return n;
             }

### See also

markp , push_mark

## function copy_region

### Synopsis

copy_region

### Usage

Void copy_region (String buf);

### Description

This function may be used to copy a region defined by a mark and the current position to the buffered specified by the name buf . It does not delete the characters in region but it does pop the mark that determines the region.

### See also

insbuf , bufsubstr , push_mark , pop_mark , bufferp

## function copy_region_to_kill_array

### Synopsis

copy_region_to_kill_array

### Usage

Void copy_region_to_kill_array (Integer n);

### Description

This function copies the currently defined region to the nth element, specified by n , of an internal array of character strings replacing what is currently there. Note: This function is not available on 16 bit systems.

### See also

insert_from_kill_array , append_region_kill_array

### See also

KILL_ARRAY_SIZE

## function count_narrows

### Synopsis

count_narrows

### Usage

Integer count_narrows ();

### Description

This function returns the narrow depth of the current buffer.

### See also

narrow , widen , widen_buffer , push_narrow

## function narrow

### Synopsis

narrow

### Usage

Void narrow ();

### Description

This function may be used to restict editing to the region of lines between the mark and the editing point. The region includes the line containing the mark as well as the line at the current point. All other lines outside this region are completely inacessable without first lifting the restriction using the widen function. As a simple example, suppose that there is a function called print_buffer that operates on the entire buffer. Then the following function will work on a region of lines:

            define print_region ()
            {
               narrow ();
               print_buffer ();
               widen ();
            }

The narrow function will signal an error if the mark is not set. Note also that the narrow function may be used recursively in the sense that a narrowed region may be further restricted using the narrow function. For each narrow, the widen function must be called to lift each restriction.

### See also

widen , narrow_to_region

## function narrow_to_region

### Synopsis

narrow_to_region

### Usage

Void narrow_to_region (void);

### Description

The narrow_to_region function behaves like the narrow function that narrow operates on lines and narrow_to_region restricts editing to only characters within the region.

### See also

widen_region , narrow.

## function pipe_region

### Synopsis

pipe_region

### Usage

Integer pipe_region (String cmd);

### Description

The pipe_region function executes cmd in a separate process and sends the region of characters defined by the mark and the current point to the standard input of the process. It successful, it returns the exit status of the process. Upon failure it signals an error. Note: This function is only available for Unix and OS/2 systems.

### See also

run_shell_cmd , push_mark

## function pop_narrow

### Synopsis

pop_narrow

### Usage

Void pop_narrow ();

### Description

The purpose of this function is to restore the last narrow context that was saved via push_narrow .

### See also

push_narrow , widen , widen_buffer

## function push_narrow

### Synopsis

push_narrow

### Usage

Void push_narrow ();

### Description

This function saves the current narrow context. This is useful when one wants to restore this context after widening the buffer.

### See also

pop_narrow , narrow , widen , widen_buffer

## function translate_region

### Synopsis

translate_region

### Usage

Void translate_region ();

### Description

This function uses the global character array TRANSLATE_ARRAY to modify the characters in a region based on the mapping defined by the array. The only restriction is that the newline character cannot be mapped. This example

            define swap_a_and_b ()
            {
              variable i;
              _for (0; 255, 1)
                {
                   i = ();
                   TRANSLATE_ARRAY[i] = i;
                }
              TRANSLATE_ARRAY['a'] = 'b';
              TRANSLATE_ARRAY['b'] = 'a';
              bob (); push_mark (); eob ();
              translate_region ();
            }

uses translate_region to swap the 'a' and 'b' characters in the current buffer.

### See also

insert , delete, what_char

### See also

TRANSLATE_ARRAY

## function widen

### Synopsis

widen

### Usage

Void widen ();

### Description

This function undoes the effect of narrow . Consult the documentation for narrow for more information.

### See also

widen_region , narrow

## function widen_buffer

### Synopsis

widen_buffer

### Usage

Void widen_buffer ();

### Description

This function widens the whole buffer. If one intends to restore the narrow context after calling this function, the narrow context should be saved via push_narrow .

### See also

narrow , widen , push_narrow , pop_narrow

## function widen_region

### Synopsis

widen_region

### Usage

Void widen_region ();

### Description

This function undoes the effect of narrow_to_region . Consult the documentation for narrow_to_region for more information.

### See also

widen , narrow_to_region

## function write_region_to_file

### Synopsis

write_region_to_file

### Usage

Integer write_region_to_file (String filename);

### Description

This function may be used to write a region of the current buffer to the file specified by filename . It returns the number of lines written to the file or signals an error upon failure.

### See also

write_buffer , append_region_to_file , push_mark

## function xform_region

### Synopsis

xform_region

### Usage

Void xform_region (Integer how);

### Description

This function changes the characters in the region in a way specified by the parameter how . This is an integer that can be any of of the following:

            'u'       Upcase_region
            'd'       Downcase_region
            'c'       Capitalize region

Anything else will change case of region.

### See also

translate_region , define_case