Next Previous Contents

20. Functions that Involve Regions

20.1 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

20.2 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.

20.3 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

20.4 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

20.5 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

20.6 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

20.7 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

20.8 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

20.9 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

20.10 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.

20.11 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

20.12 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

20.13 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

20.14 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

20.15 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

20.16 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

20.17 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

20.18 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

20.19 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


Next Previous Contents