ByteArray  - AS3

Liczba bajtów, które można odczytać z tablicy bajtów, począwszy od bieżącej pozycji do końca tablicy.

Przy każdej operacji uzyskiwania dostępu do obiektu ByteArray razem z metodami odczytu należy korzystać z właściwości bytesAvailable, aby upewnić się, że odczytywane są odpowiednie dane.

Oznacza domyślne kodowanie obiektów dotyczące klasy ByteArray, które będzie używane w przypadku nowej instancji klasy ByteArray. Po utworzeniu nowej instancji ByteArray kodowanie tej instancji rozpoczyna się od wartości defaultObjectEncoding. Właściwość defaultObjectEncoding zostaje zainicjowana wartością ObjectEncoding.AMF3.

Podczas zapisywania lub odczytywania obiektu z danych binarnych używana jest wartość objectEncoding w celu określenia formatu, który powinien być używany: ActionScript 3.0, ActionScript2.0 lub ActionScript 1.0. Wartość jest stałą z klasy ObjectEncoding.

Powiązane elementy interfejsu API

Powoduje zmianę lub odczytuje kolejność bajtów dla danych: Endian.BIG_ENDIAN lub Endian.LITTLE_ENDIAN. Wartość domyślna to BIG_ENDIAN.

Powiązane elementy interfejsu API

Długość obiektu ByteArray w bajtach.

Jeśli dla długości ustawiona jest wartość większa niż długość aktualna, prawa strona tablicy bajtów zostanie zapełniona zerami.

Jeśli dla długości ustawiona jest wartość mniejsza niż długość aktualna, tablica bajtów zostanie przycięta.

Pozwala określić, czy podczas zapisywania w instancji klasy ByteArray lub czytania z niej, ma być używany format ActionScript 3.0, ActionScript 2.0 czy ActionScript 1.0. Wartość jest stałą z klasy ObjectEncoding.

Powiązane elementy interfejsu API

Przenosi lub zwraca bieżące położenie wskaźnika plików do obiektu ByteArray. Jest to miejsce, w którym kolejne wywołanie metody odczytu powoduje odczytywanie, a wywołanie metody zapisu powoduje zapisywanie.

Określa, czy podstawowa pamięć tablicy bajtów ma właściwość shareable (jest współużytkowana). W przypadku współużytkowanej tablicy bajtów wszystkie wystąpienia klasy ByteArray we wszystkich procesach roboczych odnoszących się do tablicy bajtów korzystają z tej samej podstawowej pamięci systemowej. Wartością domyślną jest false, co oznacza, że pamięć podstawowa nie jest współużytkowana przez procesy robocze.

Ta właściwość ma także wpływ na działania środowiska wykonawczego w odniesieniu do tej tablicy bajtów, jeśli została ona przekazana do procesu roboczego przy użyciu metody Worker.setSharedProperty() lub MessageChannel.send().

• Niewspółużytkowana: Jeżeli ta właściwość ma wartość false, po przekazaniu tablicy bajtów do procesu roboczego środowisko wykonawcze tworzy pełną kopię tablicy bajtów, przydzielając nowy segment pamięci, w którym ma być przechowywana zawartość zduplikowanej tablicy bajtów.
• Współużytkowana: Jeżeli ta właściwość ma wartość true, po przekazaniu tablicy bajtów do procesu roboczego środowisko wykonawcze używa tej samej pamięci podstawowej jako bufora do przechowywania zawartości zarówno oryginalnego wystąpienia klasy ByteArray, jak i nowego wystąpienia utworzonego dla drugiego procesu roboczego. Oba wystąpienia klasy ByteArray zawierają odniesienia do tej samej podstawowej tablicy bajtów.

Możliwość jednoczesnego uzyskania dostępu do współużytkowanej tablicy bajtów przez wiele procesów roboczych może spowodować niepożądaną sytuację, w której oba procesy robocze równocześnie modyfikują zawartość pamięci podstawowej tablicy bajtów. Dostępem do pamięci współużytkowanej można sterować za pomocą kilku mechanizmów:

