核心 IO 作業

發行項
09/26/2024

除了提供讀取空間資料檔案的工具之外，空間 IO 模組還會公開核心基礎程式庫，以快速且有效率地讀取和寫入 XML 和分隔資料。

atlas.io.core 命名空間包含兩個低階類別，可快速讀取和寫入 CSV 和 XML 資料。這些基底類別可支援空間 IO 模組中的空間資料讀取器和寫入器。歡迎使用這些類別來新增 CSV 或 XML 檔案的更多讀取和寫入支援。

讀取分隔檔案

atlas.io.core.CsvReader 類別會讀取包含分隔資料集的字串。這個類別提供兩種方法來讀取資料：

read 函式會讀取完整的資料集，並傳回字串的二維陣列，代表分隔資料集的所有儲存格。
getNextRow 函式會讀取分隔資料集中的每個文字行，並傳回字串陣列，代表該資料集行中的所有儲存格。使用者可以處理資料列，並在處理下一個資料列之前處置該資料列任何不需要的記憶體。因此，函式更有記憶體效率。

根據預設，讀取器會使用逗號字元作為分隔符號。不過，分隔符號可以變更為任何單一字元或設定為 'auto'。當設定為 'auto' 時，讀取器會分析字串中的第一行文字。然後，會從下表中選取最常見的字元，以作為分隔符號使用。

分隔符號	字元
Comma	`,`
定位字元	`\t`
Pipe	`\|`

此讀取器也支援文字限定詞，可用來處理包含分隔符號字元的儲存格。引號 ('"') 字元是預設文字限定詞，但是可以變更為任何單一字元。

寫入分隔檔案

atlas.io.core.CsvWriter 會將物件的陣列寫入為分隔字串。任何單一字元都可以當做分隔符號或文字限定詞使用。預設分隔符號是逗號 (',')，而預設文字限定詞是引號 ('"') 字元。

若要使用此類別，請遵循下列步驟：

建立類別的執行個體，並選擇性地設定自訂分隔符號或文字限定詞。
使用 write 函式或 writeRow 函式將資料寫入類別。針對 write 函式，傳遞代表多個資料列和儲存格的物件二維陣列。若要使用 writeRow 函式，請傳遞物件陣列，代表具有多個資料行的資料列。
呼叫 toString 函式以擷取分隔字串。
或者，呼叫 clear 方法讓寫入器可重複使用並減少其資源配置，或呼叫 delete 方法來處置寫入器執行個體。

注意

寫入的資料行數目會受限於傳遞至寫入器之資料的第一個資料列中的儲存格數目。

讀取 XML 檔案

atlas.io.core.SimpleXmlReader 類別在剖析 XML 檔案時速度比 DOMParser 快。不過，atlas.io.core.SimpleXmlReader 類別需要格式化良好的 XML 檔案。格式不佳的 XML 檔案 (例如遺漏結尾標記) 可能會導致錯誤。

下列程式碼示範如何使用 SimpleXmlReader 類別將 XML 字串剖析為 JSON 物件，並將其序列化為所需的格式。

//Create an instance of the SimpleXmlReader and parse an XML string into a JSON object.
var xmlDoc = new atlas.io.core.SimpleXmlReader().parse(xmlStringToParse);

//Verify that the root XML tag name of the document is the file type your code is designed to parse.
if (xmlDoc && xmlDoc.root && xmlDoc.root.tagName && xmlDoc.root.tagName === '<Your desired root XML tag name>') {

    var node = xmlDoc.root;

    //Loop through the child node tree to navigate through the parsed XML object.
    for (var i = 0, len = node.childNodes.length; i < len; i++) {
        childNode = node.childNodes[i];

        switch (childNode.tagName) {
            //Look for tag names, parse and serialized as desired.
        }
    }
}

寫入 XML 檔案

atlas.io.core.SimpleXmlWriter 類別會以有記憶體效率的方式寫入格式良好的 XML。

下列程式碼示範如何使用 SimpleXmlWriter 類別來產生格式良好的 XML 字串。

//Create an instance of the SimpleXmlWriter class.
var writer = new atlas.io.core.SimpleXmlWriter();

//Start writing the document. All write functions return a reference to the writer, making it easy to chain the function calls to reduce the code size.
writer.writeStartDocument(true)
    //Specify the root XML tag name, in this case 'root'
    .writeStartElement('root', {
        //Attributes to add to the root XML tag.
        'version': '1.0',
        'xmlns': 'http://www.example.com',
         //Example of a namespace.
        'xmlns:abc': 'http://www.example.com/abc'
    });

//Start writing an element that has the namespace abc and add other XML elements as children.
writer.writeStartElement('abc:parent');

//Write a simple XML element like <title>Azure Maps is awesome!</title>
writer.writeElement('title', 'Azure Maps is awesome!');

//Close the element that we have been writing children to.
writer.writeEndElement();

//Finish writing the document by closing the root tag and the document.
writer.writeEndElement().writeEndDocument();

//Get the generated XML string from the writer.
var xmlString = writer.toString();

上述程式碼產生的 XML 看起來如下所示。

<?xml version="1.0" encoding="UTF-8"?>
<root version="1.0" xmlns="http://www.example.com" xmlns:abc="http://www.example.com/abc">
    <abc:parent>
        <title>Azure Maps is awesome!</title>
    </abc:parent>
</root>