آرایه در

درباره‌ی آرایه

JSON یک آرایه را این‌گونه تعریف می‌کند:

آرایه مجموعه‌ی مرتبی از مقادیر است. آرایه با [ براکت چپ شروع می‌شود و با ] براکت راست پایان می‌یابد. مقادیر با , کاما از هم جدا می‌شوند.

آرایه می‌تواند صفر یا چند مقدار از هر نوعی از مقادیر JSON را در خود نگه دارد. لازم نیست عنصرهای آرایه همگی از یک نوع باشند.

ساختن آرایه‌ها

برای گردآوردن عنصرها در یک آرایه از براکت استفاده کنید.

[1, 2, 3]

می‌توان عنصرهای یک «جریان» را با گذاشتن آن میان براکت‌ها، در یک آرایه گرد آورد.

range(5)     # => a stream of 5 numbers
[range(5)]   # => the array [0, 1, 2, 3, 4]

اندازه

تابع length تعداد عنصرهای یک آرایه را برمی‌گرداند.

اندیس‌گذاری و برش

اندیس‌گذاری آرایه از صفر شروع می‌شود.

برای به‌دست آوردن یک عنصر از آرایه، از یک عبارت براکتی استفاده کنید: .[2] سومین عنصر را می‌گیرد.

اندیس‌های منفی از انتهای آرایه به عقب شمرده می‌شوند: .[-1] آخرین عنصر را می‌گیرد؛ .[-2] دومین عنصر از آخر است.

یک برش زیردنباله‌ای از آرایه است. .[10:15] پنج عنصر را از اندیس ۱۰ به بعد برمی‌گرداند؛ اندیس پایانی لحاظ نمی‌شود.

چند تابع کمکی هم وجود دارد:

• first اولین عنصر را می‌گیرد.
• last آخرین عنصر را می‌گیرد.
• nth(n) عنصر واقع در اندیس n را می‌گیرد.

تبدیل به جریانی از عنصرها

در برخی موقعیت‌ها می‌خواهیم عنصرهای یک آرایه را تک‌تک به‌صورت جریان بیرون بدهیم. برای این کار از .[] استفاده می‌کنیم.

فرض کنید می‌خواهیم جریانی از طول رشته‌های داخل یک آرایه داشته باشیم.

["a", "be", "cat", "door"] | length        # => 4 -- the number of elements in the array
["a", "be", "cat", "door"] | .[] | length  # => 1, 2, 3, 4 -- the lengths of each element

می‌توان براکت‌های خالی را کنار عبارت قبلی آورد و | را ننوشت.

["a", "be", "cat", "door"][] | length      # => 1, 2, 3, 4 -- the lengths of each element
# ........................^^

الحاق و تفریق

برای الحاق آرایه‌ها از + استفاده کنید.

[1, 2, 3] + [4, 5]          # => [1, 2, 3, 4, 5]

عملگر - عنصرهای آرایه‌ی سمت راست را از آرایه‌ی سمت چپ حذف می‌کند.

[range(10)] - [2, 4, 6]     # => [0, 1, 3, 5, 7, 8, 9]

پیمایش

jq توابع زیادی برای پوشش کاربردهای رایج پیمایش فراهم می‌کند:

• map(expr) آرایه‌ی تازه‌ای برمی‌گرداند که در آن expr به‌نوبت روی هر عنصر اعمال می‌شود.

  [1, 2, 3] | map(. * 10)    # => [10, 20, 30]
  
  

• select(expr) تابعی است که expr را روی یک مقدار تکی اعمال می‌کند؛ اگر نتیجه‌ی عبارت «درست» باشد، آن مقدار برگردانده می‌شود؛ اگر نتیجه «غلط» باشد، هیچ‌چیز برگردانده نمی‌شود؛ نه null، بلکه واقعاً هیچ‌چیز.

  برای اعمال آن روی یک آرایه، آن را با map ترکیب کنید.

  [range(10)] | map(select(. % 2 == 0))    # => [0, 2, 4, 6, 8]
  

  روش دیگر این است که select را روی یک جریان اعمال کنید و نتیجه‌ها را جمع کنید.

  [range(10) | select(. % 2 == 0)]    # => [0, 2, 4, 6, 8]
  

• any(condition) و all(condition) یک مقدار منطقی برمی‌گردانند: آیا دست‌کم یکی از عنصرهای آرایه شرط را برآورده می‌کند، یا همه‌ی آن‌ها.

  [1, 2, 3, 4] | any(. > 4)    # false
  [1, 2, 3, 4] | any(. >= 4)   # true
  
  [1, 2, 3, 4] | all(. >= 4)   # false
  [1, 2, 3, 4] | all(. <= 4)   # true
  

عضویت

می‌توان با index بررسی کرد که آیا آرایه عنصری را در خود دارد یا نه. این تابع اگر عنصر داده‌شده در آرایه باشد، اندیس آن را برمی‌گرداند؛ در غیر این صورت تابع null را برمی‌گرداند.

["carrots", "beef", "potatoes"] | index("beef")    # => 1
["carrots", "beef", "potatoes"] | index("bees")    # => null

تابع معکوسی هم به اسم IN وجود دارد (بله، با حروف بزرگ). نکته‌ی ظریف درباره‌ی IN این است که آرگومانش یک آرایه نیست، بلکه یک جریان است.

"beef" | IN(["carrots", "beef", "potatoes"][])    # => true
"bees" | IN(["carrots", "beef", "potatoes"][])    # => false

توابع دیگر (برای جزئیات به دفترچه‌ی راهنما مراجعه کنید)

• Ruby متد مفیدی به اسم each_with_index دارد که مقدار عنصر را با اندیسش جفت می‌کند. Python تابع enumerate را دارد. jq چیز مشابهی به اسم to_entries دارد. این تابع آرایه را به آرایه‌ای از شیءهای {key: index, value: value} تبدیل می‌کند.

  [11, 22, 33, 44] | to_entries
  # => [{key: 0, value: 11}, {key: 1, value: 22}, {key: 2, value: 33}, {key: 3, value: 44}]
  

• sort و sort_by

• group_by

• min، max، min_by، max_by

• unique، unique_by

• flatten