• Mechanizmy porównywania i zamiany są udostępniane przez metody atomicCompareAndSwapIntAt() i atomicCompareAndSwapLength() klasy ByteArray.
• Specjalistyczne mechanizmy są dostarczane przez klasy Mutex i Condition (w pakiecie flash.concurrent).

Ustawienie tej właściwości na wartość true wpływa wyłącznie na dalszy kod przekazujący tę tablicę bajtów do procesu roboczego. Wszystkie kopie tej tablicy bajtów, które zostały już przekazane do procesu roboczego, istnieją jako oddzielne kopie.

Jeśli wartość true właściwości zostanie zmieniona na wartość false, podstawowa pamięć tablicy bajtów zostanie natychmiast skopiowana do nowego segmentu pamięci systemowej. Od tego momentu wystąpienie klasy ByteArray będzie używać nowej pamięci podstawowej. W związku z tym podstawowa pamięć tej tablicy bajtów nie będzie już współużytkowana z innymi procesami roboczymi. Jeżeli tablica bajtów zostanie następnie przekazana do procesu roboczego, jej pamięć podstawowa zostanie skopiowana, tak jak w przypadku każdego obiektu ByteArray, którego właściwość shareable ma wartość false.

Wartością domyślną jest false.

Powiązane elementy interfejsu API

Tworzy wystąpienie klasy ByteArray, która reprezentuję upakowaną tablicę bajtów. Dzięki niej metody i właściwości tej klasy mogą być stosowane do optymalizowania zapisu danych i przetwarzania strumieniowego.

Metoda ta w ramach pojedynczej operacji atomowej porównuje wartość całkowitą w tej tabeli bajtów z inną wartością całkowitą, a jeśli wartości są zgodne, zamienia bajty na inną wartość.

Ta metoda powinna być stosowana z tablicą bajtów, której pamięć jest współużytkowana przez wiele procesów roboczych (gdy właściwość shareable wystąpienia klasy ByteArray ma wartość true). Metoda wykonuje następującą sekwencję kroków:

1. Odczytuje wartość całkowitą z tej tablicy bajtów, rozpoczynając od indeksu określonego (w bajtach) w argumencie byteIndex.
2. Porównuje faktyczną wartość z tej tablicy bajtów oraz wartość przekazaną w argumencie expectedValue.
3. Jeśli obie wartości są równe, zapisuje wartość argumentu newValue w tablicy bajtów w lokalizacji określonej przez parametr byteIndex oraz zwraca wartość, która była wcześniej zapisana w tych bajtach (wartość odczytaną w kroku 1).
4. W przeciwnym wypadku zawartość tablicy bajtów nie ulega zmianie, a metoda zwraca faktyczną wartość odczytaną z tablicy bajtów.

Wszystkie te kroki są wykonywane w ramach pojedynczej atomowej transakcji sprzętowej. Gwarantuje to, że podczas operacji porównywania i zamiany żadne operacje z innych procesów roboczych nie zmodyfikują zawartości tablicy bajtów.

Parametry

Powiązane elementy interfejsu API

W ramach pojedynczej operacji atomowej porównuje długość tej tablicy bajtów z podaną wartością, a w przypadku zgodnych wartości zmienia długość tablicy bajtów.

Ta metoda powinna być stosowana z tablicą bajtów, której pamięć jest współużytkowana przez wiele procesów roboczych (gdy właściwość shareable wystąpienia klasy ByteArray ma wartość true). Metoda wykonuje następujące kroki:

1. Odczytuje wartość całkowitą właściwości length wystąpienia klasy ByteArray.
2. Porównuje długość z wartością przekazaną w argumencie expectedLength.
3. Jeśli dwie wartości są zgodne, zmienia długość tablicy bajtów na wartość przekazaną w parametrze newLength, zwiększając lub zmniejszając rozmiar tablicy bajtów.
4. W przeciwnym wypadku tablica bajtów nie ulega zmianie.

