/ 
Google-RestApi-1.0.4
River stage zero No dependents
/ Google::RestApi::SheetsApi4::Range

NAME

Google::RestApi::SheetsApi4::Range - Represents a range in a Worksheet.

DESCRIPTION

A Range object that represents a range in a remote spreadsheet. These are normally short-lived objects used to set up and execute a remote action. Keep in mind that the remote spreadsheet can be concurrently updated by many people, so a compromise must always be reached between holding a copy of the local cell values versus the number of network calls to the Google API to keep the values current.

A range can be specified in whatever way is most convenient.

For ranges:

* A1 notation: A1:B2
* Hash: [ { col => (A|1), row => 1 }, { col => (B|2), row => 2 } ]
* Array: [ [ (A|1), 1 ], [ (B|2), 2 ] ]

For columns:

* A1 notation: A or A:A
* Hash: { col => (A|1) }
* Array: [ A|1 ]

For rows:

* A1 notation: 1 or 1:1
* Hash: { row => 1 }
* Array: [ <false>, 1 ]

For cells:

* A1 notation: A1
* Hash: { col => (A|1), row => 1 }
* Array: [ (A|1), 1 ]

See the description and synopsis at Google::RestApi::SheetsApi4.

NAVIGATION

SUBROUTINES

new(%args);

Creates a new range object for the given worksheet.

%args consists of:

  • worksheet <Worksheet>: The parent Worksheet object for this range.

  • range <range>: The range for this object, either A1 notation, hash {col => x, row => x} or array [col, row].

  • dim <col|row>: The major dimension for this range, either 'col' or 'row', defaults to 'row'.

You would not normally call this directly, you'd use Worksheet::range* methods to create the range object for you. It is recommended and safer to use the Worksheet's methods to create ranges.

api(%args);

Calls the parent Worksheet's 'api' routine with the range added into the URI or content appropriately. This then get's passed to the Spreadsheet's api routine where the spreadsheet ID is tacked on to the URI. This then gets passed to the SheetsApi4's api routine where the Sheets endpoint is tacked on to the URI. This then gets passed to RestApi's api routine for actual execution.

You would not normally call this directly unless you were making a Google API call not currently supported by this API framework.

clear();

Clears the values using Google API's 'A1:clear' call.

refresh_values();

Immediately refreshes and returns the values from the spreadsheet.

values(values => <arrayref>, %args);

Immediately gets or sets the values using Google API's 'get' or 'update'.

values: The array ref of cells to update.

'args' are passed to the SheetsApi4's 'api' routine so you may add extra arguments to the 'params' (such as valueInputOption) or 'content' as necessary.

batch_values(values => <arrayref>);

Gets or sets the queued batch values that will be sent to Google API at a later time. Call 'submit_values' to send them later.

values: The array ref of cells to update.
submit_values(%args);

Sends the previously queued batch values to Google API, if any.

'args' are passed to the SheetsApi4's 'api' routine so you may add extra arguments to the 'params' or 'content' as necessary.

submit_requests(%args);

Sends the previously queued requests (formatting, sheet properties etc) to Google API, if any.

'args' are passed to the SheetsApi4's 'api' routine so you may add extra arguments to the 'params' or 'content' as necessary.

normalize_named();

If this is a 'named range', get the named range property from the spreadsheet and set this object's real range that the named range represents.

named();

Returns the 'named range' for this range, if any.

range();

Returns the A1 notation for this range.

range_to_hash();

Returns the hash representation for this range (e.g. {col => 1, row => 1}). Passing $RANGE_EXPANDED will always return a double cell notations: [{col => 1, row => 1}, {col => 1, row => 1}].

range_to_array();

Returns the array representation for this range (e.g. [1, 1]). Passing $RANGE_EXPANDED will always return a double cell notations: [[ 1, 1 ], [ 1, 1]].

range_to_index();

Returns the index hash representation for this range, used for formatting requests etc. You would not normally need to call this yourself.

range_to_dimension();

Returns the dimension hash representation for this range, used for insert requests etc. You would not normally need to call this yourself.

offset(col => <int>, row => <int>, top => <int>, left => <int>, bottom => <int>, right => <int>);

Returns a new range object offset from this range.

col: Optionally offset the new range by this many columns.
row: Optionally offset the new range by this many rows.
top: Optionally offset the new range with the new top.
left: Optionally offset the new range with the new left.
bottom: Optionally offset the new range with the new bottom.
right: Optionally offset the new range with the new right.
offsets(range<Range>);

Returns the offsets of this range from the given range in an array (top, left, bottom, right).

iterator(%args);

Returns an iterator for this range. Any 'args' are passed to the 'new' routine for the iterator.

is_other_inside(range<Range>);

Returns a true value if the given range fits entirely inside this range.

share_values(range<Range>);

Share the cell values between this range and the passed range.

Normally ranges are short-lived, throw-away objects used to interact with the Google API. Range objects work independently and don't share any common storage of cells. No attempt is made to share a common, local grid that mirrors what's in the remote spreadsheet. The spreadsheet is a shared resource that can be updated concurrently by multiple users, so attempting to mirror it locally is a waste of time unless some kind of listener is provided that can be used to syncronize the remote updates with the local copy (which Google doesn't).

However, for some cases, like iterators, we can set up ranges to share values between them for a short time in order to reduce the number of network calls to the Google API while you iterate over the cells. When the iterated cell values are updated, the parent range's value is also updated.

So far, this is the only use-case I can see for sharing the cell grid between ranges.

dimension();

Returns this range's major dimension (col|row).

has_values();

Returns a true value if this range's values have been set either via 'values' or 'batch_values' routines.

worksheet();

Returns the parent Worksheet object.

worksheet_name();

Returns the parent Worksheet name.

worksheet_id();

Returns the parent Worksheet ID.

spreadsheet();

Returns the parent Spreadsheet object.

spreadsheet_id();

Returns the parent Spreadsheet ID.

AUTHORS

  • Robin Murray mvsjes@cpan.org

COPYRIGHT

Copyright (c) 2021, Robin Murray. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.