ORC-2213: [C++] Add option to read timestamps with writer timezone

### What changes were proposed in this pull request?

Add a RowReaderOptions flag that lets timestamp readers use the writer timezone recorded in each stripe footer instead of the configured reader timezone. This preserves the stored timestamp value for callers that need to avoid ORC timestamp timezone conversion.

### Why are the changes needed?

In old days, ORC only supports orc::TIMESTAMP type. The semantics of orc::TIMESTAMP is equivalent to TIMESTAMP_NTZ but with a complex writer and reader timezone adjustment.  So it is difficult to support both TIMESTAMP_NTZ and TIMESTAMP_LTZ types using a single orc::TIMESTAMP. In later versions, orc::TIMESTAMP_INSTANT has been added to support TIMESTAMP_LTZ type. However, users may not know the difference under the hood and still use legacy systems to write both TIMESTAMP_LTZ and TIMESTAMP_NTZ semantics to the old orc::TIMESTAMP type. When users use orc::TIMESTAMP as TIMESTAMP_LTZ values, we should set reader timezone to the writer timezone to avoid value conversion. However, users may not know the writer timezone in advance and ORC files may have different writer timezone (considering files are produced by teams in different time zones.) We need an approach to enforce reader to use writer timezone via explicit configuration.

### How was this patch tested?

Added a new test case.

### Was this patch authored or co-authored using generative AI tooling?

Generated-by: Codex GPT-5.6 Sol

Closes #2699 from wgtmac/ORC-2213.

Authored-by: Gang Wu <ustcwg@gmail.com>
Signed-off-by: Gang Wu <ustcwg@gmail.com>

Author: wgtmac

c++/include/orc/Reader.hh