Wszystkie te kroki są wykonywane w ramach pojedynczej atomowej transakcji sprzętowej. Gwarantuje to, że podczas operacji porównywania i zmiany rozmiaru żadne operacje z innych procesów roboczych nie zmodyfikują zawartości tablicy bajtów.

Parametry

Powiązane elementy interfejsu API

Aplikacja usunie zawartość tablicy bajtów i ustawi dla właściwości length i position wartość 0. Jawne wywołanie tej metody powoduje zwolnienie pamięci używanej przez instancję ByteArray.

Kompresuje tablicę bajtów. Cała tablica bajtów jest skompresowana. Po wywołaniu właściwość length obiektu ByteArray zostanie ustawiona na nową długość. Właściwość position została ustawiona na końcu tablicy bajtów.

Aby określić algorytm kompresji, należy przekazać wartość (zdefiniowaną w klasie CompressionAlgorithm) jako parametr algorithm. Są obsługiwane następujące algorytmy:

Format danych skompresowanych zlib został opisany na stronie: http://www.ietf.org/rfc/rfc1950.txt.

Algorytm kompresji deflate został opisany na stronie: http://www.ietf.org/rfc/rfc1951.txt.

Opis algorytmu kompresji LZMA można znaleźć na stronie http://www.7-zip.org/7z.html.

Algorytm kompresji deflate jest używany w kilku formatach kompresji, takich jak zlib, gzip, niektóre implementacje zip oraz inne. Gdy dane są kompresowane przy użyciu jednego z tych formatów kompresji, wówczas — oprócz zapisywania skompresowanej wersji oryginalnych danych — dane formatu kompresji (np. plik .zip) zawierają również metadane. Niektóre przykłady typów metadanych zawartych w różnych formatach plików obejmują: nazwy plików, daty/godziny modyfikacji pliku, oryginalne rozmiary plików, opcjonalne komentarze, sumy kontrolne i wiele więcej.

Na przykład: gdy obiekt ByteArray zostanie skompresowany za pomocą algorytmu zlib, wynikowy obiekt ByteArray otrzyma określoną strukturę i format. Niektóre bajty będą zawierały metadane dotyczące danych skompresowanych, inne bajty będą zawierały rzeczywistą skompresowaną wersję oryginalnych danych ByteArray. Zgodnie z definicją specyfikacji formatu skompresowanych danych zlib (tj. cześć, która zawiera skompresowaną postać danych oryginalnych) — dane są kompresowane przy użyciu algorytmu deflate. Dlatego te bajty są identyczne z wynikiem wywołania compress(air.CompressionAlgorithm.DEFLATE) dla pierwotnego obiektu ByteArray. Jednak wynik wywołania compress(air. CompressionAlgorithm.ZLIB) zawiera dodatkowe metadane, podczas gdy wynik wywołania compress(CompressionAlgorithm.DEFLATE) zawiera jedynie skompresowaną wersję oryginalnych danych obiektu ByteArray i nic poza tym.

Aby użyć formatu deflate do kompresji danych instancji ByteArray do określonego formatu, takiego jak gzip lub zip, nie wystarczy wywołać metody compress(CompressionAlgorithm.DEFLATE). Należy utworzyć strukturę obiektu ByteArray zgodnie ze specyfikacją formatu kompresji, łącznie z odpowiednimi metadanymi, a także danymi skompresowanymi uzyskanymi za pomocą formatu deflate. I podobnie — w celu dekodowania danych skompresowanych w formacie, takim jak gzip lub zip, nie wystarczy wywołać metody uncompress(CompressionAlgorithm.DEFLATE) dla danych. Najpierw należy oddzielić metadane od danych skompresowanych, a następnie można użyć formatu deflate w celu dokonania dekompresji skompresowanych danych.

Parametry

Powiązane elementy interfejsu API

