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 potentially updated by many people, so a compromise must always be reached between holding a copy of the local cell values and 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 cells:

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

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 ]

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

SUBROUTINES

new(worksheet => <Worksheet>, range => <Range>, dim => (col|row));

Creates a new range object for the given worksheet.

 worksheet: The parent Worksheet object for this range.
 range: The range for this object, either A1 notation, hash {col => x, row => x} or array [col, row].
 dim: 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.

api(%args);

Calls the parent worksheet's 'api' routine with the range added into the URI or content appropriately.

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

is_named {

Returns a true value if this range represents a 'named range'. See: https://support.google.com/docs/answer/63175?co=GENIE.Platform%3DDesktop&hl=en

range();

Returns the A1 notation for this range.

range_to_hash();

Returns the hash representation for this range (e.g. {col => 1, row => 1}).

range_to_array();

Returns the array representation for this range (e.g. [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: Optional offset of the new range by this many columns.
 row: Optional offset of the new range by this many rows.
 top: Optional offset of the new range with the new top.
 left: Optional offset of the new range with the new left.
 bottom: Optional offset of the new range with the new bottom.
 right: Optional offset of 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_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.

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.

config();

Returns the parent Worksheet config hash.

AUTHORS

• Robin Murray mvsjes@cpan.org

COPYRIGHT

Copyright (c) 2019, 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.