How to replace numbered list elements with an identifier containing the number

Question

I have gotten amazing help here today!

I'm trying to do something else. I have a numbered list of questions in a Google Doc, and I'd like to replace the numbers with something else.

For example, I'd like to replace the numbers in a list such as:

9. The Earth is closest to the Sun in which month of the year? ~July ~June =January ~March ~September

10. In Australia (in the Southern Hemisphere), when are the days the shortest and the nights the longest? ~in late December ~in late March =in late June ~in late April ~days and nights are pretty much the same length throughout the year in Australia

With:

::Q09:: The Earth is closest to the Sun in which month of the year? ~July ~June =January ~March ~September

::Q11:: In Australia (in the Southern Hemisphere), when are the days the shortest and the nights the longest? ~in late December ~in late March =in late June ~in late April ~days and nights are pretty much the same length throughout the year in Australia

I've tried using suggestions from previous posts but have come up only with things such as the following, which doesn't seem to work.

Thank you for being here!!!

function questionName2(){
  var body = DocumentApp.getActiveDocument().getBody();
  var text = body.editAsText();
    var pattern = "^[1-9]";
    var found = body.findText(pattern);
    var matchPosition = found.getStartOffset();
  
  while(found){
    text.insertText(matchPosition,'::Q0');
    found = body.findText(pattern, found);
  }
}

Answer 1

Regular expressions

Text.findText(searchPattern) uses a string that will be parsed as a regular expression using Google's RE2 library for the searchPattern. Using a string in this way requires we add an extra backslash whenever we are removing special meaning from a character, such as matching the period after the question number, or using a character matching set like \d for digits.

^\\s*\\d+?\\. will match a set of digits, of any non-zero length, that begin a line, with any length (including zero) of leading white space. \d is for digits, + is one or more, and the combination +? makes the match lazy. The lazy part is not required here, but it's my habit to default to lazy to avoid bugs. An alternative would be \d{1,2} to specifically match 1 to 2 digits.

To extract just the digits from the matched text, we can use a JavaScript RegExp object. Unlike the Doc regular expression, this regular expression will not require extra backslashes and will allow us to use capture groups using parentheses.

^\s*(\d+?)\. is almost the same as above, except no extraneous slashes and we will now "save" the digits so we can use them in our replacement string. We mark what we want to save using parentheses. Because this will be a normal JavaScript regular expression literal, we will wrap the whole thing in slashes: /^\s*(\d+?)\./, but the starting and ending / are just to indicate this is a RegExp literal.

text elements and text strings

Text.findText can return more than just the exact match we asked for: it returns the entire element that contains the text plus indices for what the regular expression matched. In order to perform search and replace with capture groups, we have to use the indices to delete the old text and then insert the new text.

The following assignments get us all the data we need to do the search and replace: first the element, then the start & stop indices, and finally extracting the matched text string using slice (note that slice uses an exclusive end, whereas the Doc API uses an inclusive end, hence the +1).

var found = DocumentApp.getActiveDocument().getBody().findText(pattern);
var matchStart = found.getStartOffset();
var matchEnd = found.getEndOffsetInclusive();
var matchElement = found.getElement().asText();
var matchText = matchElement.getText().slice(matchStart, matchEnd + 1);

Caveats

As Tanaike pointed out in the comments, this assumes the numbering is not List Items, which automatically generates numbers, but numbers you typed in manually. If you are using an automatically generated list of numbers, the API does not allow you to edit the format of the numbering.

This answer also assumes that in the example, when you mapped "9." to "::Q09::" and "10." to "::Q11::", that the mapping of 10 to 11 was a typo. If this was intended, please update the question to clarify the rules for why the numbering might change.

Also assumed is that the numbers are supposed to be less than 100, given the example zero padding of "Q09". The example should be flexible enough to allow you to update this to a different padding scheme if needed.

Full example

Since the question did not use any V8 features, this assumes the older Rhino environment.

/**
 * Replaces "1." with "::Q01::"
 */
function updateQuestionNumbering(){
  var text = DocumentApp.getActiveDocument().getBody();
  var pattern = "^\\s*\\d+?\\.";
  var found = text.findText(pattern);
  while(found){
    var matchStart = found.getStartOffset();
    var matchEnd = found.getEndOffsetInclusive();
    var matchElement = found.getElement().asText();
    var matchText = matchElement.getText().slice(matchStart, matchEnd + 1);
    matchElement.deleteText(matchStart, matchEnd);
    matchElement.insertText(matchStart, matchText.replace(/^\s*(\d+?)\./, replacer));  
    found = text.findText(pattern, found);
  }
  
  /**
   * @param {string} _ - full match (ignored)
   * @param {string} number - the sequence of digits matched
   */
  function replacer(_, number) {
    return "::Q" + padStart(number, 2, "0") + "::";
  }
  
  // use String.prototype.padStart() in V8 environment
  // above usage would become `number.padStart(2, "0")`
  function padStart(string, targetLength, padString) {
    while (string.length < targetLength) string = padString + string;
    return string;
  }
}