Kompresuje tablicę bajtów przy użyciu algorytmu kompresji deflate. Cała tablica bajtów do skompresowania.

Po wywołaniu właściwość length obiektu ByteArray zostanie ustawiona na nową długość. Właściwość position została ustawiona na końcu tablicy bajtów.

Algorytm kompresji deflate został opisany na stronie: http://www.ietf.org/rfc/rfc1951.txt.

Aby użyć formatu deflate do kompresji danych instancji ByteArray do określonego formatu, takiego jak gzip lub zip, nie wystarczy wywołać metody deflate(). Należy utworzyć strukturę obiektu ByteArray zgodnie ze specyfikacją formatu kompresji, łącznie z odpowiednimi metadanymi, a także danymi skompresowanymi uzyskanymi za pomocą formatu deflate. I podobnie — w celu dekodowania danych skompresowanych w formacie, takim jak gzip lub zip, nie wystarczy wywołać metody inflate() dla danych. Najpierw należy oddzielić metadane od danych skompresowanych, a następnie można użyć formatu deflate w celu dokonania dekompresji skompresowanych danych.

Powiązane elementy interfejsu API

Dekompresuje tablicę bajtów przy użyciu algorytmu kompresji deflate. Należy zastosować ten sam algorytm, który był stosowany podczas kompresowania tablicy bajtów.

Po wywołaniu właściwość length obiektu ByteArray zostanie ustawiona na nową długość. Dla właściwości position ustawiono wartość 0.

Algorytm kompresji deflate został opisany na stronie: http://www.ietf.org/rfc/rfc1951.txt.

W celu zdekodowania danych skompresowanych w formacie, który korzysta z algorytmu kompresji deflate (np. format gzip lub zip), wywołanie jedynie metody inflate() dla obiektu ByteArray zawierającego dane formatu kompresji nie będzie wystarczające. Najpierw należy oddzielić metadane, które stanowią część formatu skompresowanych danych, od rzeczywistych skompresowanych danych. Więcej informacji zawiera opis metody compress().

Powiązane elementy interfejsu API

Czyta ze strumienia bajtów wartość typu Boolean. Po odczytaniu jednego bajtu metoda zwraca true, jeśli bajt jest wartością niezerową; w przeciwnym wypadku false.

Czyta ze strumienia bajtów bajt ze znakiem.

Zwrócona wartość należy do zakresu od –128 do 127.

Pozwala odczytać ze strumienia bajtów liczbę bajtów określoną przez parametr lenght. Bajty są odczytywane do obiektu ByteArray określonego przez parametr bytes, a następnie bajty są zapisywane do docelowej tablicy ByteArray począwszy od pozycji określonej przez parametr offset.

Parametry

Czyta ze strumienia bajtów liczbę zmiennoprzecinkową o podwójnej precyzji (64 bity, IEEE 754).

Czyta ze strumienia bajtów liczbę zmiennoprzecinkową o pojedynczej precyzji (32 bity, IEEE 754).

Czyta ze strumienia bajtów 32-bitową liczbę całkowitą ze znakiem.

Zwrócona wartość należy do zakresu od –2147483648 do 2147483647.

Czyta ze strumienia bajtów wielobajtowy ciąg o określonej długości, korzysając z określonego zestawu znaków.

Parametry

Czyta z tablicy bajtów obiekt zakodowany w formacie serializowanym AMF.

Powiązane elementy interfejsu API

Czyta ze strumienia bajtów 16-bitową liczbę całkowitą ze znakiem.

Zwrócona wartość należy do zakresu od -32768 do 32767.

Czyta ze strumienia bajtów bajt bez znaku.

Zwrócona wartość należy do zakresu od 0 do 255.

Czyta ze strumienia bajtów 32-bitową liczbę całkowitą bez znaku.

Zwrócona wartość należy do zakresu od 0 do 4294967295.

Czyta ze strumienia bajtów 16-bitową liczbę całkowitą bez znaku.

Zwrócona wartość należy do zakresu od 0 do 65535.

