Values and Types

[Previous << Type Annotations](https://qiita.com/flowcadence/items/aefb58373b7b6dc956d9)
[Next >> Operators](https://qiita.com/flowcadence/items/3220cbef5b83f3d27f7a)

https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a#cadenceの言語仕様を学ぶ

Valuesはオブジェクトであり、例えばBoolean、Integer、配列などです。Valuesは型付けされています。

<h1 id="Booleans">Booleans</h1>

2つのブール値`true`と`false`は、型が`Bool`です。

<h1 id="Numeric-Literals">Numeric Literals</h1>

数値はさまざまな基数で表記できます。数値はデフォルトで10進数と見なされます。
10進数以外のリテラルには特定の接頭辞があります。
| Numeral system | Prefix | Characters |
|:-:|:-:|:-:|
| Decimal | *None* | one or more numbers (`0` to `9`) |
| Binary | `0b` | one or more zeros or ones (`0` or `1`) |
| Octal | `0o` | one or more numbers in the range `0` to `7` |
| Hexadecimal | `0x` | one or more numbers, or characters `a` to `f`, lowercase or uppercase |

```ruby
/* A decimal number */

1234567890
// `1234567890`

/* A binary number */

0b101010
// `42`

/* An octal number */

0o12345670
// `2739128`

/* A hexadecimal number */

0x1234567890ABCabc
// `1311768467294898876`

/* Invalid: unsupported prefix 0z */
0z0

/* A decimal number with leading zeros. Not an octal number! */

00123
// `123`

/* A binary number with several trailing zeros. */

0b001000
// `8`
```
10進数の数字は、視覚的に意味を持たせて要素を区切るためにアンダースコア（`_`）を使用することができます。
```ruby
let largeNumber = 1_000_000

/* Invalid: Value is not a number literal, but a variable. */
let notNumber = _123
```

全ての数字表記でアンダースコアの使用が可能です。
```ruby
let binaryNumber = 0b10_11_01
```

<h1 id="Integers">Integers</h1>
Integerとは、小数部分を持たない数値です。 符号付き（正、ゼロ、負）または符号なし（正またはゼロ）です。

オーバーフローとアンダーフローをチェックする符号付き整数型には、`Int`接頭辞が付いており、以下の範囲の値を表すことができます。
* `Int8`： -2^7 から 2^7 − 1（-128 から 127）
* `Int16`： -2^15 から 2^15 - 1 (-32768 から 32767)
* `Int32`： -2^31 から 2^31 - 1 (-2147483648 から 2147483647)
* `Int64`： -2^63 から 2^63 - 1 (-9223372036854775808 から 9223372036854775807)
* `Int128`： -2^127 から 2^127 - 1
* `Int256`： -2^255 から 2^255 − 1

オーバーフローおよびアンダーフローをチェックする符号なし整数型には、`UInt`という接頭辞が付いており、以下の範囲の値を表すことができます。
* `UInt8`： 0 から 2^8 − 1 (255)
* `UInt16`： 0 から 2^16 − 1 (65535)
* `UInt32`：0～2^32-1（4294967295）
* `UInt64`：0～2^64-1（18446744073709551615）
* `UInt128`：0～2^128-1
* `UInt256`： 0 から 2^256 − 1

オーバーフローやアンダーフローをチェック**しない**符号なし整数型(つまりラップアラウンド)には、`Word`接頭辞が付いており、以下の範囲の値を表すことができます。
* `Word8`: 0 から 2^8 − 1 (255)
* `Word16`: 0 から 2^16 − 1 (65535)
* `Word32`: 0から2の32乗-1（4294967295）
* `Word64`: 0 から 2^64 − 1 (18446744073709551615)
* `Word128`: 0 から 2^128 − 1 (340282366920938463463374607431768211455)
* `Word256`: 0 から 2^256 - 1 (115792089237316195423570985008687907853269984665640564039457584007913129639935)

型は独立した型であり、すなわち、互いにサブタイプではありません。

異なる整数型の動作に関する詳細については、[Arithmetic Operators](https://qiita.com/flowcadence/items/3220cbef5b83f3d27f7a#arithmetic-operators)のセクションを参照してください。

```ruby
/* Declare a constant that has type `UInt8` and the value 10. */
let smallNumber: UInt8 = 10
```
```ruby
/* Invalid: negative literal cannot be used as an unsigned integer */
let invalidNumber: UInt8 = -10
```
さらに、任意精度整数型`Int`が提供されています。
```ruby
let veryLargeNumber: Int = 10000000000000000000000000000000
```

整数リテラルは、`Int`型であると[推論](https://qiita.com/flowcadence/items/cf6493f9fd297b677452)されます。
```ruby
let someNumber = 123

/* `someNumber` has type `Int` */
```
負の整数は2つの補数表現(complement representation)でエンコードされます。

整数型は自動的には変換されません。型は明示的に変換する必要があり、そのinteger型のコンストラクタを呼び出すことで実行できます。
```ruby
let x: Int8 = 1
let y: Int16 = 2

/* Invalid: the types of the operands, `Int8` and `Int16` are incompatible. */
let z = x + y

/* Explicitly convert `x` from `Int8` to `Int16`. */
let a = Int16(x) + y

/* `a` has type `Int16`

 * Invalid: The integer literal is expected to be of type `Int8`,
 * but the large integer literal does not fit in the range of `Int8`.
 */
let b = x + 1000000000000000000000000
```

<h1 id="Integer-Functions">Integer Functions</h1>

整数には、使用できる組み込み関数が複数あります。

<h4>toString</h4>

```ruby
view fun toString(): String
```
* 整数を文字列で返します。
```ruby
let answer = 42

answer.toString()  // is "42"
```
<h4>toBigEndianBytes</h4>

```ruby
view fun toBigEndianBytes(): [UInt8]
```
* 整数のビッグエンディアン順のバイト配列表現（`[UInt8]`）を返します。
```ruby
let largeNumber = 1234567890

largeNumber.toBigEndianBytes()  // is `[73, 150, 2, 210]`
```
すべての整数型(integer)は以下の関数をサポートしています。
<h4>fromString</h4>

```ruby
view fun T.fromString(_ input: String): T?
```
10進数エンコードされた文字列から整数値を解析しようとし、その文字列が無効な場合は`nil`を返します。

与えられた整数`n`の型が`T`の場合、`T.fromString(n.toString())`は、`n`を[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)で包み込むことと同等です。

文字列が無効になる場合は、以下の通りです。
* 数字以外の文字が含まれている場合
* ターゲットの型に適合しない場合

`Int64`や`Int`のような符号付き整数型の場合、文字列はオプションで`+`または`-`符号の接頭辞で始まることが出来ます。

`Word64`や`UInt64`、`UInt`のような符号なし整数型の場合は符号の接頭辞を付けることが出来ません。

例：
```ruby
let fortyTwo: Int64? = Int64.fromString("42")
/* ok */

let twenty: UInt? = UInt.fromString("20")
/* ok */

let nilWord: Word8? = Word8.fromString("1024")
/* nil, out of bounds */

let negTwenty: Int? = Int.fromString("-20")
/* ok */
```
<h4>fromBigEndianBytes</h4>

```ruby
view fun T.fromBigEndianBytes(_ bytes: [UInt8]): T?
```
バイト配列表現（`[UInt8]`）からビッグエンディアン順で整数値を解析しようと試み、バイトが無効な場合は`nil`を返します。

与えられた整数`n`の型が`T`の場合、`T.fromBigEndianBytes(n.toBigEndianBytes())`は、`n`を[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)で包み込むことと同等です。

バイトが無効になる場合は以下の通りです。
* バイト配列の長さがターゲットの型に必要なバイト数を超える場合
* ターゲットの型に収まらない場合

例：
```ruby
let fortyTwo: UInt32? = UInt32.fromBigEndianBytes([42])
/* ok */

let twenty: UInt? = UInt.fromBigEndianBytes([0, 0, 20])
/* ok */

let nilWord: Word8? = Word8.fromBigEndianBytes("[0, 22, 0, 0, 0, 0, 0, 0, 0]")
/* nil, out of bounds */

let nilWord2: Word8? = Word8.fromBigEndianBytes("[0, 0]")
/* nil, size (2) exceeds number of bytes needed for Word8 (1) */

let negativeNumber: Int64? = Int64.fromBigEndianBytes([128, 0, 0, 0, 0, 0, 0, 1])
/* ok -9223372036854775807 */
```
<h1 id="Fixed-Point-Numbers">Fixed-Point Numbers</h1>

:::note warn
🚧 ステータス
現在は、64ビット幅の`Fix64`および`UFix64`型のみが利用可能です。 固定小数点数の型は、今後のリリースでさらに追加される予定です。
:::

固定小数点数は、小数値の表現に便利です。小数点以下の桁数が固定されています(have a fixed number)。

本質的には整数であり、係数でスケーリングされます。例えば、1.23という値は、スケーリング係数1/1000で1230と表現できます。スケーリング係数は、同じタイプのすべての値に対して同じであり、計算中も変わりません。

Cadenceの固定小数点数は、2の累乗ではなく10の累乗のスケーリング係数を使用します。つまり、2進数(binary)ではなく10進数です。

符号付き固定小数点数型は接頭辞`Fix`を持ち、以下の因子(factor)を持ち、以下の範囲の値を表現できます。
* `Fix64`：因子(Factor)1/100,000,000、-92233720368.54775808～92233720368.54775807

符号なし固定小数点数型は接頭辞`UFix`を持ち、以下の因子を持ち、以下の範囲の値を表すことができます。
* `UFix64`：因子1/100,000,000；0.0から184467440737.09551615


<h1 id="Fixed-Point-number-functions">Fixed-Point Number Functions</h1>

固定小数点数(Fixed-Point numbers)には、使用できる複数の組み込み関数が用意されています。
<h4>toString</h4>

```ruby
view fun toString(): String
```
* 固定小数点数の文字列表現を返します。
```ruby
let fix = 1.23

fix.toString()
/* is "1.23000000" */
```
<h4>toBigEndianBytes</h4>

```ruby
view fun toBigEndianBytes(): [UInt8]
```
* 固定小数点数のビッグエンディアン順のバイト配列表現（`[UInt8]`）を返します。
```ruby
let fix = 1.23

fix.toBigEndianBytes()
/* is `[0, 0, 0, 0, 7, 84, 212, 192]` */
```
すべての固定小数点型は、以下の関数をサポートしています。
<h4>fromString</h4>

```ruby
view fun T.fromString(_ input: String): T?
```
10進数エンコードされた文字列から固定小数点値を解析しようとし、文字列が無効な場合は`nil`を返します。

固定小数点数値`n`（型`T`）に対しては、`T.fromString(n.toString())`は`n`を`optional`でラップすることと同義です。

文字列が無効な場合は以下の通りです。
* 数字以外の文字が含まれている場合。
* ターゲットの型に適合しない場合。

小数点以下または小数部分が欠けている場合。例えば、"0." と ".1" は無効な文字列ですが、 "0.1" は有効です。

`Fix64`のような符号付き型では、文字列の先頭に`+`または`-`符号が前置される場合があります。

`UFix64`のような符号なし型では、符号の前置は許可されません。

例：
```ruby
let nil1: UFix64? = UFix64.fromString("0.")
/* nil, fractional part is required */

let nil2: UFix64? = UFix64.fromString(".1")
/* nil, decimal part is required */

let smol: UFix64? = UFix64.fromString("0.1")
/* ok */

let smolString: String = "-0.1"

let nil3: UFix64? = UFix64.fromString(smolString)
/* nil, unsigned types don't allow a sign prefix */

let smolFix64: Fix64? = Fix64.fromString(smolString)
/* ok */
```
<h4>fromBigEndianBytes</h4>

```ruby
view fun T.fromBigEndianBytes(_ bytes: [UInt8]): T?
```
バイト配列表現（`[UInt8]`）からビッグエンディアン順で整数値を解析しようと試み、入力バイトが無効な場合は`nil`を返します。

与えられた整数`n`の型が`T`の場合、`T.fromBigEndianBytes(n.toBigEndianBytes())`は、`n`を[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)のオブジェクトでラップすることと同等です。

バイト配列が無効な場合は以下の通りです。
* バイト配列の長さがターゲットの型に必要なバイト数を超える場合
* ターゲットの型に収まらない場合

例：
```ruby
let fortyTwo: UFix64? = UFix64.fromBigEndianBytes([0, 0, 0, 0, 250, 86, 234, 0])
/* ok, 42.0 */

let nilWord: UFix64? = UFix64.fromBigEndianBytes("[100, 22, 0, 0, 0, 0, 0, 0, 0]")
/* nil, out of bounds */

let nilWord2: Fix64? = Fix64.fromBigEndianBytes("[0, 22, 0, 0, 0, 0, 0, 0, 0]")
/* nil, size (9) exceeds number of bytes needed for Fix64 (8) */

let negativeNumber: Fix64? = Fix64.fromBigEndianBytes([255, 255, 255, 255, 250, 10, 31, 0])
/* ok, -1 */
```

<h1 id="Minimum-and-maximum-values">Minimum and maximum values</h1>

すべての整数および固定小数点数の最小値と最大値は、`min`および`max`のフィールドで取得できます。

例えば：
```ruby
let max = UInt8.max
/* `max` is 255, the maximum value of the type `UInt8` */
```
```ruby
let max = UFix64.max
/* `max` is 184467440737.09551615, the maximum value of the type `UFix64` */
```

<h1 id="Saturation-Arithmetic">Saturation Arithmetic</h1>

整数および固定小数点数は飽和算術をサポートしています。加算や乗算などの算術演算は、数値の限界で飽和し、オーバーフローしません。

演算結果がオペランドの型の最大値よりも大きい場合、最大値が返されます。演算結果がオペランドの型の最小値よりも小さい場合、最小値が返されます。

飽和加算、減算、乗算、および除算は、接頭辞`saturating`を持つ関数として提供されています。
* `Int8`、`Int16`、`Int32`、`Int64`、`Int128`、`Int256`、`Fix64`：
  * `saturatingAdd`
  * `saturatingSubtract`
  * `saturatingMultiply`
  * `saturatingDivide`
* `Int`:
  * なし
* `UInt8`、`UInt16`、`UInt32`、`UInt64`、`UInt128`、`UInt256`、`UFix64`:
  * `saturatingAdd`
  * `saturatingSubtract`
  * `saturatingMultiply`
* `UInt`:
  * `saturatingSubtract`
```ruby
let a: UInt8 = 200
let b: UInt8 = 100
let result = a.saturatingAdd(b)
/* `result` is 255, the maximum value of the type `UInt8` */
```

<h1 id="Floating-Point-Numbers">Floating-Point Numbers</h1>

浮動小数点数のサポートは**ありません**。
スマートコントラクトは誤差のある値を扱うことを想定していないため、浮動小数点演算は適切ではありません。
代わりに、[fixed point numbers](#fixed-point-numbers)(固定小数点数)の使用を検討してください。

<h1 id="Addresses">Addresses</h1>

`Address`型はアドレスを表します。アドレスは符号なし整数値で、64ビット（8バイト）です。16進数表記の整数リテラルを使用してアドレス値を作成することができます。
```ruby
/* Declare a constant that has type `Address`. */
let someAddress: Address = 0x436164656E636521

/* Invalid: Initial value is not compatible with type `Address`,
 * it is not a number.
 */
let notAnAddress: Address = ""

/* Invalid: Initial value is not compatible with type `Address`.
 * The integer literal is valid, however, it is larger than 64 bits.
 */
let alsoNotAnAddress: Address = 0x436164656E63652146757265766572
```
整数リテラルは、アドレス(Address)として解釈されることはありません。
```ruby
/* Declare a number. Even though it happens to be a valid address,
 * it is not inferred as it.
 */
let aNumber = 0x436164656E636521

/* `aNumber` has type `Int` */
```
アドレス(Address)はバイト配列または文字列を使用して作成することもできます。
```ruby
/* Declare an address with hex representation as 0x436164656E636521. */
let someAddress: Address = Address.fromBytes([67, 97, 100, 101, 110, 99, 101, 33])

/* Invalid: Provided value is not compatible with type `Address`. The function panics. */
let invalidAddress: Address = Address.fromBytes([12, 34, 56, 11, 22, 33, 44, 55, 66, 77, 88, 99, 111])

/* Declare an address with the string representation as "0x436164656E636521". */
let addressFromString: Address? = Address.fromString("0x436164656E636521")

/* Invalid: Provided value does not have the "0x" prefix. Returns Nil */
let addressFromStringWithoutPrefix: Address? = Address.fromString("436164656E636521")

/* Invalid: Provided value is an invalid hex string. Return Nil. */
let invalidAddressForInvalidHex: Address? = Address.fromString("0xZZZ")

/* Invalid: Provided value is larger than 64 bits. Return Nil. */
let invalidAddressForOverflow: Address? = Address.fromString("0x436164656E63652146757265766572")
```

<h1 id="Address-Functions">Address Functions</h1>

アドレス(Address)には、使用可能な組み込み関数が複数用意されています。
<h4>toString</h4>

```ruby
view fun toString(): String
```
* アドレス(Address)の文字列表現を返します。結果には`0x`の接頭辞が付き、ゼロで埋められます。
```ruby
let someAddress: Address = 0x436164656E636521
someAddress.toString()
/* is "0x436164656E636521" */

let shortAddress: Address = 0x1
shortAddress.toString()
/* is "0x0000000000000001" */
```
<h4>toBytes</h4>

```ruby
view fun toBytes(): [UInt8]
```
* アドレス(Address)のバイト配列表現（`[UInt8]`）を返します。
```ruby
let someAddress: Address = 0x436164656E636521

someAddress.toBytes()
/* is `[67, 97, 100, 101, 110, 99, 101, 33]` */
```

<h1 id="AnyStruct-and-AnyResource">AnyStruct and AnyResource</h1>

`AnyStruct`は、すべての非リソース型の最上位の型であり、すなわち、すべての非リソース型は、そのサブタイプです。

`AnyResource`は、すべてのリソース型の最上位の型です。
```ruby
/* Declare a variable that has the type `AnyStruct`.
 * Any non-resource typed value can be assigned to it, for example an integer,
 * but not resource-typed values.
 */
var someStruct: AnyStruct = 1

/* Assign a value with a different non-resource type, `Bool`. */
someStruct = true

/* Declare a structure named `TestStruct`, create an instance of it,
 * and assign it to the `AnyStruct`-typed variable
 */
struct TestStruct {}

let testStruct = TestStruct()

someStruct = testStruct

/* Declare a resource named `TestResource` */

resource TestResource {}

/* Declare a variable that has the type `AnyResource`.
 * Any resource-typed value can be assigned to it,
 * but not non-resource typed values.
 */
var someResource: @AnyResource <- create TestResource()

/* Invalid: Resource-typed values can not be assigned
 * to `AnyStruct`-typed variables
 */
someStruct <- create TestResource()

/* Invalid: Non-resource typed values can not be assigned
 * to `AnyResource`-typed variables
 */
someResource = 1
```
ただし、`AnyStruct`および`AnyResource`を使用しても、型チェックを省略できるわけではありません。これらの型にはフィールドも関数も存在しないため、フィールドにアクセスしたり関数を呼び出したりすることはできません。
```ruby
/* Declare a variable that has the type `AnyStruct`.
 * The initial value is an integer,
 * but the variable still has the explicit type `AnyStruct`.
 */
let a: AnyStruct = 1

/* Invalid: Operator cannot be used for an `AnyStruct` value (`a`, left-hand side)
 * and an `Int` value (`2`, right-hand side).
 */
a + 2
```
`AnyStruct`および`AnyResource`は、他の型と同様に使用することができます。例えば、[配列](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#arrays)の要素型として使用したり、[オプショナル型](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)の要素型として使用することができます。
```ruby
/* Declare a variable that has the type `[AnyStruct]`,
 * i.e. an array of elements of any non-resource type.
 */
let anyValues: [AnyStruct] = [1, "2", true]

/* Declare a variable that has the type `AnyStruct?`,
 * i.e. an optional type of any non-resource type.
 */
var maybeSomething: AnyStruct? = 42

maybeSomething = "twenty-four"

maybeSomething = nil
```

`AnyStruct`は、リソースでないオプショナル型すべてのスーパータイプでもあり、`AnyResource`は、リソースのオプショナル型すべてのスーパータイプでもあります。
```ruby
let maybeInt: Int? = 1
let anything: AnyStruct = maybeInt
```
[条件付きダウンキャスト(as?演算子)](https://qiita.com/flowcadence/items/3220cbef5b83f3d27f7a#conditional-downcasting-operator-as)により、`AnyStruct`または`AnyResource`の型を持つ値を、元の型に強制的に戻すことができます。

<h1 id="Optionals">Optionals</h1>

オプショナルは、値の不在を表す値です。オプショナルには2つのケースがあります。すなわち、値があるか、または何もないかのいずれかです。

オプショナル型は、他の型の後に`?`接尾辞を付けて宣言します。例えば、`Int`は非オプショナルの整数であり、`Int?`はオプショナルの整数、すなわち何もないか、または整数かのいずれかです。

何もないことを表す値は`nil`です。
```ruby
/* Declare a constant which has an optional integer type,
 * with nil as its initial value.
 */
let a: Int? = nil

/* Declare a constant which has an optional integer type,
 * with 42 as its initial value.
 */
let b: Int? = 42

/* Invalid: `b` has type `Int?`, which does not support arithmetic. */
b + 23

/* Invalid: Declare a constant with a non-optional integer type `Int`,
 * but the initial value is `nil`, which in this context has type `Int?`.
 */
let x: Int = nil
```
オプショナルは、リテラルだけでなく、どんな値に対しても作成することができます。
```ruby
/* Declare a constant which has a non-optional integer type,
 * with 1 as its initial value.
 */
let x = 1

/* Declare a constant which has an optional integer type.
 * An optional with the value of `x` is created.
 */
let y: Int? = x

/* Declare a variable which has an optional any type, i.e. the variable
 * may be `nil`, or any other value.
 * An optional with the value of `x` is created.
 */
var z: AnyStruct? = x
```
非オプショナル型はそのオプショナル型のサブタイプです。
```ruby
var a: Int? = nil
let b = 2
a = b

/* `a` is `2` */
```
オプショナル型は、例えば[配列](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#arrays)やオプショナル型（にさえも）など、他の型に含まれることがあります。
```ruby
/* Declare a constant which has an array type of optional integers. */
let xs: [Int?] = [1, nil, 2, nil]

/* Declare a constant which has a double optional type. */
let doubleOptional: Int?? = nil
```
オプショナルの演算子に関する情報は、[optional operators](https://qiita.com/flowcadence/items/3220cbef5b83f3d27f7a#optional-operators)(オプショナル演算子)のセクションをご覧ください。

<h1 id="Never">Never</h1>

`Never`はボトム型であり、すなわち、すべての型のサブタイプです。`Never`の型を持つ値はありません。`Never`は、通常は値を返さない関数の戻り値の型として使用できます。例えば、[`panic`](https://qiita.com/flowcadence/items/e1528810ca4a72c8f521#panic)関数の戻り値の型です。
```ruby
/* Declare a function named `crashAndBurn` which will never return,
 * because it calls the function named `panic`, which never returns.
 */
fun crashAndBurn(): Never {
    panic("An unrecoverable error occurred")
}

/* Invalid: Declare a constant with a `Never` type, but the initial value is an integer. */
let x: Never = 1

/* Invalid: Declare a function which returns an invalid return value `nil`,
 * which is not a value of type `Never`.
 */
fun returnNever(): Never {
    return nil
}
```

<h1 id="Strings-and-Characters">Strings and Characters</h1>

文字列は文字の集合です。文字列の型は`String`、文字の型は`Character`です。文字列は、Unicode準拠の方法でテキストを処理するために使用できます。文字列は不変です。

文字列リテラルおよび文字リテラルは、二重引用符(`"`)で囲みます。
```ruby
let someString = "Hello, world!"
```
文字列リテラルにはエスケープシーケンスを含めることができます。エスケープシーケンスはバックスラッシュ（`\`）で始まります。
* `\0`: Null文字
* `\\`: バックスラッシュ
* `\t`: 水平タブ
* `\n`: 改行
* `\r`: 復帰
* `\"`: ダブルクォーテーションマーク
* `\'`: シングルクォーテーションマーク
* `\u`: Unicode スカラー値で`\u{x}`と表記します。ここで`x`は16進数で1桁から8桁の数字で、有効なUnicodeスカラー値である必要があります。つまり、0から0xD7FF、0xE000から0x10FFFFまでの範囲の値です。
```ruby
/* Declare a constant which contains two lines of text
 * (separated by the line feed character `\n`), and ends
 * with a thumbs up emoji, which has code point U+1F44D (0x1F44D).
 */
let thumbsUpText =
    "This is the first line.\nThis is the second line with an emoji: \u{1F44D}"
```
`Character`という型は、人間が読める1つの文字を表します。文字は拡張表記素クラスタであり、1つまたは複数のユニコードスカラー(Unicode scalar)で構成されます。

例えば、1つの文字`ü`は、ユニコードではいくつかの方法で表現できます。まず、1つのユニコードスカラー値`ü`で表現できます（「LATIN SMALL LETTER U WITH DIAERESIS」、コードポイントU+00FC）。次に、同じ文字は2つのユニコードスカラー値でも表現できます。`u`（「LATIN SMALL LETTER U」、コードポイントU+0075）と「COMBINING DIAERESIS」（コードポイントU+0308）です。結合ユニコードスカラー値は、その前のスカラーに適用され、`u`を`ü`に変換します。それでも、どちらのバリエーションも同じ人間が読める文字`ü`を表しています。
```ruby
let singleScalar: Character = "\u{FC}"
/* `singleScalar` is `ü` */
let twoScalars: Character = "\u{75}\u{308}"
/* `twoScalars` is `ü` */
```
複数のUnicodeスカラー値が、人間が読める1つの文字として表示されるもう一つの例は、旗の絵文字です。これらの絵文字は、2つの「REGIONAL INDICATOR SYMBOL LETTER」Unicodeスカラー値で構成されています。
```ruby
/* Declare a constant for a string with a single character, the emoji
 * for the Canadian flag, which consists of two Unicode scalar values:
 * - REGIONAL INDICATOR SYMBOL LETTER C (U+1F1E8)
 * - REGIONAL INDICATOR SYMBOL LETTER A (U+1F1E6)
 */
let canadianFlag: Character = "\u{1F1E8}\u{1F1E6}"
/* `canadianFlag` is `🇨🇦` */
```
<h1 id="String-Fields-and-Functions">String Fields and Functions</h1>

文字列には、使用できる複数の組み込み関数が用意されています。
<h4>length</h4>

```ruby
let length: Int
```
* 文字列内の文字数を整数で返します。
```ruby
let example = "hello"

/* Find the number of elements of the string. */
let length = example.length
/* `length` is `5` */
```
<h4>utf8</h4>

```ruby
let utf8: [UInt8]
```
* UTF-8エンコーディングのバイト配列を返します。
```ruby
let flowers = "Flowers \u{1F490}"
let bytes = flowers.utf8
/* `bytes` is `[70, 108, 111, 119, 101, 114, 115, 32, 240, 159, 146, 144]` */
```
<h4>concat</h4>

```ruby
view fun concat(_ other: String): String
```
* `other`文字列を元の文字列の末尾に連結しますが、元の文字列は変更しません。この関数は、呼び出された関数とパラメータとして与えられた文字列の長さの合計の長さを持つ新しい文字列を作成します。
```ruby
let example = "hello"
let new = "world"

/* Concatenate the new string onto the example string and return the new string. */
let helloWorld = example.concat(new)
/* `helloWorld` is now `"helloworld"` */
```
```ruby
let example = "hello"
let new = "world"

/* Concatenate the new string onto the example string and return the new string. */
let helloWorld = example.concat(new)
/* `helloWorld` is now `"helloworld"` */
```
<h4>slice</h4>

```ruby
view fun slice(from: Int, upTo: Int): String
```
* 指定した文字列の文字を、開始インデックス`from`から、終了インデックス`upTo`までの文字列スライスとして返します。この関数は、長さが`upTo - from`である新しい文字列を作成します。元の文字列は変更されません。パラメータのいずれかが文字列の範囲外である場合、またはインデックスが無効(`from > upTo`)である場合、関数は失敗します。
```ruby
let example = "helloworld"

/* Create a new slice of part of the original string. */
let slice = example.slice(from: 3, upTo: 6)
/* `slice` is now `"low"` */

/* Run-time error: Out of bounds index, the program aborts. */
let outOfBounds = example.slice(from: 2, upTo: 10)

/* Run-time error: Invalid indices, the program aborts. */
let invalidIndices = example.slice(from: 2, upTo: 1)
```
<h4>decodeHex</h4>

```ruby
view fun decodeHex(): [UInt8]
```
* 指定された16進文字列で表されるバイトを含む配列を返します。

指定された文字列は、16進文字のみで構成され、偶数長でなければなりません。文字列が不正な場合、プログラムは中断します。
```ruby
let example = "436164656e636521"

example.decodeHex()
/* is `[67, 97, 100, 101, 110, 99, 101, 33]` */
```
<h4>toLower</h4>

```ruby
view fun toLower(): String
```
* 大文字をすべて小文字に置き換えた文字列を返します。
```ruby
let example = "Flowers"

example.toLower()
/* is `flowers` */
```
<h4>replaceAll</h4>

```ruby
view fun replaceAll(of: String, with: String): String
```
* `of`の文字列がすべて`with`の文字列に置き換えられた文字列を返します。`of`が空の場合、文字列の先頭と各 UTF-8 シーケンスの後に一致し、長さ k の文字列に対して k+1 個の置換が生成されます。
```ruby
let example = "abababa"

example.replaceAll(of: "a", with: "o")
/* is `obobobo` */
```
<h4>split</h4>

```ruby
view fun split(separator: String): [String]
```
* `separator`で文字列を分割して作成した、可変長の文字列配列を返します。
```ruby
let example = "hello world"

example.split(separator: " ")
/* is `["hello", "world"]` */
```
`String`型は、以下の関数も提供します。
<h4>encodeHex</h4>

```ruby
view fun String.encodeHex(_ data: [UInt8]): String
```
* 指定されたバイト配列に対して16進数文字列を返します。
```
let data = [1 as UInt8, 2, 3, 0xCA, 0xDE]

String.encodeHex(data)  // is `"010203cade"`
```
<h4>join</h4>

```ruby
view fun String.join(_ strings: [String], separator: String): String
```
* `strings`の配列と、指定された`separator`を結合して作成された文字列を返します。
```ruby
let strings = ["hello", "world"]
String.join(strings, " ")
/* is "hello world" */
```
`String`は、`Character`型の値を返すインデックス指定も可能です。
```ruby
let str = "abc"
let c = str[0]
/* is the Character "a" */
```
<h4>fromUTF8</h4>

```ruby
view fun String.fromUTF8(_ input: [UInt8]): String?
```
* UTF-8 エンコードされたバイト配列を`String`に変換しようと試みます。 この関数は、バイト配列が不完全なコードポイントシーケンス(codepoint sequences)や未定義の書記素(undefined graphemes)など、無効な UTF-8 を含む場合`nil`を返します。

与えられた文字列`s`に対して、`String.fromUTF8(s.utf8)`は`s`を[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)でラップすることと同義です。
<h1 id="Character-Fields-and-Functions">Character Fields and Functions</h1>

`Character`値は、`toString`関数を使用して`String`値に変換できます。
<h4>toString</h4>

```ruby
view fun toString(): String
```
* 文字の文字列表現を返します。
```ruby
let c: Character = "x"

c.toString()
/* is "x" */
```
<h4>fromCharacters</h4>

```ruby
view fun String.fromCharacters(_ characters: [Character]): String
```
* `Character`の配列から新しい`String`値を構築します。
`String`は不変(immutable)であるため、この操作では入力配列のコピー(copy of the input array)が作成されます。
```ruby
let rawUwU: [Character] = ["U", "w", "U"]
let uwu: String = String.fromCharacters(rawUwU)
/* "UwU" */
```
<h4>utf8</h4>

```ruby
let utf8: [UInt8]
```
* UTF-8エンコーディングのバイト配列を返します。
```ruby
let a: Character = "a"
let a_bytes = a.utf8
/* `a_bytes` is `[97]` */

let bouquet: Character = "\u{1F490}"
let bouquet_bytes = bouquet.utf8
/* `bouquet_bytes` is `[240, 159, 146, 144]` */
```

<h1 id="Arrays">Arrays</h1>

配列は、mutable(変更可能)で、値の順序付けられた集合です。配列は、同じ値を複数回含めることができます。配列リテラルは、開き角括弧 `[` で始まり、閉じ角括弧 `]` で終わります。
```ruby
/* An empty array */
[]

/* An array with integers */
[1, 2, 3]
```

<h1 id="Array-Types">Array Types</h1>

配列は固定サイズか可変サイズであり、つまり要素の追加や削除が可能です。

固定サイズの配列の型は、`[T; N]` の形式です。ここで、`T` は要素の型、`N` は配列のサイズです。 `N` は宣言時に既知である必要があり、つまり整数リテラルでなければなりません。例えば、`Int8` の3要素の固定サイズ配列は、型が `[Int8; 3]` となります。

可変サイズの配列の型は、`[T]`という形式で表され、`T`は要素の型です。例えば、`[Int16]`型は、`Int16`型の要素を持つ可変サイズの配列を指定します。

配列内のすべての値は、配列の要素の型（`T`）のサブタイプである型でなければなりません。

配列は値型であり、定数または変数の初期値として使用される時、変数に代入する時、関数の引数として使用される時、または関数呼び出しから返される時にのみコピーされることを理解することが重要です。
```ruby
let size = 2
/* Invalid: Array-size must be an integer literal */
let numbers: [Int; size] = []

/* Declare a fixed-sized array of integers
 * which always contains exactly two elements.
 */
let array: [Int8; 2] = [1, 2]

/* Declare a fixed-sized array of fixed-sized arrays of integers.
 * The inner arrays always contain exactly three elements,
 * the outer array always contains two elements.
 */
let arrays: [[Int16; 3]; 2] = [
    [1, 2, 3],
    [4, 5, 6]
]

/* Declare a variable length array of integers */
var variableLengthArray: [Int] = []

/* Mixing values with different types is possible
 * by declaring the expected array type
 * with the common supertype of all values.
 */
let mixedValues: [AnyStruct] = ["some string", 42]
```
配列の型は、要素の型に対して上位互換です。例えば、`[Int]`は`[AnyStruct]`のサブタイプです。これは安全です。なぜなら、配列は値型であり、参照型ではないからです。

<h1 id="Array-Indexing">Array Indexing</h1>

配列の特定のインデックスの要素を取得するには、インデックス構文を使用します。配列の後に開き角括弧 `[`、インデックス値、閉じ角括弧 `]`を続けます。

インデックスは配列の最初の要素が0から始まります。

範囲外の要素にアクセスすると、実行時に致命的なエラー(原文: fatal error at run-time)が発生し、プログラムが中断されます。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Get the first number of the array. */
numbers[0]
// `42`

/* Get the second number of the array. */
numbers[1]
// `23`

/* Run-time error: Index 2 is out of bounds, the program aborts. */
numbers[2]
```
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Get the first number of the array. */
numbers[0]
// `42`

/* Get the second number of the array. */
numbers[1]
// `23`

/* Run-time error: Index 2 is out of bounds, the program aborts. */
numbers[2]
```
```ruby
/* Declare an array of arrays of integers, i.e. the type is `[[Int]]`. */
let arrays = [[1, 2], [3, 4]]

/* Get the first number of the second array. */
arrays[1][0]
// `3`
```
配列の要素を特定のインデックスに設定するには、インデックス構文を使用することもできます。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Change the second number in the array.
 *
 * NOTE: The declaration `numbers` is constant, which means that
 * the *name* is constant, not the *value* – the value, i.e. the array,
 * is mutable and can be changed.
 */
numbers[1] = 2

/* `numbers` is `[42, 2]` */
```

<h1 id="Array-Fields-and-Functions">Array Fields and Functions</h1>

配列には、配列の内容に関する情報を取得したり、配列の内容を操作したりするために使用できる複数の組み込みフィールドと組み込み関数が用意されています。

`length`フィールド、および`concat`、`contains`関数は、可変長配列と固定長配列の両方で使用できます。
<h4>length</h4>

```ruby
let length: Int
```
* 配列の要素数を返します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23, 31, 12]

/* Find the number of elements of the array. */
let length = numbers.length

/* `length` is `4` */
```
<h4>concat</h4>

```ruby
access(all)
view fun concat(_ array: T): T
```
* パラメータの`array`を、関数が呼び出された配列の末尾に連結しますが、その配列を変更することはありません。

両方の配列は同じ型`T`でなければなりません。

この関数は、関数が呼び出された配列の長さと、パラメータとして指定された配列の長さの合計の長さを持つ新しい配列を作成します。
```ruby
/* Declare two arrays of integers. */
let numbers = [42, 23, 31, 12]
let moreNumbers = [11, 27]

/* Concatenate the array `moreNumbers` to the array `numbers`
 * and declare a new variable for the result.
 */
let allNumbers = numbers.concat(moreNumbers)

/* `allNumbers` is `[42, 23, 31, 12, 11, 27]`
 * `numbers` is still `[42, 23, 31, 12]`
 * `moreNumbers` is still `[11, 27]` */
```
<h4>contains</h4>

```ruby
access(all)
view fun contains(_ element: T): Bool
```
* `T`の型の要素が配列にある場合は、trueを返します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23, 31, 12]

/* Check if the array contains 11. */
let containsEleven = numbers.contains(11)
/* `containsEleven` is `false` */

/* Check if the array contains 12. */
let containsTwelve = numbers.contains(12)
/* `containsTwelve` is `true` */

/* Invalid: Check if the array contains the string "Kitty".
 * This results in a type error, as the array only contains integers.
 */
let containsKitty = numbers.contains("Kitty")
```
<h4>firstIndex</h4>

```ruby
access(all)
view fun firstIndex(of: T): Int?
```
* 配列内で指定のオブジェクトに一致する最初の要素のインデックスを返します。一致しない場合は nil を返します。`T` がリソース型およびそれと同等でない場合に利用可能です。

```ruby
 /* Declare an array of integers. */
 let numbers = [42, 23, 31, 12]

 /* Check if the array contains 31 */
 let index = numbers.firstIndex(of: 31)
 /* `index` is 2 */

 /* Check if the array contains 22 */
 let index = numbers.firstIndex(of: 22)
 /* `index` is nil */
```
<h4>slice</h4>

```ruby
access(all)
view fun slice(from: Int, upTo: Int): [T]
```
* 指定した配列の要素を、開始インデックス`from`から、終了インデックス`upTo`までを配列のスライスとして返します。この関数は、長さが`upTo - from`となる新しい配列を作成します。元の配列は変更されません。パラメータのいずれかが配列の範囲外である場合、またはインデックスが無効である場合（`from > upTo`）は、関数は失敗します。
```ruby
let example = [1, 2, 3, 4]

/* Create a new slice of part of the original array. */
let slice = example.slice(from: 1, upTo: 3)
/* `slice` is now `[2, 3]` */

/* Run-time error: Out of bounds index, the program aborts. */
let outOfBounds = example.slice(from: 2, upTo: 10)

/* Run-time error: Invalid indices, the program aborts. */
let invalidIndices = example.slice(from: 2, upTo: 1)
```
<h4>reverse</h4>

```ruby
access(all)
view fun reverse(): [T]
```
* 内容を逆順にした新しい配列を返します。`T` がリソース類でない場合に利用可能です。
```ruby
let example = [1, 2, 3, 4]

/* Create a new array which is the reverse of the original array. */
let reversedExample = example.reverse()
/* `reversedExample` is now `[4, 3, 2, 1]` */
```
```ruby
access(all)
view fun reverse(): [T; N]
```
* 同じ内容で順序が逆転した、同じサイズの新しい固定サイズ配列を返します。
```ruby
let fixedSizedExample: [String; 3] = ["ABC", "XYZ", "PQR"]

/* Create a new array which is the reverse of the original array. */
let fixedArrayReversedExample = fixedSizedExample.reverse()
/* `fixedArrayReversedExample` is now `["PQR", "XYZ", "ABC"]` *?
```
<h4>map</h4>

```ruby
access(all)
fun map(_ f: fun(T): U): [U]
```
* 元の配列の各要素にMap関数を適用して生成した要素からなる新しい配列を返します。`T` がリソース類でない場合に利用可能です。
```ruby
let example = [1, 2, 3]
let trueForEven =
    fun (_ x: Int): Bool {
        return x % 2 == 0
    }

let mappedExample: [Bool] = example.map(trueForEven)
/* `mappedExample` is `[False, True, False]`
 * `example` still remains as `[1, 2, 3]`

 * Invalid: Map using a function which accepts a different type.
 * This results in a type error, as the array contains `Int` values
 * while function accepts `Int64`.
 */
let functionAcceptingInt64 =
    fun (_ x: Int64): Bool {
        return x % 2 == 0
    }
let invalidMapFunctionExample = example.map(functionAcceptingInt64)
```
`map`関数は固定サイズの配列でも使用できます。
```ruby
access(all)
fun map(_ f: fun(T): U): [U; N]
```
* 元の配列の各要素にMap関数を適用して生成した要素からなる、新しい固定サイズの配列を返します。`T` がリソース類でない場合に利用可能です。
```ruby
let fixedSizedExample: [String; 3] = ["ABC", "XYZYX", "PQR"]
let lengthOfString =
    fun (_ x: String): Int {
        return x.length
    }

let fixedArrayMappedExample = fixedSizedExample.map(lengthOfString)
/* `fixedArrayMappedExample` is now `[3, 5, 3]`
 * `fixedSizedExample` still remains as ["ABC", "XYZYX", "PQR"]

 * Invalid: Map using a function which accepts a different type.
 * This results in a type error, as the array contains `String` values
 * while function accepts `Bool`.
 */
let functionAcceptingBool =
    fun (_ x: Bool): Int {
        return 0
    }
let invalidMapFunctionExample = fixedSizedExample.map(functionAcceptingBool)
```
<h4>filter</h4>

```ruby
access(all)
view fun filter(_ f: view fun(T): Bool): [T]
```
* 元の配列の各要素にフィルタ関数を適用してフィルタリングした新しい配列を返します。`T` がリソース類でない場合に利用可能です。
```ruby
let example = [1, 2, 3]
let trueForEven =
    fun (_ x: Int): Bool {
        return x % 2 == 0
    }

let filteredExample: [Int] = example.filter(trueForEven)
/* `filteredExample` is `[2]`
 * `example` still remains as `[1, 2, 3]`
 */

/* Invalid: Filter using a function which accepts a different type.
 * This results in a type error, as the array contains `Int` values
 * while function accepts `Int64`.
 */
let functionAcceptingInt64 =
    fun (_ x: Int64): Bool {
        return x % 2 == 0
    }
let invalidFilterFunctionExample = example.filter(functionAcceptingInt64)
```
`filter`関数は、固定サイズの配列にも使用できます。
```ruby
access(all)
view fun filter(_ f: view fun(T): Bool): [T]
```
* 元の配列の各要素に対してfilter関数を適用してフィルタリングした、新しい**可変長の**配列を返します。`T` がリソース型類でない場合に利用可能です。
```ruby
let fixedSizedExample: [String; 3] = ["AB", "XYZYX", "PQR"]
let lengthOfStringGreaterThanTwo =
    fun (_ x: String): Bool {
        return x.length > 2
    }

let fixedArrayFilteredExample = fixedSizedExample.filter(lengthOfStringGreaterThanTwo)
/* `fixedArrayFilteredExample` is `["XYZYX", "PQR"]`
 * `fixedSizedExample` still remains as ["AB", "XYZYX", "PQR"]
 */

/* Invalid: Filter using a function which accepts a different type.
 * This results in a type error, as the array contains `String` values
 * while function accepts `Bool`.
 */
let functionAcceptingBool =
    fun (_ x: Bool): Bool {
        return True
    }
let invalidFilterFunctionExample = fixedSizedExample.filter(functionAcceptingBool)
```
**Variable-size Array Functions**

以下の関数は可変長配列でのみ使用できます。 これらの関数を固定長配列で使用することは出来ません。
<h4>append</h4>

```ruby
access(Mutate | Insert)
fun append(_ element: T): Void
```
新しい要素`element`（`T`型）を配列の最後に追加します。

新しい要素は、配列内の他のすべての要素と同じ型でなければなりません。

この関数は配列を変更(mutate)します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23, 31, 12]

/* Add a new element to the array. */
numbers.append(20)
/* `numbers` is now `[42, 23, 31, 12, 20]` */

/* Invalid: The parameter has the wrong type `String`. */
numbers.append("SneakyString")
```
<h4>appendAll</h4>

```ruby
access(Mutate | Insert)
fun appendAll(_ array: T): Void
```
* `array`のすべての要素を、この関数を呼び出した配列の末尾に追加します。

両方の配列は同じ型`T`でなければなりません。

この関数は配列を変更(mutate)します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Add new elements to the array. */
numbers.appendAll([31, 12, 20])
/* `numbers` is now `[42, 23, 31, 12, 20]` */

/* Invalid: The parameter has the wrong type `[String]`. */
numbers.appendAll(["Sneaky", "String"])
```
<h4>insert</h4>

```ruby
access(Mutate | Insert)
fun insert(at: Int, _ element: T): Void
```
* この関数が呼び出された配列に`T`型の新しい要素`element`を指定された`index`に挿入します。
新しい要素は配列内の他の要素と同じ型でなければなりません。
`index`は配列の範囲内に存在しなければなりません。インデックスが範囲外の場合、プログラムは中断します。
指定されたインデックスの既存の要素は上書きされません。
新しい要素が挿入された後のすべての要素は、1つ右にシフトされます。
この関数は配列を変化(mutate)させます。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23, 31, 12]

/* Insert a new element at position 1 of the array. */
numbers.insert(at: 1, 20)
/* `numbers` is now `[42, 20, 23, 31, 12]` */

/* Run-time error: Out of bounds index, the program aborts. */
numbers.insert(at: 12, 39)
```
<h4>remove</h4>

```ruby
access(Mutate | Remove)
fun remove(at: Int): T
```
* 指定した`index`の要素を配列から取り除き、それを返します。
`index`は配列の範囲内に限ります。インデックスが範囲外の場合、プログラムは中断します。
この関数は配列を変更(mutate)します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23, 31]

/* Remove element at position 1 of the array. */
let twentyThree = numbers.remove(at: 1)
/* `numbers` is now `[42, 31]`
 * `twentyThree` is `23` */

/* Run-time error: Out of bounds index, the program aborts. */
numbers.remove(at: 19)
```
<h4>removeFirst</h4>

```ruby
access(Mutate | Remove)
fun removeFirst(): T
```
* 配列から最初の要素を取り出し、それを返します。
配列は空であってはなりません。配列が空の場合、プログラムは中断します。
この関数は配列を変更(mutate)します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Remove the first element of the array. */
let fortytwo = numbers.removeFirst()
/* `numbers` is now `[23]`
 * `fortywo` is `42` */

/* Remove the first element of the array. */
let twentyThree = numbers.removeFirst()
/* `numbers` is now `[]`
 * `twentyThree` is `23` */

/* Run-time error: The array is empty, the program aborts. */
numbers.removeFirst()
```
<h4>removeLast</h4>

```ruby
access(Mutate | Remove)
fun removeLast(): T
```
* 配列から最後の要素を削除し、それを返します。
配列は空であってはなりません。配列が空の場合、プログラムは中断します。
この関数は配列を変更(mutate)します。
```ruby
/* Declare an array of integers. */
let numbers = [42, 23]

/* Remove the last element of the array. */
let twentyThree = numbers.removeLast()
/* `numbers` is now `[42]`
 * `twentyThree` is `23` */

/* Remove the last element of the array. */
let fortyTwo = numbers.removeLast()
/* `numbers` is now `[]`
 * `fortyTwo` is `42` */

/* Run-time error: The array is empty, the program aborts. */
numbers.removeLast()
```

<h1 id="Dictionaries">Dictionaries</h1>

ディクショナリは、変更可能で順序のないキーと値の関連付けの集合です。 ディクショナリには、キーは1つだけ、値は複数含めることができます。

ディクショナリ リテラルは、開始波括弧 `{`で始まり、終了波括弧 `}`で終わります。 キーと値はコロンで区切られ、キーと値の関連付けはカンマで区切られます。

```ruby
/* An empty dictionary */
{}

/* A dictionary which associates integers with booleans */
{
    1: true,
    2: false
}
```

<h1 id="Dictionary-Types">Dictionary Types</h1>

ディクショナリ型の形式は `{K: V}` です。ここで、`K` はキーの型、`V` は値の型です。例えば、`Int`キーと`Bool`値を持つディクショナリは、型が `{Int: Bool}` となります。

ディクショナリでは、すべてのキーはディクショナリのキーの型 (`K`) のサブタイプである型を持ち、すべての値はディクショナリの値の型 (`V`) のサブタイプである型を持つ必要があります。

```ruby
/* Declare a constant that has type `{Int: Bool}`,
 * a dictionary mapping integers to booleans.
 */
let booleans = {
    1: true,
    0: false
}

/* Declare a constant that has type `{Bool: Int}`,
 * a dictionary mapping booleans to integers.
 */
let integers = {
    true: 1,
    false: 0
}

/* Mixing keys with different types, and mixing values with different types,
 * is possible by declaring the expected dictionary type with the common supertype
 * of all keys, and the common supertype of all values.
 */
let mixedValues: {String: AnyStruct} = {
    "a": 1,
    "b": true
}
```
ディクショナリ型は、キーと値の型が最小上位互換型(covariant)です。例えば、`{Int: String}`は`{AnyStruct: String}`のサブタイプであり、また`{Int: AnyStruct}`のサブタイプでもあります。これは安全です。なぜなら、ディクショナリは値型であり参照型ではないからです。

<h1 id="Dictionary-Access">Dictionary Access</h1>

ディクショナリから特定のキーの値を取得するには、アクセス構文を使用します。ディクショナリの後に角括弧 `[` を開き、キーを指定し、角括弧 `]`を閉じます。

キーにアクセスすると、[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)の値が返されます。キーがディクショナリ内に存在する場合は、指定されたキーの値が返され、キーが見つからない場合は`nil`が返されます。
```ruby
/* Declare a constant that has type `{Int: Bool}`,
 * a dictionary mapping integers to booleans.
 */
let booleans = {
    1: true,
    0: false
}

/* The result of accessing a key has type `Bool?`. */
booleans[1]
// `true`
booleans[0]
// `false`
booleans[2]
// `nil`

/* Invalid: Accessing a key which does not have type `Int`. */
booleans["1"]
```
```ruby
/* Declare a constant that has type `{Bool: Int}`,
 * a dictionary mapping booleans to integers.
 */
let integers = {
    true: 1,
    false: 0
}

/* The result of accessing a key has type `Int?` */
integers[true]
// `1`
integers[false]
// `0`
```
ディクショナリ内のキーに値を設定するために、アクセス構文を使用することもできます。
```ruby
/* Declare a constant that has type `{Int: Bool}`,
 * a dictionary mapping booleans to integers.
 */
let booleans = {
    1: true,
    0: false
}

/* Assign new values for the keys `1` and `0`. */
booleans[1] = false
booleans[0] = true
/* `booleans` is `{1: false, 0: true}` */
```

<h1 id="Dictionary-Fields-and-Functions">Dictionary Fields and Functions</h1>

<h4>length</h4>

```ruby
let length: Int
```

* ディクショナリに格納されている項目数を返します。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"fortyTwo": 42, "twentyThree": 23}

/* Find the number of entries of the dictionary. */
let length = numbers.length

/* `length` is `2` */
```
<h4>insert</h4>

```ruby
access(Mutate | Insert)
fun insert(key: K, _ value: V): V?
```
* `V`型の値を、`K`型の`key`の下のディクショナリに格納します。

格納されたキーは、ディクショナリのキーの型と同じ型でなければならず、格納された値は、ディクショナリの値の型と同じ型でなければなりません。

ディクショナリがキーを含んでいる場合は、以前の値をオプショナルとして返します。それ以外の場合、`nil`を返します。

ディクショナリがすでにキーを含んでいる場合は、値を更新します。

この関数は、ディクショナリを変更(mutate)します。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"twentyThree": 23}

/* Insert the key `"fortyTwo"` with the value `42` into the dictionary.
 * The key did not previously exist in the dictionary,
 * so the result is `nil`
 */
let old = numbers.insert(key: "fortyTwo", 42)

/* `old` is `nil`
 * `numbers` is `{"twentyThree": 23, "fortyTwo": 42}` */
```
<h4>remove</h4>

```ruby
access(Mutate | Remove)
fun remove(key: K): V?
```
* 引数の`K`型の`key`の値をディクショナリから削除します。

ディクショナリにキーが含まれていた場合、`V`型の値を[オプショナル](https://qiita.com/flowcadence/items/c917af1e35cd46cf6a7f#optionals)として返します。そうでなければ`nil`を返します。

この関数はディクショナリを変更(mutate)します。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"fortyTwo": 42, "twentyThree": 23}

/* Remove the key `"fortyTwo"` from the dictionary.
 * The key exists in the dictionary,
 * so the value associated with the key is returned.
 */
let fortyTwo = numbers.remove(key: "fortyTwo")

/* `fortyTwo` is `42`
 * `numbers` is `{"twentyThree": 23}`
 */

/* Remove the key `"oneHundred"` from the dictionary.
 * The key does not exist in the dictionary, so `nil` is returned.
 */
let oneHundred = numbers.remove(key: "oneHundred")

/* `oneHundred` is `nil`
 * `numbers` is `{"twentyThree": 23}` */
```
<h4>keys</h4>

```ruby
let keys: [K]
```
* ディクショナリ内の型`K`のキーの配列を返します。これはディクショナリを変更するものではなく、単にキーの配列のコピーを返すだけです。ディクショナリが空の場合は空の配列を返します。キーの順序は未定義です。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"fortyTwo": 42, "twentyThree": 23}

/* Find the keys of the dictionary. */
let keys = numbers.keys

/* `keys` has type `[String]` and is `["fortyTwo","twentyThree"]` */
```
<h4>values</h4>

```ruby
let values: [V]
```
* ディクショナリ内の型`V`の値の配列を返します。これはディクショナリを変更するものではなく、値の配列のコピーを返すだけです。ディクショナリが空の場合は空の配列を返します。
このフィールドは、`V`がリソース型の場合は利用できません。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"fortyTwo": 42, "twentyThree": 23}

/* Find the values of the dictionary. */
let values = numbers.values

/* `values` has type [Int] and is `[42, 23]` */
```
<h4>containsKey</h4>

```ruby
access(all)
view fun containsKey(key: K): Bool
```

* `K`型の指定されたキーがディクショナリにある場合はtrueを返します。
```ruby
/* Declare a dictionary mapping strings to integers. */
let numbers = {"fortyTwo": 42, "twentyThree": 23}

/* Check if the dictionary contains the key "twentyFive". */
let containsKeyTwentyFive = numbers.containsKey("twentyFive")
/* `containsKeyTwentyFive` is `false` */

/* Check if the dictionary contains the key "fortyTwo". */
let containsKeyFortyTwo = numbers.containsKey("fortyTwo")
/* `containsKeyFortyTwo` is `true` */

/* Invalid: Check if the dictionary contains the key 42.
 * This results in a type error, as the key type of the dictionary is `String`.
 */
let containsKey42 = numbers.containsKey(42)
```
<h4>forEachKey</h4>

```ruby
access(all)
fun forEachKey(_ function: fun(K): Bool): Void
```
* ディクショナリ内のすべてのキーを繰り返し処理し、処理している関数内で false を返した場合は早期終了します。これは、`.keys` を呼び出し、その結果の配列を繰り返し処理するよりも効率的です。中間的な割り当てが回避されるためです。キーの繰り返し処理の順序は未定義であり、`.keys` と同様です。
```ruby
/* Take in a targetKey to look for, and a dictionary to iterate through. */
fun myContainsKey(targetKey: String, dictionary: {String: Int}) {
  /* Declare an accumulator that we'll capture inside a closure. */
  var found = false

  /* At each step, `key` will be bound to another key from `dictionary`. */
  dictionary.forEachKey(fun (key: String): Bool {
    found = key == targetKey

    /* The returned boolean value, signals whether to continue iterating.
     * This allows for control flow during the iteration process:
     *  true = `continue`
     *  false = `break`
     */
    return !found
  })

  return found
}
```
<h1 id="Dictionary-Keys">Dictionary Keys</h1>

ディクショナリのキーはハッシュ化可能かつ等価(equatable)でなければなりません。

ブール値や整数などの組み込みの型は、ほとんどがハッシュ化可能かつ等価であるため、ディクショナリのキーとして使用できます。

<h1 id="InclusiveRange">InclusiveRange</h1>

`InclusiveRange<T: Integer>`の値は、2つの整数の間の数値の範囲(range)を表し、その名前が示すように、開始値と終了値も範囲に含まれます。

範囲の値には、`start`、`end`、および`step`があり、これは、`start`から`end`までの範囲の値が区切られる間隔を表します。

範囲(range)は、`InclusiveRange`コンストラクタを使用して作成でき、このコンストラクタには2つまたは3つの引数を指定できます。

範囲が2つの引数で構成される場合、最初の引数は`start`、2番目の引数は`end`です。`step`は、`1`（`end >= start`の場合）または`-1`（`end < start`の場合）のいずれかと推論されます。

例
```ruby
/* start is 1, end is 100, step is 1 */
let range: InclusiveRange<UInt> = InclusiveRange(1, 100)
```
オプショナルとして、ラベル付きのゼロではない`step`引数を指定して、`1`以外のステップを指定することができます。例えば、次の範囲(range)には、1から100までのすべての奇数が含まれます。
```ruby
/* start is 1, end is 100, step is 2 */
let range: InclusiveRange<UInt> = InclusiveRange(1, 100, step: 2)
```
この例では、範囲の「end」が100と指定されているにもかかわらず、その範囲が実際に取得できる最後の値は99であることに注意してください。

指定された`step`引数が`end`で示した範囲を超えてしまう場合、生成は失敗します。

例：
```ruby
/* Throws an error because a step of -2 cannot progress from 1 to 100 */
let range: InclusiveRange<Int> = InclusiveRange(1, 100, step: -2)
```
範囲(range)を作成する際には、型アノテーションを指定する必要があります。

<h1 id="InclusiveRange-fields-and-functions">InclusiveRange fields and functions</h1>

`InclusiveRange<T>`型の値は、`T`が数値型で、以下のフィールドと関数を持ちます。
```ruby
let start: T
```
* 範囲の開始位置を返します。
```ruby
/* Declare a range of `Int`s */
let range = let r: InclusiveRange<Int> = InclusiveRange(3, 9)

/* Get the start of the range */
let start = range.start

/* `start` is `3` */
```
```ruby
let end: T
```
* 範囲の終了位置を返します。
```ruby
/* Declare a range of `Int`s */
let range: InclusiveRange<Int> = InclusiveRange(3, 9)

/* Get the end of the range */
let end = range.end

/* `end` is `9` */
```
```ruby
let step: T
```
* 範囲のstepを返します。
```ruby
/* Declare a range of `Int`s with a `step` of 2 */
let rangeWithStep: InclusiveRange<Int> = InclusiveRange(3, 9, step: 2)

/* Get the step of the range */
var step = range.step

/* `step` is `2` */

/* Declare a range of `Int`s without an explicit `step` */
let rangeWithStep: InclusiveRange<Int> = InclusiveRange(3, 9)

/* Get the step of the range */
step = rangeWithStep.step

/* `step` is implicitly `1` */
```
```ruby
access(all)
view fun contains(_ element: T): Bool
```
* 引数の整数が `InclusiveRange` シーケンスに含まれる場合は`true`を返し、含まれない場合は`false`を返します。

特に、`start`、`step`、`end`で定義されたある`InclusiveRanger` `r`に対して、`r.contains(x)`は以下のいずれかの場合に`true`を返します。

* `start <= end`かつ、ある `i >= 0`の整数が存在し、`start + i * step = x` 且つ `x <= end`
* `start > end`かつ、ある `i >= 0`の整数が存在し、`start - i * step = x` 且つ `x >= end`
```ruby
/* Declare a range of `Int`s with a `step` of 2 */
let rangeWithStep: InclusiveRange<Int> = InclusiveRange(3, 9, step: 2)

/* `contains` is `true` */
var contains = range.contains(5)

/* `contains` is `true` */
var contains = range.contains(9)

/* `contains` is `false` */
contains = range.contains(6)

/* `contains` is `false` */
contains = range.contains(11)
```



翻訳元

https://cadence-lang.org/docs/language/values-and-types

***
<b>[Previous << Type Annotations](https://qiita.com/flowcadence/items/aefb58373b7b6dc956d9)
</b>

[Flow blockchain / Cadence version1.0ドキュメント](https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a) (Values and Types)

<b>[Next >> Operators](https://qiita.com/flowcadence/items/3220cbef5b83f3d27f7a)</b>