This document serves as a guide for working with Plutus Core builtin pairs. It's primarily meant for Pluto and Plutarch developers.
Note: If you spot any mistakes/have any related questions that this guide lacks the answer to, please don't hesitate to raise an issue. The goal is to have high quality documentation for Pluto and Plutarch users!
For using and operating on builtin pairs, all you need are a few builtin functions. These are discussed below.
Here's the synonym to Haskell's fst! Its type looks like- FstPair :: forall a b. BuiltinPair a b -> a. It takes two forces, which you may already have known from Builtin Function Reference. You force it twice, and pass in a builtin pair, and you get the first element of the pair.
You can call FstPair as you would any other function, just make sure you force it!
! ! FstPair pWhere p is a builtin pair.
Plutarch has a synonym to FstPair, pfstBuiltin (Plutarch.Builtin)-
pfstBuiltin :: Term s (PBuiltinPair a b :--> a)
pfstBuiltin = phoistAcyclic $ pforce $ pforce $ punsafeBuiltin PLC.FstPairYou would use it like any other Plutarch level function.
pfstBuiltin # pWhere p is of type PBuiltinPair a b.
We can't just have FstPair without SndPair now, can we? Its type looks like SndPair :: forall a b. BuiltinPair a b -> b. It also takes two forces. You force it twice, and pass in a builtin pair, and you get the second member.
You can call SndPair as you would any other function, just make sure you force it!
! ! SndPair pWhere p is a builtin pair.
Plutarch has a synonym to SndPair, psndBuiltin (Plutarch.Builtin)-
psndBuiltin :: Term s (PBuiltinPair a b :--> b)
psndBuiltin = phoistAcyclic $ pforce $ pforce $ punsafeBuiltin PLC.SndPairYou would use it like any other Plutarch level function.
psndBuiltin # pWhere p is of type PBuiltinPair a b.
Now we get to build a pair! A pair of Data.
Its type looks like MkPairData :: Data -> Data -> BuiltinPair Data Data. It takes two Data elements, and returns a pair of those elements.
You can call MkPairData as you would any other function.
MkPairData x yWhere x and y are both data values.
Plutarch has a synonym to MkPairData, ppairDataBuiltin (Plutarch.Builtin)-
ppairDataBuiltin :: Term s (PAsData a :--> PAsData b :--> PBuiltinPair (PAsData a) (PAsData b))
ppairDataBuiltin = punsafeBuiltin PLC.MkConsYou would use it like any other Plutarch level function.
ppairDataBuiltin # x # yWhere x and y are of type PAsData a and PAsData b respectively.
Wondering how to make pairs of elements other than Data. Well, you won't really need to do that most of the time. But you can! You just need to build a constant directly.
This is not currently possible in Pluto. But if you're using Plutarch, read constant building and PLift.
Here's how to make the pair of integer and bytestring in Plutarch-
pf :: (Integer, ByteString) -> Term s (PBuiltinPair PInteger PByteString)
pf = pconstantOf course, this is a Haskell level function, operating on Haskell data types - to build Plutarch term. So this still won't work if you want to apply it to dynamic Plutarch terms.