Czyta ze strumienia bajtów ciąg znaków UTF-8. Zakłada się, że ciąg jest poprzedzony prefiksem w postaci liczby typu short bez znaku, która określa długość ciągu w bajtach.

Powiązane elementy interfejsu API

Czyta ze strumienia bajtów sekwencję bajtów UTF-8 określoną przez parametr length, a zwraca ciąg znaków.

Parametry

Dostarcza możliwą do przesłonięcia metodę, która pozwala na dostosowywanie kodowania JSON wartości w obiekcie ByteArray.

Metoda JSON.stringify() szuka metody toJSON() w każdym obiekcie, który przegląda. Jeżeli metoda toJSON() zostanie odnaleziona, metoda JSON.stringify() wywołuję ją dla każdej wartości, którą napotka, przekazując klucz będący w parze z tą wartością.

Obiekt ByteArray dostarcza domyślną implementację metody toJSON() zwracającą po prostu nazwę klasy. Zawartość każdego obiektu ByteArray wymaga interpretacji, dlatego klienci, którzy chcą eksportować obiekty ByteArray do klasy JSON, muszą dostarczyć swoje własne implementacje. Można to zrobić, ponownie definiując metodę toJSON() prototypu klasy.

Metoda toJSON() może zwracać wartość dowolnego typu. W przypadku zwrócenia obiektu metoda stringify() przeszukuje rekurencyjnie ten obiekt. Jeżeli metoda toJSON() zwraca ciąg, to metoda stringify() nie działania rekurencyjnie i kontynuuje przeglądanie.

Parametry

Powiązane elementy interfejsu API

Konwertuje tablicę bajtów na ciąg znaków. Jeśli dane w tablicy rozpoczynają się znacznikiem kolejności bajtów Unicode, aplikacja będzie uwzględniała ten znacznik podczas konwertowania ciągu znaków. Jeśli dla właściwości System.useCodePage ustawiona jest wartość true, podczas konwersji aplikacja będzie traktować dane w tablicy jako podlegające bieżącej stronie kodowej systemu.

Dekompresuje tablicę bajtów. Po wywołaniu właściwość length obiektu ByteArray zostanie ustawiona na nową długość. Dla właściwości position ustawiono wartość 0.

Podczas dekompresji należy zastosować ten sam algorytm, który był używany podczas kompresowania tablicy bajtów. Aby określić algorytm dekompresji, należy przekazać wartość (zdefiniowaną w klasie CompressionAlgorithm) jako parametr algorithm. Są obsługiwane następujące algorytmy:

Format danych skompresowanych zlib został opisany na stronie: http://www.ietf.org/rfc/rfc1950.txt.

Algorytm kompresji deflate został opisany na stronie: http://www.ietf.org/rfc/rfc1951.txt.

Opis algorytmu kompresji LZMA można znaleźć na stronie http://www.7-zip.org/7z.html.

W celu zdekodowania danych skompresowanych w formacie, który korzysta z algorytmu kompresji deflate (np. format gzip lub zip), wywołanie metody uncompress(CompressionAlgorithm.DEFLATE) dla obiektu ByteArray zawierającego dane formatu kompresji nie będzie wystarczające. Najpierw należy oddzielić metadane, które stanowią część formatu skompresowanych danych, od rzeczywistych skompresowanych danych. Więcej informacji zawiera opis metody compress().

Parametry

Powiązane elementy interfejsu API

Zapisuje wartość typu Boolean. Zapisany zostanie pojedynczy bajt zgodnie z parametrem value — 1 dla true lub 0 dla false.

Parametry

Zapisuje bajt w strumieniu bajtów.

Używanych jest 8 najmłodszych bitów parametru. 24 starsze bity są ignorowane.

Parametry

Zapisuje do strumienia bajtów sekwencję o długości length bajtów z określonej tablicy bajtów (zmienna bytes), zaczynając od podanego bajtu początkowego (zmienna offset, przy indeksie liczonym od zera).