@@ -353,6 +353,16 @@ namespace orc {
      */
     const std::string& getTimezoneName() const;
 
+    /**
+     * Use the writer timezone when reading timestamp values.
+     */
+    RowReaderOptions& setUseWriterTimezone(bool useWriterTimezone);
+
+    /**
+     * Get whether to use the writer timezone when reading timestamp values.
+     */
+    bool getUseWriterTimezone() const;
+
     /**
      * Get the IdReadIntentMap map that was supplied by client.
      */

c++/src/Options.hh

@@ -151,6 +151,7 @@ namespace orc {
     bool enableLazyDecoding;
     std::shared_ptr<SearchArgument> sargs;
     std::string readerTimezone;
+    bool useWriterTimezone;
     RowReaderOptions::IdReadIntentMap idReadIntentMap;
     bool useTightNumericVector;
     std::shared_ptr<Type> readType;
@@ -167,6 +168,7 @@ namespace orc {
       forcedScaleOnHive11Decimal = 6;
       enableLazyDecoding = false;
       readerTimezone = "GMT";
+      useWriterTimezone = false;
       useTightNumericVector = false;
       throwOnSchemaEvolutionOverflow = false;
       enableAsyncPrefetch = false;
@@ -318,13 +320,23 @@ namespace orc {
 
   RowReaderOptions& RowReaderOptions::setTimezoneName(const std::string& zoneName) {
     privateBits_->readerTimezone = zoneName;
+    privateBits_->useWriterTimezone = false;
     return *this;
   }
 
   const std::string& RowReaderOptions::getTimezoneName() const {
     return privateBits_->readerTimezone;
   }
 
+  RowReaderOptions& RowReaderOptions::setUseWriterTimezone(bool useWriterTimezone) {
+    privateBits_->useWriterTimezone = useWriterTimezone;
+    return *this;
+  }
+
+  bool RowReaderOptions::getUseWriterTimezone() const {
+    return privateBits_->useWriterTimezone;
+  }
+
   const RowReaderOptions::IdReadIntentMap RowReaderOptions::getIdReadIntentMap() const {
     return privateBits_->idReadIntentMap;
   }

c++/src/Reader.cc

@@ -314,7 +314,9 @@ namespace orc {
         footer_(contents_->footer.get()),
         firstRowOfStripe_(*contents_->pool, 0),
         enableEncodedBlock_(opts.getEnableLazyDecoding()),
-        readerTimezone_(getTimezoneByName(opts.getTimezoneName())),
+        readerTimezone_(opts.getUseWriterTimezone() ? localTimezone_
+                                                    : getTimezoneByName(opts.getTimezoneName())),
+        useWriterTimezone_(opts.getUseWriterTimezone()),
         schemaEvolution_(opts.getReadType(), contents_->schema.get()) {
     uint64_t numberOfStripes;
     numberOfStripes = static_cast<uint64_t>(footer_->stripes_size());
@@ -1366,7 +1368,8 @@ namespace orc {
               : localTimezone_;
       StripeStreamsImpl stripeStreams(*this, currentStripe_, currentStripeInfo_,
                                       currentStripeFooter_, currentStripeInfo_.offset(),
-                                      *contents_->stream, writerTimezone, readerTimezone_);
+                                      *contents_->stream, writerTimezone,
+                                      useWriterTimezone_ ? writerTimezone : readerTimezone_);
       reader_ = buildReader(*contents_->schema, stripeStreams, useTightNumericVector_,
                             throwOnSchemaEvolutionOverflow_, /*convertToReadType=*/true);
 

c++/src/Reader.hh

@@ -189,6 +189,7 @@ namespace orc {
 
     // desired timezone to return data of timestamp types.
     const Timezone& readerTimezone_;
+    const bool useWriterTimezone_;
 
     // match read and file types
     SchemaEvolution schemaEvolution_;

c++/test/TestWriter.cc

@@ -840,6 +840,44 @@ namespace orc {
                                    "2014-06-06 12:34:56", IS_DST);
   }
 
+  TEST_P(WriterTest, readTimestampWithWriterTimezone) {
+    MemoryOutputStream memStream(DEFAULT_MEM_STREAM_SIZE);
+    MemoryPool* pool = getDefaultPool();
+    std::unique_ptr<Type> type(Type::buildTypeFromString("struct<col1:timestamp>"));
+
+    std::unique_ptr<Writer> writer =
+        createWriter(16 * 1024, 64, 1024, CompressionKind_ZLIB, *type, pool, &memStream,
+                     fileVersion, 0, "Asia/Shanghai");
+    std::unique_ptr<ColumnVectorBatch> batch = writer->createRowBatch(1);
+    auto* structBatch = dynamic_cast<StructVectorBatch*>(batch.get());
+    auto* tsBatch = dynamic_cast<TimestampVectorBatch*>(structBatch->fields[0]);
+    tsBatch->data[0] = 0;
+    tsBatch->nanoseconds[0] = 123000000;
+    structBatch->numElements = 1;
+    tsBatch->numElements = 1;
+    writer->add(*batch);
+    writer->close();
+
+    auto readTimestamp = [&](bool useWriterTimezone) {
+      auto inStream =
+          std::make_unique<MemoryInputStream>(memStream.getData(), memStream.getLength());
+      std::unique_ptr<Reader> reader = createReader(pool, std::move(inStream));
+      RowReaderOptions rowReaderOptions;
+      rowReaderOptions.setTimezoneName("GMT");
+      rowReaderOptions.setUseWriterTimezone(useWriterTimezone);
+      std::unique_ptr<RowReader> rowReader = reader->createRowReader(rowReaderOptions);
+      std::unique_ptr<ColumnVectorBatch> readBatch = rowReader->createRowBatch(1);
+      EXPECT_TRUE(rowReader->next(*readBatch));
+      auto* readStructBatch = dynamic_cast<StructVectorBatch*>(readBatch.get());
+      auto* readTsBatch = dynamic_cast<TimestampVectorBatch*>(readStructBatch->fields[0]);
+      EXPECT_EQ(123000000, readTsBatch->nanoseconds[0]);
+      return readTsBatch->data[0];
+    };
+
+    EXPECT_EQ(8 * 60 * 60, readTimestamp(/*useWriterTimezone=*/false));
+    EXPECT_EQ(0, readTimestamp(/*useWriterTimezone=*/true));
+  }
+
   // Test that the ORC-306 compensation (-1s for pre-1970 timestamps with
   // nanos > 999999) is applied BEFORE timezone conversion in the Reader.
   //