Jeśli parametr length został pominięty, używana jest domyślna długość 0; metoda zapisuje cały bufor począwszy od miejsca offset. Jeśli parametr offset również został pominięty, zapisany zostanie cały bufor.

Jeśli wartość parametru offset lub length jest poza zakresem, parametry zostaną ograniczone do początku i końca tablicy bytes.

Parametry

Zapisuje w strumieniu bajtów liczbę zmiennoprzecinkową o podwójnej precyzji (64 bity, IEEE 754).

Parametry

Zapisuje w strumieniu bajtów liczbę zmiennoprzecinkową o pojedynczej precyzji (32 bity, IEEE 754).

Parametry

Zapisuje w strumieniu bajtów 32-bitową liczbę całkowitą ze znakiem.

Parametry

Zapisuje w strumieniu bajtów wielobajtowy ciąg znaków, przy użyciu określonego zestawu znaków.

Parametry

Zapisuje obiekt w tablicy bajtów, w formacie serializowanym AMF.

Parametry

Powiązane elementy interfejsu API

Zapisuje w strumieniu bajtów 16-bitową liczbę całkowitą. Używanych jest 16 najmłodszych bitów parametru. 16 bitów starszych zostaje zignorowane.

Parametry

Zapisuje w strumieniu bajtów 32-bitową liczbę całkowitą bez znaku.

Parametry

Zapisuje w strumieniu bajtów ciąg znaków UTF-8. Długość ciągu znaków UTF-8 w bajtach jest zapisywana na początku jako 16-bitowa wartość integer, a po niej następują bajty reprezentujące znaki ciągu znaków.

Parametry

Zapisuje w strumieniu bajtów ciąg znaków UTF-8. Podobnie, jak metoda writeUTF(), ale metoda writeUTFBytes() nie umieszcza przed ciągiem znaków słowa o długości 16 bitów.

Parametry

1. Zadeklaruj nową instancję obiektu ByteArray: byteArr.
2. Zapisz wartość (typu Boolean) false w postaci równoważnika bajtowego i sprawdź jego długość, a następnie odczytaj.
3. Zapisz zmiennoprzecinkowy równoważnik (o podwójnej precyzji) matematycznej wartości liczby pi.
4. Odczytaj każdy z dziewięciu bajtów zapisanych do tablicy bajtów.

Uwaga: wywołanie metody trace() dla bajtu powoduje wyświetlenie dziesiętnego równoważnika bajtów zapisanych w tablicy bajtów.

Na końcu został dodany segment kodu — sprawdź zakończenie błędów pliku, aby upewnić się, że strumień bajtów nie został odczytany poza koniec.

package {
    import flash.display.Sprite;
    import flash.utils.ByteArray;
    import flash.errors.EOFError;

    public class ByteArrayExample extends Sprite {        
        public function ByteArrayExample() {
            var byteArr:ByteArray = new ByteArray();

            byteArr.writeBoolean(false);
            trace(byteArr.length);            // 1
            trace(byteArr[0]);            // 0

            byteArr.writeDouble(Math.PI);
            trace(byteArr.length);            // 9
            trace(byteArr[0]);            // 0
            trace(byteArr[1]);            // 64
            trace(byteArr[2]);            // 9
            trace(byteArr[3]);            // 33
            trace(byteArr[4]);            // 251
            trace(byteArr[5]);            // 84
            trace(byteArr[6]);            // 68
            trace(byteArr[7]);            // 45
            trace(byteArr[8]);            // 24
            
            byteArr.position = 0;

            try {
                trace(byteArr.readBoolean() == false); // true
            } 
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());        // 3.141592653589793
            }
            catch(e:EOFError) {
                trace(e);           // EOFError: Error #2030: End of file was encountered.
            }
            
            try {
                trace(byteArr.readDouble());
            } 
            catch(e:EOFError) {
                trace(e);            // EOFError: Error #2030: End of file was encountered.
            }
        }
    }
}